# colourmap

##### Colour Lookup Tables

Create a colour map (colour lookup table).

##### Usage

`colourmap(col, …, range=NULL, breaks=NULL, inputs=NULL, gamma=1)`

##### Arguments

- col
Vector of values specifying colours

- …
Ignored.

- range
Interval to be mapped. A numeric vector of length 2, specifying the endpoints of the range of values to be mapped. Incompatible with

`breaks`

or`inputs`

.- inputs
Values to which the colours are associated. A factor or vector of the same length as

`col`

. Incompatible with`breaks`

or`range`

.- breaks
Breakpoints for the colour map. A numeric vector of length equal to

`length(col)+1`

. Incompatible with`range`

or`inputs`

.- gamma
Exponent for the gamma correction, when

`range`

is given. A single positive number. See Details.

##### Details

A colour map is a mechanism for associating colours with data. It can be regarded as a function, mapping data to colours.

The command `colourmap`

creates an object representing
a colour map, which can then be used to control the plot commands
in the spatstat package. It can also be used to compute the
colour assigned to any data value.

The argument `col`

specifies the colours to which
data values will be mapped. It should be a vector
whose entries can be interpreted as colours by the standard
R graphics system. The entries can be string names of colours
like `"red"`

, or integers that refer to
colours in the standard palette, or strings containing
six-letter hexadecimal codes like `"#F0A0FF"`

.

Exactly one of the arguments `range`

, `inputs`

or `breaks`

must be specified by name.

If

`inputs`

is given, then it should be a vector or factor, of the same length as`col`

. The entries of`inputs`

can be any atomic type (e.g. numeric, logical, character, complex) or factor values. The resulting colour map associates the value`inputs[i]`

with the colour`col[i]`

. The argument`col`

should have the same length as`inputs`

.If

`range`

is given, then it determines the interval of the real number line that will be mapped. It should be a numeric vector of length 2. The interval will be divided evenly into bands, each of which is assigned one of the colours in`col`

. (If`gamma`

is given, then the bands are equally spaced on a scale where the original values are raised to the power`gamma`

.)If

`breaks`

is given, then it determines the precise intervals of the real number line which are mapped to each colour. It should be a numeric vector, of length at least 2, with entries that are in increasing order. Infinite values are allowed. Any number in the range between`breaks[i]`

and`breaks[i+1]`

will be mapped to the colour`col[i]`

. The argument`col`

should have length equal to`length(breaks) - 1`

.

It is also permissible for `col`

to be a single colour value,
representing a trivial colour map in which all data values are mapped to
the same colour.

The result is an object of class `"colourmap"`

.
There are `print`

and `plot`

methods for this class.
Some plot commands in the spatstat package accept an object
of this class as a specification of the colour map.

The result is also a function `f`

which can be used to compute
the colour assigned to any data value.
That is, `f(x)`

returns the character value of the colour assigned
to `x`

. This also works for vectors of data values.

##### Value

A function, which is also an object of class `"colourmap"`

.

##### See Also

The plot method `plot.colourmap`

.

See the R help file on
`colours`

for information about the colours
that R recognises, and how to manipulate them.

To make a smooth transition between colours, see
`interp.colourmap`

.
To alter individual colour values, see
`tweak.colourmap`

.
To extract or replace all colour values, see
`colouroutputs`

.

See `colourtools`

for more tools to manipulate colour values.

See `lut`

for lookup tables.

##### Examples

```
# NOT RUN {
# colour map for real numbers, using breakpoints
cr <- colourmap(c("red", "blue", "green"), breaks=c(0,5,10,15))
cr
cr(3.2)
cr(c(3,5,7))
# a large colour map
co <- colourmap(rainbow(100), range=c(-1,1))
co(0.2)
# colour map for discrete set of values
ct <- colourmap(c("red", "green"), inputs=c(FALSE, TRUE))
ct(TRUE)
# }
```

*Documentation reproduced from package spatstat, version 1.63-3, License: GPL (>= 2)*