io: Image I/O

In EBImage: Image processing and analysis toolbox for R

Description

Read images from files and URLs, and write images to files.

Usage

readImage(files, type, all = TRUE, names = sub("\\.[^.]*$", "", basename(files)), ...)
writeImage(x, files, type, quality = 100, bits.per.sample, compression = "none", ...)

Arguments

files	a character vector of file names or URLs.
type	image type (optional). Supported values are: jpeg, png, and tiff. If missing, file format is automatically determined by file name extension.
all	logical: when the file contains more than one image should all frames be read, or only the first one?
names	a character vector used for frame names. Should have the same length as files.
x	an Image object or an array.
bits.per.sample	a numeric scalar specifying the number of bits per sample (only for tiff files). Supported values are 8 and 16.
compression	the desired compression algorithm (only for tiff files). For a list of supported values consult the documentation of the writeTIFF function from the tiff package.
quality	a numeric ranging from 1 to 100 (default) controlling the quality of the JPEG output.
...	arguments passed to the corresponding functions from the jpeg, png, and tiff packages.

Details

readImage loads all images from the files vector and returns them stacked into a single Image object containing an array of doubles ranging from 0 (black) to 1 (white). All images need to be of the same type and have the same dimensions and color mode. If type is missing, the appropriate file format is determined from file name extension. Color mode is determined automatically based on the number of channels. When the function fails to read an image it skips to the next element of the files vector issuing a warning message. Non-local files can be read directly from a valid URL.

writeImage writes images into files specified by files, were the number of files needs to be equal 1 or the number of frames. Given an image containing multiple frames and a single file name either the whole stack is written into a single TIFF file, or each frame is saved to an individual JPEG/PNG file (for files = "image.*" frames are saved into image-X.* files, where X equals the frame number less one; for an image containing n frames this results in file names numbered from 0 to n-1).

When writing JPEG files the compression quality can be specified using quality. Valid values range from 100 (highest quality) to 1 (lowest quality). For TIFF files additional information about the desired number of bits per sample (bits.per.sample) and the compression algorithm (compression) can be provided. For a complete list of supported values please consult the documentation of the tiff package.

Value

readImage returns a new Image object.

writeImage returns an invisible vector of file names.

Note

Image formats have a limited dynamic range (e.g. JPEG: 8 bit, TIFF: 16 bit) and writeImage may cause some loss of accuracy. In specific, writing 16 bit image data to formats other than TIFF will strip the 8 LSB. When writing TIFF files a dynamic range check is performed and an appropriate value of bits.per.sample is set automatically.

Author(s)

Andrzej Oles, [e-mail], 2012

See Also

Image, display, readJPEG/writeJPEG, readPNG/writePNG, readTIFF/writeTIFF

Examples

  ## Read and display an image
  f = system.file("images", "sample-color.png", package="EBImage")
  x = readImage(f)
  display(x)

  ## Read and display a multi-frame TIFF
  y = readImage(system.file("images", "nuclei.tif", package="EBImage"))
  display(y)

  ## Read an image directly from a remote location by specifying its URL
  try({
    im = readImage("http://www-huber.embl.de/EBImage/ExampleImages/berlin.tif")
    display(im, title = "Berlin Impressions")
  })

  ## Convert a PNG file into JPEG
  tempfile = tempfile("", , ".jpeg")
  writeImage(x, tempfile, quality = 85)
  cat("Converted '", f, "' into '", tempfile, "'.\n", sep="")

  ## Save a frame sequence
  files = writeImage(y, tempfile("", , ".jpeg"), quality = 85)
  cat("Files created: ", files, sep="\n")

Example output

Only the first frame of the image stack is displayed.
To display all frames use 'all = TRUE'.
Error in validImage(x) : object must be an array
In addition: Warning message:
In .loadFun(files, ...) :
  URL 'http://www-huber.embl.de/EBImage/ExampleImages/berlin.tif': status was 'Couldn't resolve host name'
Converted '/usr/lib/R/site-library/EBImage/images/sample-color.png' into '/work/tmp/tmp/RtmpTD2lmo/1b305c24b292.jpeg'.
Files created: 
/work/tmp/tmp/RtmpTD2lmo/1b3051a9e77b-0.jpeg
/work/tmp/tmp/RtmpTD2lmo/1b3051a9e77b-1.jpeg
/work/tmp/tmp/RtmpTD2lmo/1b3051a9e77b-2.jpeg
/work/tmp/tmp/RtmpTD2lmo/1b3051a9e77b-3.jpeg

EBImage documentation built on Nov. 8, 2020, 5:41 p.m.