Quantisation of colours and indexing a grDevices raster image

Converts an image represented by a grDevices raster object into a matrix containing numeric indices of a quantised colour palette.

Usage

index.colours(
  x,
  length.out = 8,
  palette = NULL,
  background = "#FFFFFF",
  dither = c("none", "floyd-steinberg", "JJN", "stucki", "atkinson", "burkse", "sierra",
    "two-row-sierra", "sierra-lite"),
  colour.depth = c("12 bit", "24 bit"),
  ...
)

Arguments

x

A raster object (grDevices::as.raster()), or a matrix containing character strings representing colours. x can also be a list of such matrices or rasters. All elements of this list should have identical dimensions. An overall palette will be generated for elements in the list.

length.out

A numeric value indicating the number of desired colours in the indexed palette.

It can also be a character string indicating which special Amiga display mode should be used when indexing colours. ‘HAM6’ and ‘HAM8’ are supported. See rasterToBitmap() for more details on these special modes.

palette

A vector of no more than length.out colours, to be used for the bitmap image. When missing or set to NULL, a palette will be generated based on the provided colours in raster x. In that case, stats::kmeans() is used on the hue, saturation, brightness and alpha values of the colours in x for clustering the colours. The cluster centres will be used as palette colours.

background

On the Amiga, indexed images could not be semi-transparent. Only a single colour could be designated as being fully transparent. The ``background`' argument should contain a background colour with which semi-transparent colours should be mixed, before colour quantisation. It is white by default.

dither

Dither the output image using the algorithm specified here. See the usage section for possible options. By default no dithering ("none") is applied. See dither() for more details.

colour.depth

A character string indicating the colour depth to be used. Can be either "12 bit" (default, standard on an Amiga with original chipset), or "24 bit".

This argument is overruled when length.out is set to “HAM6” or “HAM8”. In that case the colour depth linked to that special mode is used (12 bit for HAM6, 24 bit for HAM8).

...

Arguments that are passed onto stats::kmeans() (see palette argument).

Value

Returns a matrix with the same dimensions as x containing numeric index values. The corresponding palette is returned as attribute, as well as the index value for the fully transparent colour in the palette. When x is a list a list of matrices is returned.

Details

Determines the optimal limited palette by clustering colours in an image with stats::kmeans(). The result of the optimisation routine will depend on the randomly chosen cluster centres by this algorithm. This means that the result may slightly differ for each call to this function. If you want reproducible results, you may want to reset the random seed (set.seed()) before each call to this function.

Author

Pepijn de Vries

Examples

if (FALSE) {
## first: Let's make a raster out of the 'volcano' data, which we can use in the example:
volcano.raster <- as.raster(t(matrix(terrain.colors(1 + diff(range(volcano)))[volcano -
  min(volcano) + 1], nrow(volcano))))

## This will create an image of the original raster using an indexed palette:
volcano.index <- index.colours(volcano.raster)

## The index values can be converted back into colours, using the palette:
volcano.index <- as.raster(apply(volcano.index, 2,
                                 function(x) attributes(volcano.index)$palette[x]))

## Create an indexed image using dithering
volcano.dith <- index.colours(volcano.raster, dither = "floyd-steinberg")
volcano.dith <- as.raster(apply(volcano.dith, 2,
                                function(x) attributes(volcano.dith)$palette[x]))

## plot the images side by side for comparison
par(mfcol = c(1, 3))
plot(volcano.raster, interpolate = F)
plot(volcano.index, interpolate = F)
plot(volcano.dith, interpolate = F)
}