Write a bitmap image in PNG format

Description

Usage

Arguments

image

image represented by a real matrix or array with values
in the range of 0 to 1. Values outside this range will be
clipped. The object must be either two-dimensional (grayscale
matrix) or three dimensional array (third dimension specifying the
plane) and must have either one (grayscale), two (grayscale +
alpha), three (RGB) or four (RGB + alpha) planes. (For alternative
image specifications see details)

target

Either name of the file to write, a binary connection or
a raw vector (raw() - the default - is good enough)
indicating that the output should be a raw vector.

dpi

optional, if set, must be a numeric vector of length 1 or 2
specifying the resolution of the image in DPI (dots per inch) for x
and y (in that order) - it is recycled to length 2.

asp

optional, if set, must be a numeric scalar specifying the
aspect ratio (x / y). dpi and asp are mutually
exclusive, speciyfing both is an error.

text

optional, named character vector of entries that will be
saved in the text chunk of the PNG. Names are used as keys. Note
that the "R.metadata" key is reserved for internal use - see
below

metadata

optional, an R object that will be serialized
into the "R.metadata" text key

Details

writePNG takes an image as input and compresses it into PNG
format. The image input is usually a matrix (for grayscale images -
dimensions are width, height) or an array (for color and alpha
images - dimensions are width, height, planes) of reals. The planes
are interpreted in the sequence red, green, blue, alpha.

Alternative representation of an image is of nativeRaster class
which is an integer matrix with each entry representing one pixel in
binary encoded RGBA format (as used internally by R). It can be
obtained from readPNG using native = TRUE.

Finally, writePNG also supports raw array containing the RGBA
image as bytes. The dimensions of the raw array have to be planes,
width, height (because the storage is interleaved). Currently only 4
planes (RGBA) are supported and the processing is equivalent to that
of a native raster.

The result is either stored in a file (if target is a file
name), in a raw vector (if target is a raw vector) or sent to a
binary connection.

If either dpi or asp is set, the sPHy chunk is
generated based on that information. Note that not all image viewers
interpret this setting, and even fewer support non-square pixels.

Value

Either NULL if the target is a file or a raw vector containing
the compressed PNG image if the target was a raw vector.

Note

Currently writePNG only produces 8-bit, deflate-compressed,
non-quantized, non-interlaced images. Note in particular that
readPNG can read 16-bit channels but storing them
back using writePNG will strip the 8 LSB (irrelevant for
display purposes but possibly relevant for use of PNG in
signal-processing if the input is truly 16-bit wide).