Obtain or replace the ``xform'' transforms for an image

Source: R/xform.R

These functions convert the ``qform'' or ``sform'' information in a NIfTI header to or from a corresponding affine matrix. These two ``xform'' mechanisms are defined by the NIfTI standard, and may both be in use in a particular image header. They define the relationship between the storage order of the image and real space.

xform(image, useQuaternionFirst = TRUE)

qform(x) <- value

sform(x) <- value

orientation(x, useQuaternionFirst = TRUE)

orientation(x) <- value

rotation(x, useQuaternionFirst = TRUE)

Arguments

image, x

An image, in any acceptable form (see asNifti), or a 4x4 numeric xform matrix.
useQuaternionFirst

A single logical value. If TRUE, the ``qform'' matrix will be used first, if it is defined; otherwise the ``sform'' matrix will take priority.
value

A new 4x4 qform or sform matrix, or orientation string. If a matrix has a "code" attribute, the appropriate qform or sform code is also set.

Value

For xform, an affine matrix corresponding to the ``qform'' or ``sform'' information in the image header, with a "code" attribute giving the corresponding xform code. For orientation, a string with three characters indicating the (approximate) orientation of the image. The replacement forms return the modified object.

Details

Image orientation is indicated using a three-character string, with each character indicating the approximate world-space direction of the positive axes in the first, second and third dimensions, in order. Each character may be `R' for left-to-right, `L' for right-to-left, `A' for posterior-to- anterior, `P' for anterior-to-posterior, `S' for inferior-to-superior, or `I' for superior-to-inferior. The default for NIfTI is RAS, meaning that the first dimension points towards the right, the second towards the front and the third towards the top. An xform matrix is an affine transform relative to that default.

The upper-left 3x3 matrix in a 3D affine transform governs scale, rotation and skew, while the last column is a translation. (The rotation function extracts the rotation part alone.) The final row is always (0,0,0,1). Reorienting an image involves permuting and possibly reversing some of the axes, both in the data and the metadata. The sense of the translation may also need to be reversed, but this is only possible if the image dimensions are known, which isn't the case when reorienting an xform alone.

Note

The qform and sform replacement functions are for advanced users only. Modifying the transforms without knowing what you're doing is usually unwise, as you can make the image object inconsistent.

References

The NIfTI-1 standard (https://www.nitrc.org/docman/view.php/26/64/nifti1.h) is the definitive reference on ``xform'' conventions.

Author

Jon Clayden <code@clayden.org>

Examples

im <- readNifti(system.file("extdata", "example.nii.gz", package="RNifti"))
xform(im)
#>      [,1] [,2] [,3]      [,4]
#> [1,] -2.5  0.0  0.0 122.03390
#> [2,]  0.0  2.5  0.0 -95.18523
#> [3,]  0.0  0.0  2.5 -55.03814
#> [4,]  0.0  0.0  0.0   1.00000
#> attr(,"code")
#> [1] 2

# Remove the qform information
qform(im) <- structure(diag(4), code=0L)

# The same as above, since the sform is unmodified
xform(im)
#>      [,1] [,2] [,3]      [,4]
#> [1,] -2.5  0.0  0.0 122.03390
#> [2,]  0.0  2.5  0.0 -95.18523
#> [3,]  0.0  0.0  2.5 -55.03814
#> [4,]  0.0  0.0  0.0   1.00000
#> attr(,"code")
#> [1] 2

# The identity matrix corresponds to RAS orientation
orientation(diag(4))
#> [1] "RAS"