sparseImage: Sparse images

In imply: Efficiently Apply Functions to Images

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.

Usage

sparseImage(
  mask,
  values,
  dim,
  spatial = NULL,
  voxelSize = NULL,
  worldTransform = NULL,
  spaceUnit = NULL,
  timeUnit = NULL,
  template = NULL
)

isSparseImage(x)

asSparse(x, ...)

maskedMatrix(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, spatial, voxelSize, worldTransform, spaceUnit, timeUnit	Image geometry, as for denseImage().
template	An image to take unspecified geometry from.
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 coordinate list, the other common representation, would store three or four indices alongside every value, and may cost more memory than saves at typical densities.

A location holding NA is kept, since NA is not zero. Packing an image therefore loses nothing.

Value

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

imply documentation built on Sept. 15, 2026, 5:09 p.m.