Skip to content

Transform

Coordinate transforms used to map between coordinate systems.

cellier.transform

Coordinate transforms for cellier v2.

AffineTransform pydantic-model

Bases: BaseTransform

N-dimensional affine transformation using a homogeneous matrix.

The matrix has shape (ndim+1, ndim+1) where ndim is the number of data dimensions. Coordinates and scale/translation parameters follow data-axis order (e.g. (axis0, axis1, axis2)).

Instances are frozen (immutable). To change a transform, construct a new one and assign it to the visual's transform field.

Composition uses left-to-right application order::

(A @ B).map_coordinates(p) == B.map_coordinates(A.map_coordinates(p))

Parameters:

Name Type Description Default
matrix ndarray

An (N, N) affine transformation matrix where N >= 2.

 required

Fields:

  • matrix (ndarray)

Validators:

  • _coerce_to_ndarray_float32 → matrix
ndim cached property 
ndim: int

Number of spatial dimensions.

inverse_matrix cached property 
inverse_matrix: ndarray

Cached inverse of the affine matrix.

map_coordinates 
map_coordinates(coordinates: ndarray) -> ndarray

Apply the forward (data -> world) transform to coordinates.

Coordinates are in data-axis order matching the numpy array shape convention (e.g. (axis0, axis1, axis2)).

Parameters:

Name Type Description Default
coordinates ndarray

(n, ndim) or (n, ndim+1) array of points.

 required

Returns:

Type Description
ndarray

(n, ndim) transformed coordinates.
imap_coordinates 
imap_coordinates(coordinates: ndarray) -> ndarray

Apply the inverse (world -> data) transform to coordinates.

Coordinates are in data-axis order matching the numpy array shape convention (e.g. (axis0, axis1, axis2)).

Parameters:

Name Type Description Default
coordinates ndarray

(n, ndim) or (n, ndim+1) array of points.

 required

Returns:

Type Description
ndarray

(n, ndim) transformed coordinates.
map_normal_vector 
map_normal_vector(normal_vector: ndarray) -> ndarray

Transform a normal vector from data space to world space.

Notes

Normals transform by the transpose-inverse of the point transform. Because the point transform is M, the normal transform is (M^-1)^T. Multiplying row vectors on the left by M^-1 is equivalent to (M^-1)^T * n in column-vector convention.

See Also

imap_normal_vector : The inverse operation (world -> data).

Parameters:

Name Type Description Default
normal_vector ndarray

(n, ndim) normal vectors in data space.

 required

Returns:

Type Description
ndarray

(n, ndim) unit normal vectors in world space.
imap_normal_vector 
imap_normal_vector(normal_vector: ndarray) -> ndarray

Transform a normal vector from world space to data space.

Notes

This is the inverse of :meth:map_normal_vector. The inverse normal transform uses M (the forward point matrix), because ((M^-1)^-1)^T = M^T, and left-multiplying by M is equivalent.

See Also

map_normal_vector : The forward operation (data -> world).

Parameters:

Name Type Description Default
normal_vector ndarray

(n, ndim) normal vectors in world space.

 required

Returns:

Type Description
ndarray

(n, ndim) unit normal vectors in data space.
select_axes 
select_axes(axes: tuple[int, ...]) -> AffineTransform

Extract a sub-transform for the given data axes.

Returns a lower-dimensional transform containing only the rows/columns for the specified axes. The output axis order matches the order of axes.

Parameters:

Name Type Description Default
axes tuple[int, ...]

Data axis indices to keep (e.g. (1, 2, 3) for z/y/x from a 4-D transform).

 required

Returns:

Type Description
AffineTransform

A len(axes)-dimensional transform.
swap_axes 
swap_axes(permutation: tuple[int, ...]) -> AffineTransform

Reorder the axes of this transform by an explicit permutation.

Use this to convert a transform from one axis ordering to another (e.g. data axis order (z, y, x) to display axis order (x, y, z)). The permutation must be a permutation of range(self.ndim).

Parameters:

Name Type Description Default
permutation tuple[int, ...]

permutation[i] is the source axis index whose row/column becomes output axis i.

 required

Returns:

Type Description
AffineTransform

A transform of the same ndim with axes reordered.

Raises:

Type Description
ValueError

If permutation is not a permutation of range(self.ndim).
expand_dims 
expand_dims(target_ndim: int) -> AffineTransform

Embed this transform as the last self.ndim axes of a larger identity.

Parameters:

Name Type Description Default
target_ndim int

Desired number of dimensions (must be >= self.ndim).

 required

Returns:

Type Description
AffineTransform

A target_ndim-dimensional transform with leading identity axes.

Raises:

Type Description
ValueError

If target_ndim < self.ndim.
identity classmethod 
identity(ndim: int = 3) -> Self

Return the identity transform.

Parameters:

Name Type Description Default
ndim int

Number of spatial dimensions (default 3).

 3
from_scale classmethod 
from_scale(scale: tuple[float, ...]) -> Self

Return a scale-only transform with no translation.

Parameters:

Name Type Description Default
scale tuple[float, ...]

Scale factors in data-axis order (axis0, axis1, ...).

 required

Returns:

Type Description
AffineTransform
from_scale_and_translation classmethod 
from_scale_and_translation(scale: tuple[float, ...], translation: tuple[float, ...] | None = None) -> Self

Create an AffineTransform from scale and translation parameters.

Parameters:

Name Type Description Default
scale tuple[float, ...]

Scale factors in data-axis order (axis0, axis1, ...).

 required
translation tuple[float, ...] or None

Translation in data-axis order. Default is all zeros.

 None

Returns:

Type Description
AffineTransform
from_translation classmethod 
from_translation(translation: tuple[float, ...]) -> Self

Create an AffineTransform from translation parameters.

Parameters:

Name Type Description Default
translation tuple[float, ...]

Translation in data-axis order (axis0, axis1, ...).

 required

Returns:

Type Description
AffineTransform
compose 
compose(other: AffineTransform) -> AffineTransform

Return a new transform: apply self first, then other.

self.compose(other).map_coordinates(p) is equivalent to other.map_coordinates(self.map_coordinates(p)).

Parameters:

Name Type Description Default
other AffineTransform

The transform to apply after self.

 required

Returns:

Type Description
AffineTransform

Raises:

Type Description
ValueError

If the two transforms have different ndim.
__matmul__ 
__matmul__(other: AffineTransform) -> AffineTransform

Compose transforms: (A @ B) applies A first, then B.

Parameters:

Name Type Description Default
other AffineTransform

The transform to apply after self.

 required

Returns:

Type Description
AffineTransform

BaseTransform pydantic-model

Bases: BaseModel, ABC

Base class for coordinate transforms.

All v2 transforms are frozen pydantic models. The signal for a transform change travels on the visual's EventedModel field, not on the transform itself.

Config:

  • frozen: True
  • arbitrary_types_allowed: True
map_coordinates abstractmethod 
map_coordinates(coordinates: ndarray) -> ndarray

Apply the forward transform to coordinates.

Parameters:

Name Type Description Default
coordinates ndarray

(n, ndim) or (n, ndim+1) array of points.

 required

Returns:

Type Description
ndarray

(n, ndim) transformed coordinates.
imap_coordinates abstractmethod 
imap_coordinates(coordinates: ndarray) -> ndarray

Apply the inverse transform to coordinates.

Parameters:

Name Type Description Default
coordinates ndarray

(n, ndim) or (n, ndim+1) array of points.

 required

Returns:

Type Description
ndarray

(n, ndim) transformed coordinates.
map_normal_vector abstractmethod 
map_normal_vector(normal_vector: ndarray) -> ndarray

Transform a normal vector from data space to world space.

Parameters:

Name Type Description Default
normal_vector ndarray

The normal vector(s) to be transformed.

 required

Returns:

Type Description
ndarray

The transformed normal vectors as unit vectors.
imap_normal_vector abstractmethod 
imap_normal_vector(normal_vector: ndarray) -> ndarray

Transform a normal vector from world space to data space.

Parameters:

Name Type Description Default
normal_vector ndarray

The normal vector(s) to be transformed.

 required

Returns:

Type Description
ndarray

The transformed normal vectors as unit vectors.