readImageData: Reading and writing image data

readImageDataR Documentation

Reading and writing image data

Description

readImageData() reads the values of an image from a connection, as described by a storageDescriptor(), and returns an image. writeImageData() writes them. Neither knows anything about file formats, which are the business of packages built on this one: a format package parses any header or metadata, builds a descriptor and a geometry, and calls these to handle the data.

Usage

readImageData(
  con,
  descriptor,
  dims,
  geometry = NULL,
  as = c("auto", "dense", "sparse", "packed"),
  volumes = NULL,
  mask = NULL
)

writeImageData(image, con, descriptor)

Arguments

con

A connection, or the path to a file. A connection must be open for binary reading or writing. If its position can be queried, it is moved forwards to the descriptor's offset, or when writing, padded with zeros up to it; otherwise it is taken to be already there. A path is opened, read or written from the start, and closed.

descriptor

A storageDescriptor().

dims

The full dimensions of the image, in its own axis order.

geometry

An imageGeometry, or an image to take one from, for the spatial grid. By default the leading three dimensions (or all of them, if fewer) are spatial, with unit voxels at the origin.

as

The representation wanted: "auto", "dense", "sparse" or "packed".

volumes

Optionally, which volumes to read, as one-based indices into the values held at each location, taken together. The result then has the spatial dimensions followed by one dimension over the volumes read, in the order given. Only data stored a volume at a time can be read this way.

mask

Optionally, the spatial locations to keep, in any form asMaskVector() accepts. Only meaningful for a sparse result.

image

An image or array to write.

Details

Bytes are read through R connections, so compressed streams need nothing special: gzfile() reads gzipped and plain files alike. They are read in chunks, so the only large allocation is the result itself. A gzipped stream cannot be read backwards, so volumes are always read in the order they are stored, whatever order they are asked for in.

The image comes back dense, packed or sparse, according to the as argument. The default, "auto", gives a sparse image if a mask is given; otherwise a packed image if the stored type is one a packedImage can hold, keeping the file's narrow representation and scaling; and otherwise a dense image. The class returned therefore depends on the data, so code that relies on a specific class should ask for it.

A packed image keeps the stream's order, with the layout recording how its axes map onto it, so no data is moved; see reorient(). A dense image is always in its own axis order, so a stream in any other order is rearranged as it is read.

A sparse image keeps exactly the locations selected by mask, if one is given, and otherwise those where any value is non-zero. Only volume-ordered data can be read straight into sparse form, without the dense array ever existing; other layouts, and bit data, are read densely first.

Value

readImageData() returns an image. writeImageData() returns, invisibly, the descriptor as used, with any scaling it chose filled in, which is what a format package needs to write its header.

Examples

image <- denseImage(array(1:24, c(2, 3, 4)))
descriptor <- storageDescriptor("int16", endian = "big")
file <- tempfile()
writeImageData(image, file, descriptor)
readImageData(file, descriptor, dim(image))

imply documentation built on Nov. 20, 2026, 5:12 p.m.