geometry: Image geometry

geometryR Documentation

Image geometry

Description

An image geometry describes the spatial grid an image is sampled on, without any of its data: the extent of the grid, the voxel size, the placement of the grid in world space and the unit of measurement. Every image holds one, and any of the functions here may be given either an image or a bare geometry. A bare geometry is useful in its own right, to describe a space that no image has been created in yet, such as the target grid of a resampling.

Usage

imageGeometry(
  dims = integer(0),
  voxelSize = NULL,
  worldTransform = NULL,
  unit = NULL
)

isImageGeometry(x)

isImage(x)

geometry(x)

geometry(x) <- value

spatial(x)

voxelSize(x)

voxelSize(x) <- value

worldTransform(x)

worldTransform(x) <- value

centre(x)

center(x)

extent(x)

sameGeometry(x, y, tolerance = sqrt(.Machine$double.eps))

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

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

Arguments

dims

The extent of the grid, one per spatial dimension.

voxelSize

Voxel size, one per spatial dimension.

worldTransform

A 4x4 affine transform mapping (zero-based) voxel to world coordinates, from which the voxel size is also taken unless it is given separately.

unit

The unit of measurement of voxel size and world coordinates.

x, y

Images or geometries. Anything else with a dimension attribute is treated as having unit voxels at the origin, with the leading three dimensions (or all of them, if fewer) spatial. worldTransform() also accepts a bare 4x4 matrix, which is validated and returned.

value

A replacement value.

tolerance

Numerical tolerance for comparing world transforms.

points

A matrix of points, one per row and one to three columns. Missing columns are taken to be zero. 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. The stored placement is always a rigid transform: rotation or reflection plus translation; no scale and no shear. worldTransform() composes the two into the single 4x4 affine that some 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.

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

imageGeometry() and geometry() return an object of S7 class imageGeometry, with properties dims, voxelSize, orientation (the rigid part of the world transform) and unit. isImage() and isImageGeometry() return a Boolean value indicating whether their argument is one of the package's image types, or a geometry, respectively. spatial() returns the number of spatial dimensions. voxelSize() returns a vector of sizes in each spatial dimension. worldTransform() returns a numeric affine transform matrix. centre() returns the world coordinates of the centre of the grid, always as three values; center() is an alias. extent() returns the physical size of the grid along each spatial axis. sameGeometry() returns a Boolean value, which is TRUE if the two grids are the same size and are placed identically in world space, up to tolerance; units are compared only if both are known. toVoxel() and fromVoxel() return matrices of transformed points, one per row. Voxel coordinates have as many columns as points, and world or scaled coordinates always have three. The assignment functions are called for their side-effects.


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