worldAxes: World axes and reorientation

worldAxesR Documentation

World axes and reorientation

Description

Every image has an axis order and direction relative to world space. worldAxes() reports it as a signed integer for each spatial axis: which world axis it runs along, one to three, negated if its index increases in the negative direction. So c(-1, 2, 3) describes an image whose first index increases along the negative first world axis, and whose second and third increase along the second and third. The form is the same as a storage layout's, with world axes in place of storage axes.

Usage

worldAxes(x)

reorient(x, to = 1:3)

storageLayout(x)

Arguments

x

An image, or for worldAxes() also a geometry.

to

The world axes wanted, in the same form as worldAxes() returns: a signed integer per axis, naming each world axis at most once. The default puts every axis along its positive world axis, in order.

Details

Nothing here attaches a meaning to the world axes. Conventions that do, such as the anatomical codes used in neuroimaging, belong in packages built on this one.

reorient() permutes and reverses an image's spatial axes so that they run along the world axes given, updating the geometry to match, so that every voxel keeps its position in world space. Only the 48 axis-aligned orientations are reachable this way; whatever oblique rotation is left over stays in the geometry. For an image with fewer than three spatial dimensions, the entries for the world axes it does not span are ignored.

For packed and sparse images this is a change of view rather than of data: the image records how its axes map onto its storage, and indexing, dim(), the geometry and every apply function work in the view, so no values are moved or copied. A dense image is a plain R array, which base R indexes in memory order, so a dense image is always stored in view order and reorienting one copies its data.

storageLayout() returns the layout of an image: one entry per axis, giving the one-based rank of the storage axis it corresponds to (rank one varying fastest), negated where the image runs along that axis backwards. It is the identity for a dense image, and for any image that has not been reoriented or read from a file stored in another order.

Value

worldAxes() returns an integer vector with one element per spatial dimension, up to three. reorient() returns an image of the same class as x, with its axes permuted and reversed as needed.

Examples

image <- denseImage(array(1:24, c(2, 3, 4)), worldTransform = diag(c(-1, 1, 1, 1)))
worldAxes(image)
worldAxes(reorient(image))

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