geometry: Image geometry

In imply: Efficiently Apply Functions to Images

Image geometry

Description

Accessors for the geometry of an image: the number of spatial dimensions, the voxel size and the placement of the image in world space.

Usage

isImage(x)

spatial(x)

voxelSize(x)

voxelSize(x) <- value

worldTransform(x)

worldTransform(x) <- value

toVoxel(points, x, type = "world", round = "none", bounds = NULL)

fromVoxel(points, x, type = "world")

Arguments

x	An image, or for worldTransform either an image or a 4x4 matrix.
value	A replacement value.
points	A matrix of points, one per row and three columns. Where type is "voxel" (the default convention for fromVoxel()'s input and toVoxel()'s output), these are one-based, as for x[i, j, k].
type	The coordinate convention of points: "voxel" (one-based), "scaled" (millimetres from the one-based origin, ignoring rotation) or "world" (fully transformed).
round	Rounding strategy: "none", "conventional" for nearest neighbour, or "probabilistic" for a stochastic nearest neighbour with probability proportional to proximity.
bounds	Optional image extents, used only by probabilistic rounding to avoid selecting a location beyond the end of the image.

Details

These are deliberately free of any dependency on a file format, and of any assumption that geometry is anatomical: an image with no meaningful spatial interpretation is free to leave it at the identity default and never think about it again.

Voxel size and world placement are stored, and can be set, independently of one another, unlike a NIfTI xform, which bakes voxel size into the same matrix that carries rotation and translation and so has to be kept in sync by hand. Here, ⁠voxelSize<-⁠ never touches rotation or translation, and the stored placement is always a rigid transform (rotation or reflection plus translation; no scale and no shear) so that the two cannot drift out of agreement.

worldTransform() composes the two into the single 4x4 affine that other packages expect. Setting it back decomposes the matrix into rotation and scale; a matrix that doesn't decompose that way (i.e. one with genuine shear) is rejected rather than silently mangled. In practice a sheared NIfTI sform usually means the field is being used to carry an affine registration or normalisation result (to Talairach or MNI space, say) rather than to describe voxel storage geometry, which is a different kind of information than this package models.

toVoxel() and fromVoxel() use one-based voxel coordinates, matching x[i, j, k] indexing. The affine itself, and the rest of the package's C++ API, is zero-based throughout.

Value

isImage() returns a Boolean value indicating whether its argument is one of the package's image types. spatial() returns the index of the last spatial dimension. voxelSize() returns a vector of sizes in each spatial dimension. worldTransform() returns a numeric affine transform matrix. toVoxel() and fromVoxel() return matrices of transformed points, one per row. The assignment functions are called for their side-effects.

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