transforms

ngtools.transforms

Utilities to manipulate transforms (ng.CoordinateSpaceTransform) in neuroglancer.

Also provide tools to read and convert arbitrary coordinate transforms into neuroglancer format.

Functions:

Name	Description
`compose`	Compose two `ng.CoordinateSpaceTransform`.
`convert_transform`	Convert the units of a transform, while keeping the transform equivalent.
`ensure_same_scale`	Convert the units of a transform, so that all axes have the same unit and scale, while keeping the transform equivalent.
`get_matrix`	Get matrix from transform, creating one if needed.
`inverse`	Invert a `ng.CoordinateSpaceTransform`.
`load_affine`	Load an affine transform from a file or stream.
`normalize_transform`	Ensure that input and output spaces have SI units.
`subtransform`	Keep only axes whose units are of a given kind.
`to_square`	Ensure that an affine matrix is square (with its homogeneous row).

Note on transforms

A CoordinateSpaceTransform has the following fields

transform : np.ndarray
    Homogeneous affine transform that maps input coordinates
    (columns) to output coordinates (row)
inputDimensions : CoordinateSpace
    A description of the input space.
    Sometimes referred to as the "source" space in the ng sourcecode.
outputDimensions : CoordinateSpace
    A description of the output space.
    Sometimes referred to as the "view" space in the ng sourcecode.

A CoordinateSpace has the following fields:

names : list[str]
    The name of each dimension.
scales : list[float]
    The scale (voxel size) of each dimension.
units : list[str]
    The unit in which scale is expressed.

Two important points must be noted, as they differ from how transforms are encoded in other frameworks:

* The _linear part_ of the transform is ___always___ unit-less.
    That is, it maps from/to the same isotropic unit.

* The _translation_ component of the transform is ___always___
    expressed in output units.

A nifti-like "voxel to scaled-world" matrix would therefore be constructed via

    [ x ]   [ 1/vx     ]   [ Axi Axj Axk ]   [ sx       ]   [ i ]   [ Tx ]
    [ y ] = [   1/vy   ] * [ Ayi Ayj Ayk ] * [    sy    ] * [ j ] + [ Ty ]
    [ z ]   [     1/vz ]   [ Azi Azj Azk ]   [       sz ]   [ k ]   [ Tz ]

where v is the view/output voxel size and s is the source/input voxel size. In that context, [x, y, z] is expressed in "scaled world" units and [i, j, k] is expressed in "voxel" units.

Alternatively, a "scaled-voxel to world" matrix can be constructed via

    [ x ]   [ Axi Axj Axk ]   [ sx       ]   [ i ]   [ vx       ]   [ Tx ]
    [ y ] = [ Ayi Ayj Ayk ] * [    sy    ] * [ j ] + [    vy    ] * [ Ty ]
    [ z ]   [ Azi Azj Azk ]   [       sz ]   [ k ]   [       vz ]   [ Tz ]

matrix_to_quaternion

matrix_to_quaternion(mat)

Convert a rotation matrix to a quaternion.

We follow neuroglancer and assume that quaternions are ordered as [v, r] (or again, [i, j, k, r]). This differs form wikipedia which defines them as [r, v] (or [r, i, j, k]).

quaternion_to_matrix

quaternion_to_matrix(q)

Convert a quaternion to a rotation matrix.

compose_quaternions

compose_quaternions(a, b, *others)

Compose quaternions.

inverse_quaternions

inverse_quaternions(a)

Inverse quaternion.

ras2transform

ras2transform(ras2ras, names=('x', 'y', 'z'))

Convert a RAS2RAS matrix (in mm space) to a neuroglancer transform.

load_affine

load_affine(fileobj, format=None, moving=None, fixed=None, names=('x', 'y', 'z'))

Load an affine transform from a file.

Parameters:

Name	Type	Description	Default
`fileobj`	`file_like or str`	Input file. May start with a format protocol such as `"afni://path/to/file"`. Accepted protocols are `"afni://"` Affine generated by AFNI `"fsl://"` Affine generated by FSL FLIRT `"itk://"` Affine in ITK format (e.g., generated by ANTs) `"lta://"` Affine in FreeSurfer LTA format (mri_robust_register)	required
`format`	`(afni, fsl, itk, lta)`	Alternative way to provide a format hint.	`"afni"`

Returns:

Name	Type	Description
`affine`	`(4, 4) np.ndarray`	A RAS2RAS affine transform.

save_transform

save_transform(trf, out, format=None)

Save a neuroglancer transform in a neuroimaging format.

Parameters:

Name	Type	Description	Default
`trf`	`CoordinateSpaceTransform \| dict`	Transformation	required
`out`	`str \| PathLike`	Output path. Currently, only local paths are supported.	required
`format`	`str \| None`	Output format (default: guessed from extension -- or LTA)	`None`

to_square

to_square(affine)

Ensure an affine matrix is in square (homogeneous) form.

get_matrix

get_matrix(trf, square=False)

Get (a copy of) the transfomation's matrix -- create one if needed.

inverse

inverse(transform)

Invert a transform.

compose

compose(*transforms, adapt=False)

Compose two transforms.

Parameters:

Name	Type	Description	Default
`*transforms`	`CoordinateSpaceTransform`	Transforms to compose	`()`
`adapt`	`bool`	Try to adapt midspaces if they are different neurospaces.	`False`

Returns:

Name	Type	Description
`composition`	`CoordinateSpaceTransform`

convert_transform

convert_transform(transform, input=None, output=None)

Convert units of a transform.

Example

ABCDEF

Ensure that all axes have SI unit (without prefix)

new_space = convert_transform(space, "base", "base")
# or
base = ["m", "s", "hz", "rad/s"]
new_space = convert_space(space, base, base)
# or
new_space = normalize_transform(space)

Ensure that all axes have unit-scale SI unit (without prefix)

base = [[1, "m"], [1, "s"], [1, "hz"], [1, "rad/s"]]
new_space = convert_space(space, base, base)
# or
new_space = normalize_transform(space, unit_scale=True)

Ensure that input spatial axes have millimeter unit

new_space = convert_space(space, "mm")
# or
new_space = convert_space(space, "mm", None)

Ensure that all spatial axes have millimeter unit

new_space = convert_space(space, "mm", "mm")

Ensure that specific input axes have specific unit

new_space = convert_space(space, {"x": "mm", "y": "mm", "t": "ms"})
# or
new_space = convert_space(space, {("x", "y"): "mm", "t": "ms"})
# or
new_space = convert_space(space, {("x", "y", "t"): ["mm", "ms"]})

Ensure that specific input axes have specific scales

new_space = convert_space(space, {"x": [2, "mm"], "y": [2, "mm"], "t": [3, "ms"]})
# or
new_space = convert_space(space, {("x", "y"): [2, "mm"], "t": [3, "ms"]})
# or
new_space = convert_space(space, {("x", "y", "t"): [[2, "mm"], [3, "ms"]]})
# or
new_space = convert_space(space,

normalize_transform

normalize_transform(transform, unit_scale=False)

Ensure that input and output spaces have SI units.

See also: convert_transform, ensure_same_scale.

Parameters:

Name	Type	Description	Default
`transform`	`CoordinateSpaceTransform`	Transformation	required
`unit_scale`	`bool`	If `True`, make input and output space to have unit scale. Otherwise, simply convert them to SI unit.	`False`

Returns:

Name	Type	Description
`transform`	`CoordinateSpaceTransform`	Converted transformation

ensure_same_scale

ensure_same_scale(transform)

Ensure that all axes and both input and output spaces use the same unit and the same scaling.

This function is quite related to normalize_transform(*, unit_scale=True) except that the units closest to input units are used, instead of prefixless SI units.

subtransform

subtransform(transform, unit=None, *, names=None, input_names=None, output_names=None)

Generate a subtransform by keeping only axes of a certain unit kind.

Parameters:

Name	Type	Description	Default
`transform`	`CoordinateSpaceTransform`	Transformation	required
`unit`	`str \| list[str]`	Unit kind to keep.	`None`

Other Parameters:

Name	Type	Description
`names`	`str \| list[str]`	Axis names to keep.
`input_names`	`str \| list[str] \| None`	Names of input axes to keep.
`str`	`str \| list[str] \| None`	Names of input axes to keep.
`output_names`	`str \| list[str] \| None`	Names of output axes to keep.
`str`	`str \| list[str] \| None`	Names of output axes to keep.

Returns:

Name	Type	Description
`transform`	`CoordinateSpaceTransform`	Converted transformation

Name	Type	Description	Default
`transform`	`CoordinateSpaceTransform`	Transform	required
`input`	`CoordinateSpace \| str \| tuple[float, str] \| list \| dict \| None`	Either a coordinate space to use in-place of the existing one, or a new (list of) unit(s), or a mapping from axis name(s) to new unit(s).	`None`
`output`	`CoordinateSpace \| str \| tuple[float, str] \| list \| dict \| None`	Either a coordinate space to use in-place of the existing one, or a new (list of) unit(s), or a mapping from axis name(s) to new unit(s).	`None`