knitr::opts_chunk$set( fig.retina = 2, collapse = TRUE, comment = "#>", fig.path = "tools/README-" )
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]]
The second function, clcolor()
(in singular form), retrieves information about a single color based on its six-character hexidecimal representation.
clcolor('6B4106')
clcolor()
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)) clcolor(rgb(0, 1, 0, .5)) clcolor(gray(.5))
The 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]]
The other function, clpattern()
(in singular form), retrieves a pattern by its identifying number.
pattern1 <- clpattern('1451') # extract colors from the pattern swatch(pattern1)
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.
Add the following code to your website.
For more information on customizing the embed code, read Embedding Snippets.