`ngff_zarr.ngff_transform_to_itk_transform`¶

Bridge RFC-5 coordinate transformations to ITK transforms.

RFC-5 and ITK describe the same affine geometry with two different conventions, and the differences are silent rather than loud: getting one wrong yields a plausible transform that is simply in the wrong place.

Axis order RFC-5 orders transformation parameters the same way the Zarr array is ordered – parameter i belongs to coordinate-system axis i, so a zyx image has z first. ITK orders points fastest-axis-first by name: x, then y, then z. Writing P for the permutation sending an ITK-order vector to the dims-order vector, an RFC-5 affine q = M p + b becomes A = P^T M P and t = P^T b in ITK. For the canonical zyx order P is the axis reversal.

Composition order An RFC-5 sequence applies its first entry first. An ITK transform list applies its last entry first. Rather than emit a list and rely on that inversion, this module composes the chain into a single matrix here, where the order is explicit and testable.

Both conventions place the pixel center at the integer index, so no half-pixel correction is involved.

Module Contents¶

Functions¶

`_homogeneous_from_transform`	Collapse one RFC-5 transformation into an `(ndim+1, ndim+1)` matrix.
`_homogeneous_from_by_dimension`	Assemble a byDimension transformation into one homogeneous matrix.
`_by_dimension_item_block`	One byDimension item as a matrix and offset over its own axes.
`_as_matrix`
`_ngff_transform_to_itk_matrix`	Convert an RFC-5 transformation to an ITK matrix and offset.
`ngff_transform_to_itk_transform`	Convert an RFC-5 transformation to an ITK-Wasm transform list.

Data¶

_SPATIAL_DIMS

API¶

ngff_zarr.ngff_transform_to_itk_transform._SPATIAL_DIMS¶: (‘x’, ‘y’, ‘z’)

ngff_zarr.ngff_transform_to_itk_transform._homogeneous_from_transform( transform: ngff_zarr.v06.zarr_metadata.Transform, ndim: int, ) → numpy.ndarray¶

Collapse one RFC-5 transformation into an (ndim+1, ndim+1) matrix.

The matrix is in RFC-5 (Zarr) axis order and acts on column vectors in homogeneous coordinates.

ngff_zarr.ngff_transform_to_itk_transform._homogeneous_from_by_dimension( transform: ngff_zarr.v06.zarr_metadata.ByDimension, ndim: int, ) → numpy.ndarray¶

Assemble a byDimension transformation into one homogeneous matrix.

Each item is a lower-dimensional transformation between two subsets of axes, so its own matrix is written into the rows its outputAxes name and the columns its inputAxes name. Axes no item produces would leave a zero row, which collapses the image rather than transforming it, so a gap is refused here rather than resampled.

ngff_zarr.ngff_transform_to_itk_transform._by_dimension_item_block( item: ngff_zarr.v06.zarr_metadata.ByDimensionItem, ndim: int, ) → tuple[numpy.ndarray, numpy.ndarray]¶: One byDimension item as a matrix and offset over its own axes.

ngff_zarr.ngff_transform_to_itk_transform._as_matrix(values, path: str | None, field: str) → numpy.ndarray¶

ngff_zarr.ngff_transform_to_itk_transform._ngff_transform_to_itk_matrix( transform: ngff_zarr.v06.zarr_metadata.Transform, dims: collections.abc.Sequence[str], ) → tuple[numpy.ndarray, numpy.ndarray]¶

Convert an RFC-5 transformation to an ITK matrix and offset.

Internal. :func:ngff_transform_to_itk_transform is the public entry point; nothing outside this package needs the raw numbers, since ITK is what the caller wants to hand them to. The tests use it as a fine probe on the axis and composition conventions.

Parameters:

transform (Transform) – An RFC-5 (OME-Zarr v0.6) coordinate transformation. It must describe a linear mapping – identity, scale, translation, rotation, affine, mapAxis, byDimension, bijection, or a sequence of those.
dims (Sequence[str]) – The axis names of the coordinate system the transformation is defined on, in RFC-5 (Zarr) order, e.g. ("z", "y", "x").

Returns:

(matrix, offset) for the spatial axes only, in ITK (fastest-axis-first) order. ITK has no notion of a non-spatial axis, so a component acting purely on t or c – a frame interval, say – is projected away. That is lossless for the spatial mapping, which is all an ITK transform describes, but the returned transform is not a faithful copy of the input. A component that couples the two kinds of axis is refused instead, because dropping it would move the image.

Return type:

tuple[numpy.ndarray, numpy.ndarray]

Raises:

NotImplementedError – If the transformation is not linear.
ValueError – If the transformation couples spatial and non-spatial axes, or its parameters do not match dims.

ngff_zarr.ngff_transform_to_itk_transform.ngff_transform_to_itk_transform( transform: ngff_zarr.v06.zarr_metadata.Transform, dims: collections.abc.Sequence[str], *, fields: collections.abc.Mapping[str, object] | None = None, fixed=None, moving=None, ) → list¶

Convert an RFC-5 transformation to an ITK-Wasm transform list.

A linear transformation is collapsed into a single Affine entry, so the result is independent of ITK’s own list-composition order. A displacements or coordinates transformation becomes a single DisplacementField entry built from the field passed in fields.