| Title: | Simple Colour Manipulation |
|---|---|
| Description: | Functions for easily manipulating colours, creating colour scales and calculating colour distances. |
| Authors: | Jon Clayden |
| Maintainer: | Jon Clayden <[email protected]> |
| License: | BSD_3_clause + file LICENCE |
| Version: | 1.4.0 |
| Built: | 2025-01-12 05:36:00 UTC |
| Source: | https://github.com/jonclayden/shades |
These functions allow colours to be mixed in any colour space, either
additively (like light) or subtractively (like paint). The infix form
%.)% is an alternative for addmix, and %_/% for
submix, with the mixing amount being fixed to 1 in these cases.
addmix(base, mixer, amount = 1, space = NULL) submix(base, mixer, amount = 1, space = NULL) X %.)% Y X %_/% Yaddmix(base, mixer, amount = 1, space = NULL) submix(base, mixer, amount = 1, space = NULL) X %.)% Y X %_/% Y
base, X
|
A vector of base colours, or a palette function or scale. |
mixer, Y
|
A vector of colours to mix in. |
amount |
The amount of each colour to mix in, relative to the amount
of the base. This will be recycled to the length of |
space |
A string giving the space in which to perform the mixing, or
|
New colours of class "shade", or a new palette function.
Jon Clayden [email protected]
addmix(c("red","green","blue"), "red") submix(c("cyan","magenta","yellow"), "cyan")addmix(c("red","green","blue"), "red") submix(c("cyan","magenta","yellow"), "cyan")
This function returns the complement of its argument, the "opposite" colours in the specified space.
complement(shades, space = NULL)complement(shades, space = NULL)
shades |
One or more colours, in any suitable form (see
|
space |
The space in which to take the complement. |
New colours of class "shade", or a new palette function.
complement("cyan") complement("cyan", space="HSV") complement("cyan", space="Lab")complement("cyan") complement("cyan", space="HSV") complement("cyan", space="Lab")
This function retrieves the coordinates of a colour vector's elements, within whatever space it is currently defined.
coords(x, ...)coords(x, ...)
x |
An R object. |
... |
Additional arguments to methods. |
A matrix giving colour coordinates in the relevant space, one colour per row. Columns are typically named.
Jon Clayden [email protected]
coords("red")coords("red")
This functions manipulates colours to simulate the effects of different kinds of colour blindness, and specifically dichromacy, in which only two of the usual three types of photoreceptors are present. There are three types, corresponding to the loss of red, green or blue photoreceptors.
dichromat(shades, type = c("protanopic", "deuteranopic", "tritanopic", "none"))dichromat(shades, type = c("protanopic", "deuteranopic", "tritanopic", "none"))
shades |
One or more colours, in any suitable form (see
|
type |
The type of colour vision deficiency to simulate: protanopia
(red blindness), deuteranopia (green blindness) or tritanopia (blue
blindness). The latter is the rarest in the population. |
New colours of class "shade" in LMS space, representing
projections of the original shades onto a submanifold appropriate to the
type of dichromacy being simulated.
Jon Clayden [email protected]
Brettel, H., Viénot, F. and Mollon, J.D. (1997). Computerized simulation of color appearance for dichromats. Journal of the Optical Society of America A 14(10):2647-2655.
dichromat(c("red", "green", "blue"))dichromat(c("red", "green", "blue"))
This function calculates a distance measure that aims to quantify the perceptual difference between a vector of colours and a reference colour. The measure in question is the CIE Delta E (2000), which is calculated based on colour coordinates in Lab space.
distance(shades, reference)distance(shades, reference)
shades |
One or more colours, in any suitable form (see
|
reference |
A single reference colour. |
A numeric vector of distances.
Jon Clayden [email protected]
http://www.brucelindbloom.com/index.html?Eqn_DeltaE_CIE2000.html
distance(c("red","green","blue"), "red")distance(c("red","green","blue"), "red")
This function provides an expectation for use with the tinytest package,
which compares two colour vectors via all.equal.shade(hexonly=TRUE). It
evaluates TRUE if the vectors have the same length and resolve to the same
hex colour strings.
expect_equal_shades(current, target, ..., info = NA_character_)expect_equal_shades(current, target, ..., info = NA_character_)
current |
The colour vector to test. |
target |
The target values to compare against, in any form valid for
casting to |
... |
Further arguments to |
info |
An optional information string shown in case of failure. |
A "tinytest" object.
This function returns a set of colours interpolating between the specified key colours, equally separated in the specified space.
gradient(shades, steps = NULL, space = NULL)gradient(shades, steps = NULL, space = NULL)
shades |
Two or more colours, in any suitable form (see
|
steps |
An integer giving the number of shades required in the palette.
If |
space |
The colour space to traverse. Defaults to the current space of
|
The key colours may be specified explicitly, or else a built-in colour map
may be used. The maps available are currently those developed for Python's
matplotlib 2.0, namely "magma", "inferno",
"plasma" and "viridis", and certain ColorBrewer palettes,
namely "Blues", "Reds", "YlOrRd" (yellow-orange-red)
and "RdBu" (red-grey-blue, a balanced diverging scale).
A character vector of class "shade" containing the gradient
elements in the specified space, or a palette function.
Jon Clayden [email protected]
http://bids.github.io/colormap/ for the matplotlib colour maps;
http://colorbrewer2.org for the ColorBrewer ones.
gradient(c("red","blue"), 5) gradient(c("red","blue"), 5, space="Lab") gradient("viridis", 5)gradient(c("red","blue"), 5) gradient(c("red","blue"), 5, space="Lab") gradient("viridis", 5)
These functions obtain the value of a colour property, or modify it. They will convert between colour spaces as required, but the RGB representation will be appropriately updated in the result.
saturation(shades, values = NULL) brightness(shades, values = NULL) lightness(shades, values = NULL) chroma(shades, values = NULL) hue(shades, values = NULL) opacity(shades, values = NULL) delta(...) scalefac(...) recycle(...)saturation(shades, values = NULL) brightness(shades, values = NULL) lightness(shades, values = NULL) chroma(shades, values = NULL) hue(shades, values = NULL) opacity(shades, values = NULL) delta(...) scalefac(...) recycle(...)
shades |
One or more colours, in any suitable form (see
|
values |
New values for the property in question, with |
... |
Arguments to replacement functions |
Brightness and lightness differ technically, in the sense that one is absolute and the other is relative. Intuitively, a grey square on white paper is brighter under bright sunlight than in a dark room, but its lightness (relative to the white around it) is constant between conditions. In these functions, brightness is "value" in HSV space and is between 0 and 1, while lightness is defined in Lab space and is between 0 and 100. Saturation and chroma are also related. Hue is defined in HSV space, with red at 0º (and 360º), which is generally the most familiar parameterisation.
Current colour property values, or new colours of class
"shade". If shades is a function, the result will be a new
function that wraps the old one and modifies its return value accordingly.
The colour property functions are vectorised over both of their
arguments, such that the dimensions of the result will be
c(length(values),dim(shades)). However, the recycle function
can be used to suppress the usual dimensional expansion, and instead
follow R's standard recycling rule.
Jon Clayden [email protected]
saturation(c("papayawhip","lavenderblush","olivedrab")) saturation("papayawhip", 0.7) saturation("papayawhip", delta(0.2)) saturation("papayawhip", scalefac(1.5)) saturation(c("red","green"), c(0.4,0.6)) saturation(c("red","green"), recycle(0.4,0.6))saturation(c("papayawhip","lavenderblush","olivedrab")) saturation("papayawhip", 0.7) saturation("papayawhip", delta(0.2)) saturation("papayawhip", scalefac(1.5)) saturation(c("red","green"), c(0.4,0.6)) saturation(c("red","green"), recycle(0.4,0.6))
Objects of class "shade" are simply standard R character vectors
representing one or more 8-bit (s)RGB colours in CSS-like hex format, but
with extra attributes giving the current colour space and coordinates.
shade(x, ...) ## S3 method for class 'shade' shade(x, ...) ## S3 method for class 'color' shade(x, ...) ## S3 method for class 'matrix' shade(x, space = "sRGB", alpha = NULL, ...) ## S3 method for class 'character' shade(x, ...) ## Default S3 method: shade(x, ...) ## S3 method for class 'shade' print(x, ...) ## S3 method for class 'shade' x[i] ## S3 replacement method for class 'shade' x[i] <- value ## S3 method for class 'shade' c(...) ## S3 method for class 'shade' rep(x, ...) ## S3 method for class 'shade' rev(x) ## S3 method for class 'shade' x == y ## S3 method for class 'shade' x != y ## S3 method for class 'shade' all.equal(target, current, hexonly = FALSE, ...)shade(x, ...) ## S3 method for class 'shade' shade(x, ...) ## S3 method for class 'color' shade(x, ...) ## S3 method for class 'matrix' shade(x, space = "sRGB", alpha = NULL, ...) ## S3 method for class 'character' shade(x, ...) ## Default S3 method: shade(x, ...) ## S3 method for class 'shade' print(x, ...) ## S3 method for class 'shade' x[i] ## S3 replacement method for class 'shade' x[i] <- value ## S3 method for class 'shade' c(...) ## S3 method for class 'shade' rep(x, ...) ## S3 method for class 'shade' rev(x) ## S3 method for class 'shade' x == y ## S3 method for class 'shade' x != y ## S3 method for class 'shade' all.equal(target, current, hexonly = FALSE, ...)
x, y
|
R objects, or |
... |
Additional parameters to methods. For |
space |
For a matrix, the space in which coordinates are being provided. |
alpha |
For a matrix, an associated vector of opacity values between 0 and 1, if required. |
i |
An index vector. |
value |
A vector of replacement colours. |
target, current
|
Shade vectors to compare. |
hexonly |
If |
Comparison between "shade" objects x and y is achieved
by converting y (the second argument) into the colour space of
x and then comparing coordinates, after any clipping.
A character vector of class "shade", with additional
attributes as follows.
space |
A string naming a color space. |
coords |
A matrix giving colour coordinates in the relevant space, one colour per row. |
When concatenating, shades that are all from the same space will remain in that space, but shades from different spaces will be warped to "XYZ" space.
Jon Clayden [email protected]
s <- shade(c("red", "green", "blue")) s[1] s[1] <- "pink"s <- shade(c("red", "green", "blue")) s[1] s[1] <- "pink"
This function retrieves the colour space in which its argument is currently defined.
space(x, ...)space(x, ...)
x |
An R object. |
... |
Additional arguments to methods. |
A string naming a colour space.
Jon Clayden [email protected]
space("red")space("red")
This function provides a simple visualisation of a colour series as a series of boxes against the specified background colour. If the input has more than one dimension then the boxes will be arranged in a grid (flattening further dimensions after the second).
swatch(x, bg = "white", ...)swatch(x, bg = "white", ...)
x |
One or more colours, in any suitable form (see
|
bg |
A background colour. |
... |
Additional arguments (currently unused). |
Jon Clayden [email protected]
swatch(c("red", "green", "blue"))swatch(c("red", "green", "blue"))
This function shifts the current colour space of its arguments to the
specified space, returning a new object of class "shade".
warp(x, space)warp(x, space)
x |
An R object which can be coerced to class |
space |
A string naming the new space. |
Valid names for spaces are currently those supported by the
convertColor function, namely "sRGB", "Apple RGB", "CIE
RGB", "XYZ", "Lab" and "Luv"; plus "RGB" (which is treated as an
alias for "sRGB"), "HSV", "LCh" and "LMS". Case is not significant.
A new object of class "shade".
LMS space, used for chromatic adaptation and simulating colour blindness, is not uniquely defined. Here we use the (linearised) Bradford transform, obtained by Lam (1985) and used widely in ICC colour profiles and elsewhere, to transform to and from CIE XYZ space.
R uses the D65 standard illuminant as the reference white for the "Lab" and "Luv" spaces.
Jon Clayden [email protected]
Lam, K.M. (1985). Metamerism and colour constancy. PhD thesis, University of Bradford.
warp("red", "HSV")warp("red", "HSV")