saturation {shades}

Query or change colour properties

Description

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.

Usage

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(...)

Arguments

shades

One or more colours, in any suitable form (see shade), or a palette function or scale.

values

New values for the property in question, with NA as a pass-through value that will leave the property as-is. If NULL, the current value(s) will be returned. May also be a function computing new values from old ones, such as delta, which adds its argument, or scalefac, which multiplies it.

...

Arguments to replacement functions delta, scalefac and recycle, which will be concatenated.

Details

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.

Value

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.

Note

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.

Author(s)

Jon Clayden <[e-mail]>

Examples

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))