Reads an image from a TIFF file/content into a raster array.
Usage
readTIFF(source, native = FALSE, all = FALSE, convert = FALSE,
info = FALSE, indexed = FALSE, as.is = FALSE)
Arguments
source
Either name of the file to read from or a raw vector
representing the TIFF file content.
native
determines the image representation - if FALSE
(the default) then the result is an array, if TRUE then the
result is a native raster representation (suitable for plotting).
all
TIFF files can contain more than one image, if all =
TRUE then all images are returenin a list, otherwsie only the first
image is returned.
convert
first convert the image into 8-bit RGBA samples and then
to an array, see below for details.
info
if set to TRUE then the resulting image(s) will also
contain information from TIFF tags as attributes
indexed
if set to TRUE then indexed images will be
returned in the indexed form, i.e., as a matrix of integer indices
referencing into a color map which is returned in the
"color.map" attribute. This flag cannot be combined with
convert or native and has no effect on images that are
not indexed.
as.is
attempt to return original values without re-scaling
where possible
Details
Most common files decompress into RGB (3 channels), RGBA (4 channels),
Grayscale (1 channel) or GA (2 channels). Note that G and GA images
cannot be directly used in rasterImage unless
native is set to TRUE because rasterImage requires
RGB or RGBA format (nativeRaster is always 8-bit RGBA).
TIFF images can have a wide range of internal representations, but only
the most common in image processing are directly supported (8-bit, 16-bit
integer and 32-bit float samples). Other formats (color maps, sub-8-bit
images, etc.) are only supported via convert=TRUE which uses the
built-in facilities of the TIFF library to convert the image into RGBA
format with 8-bit samples (i.e. total of 32-bit per pixel) and then
store the relevant components from there into real arrays. This is the
same path as used by native=TRUE and so differs only in the
output value. Note that conversion may result in different values than
direct acccess as it is intended mainly for viewing and not computation.
Value
If native is FALSE then an array of the dimensions height
x width x channels. If there is only one channel the result is a
matrix. The values are reals between 0 and 1 (except for 32-bit floating
point sample storage which are unscaled reals, and for indexed and
as.is=TRUE which are integers). If native is
TRUE then an object of the class nativeRaster is
returned instead. The latter cannot be easily computed on but is the
most efficient way to draw using rasterImage.
If all is TRUE then the result is a list of the above with
one or more elements..
Note
Some non-standard formats such as 12-bit TIFFs are partially supported
(there is no standard for packing order for TIFFs beoynd 8-bit so we
assume big-endian packing similar to the default fill order and only
support single channel or indexed).
The as.is=TRUE option is experimental, cannot be used with
native or convert and only works for integer storage
TIFFs.
See Also
rasterImage, writeTIFF
Examples
# read a sample file (R logo)
img <- readTIFF(system.file("img", "Rlogo.tiff", package="tiff"))
# read it also in native format
img.n <- readTIFF(system.file("img", "Rlogo.tiff", package="tiff"), native=TRUE)
# and also in converted
img.c <- readTIFF(system.file("img", "Rlogo.tiff", package="tiff"), convert=TRUE)
# if your R supports it, we'll plot it
if (exists("rasterImage")) { # can plot only in R 2.11.0 and higher
plot(1:2, type='n')
if (names(dev.cur()) == "windows") {
# windows device doesn't support semi-transparency so we'll need
# to flatten the image
transparent <- img[,,4] == 0
img <- as.raster(img[,,1:3])
img[transparent] <- NA
# interpolate must be FALSE on Windows, otherwise R will
# try to interpolate transparency and fail
rasterImage(img, 1.2, 1.27, 1.8, 1.73, interpolate=FALSE)
} else {
# any reasonable device will be fine using alpha
rasterImage(img, 1.2, 1.27, 1.8, 1.73)
rasterImage(img.n, 1.5, 1.5, 1.9, 1.8)
}
}