-
Notifications
You must be signed in to change notification settings - Fork 7
/
README.Rmd
195 lines (125 loc) · 7.36 KB
/
README.Rmd
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
---
output: github_document
---
<!-- README.md is generated from README.Rmd. Please edit that file -->
```{r setup, echo=FALSE}
knitr::opts_chunk$set(
fig.retina = 2,
collapse = TRUE,
comment = "#>",
fig.path = "tools/README-"
)
```
# Client for the COLOURlovers API
[](https://cran.r-project.org/package=colourlovers)
[](https://travis-ci.org/andrewheiss/colourlovers)
[](https://codecov.io/github/andrewheiss/colourlovers?branch=master)
The **colourlovers** package connects R to the [COLOURlovers](https://www.colourlovers.com/) 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.
## Installation
You can find a stable release on [CRAN](https://cran.r-project.org/package=colourlovers):
```{r eval=FALSE}
install.packages("colourlovers")
```
or install the latest development version from GitHub using:
```{r eval=FALSE}
if (!require("remotes")) {
install.packages("remotes")
}
remotes::install_github("andrewheiss/colourlovers")
```
## Using colourlovers in R graphics
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:
```{r}
library(colourlovers)
palette1 <- clpalette('113451')
palette2 <- clpalette('92095')
palette3 <- clpalette('629637')
palette4 <- clpalette('694737')
```
```{r barplot-grid, fig.width=9, fig.height=6}
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:
```{r eval=FALSE}
swatch(clcolors('random'))
```
## [[1]]
## [1] "#88A58D"
```{r eval=FALSE}
swatch(clpalettes('random'))
```
## [[1]]
## [1] "#FFE7D1" "#D4CEAA" "#74BCA4" "#45A0A5" "#374313"
### Get Colors
Two functions retrieve information about individual colors from COLOURlovers. The first, `clcolors()` (in plural form), searches for colors according a number of named attributes.
```{r}
clcolors('top')[[1]]
```
The second function, `clcolor()` (in singular form), retrieves information about a single color based on its six-character hexidecimal representation.
```{r}
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:
```{r}
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:
```{r single-color, fig.width=5, fig.height=2}
plot(clcolor('00FF00'))
```
### Get Palettes
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).
```{r eval=FALSE}
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):
```{r single-palette, fig.width=5, fig.height=3}
palette1 <- clpalette('113451')
# plot the palette
plot(palette1)
```
### Get Patterns (Designs)
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).
```{r}
clpatterns('top')[[1]]
```
The other function, `clpattern()` (in singular form), retrieves a pattern by its identifying number.
```{r}
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):
```{r pattern, fig.width=5, fig.height=3}
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:
```{r pattern-pie, fig.width=5, fig.height=3}
plot(clpattern('1451'), type = 'pie')
```
## License
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](https://creativecommons.org/licenses/by-nc-sa/3.0/) license.
## Community guidelines
Please note that the 'colourlovers' project is released with a [Contributor Code of Conduct](https://github.com/andrewheiss/colourlovers/blob/master/CODE_OF_CONDUCT.md). By contributing to this project, you agree to abide by its terms.