R: Convert and Compare Colours in Different Formats

colourtools {spatstat} | R Documentation

## Convert and Compare Colours in Different Formats

### Description

These functions convert between different formats for specifying a colour in R, determine whether colours are equivalent, and convert colour to greyscale.

### Usage

    col2hex(x)
    rgb2hex(v, maxColorValue=255)
    rgb2hsva(red, green=NULL, blue=NULL, alpha=NULL, maxColorValue=255)
    paletteindex(x)
    samecolour(x,y)
    complementarycolour(x)
    interp.colours(x, length.out=512)
    is.colour(x)
    to.grey(x, weights=c(0.299, 0.587, 0.114), transparent=FALSE)
    is.grey(x)
    to.opaque(x)
    to.transparent(x, fraction)
    to.saturated(x, s=1)

### Arguments

`x,y` | Any valid specification for a colour or sequence of colours accepted by `col2rgb`.
`v` | A numeric vector of length 3, giving the RGB values of a single colour, or a 3-column matrix giving the RGB values of several colours. Alternatively a vector of length 4 or a matrix with 4 columns, giving the RGB and alpha (transparency) values.
`red,green,blue,alpha` | Arguments acceptable to `rgb` determining the red, green, blue channels and optionally the alpha (transparency) channel. Note that `red` can also be a matrix with 3 rows giving the RGB values, or a matrix with 4 rows giving RGB and alpha values.
`maxColorValue` | Number giving the maximum possible value for the entries in `v` or `red,green,blue,alpha`.
`weights` | Numeric vector of length 3 giving relative weights for the red, green, and blue channels respectively.
`transparent` | Logical value indicating whether transparent colours should be converted to transparent grey values (`transparent=TRUE`) or converted to opaque grey values (`transparent=FALSE`, the default).
`fraction` | Transparency fraction. Numerical value or vector of values between 0 and 1, giving the opaqueness of a colour. A fully opaque colour has `fraction=1`.
`length.out` | Integer. Length of desired sequence.
`s` | Saturation value (between 0 and 1).

### Details

`is.colour(x)` can be applied to any kind of data `x` and returns `TRUE` if `x` can be interpreted as a colour or colours. The remaining functions expect data that can be interpreted as colours.

`col2hex` converts colours specified in any format into their hexadecimal character codes.

`rgb2hex` converts RGB colour values into their hexadecimal character codes. It is a very minor extension to `rgb`. Arguments to `rgb2hex` should be similar to arguments to `rgb`.

`rgb2hsva` converts RGB colour values into HSV colour values including the alpha (transparency) channel. It is an extension of `rgb2hsv`. Arguments to `rgb2hsva` should be similar to arguments to `rgb2hsv`.

`paletteindex` checks whether the colour or colours specified by `x` are available in the default palette returned by `palette()`. If so, it returns the index or indices of the colours in the palette. If not, it returns `NA`.

`samecolour` decides whether two colours `x` and `y` are equivalent.

`is.grey` determines whether each entry of `x` is a greyscale colour, and returns a logical vector.

`to.grey` converts the colour data in `x` to greyscale colours. Alternatively `x` can be an object of class `"colourmap"` and `to.grey(x)` is the modified colour map.

`to.opaque` converts the colours in `x` to opaque (non-transparent) colours, and `to.transparent` converts them to transparent colours with a specified transparency value. Note that `to.transparent(x,1)` is equivalent to `to.opaque(x)`.

For `to.grey`, `to.opaque` and `to.transparent`, if all the data in `x` specifies colours from the standard palette, and if the result would be equivalent to `x`, then the result is identical to `x`.

`to.saturated` converts each colour in `x` to its fully-saturated equivalent. For example, pink is mapped to red. Shades of grey are converted to black; white is unchanged.

`complementarycolour` replaces each colour by its complementary colour in RGB space (the colour obtained by replacing RGB values `(r, g, b)` by `(255-r, 255-g, 255-b)`). The transparency value is not changed. Alternatively `x` can be an object of class `"colourmap"` and `complementarycolour(x)` is the modified colour map.

`interp.colours` interpolates between each successive pair of colours in a sequence of colours, to generate a more finely-spaced sequence. It uses linear interpolation in HSV space (with hue represented as a two-dimensional unit vector).

### Value

For `col2hex` and `rgb2hex` a character vector containing hexadecimal colour codes.

For `to.grey`, `to.opaque` and `to.transparent`, either a character vector containing hexadecimal colour codes, or a value identical to the input `x`.

For `rgb2hsva`, a matrix with 3 or 4 rows containing HSV colour values.

For `paletteindex`, an integer vector, possibly containing `NA` values.

For `samecolour` and `is.grey`, a logical value or logical vector.

### Warning

`paletteindex("green")` returns `NA` because the green colour in the default palette is called `"green3"`.

### Author(s)

Adrian Baddeley Adrian.Baddeley@curtin.edu.au

and Rolf Turner r.turner@auckland.ac.nz

### See Also

`col2rgb`, `rgb2hsv`, `palette`.

See also the class of colour map objects in the spatstat package: `colourmap`, `interp.colourmap`, `tweak.colourmap`.

### Examples

      samecolour("grey", "gray")
      paletteindex("grey")
      col2hex("orange")
      to.grey("orange")
      to.saturated("orange")
      complementarycolour("orange")
      is.grey("lightgrey")
      is.grey(8)
      to.transparent("orange", 0.5)
      to.opaque("red")
      interp.colours(c("orange", "red", "violet"), 5)

[Package spatstat version 1.63-3 Index]