index.colours: Quantisation of colours and indexing a grDevices raster image
In AmigaFFH: Commodore Amiga File Format Handler

index.colours

R Documentation

Quantisation of colours and indexing a grDevices raster image

Description

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

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.

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.

Author(s)

Pepijn de Vries

Examples

## Not run: 
## 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)

## End(Not run)

AmigaFFH documentation built on June 22, 2024, 11:03 a.m.