sparseImage: Sparse images

sparseImageR Documentation

Sparse images

Description

A sparse image stores only those spatial locations that hold data. Sparsity is over locations, not over individual values: a location is either present, in which case the whole vector of values held there is stored, or absent, in which case every one of them is implicitly zero. That generally matches the intent, and it keeps the stored values contiguous.

storedValues() returns the values exactly as stored, never copying, along with the location of each column as a linear index into the image's own spatial grid. The two differ only for a reoriented image.

Usage

sparseImage(
  mask,
  values,
  dim,
  spatial = NULL,
  voxelSize = NULL,
  worldTransform = NULL,
  unit = NULL,
  geometry = NULL,
  layout = NULL
)

isSparseImage(x)

asSparse(x, ...)

maskedMatrix(x)

storedValues(x)

sparseness(x)

mask(x)

Arguments

mask

A raw vector of one bit per location, or a logical vector.

values

Packed values, in location order.

dim

The full dimensions of the image.

spatial, voxelSize, worldTransform, unit, geometry

Image geometry, as for denseImage().

layout

How the image's axes map onto the stored order of locations, as described for storageLayout(). For a sparse image it may only reorder and reverse the spatial axes among themselves; the values held at each location are always stored in order. The default is the identity.

x

An image or array.

...

Further arguments to sparseImage().

Details

The mask is one bit per location and the values are packed in location order, so finding a value costs a table lookup and a bit count rather than a search. A location holding NA is kept, since NA is not zero.

A sparse image can be indexed and assigned to like an array. Assignment keeps the mask accurate: a location given a non-zero value is added, and one left holding only zeros is dropped. That takes a pass over the stored values each time, which suits occasional edits; to set many values, gather them and assign once, rather than one at a time in a loop. As for an array, values are promoted to a wider replacement type.

Value

An object of S7 class sparseImage representing a sparse image, with properties corresponding to the arguments listed above.


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