Version:	2.8.4
Date:	2024-09-30
Title:	Image Registration Using the 'NiftyReg' Library
Maintainer:	Jon Clayden <code@clayden.org>
Imports:	Rcpp, RNifti
Suggests:	jpeg, loder, mmand, tinytest, covr
LinkingTo:	Rcpp, RcppEigen, RNifti
Description:	Provides an 'R' interface to the 'NiftyReg' image registration tools https://github.com/KCL-BMEIS/niftyreg. Linear and nonlinear registration are supported, in two and three dimensions.
License:	GPL-2
URL:	https://github.com/jonclayden/RNiftyReg
BugReports:	https://github.com/jonclayden/RNiftyReg/issues
Encoding:	UTF-8
RoxygenNote:	7.3.2
NeedsCompilation:	yes
Packaged:	2024-09-30 11:56:35 UTC; jon
Author:	Jon Clayden [cre, aut], Marc Modat [aut], Benoit Presles [aut], Thanasis Anthopoulos [aut], Pankaj Daga [aut]
Repository:	CRAN
Date/Publication:	2024-09-30 16:10:02 UTC

Apply a precomputed transformation

Description

This function allows a precomputed transformation to be applied to a new image or set of points.

Usage

applyTransform(transform, x, interpolation = 3L, nearest = FALSE,
  internal = FALSE)

Arguments

Details

Points may be transformed from source to target space exactly under an affine transformation, but nonlinear transformation is inexact. Its accuracy will depend to some extent on the density of the control point grid and the geometry of the deformation in the vicinity of the points of interest. Nevertheless, it should be quite sufficient for most purposes.

The method is to first convert the control points to a deformation field (cf. deformationField), which encodes the location of each target space voxel in the source space. The target voxel closest to the requested location is found by searching through this deformation field, and returned if nearest is TRUE or it coincides exactly with the requested location. Otherwise, a block of four voxels in each dimension around the point of interest is extracted from the deformation field, and the final location is estimated by local cubic spline regression.

Value

A resampled image or matrix of transformed points.

Author(s)

Jon Clayden <code@clayden.org>

See Also

niftyreg.linear, niftyreg.nonlinear

Build an affine matrix up from its constituent transformations

Description

This function does the opposite to decomposeAffine, building up an affine matrix from its components. It can be useful for testing, or for rescaling images.

Usage

buildAffine(translation = c(0, 0, 0), scales = c(1, 1, 1), skews = c(0,
  0, 0), angles = c(0, 0, 0), source = NULL, target = NULL,
  anchor = c("none", "origin", "centre", "center"))

Arguments

Value

A 4x4 affine matrix representing the composite transformation. Note that NiftyReg affines logically transform backwards, from target to source space, so the matrix may be the inverse of what is expected.

Author(s)

Jon Clayden <code@clayden.org>

See Also

decomposeAffine, isAffine

Compose transformations

Description

Compute the composition of two or more transforms, the single transform that combines their effects in order.

Usage

composeTransforms(...)

Arguments

Value

The composed transform. If all arguments are affines then the result will also be an affine; otherwise it will be a deformation field.

Note

The source image for the composed transform is generally the source image from the first transform, and the target is the target image from the second transform. However, the target image attached to half transforms (as calculated by halfTransform) generally has a modified xform, compared to the original target. Therefore, composing a half transform with itself may not be exactly equivalent to the original.

Author(s)

Jon Clayden <code@clayden.org>

See Also

niftyreg.linear, niftyreg.nonlinear, deformationField

Decompose an affine matrix into its constituent transformations

Description

An affine matrix is composed of translation, scale, skew and rotation transformations. This function extracts these components, after first inverting the matrix so that it transforms from source to target space.

Usage

decomposeAffine(affine)

Arguments

Value

A list with components:

scaleMatrix

A 3x3 matrix representing only the scale operation embodied in the full affine transformation.

skewMatrix

A 3x3 matrix representing only the skew operation embodied in the full affine transformation.

rotationMatrix

A 3x3 matrix representing only the rotation operation embodied in the full affine transformation.

translation

A length-3 named numeric vector representing the translations (in pixunits units) in each of the X, Y and Z directions.

scales

A length-3 named numeric vector representing the scale factors in each of the X, Y and Z directions. Scale factors of 1 represent no effect.

skews

A length-3 named numeric vector representing the skews in each of the XY, XZ and YZ planes.

angles

A length-3 named numeric vector representing the rotation angles (in radians) about each of the X, Y and Z directions, i.e., roll, pitch and yaw.

Note

The decomposition is not perfect, and there is one particular degenerate case when the pitch angle is very close to pi/2 radians, known as “Gimbal lock”. In this case the yaw angle is arbitrarily set to zero.

Affine matrices embodying rigid-body transformations include only 6 degrees of freedom, rather than the full 12, so skews will always be zero and scales will always be unity (to within rounding error). Likewise, affine matrices derived from 2D registration will not include components relating to the Z direction.

Author(s)

Jon Clayden <code@clayden.org>

See Also

buildAffine, isAffine

Calculate the deformation field for a transformation

Description

This function is used to calculate the deformation field corresponding to a specified linear or nonlinear transformation. The deformation field gives the location in source image space corresponding to the centre of each voxel in target space. It is used as a common form for linear and nonlinear transformations, and allows them to be visualised.

Usage

deformationField(transform, jacobian = TRUE)

Arguments

Value

An "internalImage" representing the deformation field. If requested, the Jacobian map is stored in an attribute, which can be extracted using the jacobian accessor function.

Author(s)

Jon Clayden <code@clayden.org>

See Also

niftyreg.linear, niftyreg.nonlinear

Extract forward and reverse transformations

Description

These functions extract forward and reverse transformations in a form compatible with applyTransform and other functions. They are (S3) generic, but only methods for "niftyreg" objects currently exist.

Usage

forward(object, ...)

## S3 method for class 'niftyreg'
forward(object, i = 1L, ...)

reverse(object, ...)

## S3 method for class 'niftyreg'
reverse(object, i = 1L, ...)

Arguments

Value

A transformation object, an image or affine matrix, with suitable attributes giving pointers to source and target images. If there is no transformation information in the object then NULL is returned.

Author(s)

Jon Clayden <code@clayden.org>

See Also

niftyreg, applyTransform

Calculate a half transformation

Description

This function calculates the half-way transformation corresponding to its argument. Applying this transformation results in points or images in a space halfway between the original source and target images, which can be a useful common space in some applications.

Usage

halfTransform(transform)

Arguments

Value

The half-way transform, in a similar format to transform.

Author(s)

Jon Clayden <code@clayden.org>

See Also

niftyreg.linear, niftyreg.nonlinear

Invert an affine matrix

Description

This function is used to invert an affine matrix. It is a wrapper around solve, which additionally sets appropriate attributes.

Usage

invertAffine(affine)

Arguments

Value

The inverted affine matrix.

Author(s)

Jon Clayden <code@clayden.org>

See Also

solve

Examples

affine <- readAffine(system.file("extdata","affine.txt",package="RNiftyReg"))
print(affine)
print(invertAffine(affine))

Create, test for and print affine matrices

Description

isAffine returns a logical value indicating whether its argument is, or resembles, a 4x4 affine matrix. asAffine converts other objects to the affine class, attaching or updating the source and target image attributes. Affine transformations are a class of linear transformations which preserve points, straight lines and planes, and may consist of a combination of rotation, translation, scale and skew operations.

Usage

isAffine(object, strict = FALSE)

asAffine(object, source = NULL, target = NULL, ...)

## S3 method for class 'niftyreg'
asAffine(object, source = NULL, target = NULL, i = 1L,
  ...)

## S3 method for class 'niftyregRDS'
asAffine(object, source = NULL, target = NULL, ...)

## S3 method for class 'affine'
asAffine(object, source = NULL, target = NULL, ...)

## S3 method for class 'niftiImage'
asAffine(object, source = attr(object, "source"),
  target = attr(object, "target"), ...)

## Default S3 method:
asAffine(object, source = NULL, target = NULL, ...)

## S3 method for class 'affine'
print(x, ...)

Arguments

Details

NiftyReg's convention is for affine matrices to transform world coordinates (in the sense of voxelToWorld) from TARGET to SOURCE space, although transforms are logically applied the other way.

Value

For isAffine, a logical value, which is TRUE if object appears to be an affine matrix. For asAffine, a classed affine object with source and target attributes set appropriately.

Note

2D affines are a subset of 3D affines, and are stored in a 4x4 matrix for internal consistency, even though a 3x3 matrix would suffice.

Author(s)

Jon Clayden <code@clayden.org>

Test whether an object represents an image

Description

This function tried to determine whether an object is an image that the package knows how to handle. If its class is "nifti", "niftiImage", "internalImage" or "MriImage", then the result is always TRUE. Likewise if it has an internal image pointer. If it has no dim attribute, or looks like an affine matrix, then the result is FALSE. Otherwise the value of the unsure argument is returned.

Usage

isImage(object, unsure = NA)

Arguments

Author(s)

Jon Clayden <code@clayden.org>

Extract a Jacobian determinant map

Description

This function extracts the Jacobian determinant map associated with a deformation field.

Usage

jacobian(x)

Arguments

Author(s)

Jon Clayden <code@clayden.org>

See Also

deformationField

Two and three dimensional image registration

Description

The niftyreg function performs linear or nonlinear registration for two and three dimensional images. 4D images may also be registered volumewise to a 3D image, or 3D images slicewise to a 2D image. This function is a common wrapper for niftyreg.linear and niftyreg.nonlinear.

Usage

niftyreg(source, target, scope = c("affine", "rigid", "nonlinear"),
  init = NULL, sourceMask = NULL, targetMask = NULL, symmetric = TRUE,
  interpolation = 3L, estimateOnly = FALSE, sequentialInit = FALSE,
  internal = NA, precision = c("double", "single"),
  threads = getOption("RNiftyReg.threads"), ...)

## S3 method for class 'niftyreg'
asNifti(x, ...)

## S3 method for class 'niftyreg'
as.array(x, ...)

Arguments

Value

A list of class "niftyreg" with components:

image

An array or internal image representing the registered and resampled source image in the space of the target image. This element is NULL if the estimateOnly parameter is TRUE.

forwardTransforms

A list of (linear or nonlinear) transformations from source to target space.

reverseTransforms

A list of (linear or nonlinear) transformations from target to source space.

iterations

A list of integer vectors, giving the number of iterations completed at each “level” of the algorithm. Note that for the first level of the linear algorithm specifically, twice the specified number of iterations is allowed.

source

An internal representation of the source image for each registration.

target

An internal representation of the target image.

The as.array method for this class returns the image element.

Note

If substantial parts of the target image are zero-valued, for example because the target image has been brain-extracted, it can be useful to pass it as a target mask as well as the target image, viz. niftyreg(source, target, targetMask=target).

Author(s)

Jon Clayden <code@clayden.org>

References

Please see niftyreg.linear or niftyreg.nonlinear for references relating to each type of registration.

See Also

niftyreg.linear and niftyreg.nonlinear, which do most of the work. Also, forward and reverse to extract transformations, and applyTransform to apply them to new images or points.

Examples

## Not run: 
source <- readNifti(system.file("extdata", "epi_t2.nii.gz",
  package="RNiftyReg"))
target <- readNifti(system.file("extdata", "flash_t1.nii.gz",
  package="RNiftyReg"))

result <- niftyreg(source, target, scope="affine")

## End(Not run)

Two and three dimensional linear image registration

Description

The niftyreg.linear function performs linear registration for two and three dimensional images. 4D images may also be registered volumewise to a 3D image, or 3D images slicewise to a 2D image. Rigid-body (6 degrees of freedom) and affine (12 degrees of freedom) registration can currently be performed.

Usage

niftyreg.linear(source, target, scope = c("affine", "rigid"), init = NULL,
  sourceMask = NULL, targetMask = NULL, symmetric = TRUE, nLevels = 3L,
  maxIterations = 5L, useBlockPercentage = 50L, interpolation = 3L,
  verbose = FALSE, estimateOnly = FALSE, sequentialInit = FALSE,
  internal = NA, precision = c("double", "single"),
  threads = getOption("RNiftyReg.threads"))

Arguments

Details

This function performs the dual operations of finding a transformation to optimise image alignment, and resampling the source image into the space of the target image.

The algorithm is based on a block-matching approach and Least Trimmed Squares (LTS) fitting. Firstly, the block matching provides a set of corresponding points between a target and a source image. Secondly, using this set of corresponding points, the best rigid or affine transformation is evaluated. This two-step loop is repeated until convergence to the best transformation is achieved.

In the NiftyReg implementation, normalised cross-correlation between the target and source blocks is used to evaluate correspondence. The block width is constant and has been set to 4 voxels. A coarse-to-fine approach is used, where the registration is first performed on down-sampled images (using a Gaussian filter to resample images), and finally performed on full resolution images.

The source image may have 2, 3 or 4 dimensions, and the target 2 or 3. The dimensionality of the target image determines whether 2D or 3D registration is applied, and source images with one more dimension than the target (i.e. 4D to 3D, or 3D to 2D) will be registered volumewise or slicewise, as appropriate. In the latter case the last dimension of the resulting image is taken from the source image, while all other dimensions come from the target. One affine matrix is returned for each registration performed.

Value

See niftyreg.

Author(s)

Jon Clayden <code@clayden.org>

References

The algorithm used by this function is described in the following publication.

M. Modat, D.M. Cash, P. Daga, G.P. Winston, J.S. Duncan & S. Ourselin (2014). Global image registration using a symmetric block-matching approach. Journal of Medical Imaging 1(2):024003.

See Also

niftyreg, which can be used as an interface to this function, and niftyreg.nonlinear for nonlinear registration. Also, forward and reverse to extract transformations, and applyTransform to apply them to new images or points.

Two and three dimensional nonlinear image registration

Description

The niftyreg.nonlinear function performs nonlinear registration for two and three dimensional images. 4D images may also be registered volumewise to a 3D image, or 3D images slicewise to a 2D image. The warping is based on free-form deformations, parameterised using an image of control points.

Usage

niftyreg.nonlinear(source, target, init = NULL, sourceMask = NULL,
  targetMask = NULL, symmetric = TRUE, nLevels = 3L,
  maxIterations = 150L, nBins = 64L, bendingEnergyWeight = 0.001,
  linearEnergyWeight = 0.01, jacobianWeight = 0, finalSpacing = c(5, 5,
  5), spacingUnit = c("voxel", "world"), interpolation = 3L,
  verbose = FALSE, estimateOnly = FALSE, sequentialInit = FALSE,
  internal = NA, precision = c("double", "single"),
  threads = getOption("RNiftyReg.threads"))

Arguments

Details

This function performs the dual operations of finding a transformation to optimise image alignment, and resampling the source image into the space of the target image (and vice-versa, if symmetric is TRUE). Unlike niftyreg.linear, this transformation is nonlinear, and the degree of deformation may vary across the image.

The nonlinear warping is based on free-form deformations. A lattice of equally-spaced control points is defined over the target image, each of which can be moved to locally modify the mapping to the source image. In order to assess the quality of the warping between the two images, an objective function based on the normalised mutual information is used, with penalty terms based on the bending energy or the squared log of the Jacobian determinant. The objective function value is optimised using a conjugate gradient scheme.

The source image may have 2, 3 or 4 dimensions, and the target 2 or 3. The dimensionality of the target image determines whether 2D or 3D registration is applied, and source images with one more dimension than the target (i.e. 4D to 3D, or 3D to 2D) will be registered volumewise or slicewise, as appropriate. In the latter case the last dimension of the resulting image is taken from the source image, while all other dimensions come from the target. One image of control points is returned for each registration performed.

Value

See niftyreg.

Note

Performing a linear registration first, and then initialising the nonlinear transformation with the result (via the init parameter), is highly recommended in most circumstances.

Author(s)

Jon Clayden <code@clayden.org>

References

The algorithm used by this function is described in the following publication.

M. Modat, G.R. Ridgway, Z.A. Taylor, M. Lehmann, J. Barnes, D.J. Hawkes, N.C. Fox & S. Ourselin (2010). Fast free-form deformation using graphics processing units. Computer Methods and Programs in Biomedicine 98(3):278-284.

See Also

niftyreg, which can be used as an interface to this function, and niftyreg.linear for linear registration. Also, forward and reverse to extract transformations, and applyTransform to apply them to new images or points.

Read an affine matrix from a file

Description

This function is used to read a 4x4 numeric matrix representing an affine transformation from a file. It is a wrapper around read.table which additionally ensures that required attributes are set. The type of the matrix must be specified, as there are differing conventions across software packages.

Usage

readAffine(fileName, source = NULL, target = NULL, type = NULL)

Arguments

Value

An matrix with class "affine", converted to the NiftyReg convention and with source and target attributes set appropriately.

Author(s)

Jon Clayden <code@clayden.org>

See Also

read.table, writeAffine

Examples

print(readAffine(system.file("extdata","affine.txt",package="RNiftyReg")))

Read a NIfTI format file

Description

This function reads files in NIfTI-1 or NIfTI-2 format into R, using the standard NIfTI C library. It extends the equivalent function from the RNifti package with source and target image parameters.

Usage

readNifti(file, source = NULL, target = NULL, internal = FALSE)

Arguments

Value

An array or internal image, with class "niftiImage", and possibly also "internalImage".

Author(s)

Jon Clayden <code@clayden.org>

Objects exported from other packages

Description

These objects are imported from other packages. Follow the links below to see their documentation.

RNifti

dumpNifti, ndim, pixdim, pixdim<-, pixunits, pixunits<-, qform<-, retrieveNifti, sform<-, updateNifti, voxelToWorld, worldToVoxel, writeNifti, xform

Save and load transform objects

Description

These objects save a full transformation object, including source and target image metadata, to a self-contained RDS file, or load it back from such a file.

Usage

saveTransform(transform, fileName = NULL)

loadTransform(x)

Arguments

Value

saveTransform returns a serialised transform object, if no filename is given; otherwise it is called for its side-effect of writing to file. loadTransform returns a deserialised transform object.

Author(s)

Jon Clayden <code@clayden.org>

See Also

writeAffine, readAffine

Similarity measures between images

Description

This function calculates a similarity measure between two images, after resampling one into the space of the other. The only supported measure is currently normalised mutual information, which is also used as a cost function by the registration algorithms.

Usage

similarity(source, target, targetMask = NULL, interpolation = 3L,
  threads = getOption("RNiftyReg.threads"))

Arguments

Value

A single numeric value representing the similarity between the images.

Author(s)

Jon Clayden <code@clayden.org>

See Also

niftyreg

Apply simple transformations

Description

These functions allow simple transformations to be applied quickly, or in a chosen order. They represent simplified interfaces to the buildAffine and applyTransform functions, and are compatible with the chaining operator from the popular magrittr package (although performing one single transformation may be preferable).

Usage

translate(source, translation, ...)

rescale(source, scales, anchor = c("none", "origin", "centre", "center"),
  ...)

skew(source, skews, anchor = c("none", "origin", "centre", "center"), ...)

rotate(source, angles, anchor = c("none", "origin", "centre", "center"), ...)

Arguments

Value

The transformed image.

Author(s)

Jon Clayden <code@clayden.org>

See Also

buildAffine, applyTransform

Write an affine matrix to a file

Description

This function is used to write a 4x4 numeric matrix representing an affine transformation to a file. A comment is also (optionally) written, which specifies the matrix as using the NiftyReg convention, for the benefit of readAffine.

Usage

writeAffine(affine, fileName, comments = TRUE)

Arguments

Author(s)

Jon Clayden <code@clayden.org>

See Also

write.table, readAffine