rasterToBitmap: Convert a grDevices 'raster' object into binary bitmap data
In AmigaFFH: Commodore Amiga File Format Handler

rasterToBitmap

R Documentation

Convert a grDevices `raster` object into binary bitmap data

Description

Converts an image represented by a grDevices raster object into binary (Amiga) bitmap data.

Usage

rasterToBitmap(x, depth = 3, interleaved = T, indexing = index.colours)

Arguments

`x`	A raster object created with `as.raster` which needs to be converted into bitmap data. It is also possible to let `x` be a matrix of `character`s, representing colours.
`depth`	The colour depth of the bitmap image. The image will be composed of `2^depth` indexed colours. `depth` can also be a `character` string "HAM6" or "HAM8" representing special Amiga display modes (see details).
`interleaved`	A `logical` value, indicating whether the bitmap needs to be interleaved. An interleaved bitmap image stores each consecutive bitmap layer per horizontal scanline.
`indexing`	A function that accepts two arguments: `x` (a grDevices `raster` object); `length.out`, a numeric value indicating the desired size of the palette (i.e., the number of colours). It should return a matrix with numeric palette indices (ranging from 1 up to the number of colours in the palette). The result should have an attribute named ‘palette’ that contains the colours that correspond with the index numbers. The result should also carry an attribute with the name ‘transparent’, with a single numeric value representing which colour in the palette should be treated as transparent (or `NA` when no transparency is required). By default the function `index.colours` is used. You are free to provide a customised version of this function (see examples).

Details

Images represented by grDevices raster objects are virtually true colour (24 bit colour depth) and an alpha layer (transparency). On the early Amiga's the chipset (in combination with memory restrictions) only allowed images with indexed palettes. The colour depth was 12 bit with the original chipset and the number of colours allowed in a palette also depended on the chipset. This function will allow you to convert a raster object into binary bitmap data with an indexed palette. This means that the image is converted in a lossy way (information will be lost). So don't expect the result to have the same quality as the original image.

With the depth argument, the raster can also be converted to special mode bitmap images. One of these modes is the ‘hold and modify’ (HAM). In this mode two of the bitplanes are reserved as modifier switches. If the this switch equals zero, the remainder of the bitplanes are used as an index for colours in a fixed palette. If the switch equals 1, 2 or 3, the red, green or blue component of the previous is modified, using the number in the remainder of the bitplanes. So it holds the previous colour but modifies one of the colour components (hence the term ‘hold and modify’.) Here only the HAM6 and the HAM8 mode are implemented. HAM6 uses 6 bitplanes and a 12 bit colour depth, HAM8 uses 8 bitplanes and a 24 bit colour depth.

The HAM mode was a special video modes supported by Amiga hardware. Normal mode bitmap images with a 6 bit depth would allow for a palette of 64 (2^6) colours, HAM6 can display 4096 colours with the same bit depth.

In addition to HAM6 and HAM8, sliced HAM (or SHAM) was another HAM variant. Using the coprocessor on the Amiga, it was possible to change the palette at specific scanlines, increasing the number of available colours even further. The SHAM mode is currently not supported by this package.

Value

The bitmap is returned as a vector of logical values. The logical values reflect the bits for each bitplane. The palette used for the bitmap is returned as attribute to the vector. There will also be an attribute called ‘transparent’. This will hold a numeric index corresponding with the colour in the palette that will be treated as transparent. It will be NA when transparency is not used.

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

## convert the raster into binary (logical) bitmap data:
volcano.bm <- rasterToBitmap(volcano.raster)

## The palette for the indexed colours of the generated bitmap is returned as
## attribute. There is no transparency is the image:
attributes(volcano.bm)

## We can also include a custom function for colour quantisation. Let's include
## some dithering:
volcano.dither <- rasterToBitmap(volcano.raster,
                                 indexing = function(x, length.out) {
                                   index.colours(x, length.out,
                                                 dither = "floyd-steinberg")
                                 })

## You can also use a custom indexing function to force a specified palette,
## in this case black and white:
volcano.bw <- rasterToBitmap(volcano.raster,
                             indexing = function(x, length.out) {
                               index.colours(x, length.out,
                                             palette = c("black", "white"),
                                             dither = "floyd-steinberg")
                             })

## Make a bitmap using a special display mode (HAM6):
volcano.HAM <- rasterToBitmap(volcano.raster, "HAM6")

## End(Not run)

AmigaFFH documentation built on Aug. 27, 2023, 9:07 a.m.