Calculate colour map

Description

Map values to colours, for use in palettes and plots. There are many ways to use this function, and some study of the arguments should prove fruitful in cases that extend far beyond the examples.

Usage

colormap(z = NULL, zlim, zclip = FALSE, breaks, col = oce.colorsJet, name,
  x0, x1, col0, col1, blend = 0, missingColor,
  debug = getOption("oceDebug"))

Arguments

Details

This is a multi-purpose function that generally links (“maps”) numerical values to colours. The return value can specify colours for points on a graph, or breaks and col vectors that are suitable for use by drawPalette, imagep or image.

There are three ways of specifying colour schemes, and colormap works by checking for each condition in turn.

• Case A. Supply z but nothing else. In this case, breaks will be set to pretty(z, 10) and things are otherwise as in case B.

• Case B. Supply breaks. In this case, breaks and col are used together to specify a colour scheme. If col is a function, then it is expected to take a single numerical argument that specifies the number of colours, and this number will be set to length(breaks)-1. Otherwise, col may be a vector of colours, and its length must be one less than the number of breaks. (NB. if breaks is given, then all other arguments except col and missingColor are ignored.) The figure below explains the (breaks, col) method of specifying a colour mapping. Note that there must be one more break than colour. This is the method used by e.g. image.

• Case C. Do not supply breaks, but supply name instead. This name may be the name of a pre-defined colour palette ("gmt_relief", "gmt_ocean", "gmt_globe" or "gmt_gebco"), or it may be the name of a file (including a URL) containing a colour map in the GMT format (see “References”). (NB. if name is given, then all other arguments except z and missingColor are ignored.)

• Case D. Do not supply either breaks or name, but instead supply each of x0, x1, col0, and col1. These values are specify a value-colour mapping that is similar to that used for GMT colour maps. The method works by using seq to interpolate between the elements of the x0 vector. The same is done for x1. Similarly, colorRampPalette is used to interpolate between the colours in the col0 vector, and the same is done for col1. The figure above explains the (x0, x1, col0, col1) method of specifying a colour mapping. Note that the each of the items has the same length. The case of blend=0, which has colour col0[i] between x0[i] and x1[i], is illustrated below.

Value

A list containing the following (not necessarily in this order)

• zcol, a vector of colours for z, if z was provided, otherwise "black"

• zlim, a two-element vector suitable as the argument of the same name supplied to image or imagep

• breaks and col, vectors of breakpoints and colours, suitable as the same-named arguments to image or imagep

• zclip the provided value of zclip.

• x0 and x1, numerical vectors of the sides of colour intervals, and col0 and col1, vectors of corresponding colours. The meaning is the same as on input. The purpose of returning these four vectors is to permit users to alter colour mapping, as in example 3 in “Examples”.

• missingColor, a colour that could be used to specify missing values, e.g. as the same-named argument to imagep. If this is supplied as an argument, its value is repeated in the return value. Otherwise, its value is either "gray" or, in the case of name being given, the value in the GMT colour map specification.

Author(s)

Dan Kelley

References

Information on GMT software is given at http://gmt.soest.hawaii.edu (link worked for years but failed 2015-12-12). Diagrams showing the GMT colour schemes are at http://www.geos.ed.ac.uk/it/howto/GMT/CPT/palettes.html (link worked for years but failed 2015-12-08), and numerical specifications for some colour maps are at http://www.beamreach.org/maps/gmt/share/cpt, http://soliton.vm.bytemark.co.uk/pub/cpt-city, and other sources.

See Also

Other things related to colors: colors, oce.colorsGebco, oce.colorsTwo

Examples

library(oce)
## Example 1. colour scheme for points on xy plot
x <- seq(0, 1, length.out=40)
y <- sin(2 * pi * x)
par(mar=c(3, 3, 1, 1))
mar <- par('mar') # prevent margin creep by drawPalette()
## First, default breaks
c <- colormap(y)
drawPalette(c$zlim, col=c$col, breaks=c$breaks)
plot(x, y, bg=c$zcol, pch=21, cex=1)
grid()
par(mar=mar)
## Second, 100 breaks, yielding a smoother palette
c <- colormap(y, breaks=100)
drawPalette(c$zlim, col=c$col, breaks=c$breaks)
plot(x, y, bg=c$zcol, pch=21, cex=1)
grid()
par(mar=mar)

## Not run: 
## Example 2. topographic image with a standard colour scheme
par(mfrow=c(1,1))
data(topoWorld)
cm <- colormap(name="gmt_globe")
imagep(topoWorld, breaks=cm$breaks, col=cm$col)

## Example 3. topographic image with modified colours,
## black for depths below 4km.
cm <- colormap(name="gmt_globe")
deep <- cm$x0 < -4000
cm$col0[deep] <- 'black'
cm$col1[deep] <- 'black'
cm <- colormap(x0=cm$x0, x1=cm$x1, col0=cm$col0, col1=cm$col1)
imagep(topoWorld, breaks=cm$breaks, col=cm$col)

## Example 4. image of world topography with water colorized 
## smoothly from violet at 8km depth to blue
## at 4km depth, then blending in 0.5km increments
## to white at the coast, with tan for land.
cm <- colormap(x0=c(-8000, -4000,   0,  100),
               x1=c(-4000,     0, 100, 5000),
               col0=c("violet","blue","white","tan"),
               col1=c("blue","white","tan","yelloe"),
               blend=c(100, 8, 0))
lon <- topoWorld[['longitude']]
lat <- topoWorld[['latitude']]
z <- topoWorld[['z']]
imagep(lon, lat, z, breaks=cm$breaks, col=cm$col)
contour(lon, lat, z, levels=0, add=TRUE)
message("colormap() example 4 is broken")

## Example 5. visualize GMT style colour map
cm <- colormap(name="gmt_globe", debug=4)
plot(seq_along(cm$x0), cm$x0, pch=21, bg=cm$col0)
grid()
points(seq_along(cm$x1), cm$x1, pch=21, bg=cm$col1)

## End(Not run)