The colourlovers package connects R to the COLOURlovers API. COLOURlovers is a social networking site for sharing colors, color palettes, and color-rich visual designs. The social networking features of the site mean that COLOURlovers provides not only rich, original color palettes to use in R graphics but also provides ratings and community evaluations of those palettes, helping R graphics designers to utilize visually pleasing color combinations.
You can find a stable release on CRAN:
install.packages("colourlovers")or install the latest development version from GitHub using:
if (!require("remotes")) {
install.packages("remotes")
}
remotes::install_github("andrewheiss/colourlovers")The plot method for the various
colourlovers functions pulls PNG-formatted images from
the COLOURlovers website and displays them in R graphics, which is
helpful for previewing particular colors, palettes, or patterns. But,
using the returned colors in R graphics requires extracting the relevant
colors and using them in some way. Thus the function swatch
extracts color information from any of the function return values, and
converts them to a character vector of hexidecimal color
representations, which can easily be directly plugged into subsequent
graphics calls.
Here’s a simple barplot example using the built-in
VADeaths dataset redesigned using four different top color
patterns:
library(colourlovers)
palette1 <- clpalette('113451')
palette2 <- clpalette('92095')
palette3 <- clpalette('629637')
palette4 <- clpalette('694737')layout(matrix(1:4, nrow = 2))
par(mar = c(2, 2, 2, 2))
barplot(VADeaths, col = swatch(palette1)[[1]], border = NA)
barplot(VADeaths, col = swatch(palette2)[[1]], border = NA)
barplot(VADeaths, col = swatch(palette3)[[1]], border = NA)
barplot(VADeaths, col = swatch(palette4)[[1]], border = NA)
The API functionality is broken down into five categories: colors, palettes, patterns, lovers, and statistics. The next sections provide examples of the first three.
Note that the clcolor(), clcolors(),
clpalette(), clpalettes(),
clpattern(), and clpatterns() functions all
have S3 plot() methods. These methods produce either simple
plots of colors, palettes, and patterns using rasterImage()
(and the png::readPNG() function) or a pie chart of the
returned color values (e.g., plot(obj, type = 'pie')).
Additionally the swatch function extracts colors
returned by any of those functions to make them easily usable in
subsequent graphics calls. For example:
swatch(clcolors('random'))## [[1]]
## [1] "#88A58D"swatch(clpalettes('random'))## [[1]]
## [1] "#FFE7D1" "#D4CEAA" "#74BCA4" "#45A0A5" "#374313"Two functions retrieve information about individual colors from
COLOURlovers. The first, clcolors() (in plural form),
searches for colors according a number of named attributes.
clcolors('top')[[1]]
#> Pattern ID: 14
#> Title: Black
#> Created by user: ninjascience
#> Date created: 2004-12-17 08:36:26
#> Views: 150348
#> Votes: 1523
#> Comments: 1788
#> Hearts: 4.5
#> Rank: 1
#> URL: http://www.colourlovers.com/color/000000/Black
#> Image URL:
#> Colors: #000000The second function, clcolor() (in singular form),
retrieves information about a single color based on its six-character
hexidecimal representation.
clcolor('6B4106')
#> Pattern ID: 903893
#> Title: wet dirt
#> Created by user: jessicabrown
#> Date created: 2008-03-17 11:22:21
#> Views: 606
#> Votes: 1
#> Comments: 0
#> Hearts: 0
#> Rank: 0
#> URL: http://www.colourlovers.com/color/6B4106/wet_dirt
#> Image URL:
#> Colors: #6B4106clcolor() automatically removes leading hashes
(#) and trailing alpha-transparency values, allowing colors
returned grDevices functions to be passed directly to
clcolor. For example:
clcolor(hsv(.5, .5, .5))
#> Pattern ID: 34152
#> Title: H, S & B
#> Created by user: serafim
#> Date created: 2005-12-15 08:07:52
#> Views: 628
#> Votes: 5
#> Comments: 4
#> Hearts: 0
#> Rank: 0
#> URL: http://www.colourlovers.com/color/408080/H_S_B
#> Image URL:
#> Colors: #408080
clcolor(rgb(0, 1, 0, .5))
#> Pattern ID: 1513
#> Title: Primary Green
#> Created by user: il morto
#> Date created: 2005-07-04 09:53:05
#> Views: 4645
#> Votes: 62
#> Comments: 32
#> Hearts: 0
#> Rank: 522
#> URL: http://www.colourlovers.com/color/00FF00/Primary_Green
#> Image URL:
#> Colors: #00FF00
clcolor(gray(.5))
#> Pattern ID: 8335
#> Title: 917~choice grey
#> Created by user: DESIGNJUNKEE
#> Date created: 2005-08-29 11:30:26
#> Views: 8178
#> Votes: 46
#> Comments: 16
#> Hearts: 5
#> Rank: 722
#> URL: http://www.colourlovers.com/color/808080/917~choice_grey
#> Image URL:
#> Colors: #808080The response includes RGB and HSV representations of the requested color, a URL for for an image of the color, and COLOURlovers ratings (views, votes, comments, hearts, and rank) for the color.
Here’s an example of the image URL at work, using the
plot method for a clcolor object:
plot(clcolor('00FF00'))
Palettes are sets of colors created by COLOURlovers users. They show potentially attractive combinations of colors, and are the most useful aspect of the COLOURlovers API in an R context.
Two functions are provided for using palettes. One,
clpalettes (in plural form), searches for palettes by user,
hue(s), color(s) (in hexidecimal representation), or keyword(s).
top <- clpalettes('top')
# plot all top palettes (interactively)
plot(top)
# plot them all as pie charts of the included colors
plot(top, type = 'pie')
# extract color swatches from new palettes
swatch(top)The other function, clpalette() (in singular form),
retrieves a pattern by its identifying number. Here’s an example of the
image URL at work (credit “Anaconda” (113451) by kunteper):
palette1 <- clpalette('113451')
# plot the palette
plot(palette1)
Patterns are images created on COLOURlovers using a specified palette of colors. They serve as examples of how to use the palette in practice.
Two functions are provided for using patterns. One,
clpatterns() (in plural form), searches for patterns
according to user, hue(s), color(s) (in hexidecimal representation), or
keyword(s).
clpatterns('top')[[1]]
#> Pattern ID: 4370608
#> Title: 0479
#> Created by user: as warning
#> Date created: 2014-07-06 03:13:02
#> Views: 4346
#> Votes: 16777215
#> Comments: 0
#> Hearts: 0
#> Rank: 0
#> URL: http://www.colourlovers.com/pattern/4370608/0479
#> Image URL:
#> Colors: #FAF9CD, #002A31, #85A0AB, #BCB203, #322B33The other function, clpattern() (in singular form),
retrieves a pattern by its identifying number.
pattern1 <- clpattern('1451')
# extract colors from the pattern
swatch(pattern1)
#> [[1]]
#> [1] "#52202E" "#1A1313" "#F7F6A8" "#C4F04D"The response includes the creator’s username, COLOURlovers ratings (views, votes, comments, hearts, and rank), the palette of colors (in hexidecimal representation) used in the pattern, and URLs for the images of the pattern.
Here’s an example of the image URL at work (credit “Geek Chic” (1451) by _183):
plot(clpattern('1451'))
Using plot(clpattern('1451'), type = 'pie'), the
plot method extracts the swatch for the
pattern (or a palette or color) and displays the results as a pie chart,
with each color labeled:
plot(clpattern('1451'), type = 'pie')
The colourlovers package is released under GPL-2, while the COLOURlovers community-generated data returned by the API is available under the Creative Commons Attribution-NonCommercial-ShareAlike 3.0 license.
Please note that the ‘colourlovers’ project is released with a Contributor Code of Conduct. By contributing to this project, you agree to abide by its terms.