spacetransformer.core.transform
core.transform
4x4 homogeneous coordinate transformation matrices for 3D medical images.
This module provides the Transform class for representing and manipulating 4x4 homogeneous coordinate transformation matrices used in 3D medical image processing. The Transform class handles matrix operations, composition, and coordinate transformations.
Design Philosophy: Uses 4x4 homogeneous coordinates to represent both rotation and translation in a single matrix operation. This approach simplifies chaining multiple transformations and is numerically stable for medical imaging applications.
The class maintains references to source and target spaces for traceability
and validation, helping prevent coordinate system errors common in medical
image processing.Example: Basic transformation usage:
>>> import numpy as np
>>> from spacetransformer.core import Transform
>>> matrix = np.eye(4)
>>> transform = Transform(matrix)
>>> points = [[0, 0, 0], [1, 1, 1]]
>>> transformed = transform.apply_point(points)
>>> print(transformed)
[[0. 0. 0.]
[1. 1. 1.]]
Chaining transformations:
>>> T1 = Transform(np.eye(4))
>>> T2 = Transform(np.eye(4))
>>> combined = T2 @ T1 # Apply T1 first, then T2Classes
| Name | Description |
|---|---|
| Transform | 4x4 homogeneous coordinate transformation matrix wrapper. |
Transform
core.transform.Transform(matrix, source=None, target=None)4x4 homogeneous coordinate transformation matrix wrapper.
This class encapsulates a 4x4 transformation matrix and provides methods for applying transformations to points and vectors, computing inverses, and composing transformations.
Design Philosophy: The class is designed purely for geometric coordinate calculations without any resampling-related parameters. It maintains references to source and target spaces for traceability and validation.
Uses lazy evaluation for expensive operations like matrix inversion
and caches results for performance. The class is immutable except
for internal caching to ensure thread safety.Attributes: matrix: 4x4 transformation matrix (source.index → target.index or other) source: Source Space object (can be None for world coordinates) target: Target Space object (can be None for world coordinates)
Example: Creating and using a transformation:
>>> import numpy as np
>>> from spacetransformer.core import Transform
>>> matrix = np.array([[1, 0, 0, 10],
... [0, 1, 0, 20],
... [0, 0, 1, 30],
... [0, 0, 0, 1]])
>>> transform = Transform(matrix)
>>> point = [0, 0, 0]
>>> transformed = transform.apply_point(point)
>>> print(transformed)
[[10. 20. 30.]]Methods
| Name | Description |
|---|---|
| apply_point | Apply transformation to a set of points. |
| apply_vector | Apply transformation to a set of vectors (ignoring translation). |
| compose | Compose transformations with self applied first. |
| inverse | Return the inverse transformation (lazy computed and cached). |
apply_point
core.transform.Transform.apply_point(pts)Apply transformation to a set of points.
This method transforms 3D points using the 4x4 transformation matrix. Points are treated as having homogeneous coordinate w=1.0, so they are affected by both rotation and translation.
Args: pts: Input points with shape (N, 3) or (3,) for single point
Returns: np.ndarray: Transformed points with shape (N, 3)
Example: >>> import numpy as np >>> matrix = np.array([[1, 0, 0, 10], … [0, 1, 0, 20], … [0, 0, 1, 30], … [0, 0, 0, 1]]) >>> transform = Transform(matrix) >>> points = [[0, 0, 0], [1, 1, 1]] >>> transformed = transform.apply_point(points) >>> print(transformed) [[10. 20. 30.] [11. 21. 31.]]
apply_vector
core.transform.Transform.apply_vector(vecs)Apply transformation to a set of vectors (ignoring translation).
This method transforms 3D vectors using only the rotational part of the transformation matrix. Vectors are treated as having homogeneous coordinate w=0.0, so they are unaffected by translation.
Args: vecs: Input vectors with shape (N, 3) or (3,) for single vector
Returns: np.ndarray: Transformed vectors with shape (N, 3)
Example: >>> import numpy as np >>> matrix = np.array([[1, 0, 0, 10], # Translation has no effect … [0, 1, 0, 20], … [0, 0, 1, 30], … [0, 0, 0, 1]]) >>> transform = Transform(matrix) >>> vectors = [[1, 0, 0], [0, 1, 0]] >>> transformed = transform.apply_vector(vectors) >>> print(transformed) [[1. 0. 0.] [0. 1. 0.]]
compose
core.transform.Transform.compose(other)Compose transformations with self applied first.
This method provides an alternative composition interface where self.compose(other) means apply self first, then other.
Args: other: Transform to apply after self
Returns: Transform: Composed transformation representing self followed by other
Example: >>> import numpy as np >>> T1 = Transform(np.eye(4)) >>> T2 = Transform(np.eye(4)) >>> composed = T1.compose(T2) # Apply T1 first, then T2 >>> print(np.allclose(composed.matrix, np.eye(4))) True
inverse
core.transform.Transform.inverse()Return the inverse transformation (lazy computed and cached).
This method computes the inverse transformation matrix and caches the result for efficient repeated use. The inverse is computed using numpy’s linear algebra inverse function.
Returns: Transform: Inverse transformation with swapped source/target spaces
Example: >>> import numpy as np >>> matrix = np.array([[1, 0, 0, 10], … [0, 1, 0, 20], … [0, 0, 1, 30], … [0, 0, 0, 1]]) >>> transform = Transform(matrix) >>> inverse = transform.inverse() >>> print(inverse.matrix[0:3, 3]) # Should be [-10, -20, -30] [-10. -20. -30.]