transformnd.transforms

Implementations of some common transforms.

View Source

 1"""Implementations of some common transforms."""
 2
 3from .affine import Affine
 4from .reflection import Reflect
 5from .simple import Identity, Scale, Translate
 6from .map_axis import MapAxis
 7from .bijection import Bijection
 8from .project_axis import ProjectAxis
 9from .by_dimension import ByDimension, SubTransform
10from .vector_field import Coordinates, Displacements
11from .moving_least_squares import MovingLeastSquares
12from .thinplate import ThinPlateSplines
13
14__all__ = [
15    "Affine",
16    "Identity",
17    "ProjectAxis",
18    "Reflect",
19    "Scale",
20    "Translate",
21    "MapAxis",
22    "Bijection",
23    "ByDimension",
24    "SubTransform",
25    "Coordinates",
26    "Displacements",
27    "MovingLeastSquares",
28    "ThinPlateSplines",
29]

class Identity(transformnd.base.Transform[~ArrayT]): View Source

20class Identity(Transform[ArrayT]):
21    """No-op transformation."""
22
23    def __init__(
24        self,
25        ndim: int,
26        *,
27        spaces: Spaces = Spaces(None, None),
28    ):
29        """
30        Transform which does nothing.
31
32        Parameters
33        ----------
34        ndim:
35            Number of dimensions of this transform.
36        spaces:
37            Optional source and target spaces
38        """
39        src = chain_or(*spaces, default=None)
40        tgt = chain_or(*spaces[::-1], default=None)
41        super().__init__(NDims(ndim, ndim), spaces=Spaces(src, tgt))
42
43    def invert(self) -> Transform[ArrayT]:
44        return type(self)(self.ndims.source, spaces=self.spaces.invert())
45
46    def to_affine(self) -> Affine[ArrayT] | None:
47        return Affine[ArrayT].identity(self.ndims.source, spaces=self.spaces)
48
49    def apply(self, coords: ArrayT) -> ArrayT:
50        return coords

No-op transformation.

Identity( ndim: int, *, spaces: transformnd.Spaces = Spaces(source=None, target=None)) View Source

23    def __init__(
24        self,
25        ndim: int,
26        *,
27        spaces: Spaces = Spaces(None, None),
28    ):
29        """
30        Transform which does nothing.
31
32        Parameters
33        ----------
34        ndim:
35            Number of dimensions of this transform.
36        spaces:
37            Optional source and target spaces
38        """
39        src = chain_or(*spaces, default=None)
40        tgt = chain_or(*spaces[::-1], default=None)
41        super().__init__(NDims(ndim, ndim), spaces=Spaces(src, tgt))

Transform which does nothing.

Parameters

ndim:: Number of dimensions of this transform.
spaces:: Optional source and target spaces

def invert(self) -> transformnd.Transform[~ArrayT]: View Source

43    def invert(self) -> Transform[ArrayT]:
44        return type(self)(self.ndims.source, spaces=self.spaces.invert())

Invert the transformation, returning None if not possible.

def to_affine(self) -> Optional[Affine[~ArrayT]]: View Source

46    def to_affine(self) -> Affine[ArrayT] | None:
47        return Affine[ArrayT].identity(self.ndims.source, spaces=self.spaces)

Convert the transform into affine, if conversion is possible.

Returns

Affine[ArrayT] | None: The affine transformation, if conversion is possible. None otherwise.

def apply(self, coords: ~ArrayT) -> ~ArrayT: View Source

49    def apply(self, coords: ArrayT) -> ArrayT:
50        return coords

Apply transformation.

Parameters

coords: NxD array of N D-dimensional coordinates.

Returns

ArrayT: Transformed coordinates in the same shape.

class ProjectAxis(abc.ABC, typing.Generic[ArrayT]): View Source

 13class ProjectAxis(Transform):
 14    """Transform for adding and removing axes.
 15
 16    WARNING: inverting this transformation may be lossy.
 17    """
 18
 19    def __init__(
 20        self,
 21        dropped: set[int] | None = None,
 22        created: set[int] | None = None,
 23        source_ndim: int | None = None,
 24        target_ndim: int | None = None,
 25        *,
 26        spaces: Spaces = Spaces(None, None),
 27    ):
 28        """Create a transform for adding and dropping axes.
 29
 30        At least one of source_ndim and target_ndim must be given.
 31
 32        Parameters
 33        ----------
 34        dropped
 35            Set of INPUT dimension indices to drop, if any.
 36        created
 37            Set of OUTPUT dimension indices which are new, if any.
 38        source_ndim
 39            If omitted, can be inferred from `target_ndim`.
 40        target_ndim
 41            If omitted, can be inferred from `source_ndim`.
 42        spaces
 43            Identifiers for source and target spaces, by default Spaces(None, None)
 44
 45        Raises
 46        ------
 47        ValueError
 48            Operations are inconsistent with given dimensionality,
 49            or insufficient dimensionality information was given.
 50        """
 51        self.dropped = dropped or set()
 52        self.created = created or set()
 53
 54        if source_ndim is not None:
 55            nd = source_ndim - len(self.dropped) + len(self.created)
 56            if target_ndim is None:
 57                target_ndim = nd
 58            elif target_ndim != nd:
 59                raise ValueError("Operations do not match expected target ndim")
 60
 61        elif target_ndim is not None:
 62            nd = target_ndim - len(self.created) + len(self.dropped)
 63            if source_ndim is None:
 64                source_ndim = nd
 65            elif source_ndim != nd:
 66                raise ValueError("Operations do not match expected source ndim")
 67
 68        else:
 69            raise ValueError("At least one of source_ndim or target_ndim must be given")
 70
 71        idxs: list[int | None] = list(range(source_ndim))
 72        for drop in sorted(self.dropped, reverse=True):
 73            idxs.pop(drop)
 74        for create in sorted(self.created):
 75            idxs.insert(create, None)
 76        self._idxs = idxs
 77
 78        super().__init__(NDims(source_ndim, target_ndim), spaces=spaces)
 79
 80    def apply(self, coords: ArrayT) -> ArrayT:
 81        coords = self._validate_coords(coords)
 82        if self.created:
 83            xp = array_namespace(coords)
 84            out = xp.zeros_like(coords, shape=(xp.shape(coords)[0], self.ndims.target))
 85            for idx, orig_idx in enumerate(self._idxs):
 86                if orig_idx is not None:
 87                    out[:, idx] = coords[:, orig_idx]  # type:ignore
 88
 89        else:
 90            out = coords[:, self._idxs]  # type:ignore
 91        return out
 92
 93    def is_identity(self) -> bool:
 94        return not self.created and not self.dropped
 95
 96    def to_affine(self) -> Affine | None:
 97        m = np.eye(self.ndims.source)
 98        out_m = self.apply(m)
 99        return Affine.from_linear_map(out_m.T)
100
101    def invert(self) -> Self | None:
102        return type(self)(
103            self.created,
104            self.dropped,
105            source_ndim=self.ndims.target,
106            target_ndim=self.ndims.source,
107            spaces=self.spaces.invert(),
108        )

Transform for adding and removing axes.

WARNING: inverting this transformation may be lossy.

ProjectAxis( dropped: set[int] | None = None, created: set[int] | None = None, source_ndim: int | None = None, target_ndim: int | None = None, *, spaces: transformnd.Spaces = Spaces(source=None, target=None)) View Source

19    def __init__(
20        self,
21        dropped: set[int] | None = None,
22        created: set[int] | None = None,
23        source_ndim: int | None = None,
24        target_ndim: int | None = None,
25        *,
26        spaces: Spaces = Spaces(None, None),
27    ):
28        """Create a transform for adding and dropping axes.
29
30        At least one of source_ndim and target_ndim must be given.
31
32        Parameters
33        ----------
34        dropped
35            Set of INPUT dimension indices to drop, if any.
36        created
37            Set of OUTPUT dimension indices which are new, if any.
38        source_ndim
39            If omitted, can be inferred from `target_ndim`.
40        target_ndim
41            If omitted, can be inferred from `source_ndim`.
42        spaces
43            Identifiers for source and target spaces, by default Spaces(None, None)
44
45        Raises
46        ------
47        ValueError
48            Operations are inconsistent with given dimensionality,
49            or insufficient dimensionality information was given.
50        """
51        self.dropped = dropped or set()
52        self.created = created or set()
53
54        if source_ndim is not None:
55            nd = source_ndim - len(self.dropped) + len(self.created)
56            if target_ndim is None:
57                target_ndim = nd
58            elif target_ndim != nd:
59                raise ValueError("Operations do not match expected target ndim")
60
61        elif target_ndim is not None:
62            nd = target_ndim - len(self.created) + len(self.dropped)
63            if source_ndim is None:
64                source_ndim = nd
65            elif source_ndim != nd:
66                raise ValueError("Operations do not match expected source ndim")
67
68        else:
69            raise ValueError("At least one of source_ndim or target_ndim must be given")
70
71        idxs: list[int | None] = list(range(source_ndim))
72        for drop in sorted(self.dropped, reverse=True):
73            idxs.pop(drop)
74        for create in sorted(self.created):
75            idxs.insert(create, None)
76        self._idxs = idxs
77
78        super().__init__(NDims(source_ndim, target_ndim), spaces=spaces)

Create a transform for adding and dropping axes.

At least one of source_ndim and target_ndim must be given.

Parameters

dropped: Set of INPUT dimension indices to drop, if any.
created: Set of OUTPUT dimension indices which are new, if any.
source_ndim: If omitted, can be inferred from target_ndim.
target_ndim: If omitted, can be inferred from source_ndim.
spaces: Identifiers for source and target spaces, by default Spaces(None, None)

Raises

ValueError: Operations are inconsistent with given dimensionality, or insufficient dimensionality information was given.

def apply(self, coords: ~ArrayT) -> ~ArrayT: View Source

80    def apply(self, coords: ArrayT) -> ArrayT:
81        coords = self._validate_coords(coords)
82        if self.created:
83            xp = array_namespace(coords)
84            out = xp.zeros_like(coords, shape=(xp.shape(coords)[0], self.ndims.target))
85            for idx, orig_idx in enumerate(self._idxs):
86                if orig_idx is not None:
87                    out[:, idx] = coords[:, orig_idx]  # type:ignore
88
89        else:
90            out = coords[:, self._idxs]  # type:ignore
91        return out

Apply transformation.

Parameters

coords: NxD array of N D-dimensional coordinates.

Returns

ArrayT: Transformed coordinates in the same shape.

def is_identity(self) -> bool: View Source

93    def is_identity(self) -> bool:
94        return not self.created and not self.dropped

Whether this is a no-op transformation.

def to_affine(self) -> Affine | None: View Source

96    def to_affine(self) -> Affine | None:
97        m = np.eye(self.ndims.source)
98        out_m = self.apply(m)
99        return Affine.from_linear_map(out_m.T)

Convert the transform into affine, if conversion is possible.

Returns

Affine[ArrayT] | None: The affine transformation, if conversion is possible. None otherwise.

def invert(self) -> Optional[Self]: View Source

101    def invert(self) -> Self | None:
102        return type(self)(
103            self.created,
104            self.dropped,
105            source_ndim=self.ndims.target,
106            target_ndim=self.ndims.source,
107            spaces=self.spaces.invert(),
108        )

Invert the transformation, returning None if not possible.

class Reflect(transformnd.base.Transform[numpy.ndarray]): View Source

 87class Reflect(Transform[np.ndarray]):
 88    """Reflect coordinates about arbitrary planes."""
 89
 90    def __init__(
 91        self,
 92        normals: ArrayLike,
 93        point: float | ArrayLike = 0.0,
 94        *,
 95        spaces: Spaces = Spaces(None, None),
 96    ):
 97        """
 98        Parameters
 99        ----------
100        normals
101            Normal vectors to the planes of reflection.
102            Unitised internally.
103        point
104            Intersection point of all reflection planes
105            (can be broadcast from scalar), by default 0 (i.e. the origin)
106        spaces
107            Optional source and target spaces
108
109        Raises
110        ------
111        ValueError
112            Inconsistent dimensionality
113        """
114        normals = np.asarray(normals)
115        if normals.ndim == 1:
116            normals = [normals]
117
118        n1 = normals[0]
119        if (
120            not np.isscalar(point)
121            and isinstance(point, Sequence)
122            and len(n1) != len(point)
123        ):
124            raise ValueError("Point and normals are not of the same dimensionality")
125        self.point: np.ndarray = np.asarray(point, dtype=float)
126        self.ndim = {len(n1)}
127        self.normals = [unitise(n) for n in normals]
128        # todo: matmul is associative, so turn this into an affine in 2/3D?
129        super().__init__(NDims(len(n1), len(n1)), spaces=spaces)
130
131    def apply(self, coords: np.ndarray) -> np.ndarray:
132        coords = self._validate_coords(coords)
133        out = coords - self.point
134        for n in self.normals:
135            # mul->sum vectorises dot product
136            # normals are unit, avoids unnecessary division by 1
137            out -= 2 * np.sum(coords * n, axis=1) * n
138        out += self.point
139        return out
140
141    @classmethod
142    def from_points(
143        cls,
144        points: ArrayLike,
145        *,
146        spaces: Spaces = Spaces(None, None),
147    ) -> Self:
148        """Infer a single plane of reflection from a minimal number of points on it.
149
150        Parameters
151        ----------
152        points
153            NxD array of N points in D dimensions. N == D
154        spaces
155            Optional source and target spaces
156
157        Returns
158        -------
159        Self
160        """
161        point, normals = get_hyperplanes(np.asarray(points), unitise=False)
162        return cls(normals, point, spaces=spaces)
163
164    @classmethod
165    def from_axis(
166        cls,
167        axis: int | Sequence[int],
168        origin: ArrayLike,
169        *,
170        spaces: Spaces = Spaces(None, None),
171    ) -> Self:
172        """Reflect around hyperplane(s) parallel with axes.
173
174        Parameters
175        ----------
176        axis
177            Index (or indices) of axes in which to reflect.
178        origin
179            Point around which to reflect.
180        spaces
181            Optional source and target spaces
182
183        Returns
184        -------
185        Self
186
187        Raises
188        ------
189        ValueError
190            Selected axis does not exist.
191        """
192        origin = np.asarray(origin)
193        axis = ensure_tuple(axis)
194
195        for a in axis:
196            if a >= len(axis):
197                raise ValueError(
198                    "Cannot reflect in axis which does not exist (too high)"
199                )
200
201        normals = []
202        for i in range(len(origin) - len(axis) + 1):
203            if i not in axis:
204                v = np.zeros_like(origin)
205                v[i] += 1
206                normals.append(v)
207
208        return cls(normals, origin, spaces=spaces)
209
210    def invert(self) -> Self | None:
211        return copy(self)
212
213    def to_affine(self) -> Affine[np.ndarray] | None:
214        # TODO: should be possible?
215        # rotate to align plane with origin and reflect it
216        return None

Reflect coordinates about arbitrary planes.

Reflect( normals: ArrayLike, point: float | ArrayLike = 0.0, *, spaces: transformnd.Spaces = Spaces(source=None, target=None)) View Source

 90    def __init__(
 91        self,
 92        normals: ArrayLike,
 93        point: float | ArrayLike = 0.0,
 94        *,
 95        spaces: Spaces = Spaces(None, None),
 96    ):
 97        """
 98        Parameters
 99        ----------
100        normals
101            Normal vectors to the planes of reflection.
102            Unitised internally.
103        point
104            Intersection point of all reflection planes
105            (can be broadcast from scalar), by default 0 (i.e. the origin)
106        spaces
107            Optional source and target spaces
108
109        Raises
110        ------
111        ValueError
112            Inconsistent dimensionality
113        """
114        normals = np.asarray(normals)
115        if normals.ndim == 1:
116            normals = [normals]
117
118        n1 = normals[0]
119        if (
120            not np.isscalar(point)
121            and isinstance(point, Sequence)
122            and len(n1) != len(point)
123        ):
124            raise ValueError("Point and normals are not of the same dimensionality")
125        self.point: np.ndarray = np.asarray(point, dtype=float)
126        self.ndim = {len(n1)}
127        self.normals = [unitise(n) for n in normals]
128        # todo: matmul is associative, so turn this into an affine in 2/3D?
129        super().__init__(NDims(len(n1), len(n1)), spaces=spaces)

Parameters

normals: Normal vectors to the planes of reflection. Unitised internally.
point: Intersection point of all reflection planes (can be broadcast from scalar), by default 0 (i.e. the origin)
spaces: Optional source and target spaces

Raises

ValueError: Inconsistent dimensionality

def apply(self, coords: numpy.ndarray) -> numpy.ndarray: View Source

131    def apply(self, coords: np.ndarray) -> np.ndarray:
132        coords = self._validate_coords(coords)
133        out = coords - self.point
134        for n in self.normals:
135            # mul->sum vectorises dot product
136            # normals are unit, avoids unnecessary division by 1
137            out -= 2 * np.sum(coords * n, axis=1) * n
138        out += self.point
139        return out

Apply transformation.

Parameters

coords: NxD array of N D-dimensional coordinates.

Returns

ArrayT: Transformed coordinates in the same shape.

@classmethod

def from_points( cls, points: ArrayLike, *, spaces: transformnd.Spaces = Spaces(source=None, target=None)) -> Self: View Source

141    @classmethod
142    def from_points(
143        cls,
144        points: ArrayLike,
145        *,
146        spaces: Spaces = Spaces(None, None),
147    ) -> Self:
148        """Infer a single plane of reflection from a minimal number of points on it.
149
150        Parameters
151        ----------
152        points
153            NxD array of N points in D dimensions. N == D
154        spaces
155            Optional source and target spaces
156
157        Returns
158        -------
159        Self
160        """
161        point, normals = get_hyperplanes(np.asarray(points), unitise=False)
162        return cls(normals, point, spaces=spaces)

Infer a single plane of reflection from a minimal number of points on it.

Parameters

points: NxD array of N points in D dimensions. N == D
spaces: Optional source and target spaces

Returns

Self

@classmethod

def from_axis( cls, axis: int | Sequence[int], origin: ArrayLike, *, spaces: transformnd.Spaces = Spaces(source=None, target=None)) -> Self: View Source

164    @classmethod
165    def from_axis(
166        cls,
167        axis: int | Sequence[int],
168        origin: ArrayLike,
169        *,
170        spaces: Spaces = Spaces(None, None),
171    ) -> Self:
172        """Reflect around hyperplane(s) parallel with axes.
173
174        Parameters
175        ----------
176        axis
177            Index (or indices) of axes in which to reflect.
178        origin
179            Point around which to reflect.
180        spaces
181            Optional source and target spaces
182
183        Returns
184        -------
185        Self
186
187        Raises
188        ------
189        ValueError
190            Selected axis does not exist.
191        """
192        origin = np.asarray(origin)
193        axis = ensure_tuple(axis)
194
195        for a in axis:
196            if a >= len(axis):
197                raise ValueError(
198                    "Cannot reflect in axis which does not exist (too high)"
199                )
200
201        normals = []
202        for i in range(len(origin) - len(axis) + 1):
203            if i not in axis:
204                v = np.zeros_like(origin)
205                v[i] += 1
206                normals.append(v)
207
208        return cls(normals, origin, spaces=spaces)

Reflect around hyperplane(s) parallel with axes.

Parameters

axis: Index (or indices) of axes in which to reflect.
origin: Point around which to reflect.
spaces: Optional source and target spaces

Returns

Self

Raises

ValueError: Selected axis does not exist.

def invert(self) -> Optional[Self]: View Source

210    def invert(self) -> Self | None:
211        return copy(self)

Invert the transformation, returning None if not possible.

def to_affine(self) -> Optional[Affine[numpy.ndarray]]: View Source

213    def to_affine(self) -> Affine[np.ndarray] | None:
214        # TODO: should be possible?
215        # rotate to align plane with origin and reflect it
216        return None

Convert the transform into affine, if conversion is possible.

Returns

Affine[ArrayT] | None: The affine transformation, if conversion is possible. None otherwise.

class Scale(transformnd.base.Transform[~ArrayT]): View Source

103class Scale(Transform[ArrayT]):
104    """Scale coordinates by multiplication."""
105
106    def __init__(
107        self,
108        scale: ArrayLike,
109        *,
110        spaces: Spaces = Spaces(None, None),
111    ):
112        """Simple scale transform.
113
114        All points are scaled, i.e. distance from the origin may also change.
115
116        Parameters
117        ----------
118        scale
119            Scaling to apply in all dimensions, or each dimension.
120        spaces
121            Optional source and target spaces
122
123        Raises
124        ------
125        ValueError
126            If scale is the wrong shape.
127        """
128        self.scale = as_floats(scale)
129        if self.scale.ndim != 1:
130            raise ValueError(f"Scale must be 1D, got shape {self.scale.shape}")
131        super().__init__(NDims(len(self.scale), len(self.scale)), spaces=spaces)
132
133    def to_affine(self) -> Affine[ArrayT] | None:
134        return Affine[ArrayT].scaling(self.scale, spaces=self.spaces)
135
136    def apply(self, coords: ArrayT) -> ArrayT:
137        coords = self._validate_coords(coords)
138        xp = array_namespace(coords)
139        d = xp_device(coords)
140        return coords * xp.asarray(self.scale, device=d)
141
142    def invert(self) -> Self | None:
143        return type(self)(
144            1 / self.scale,
145            spaces=self.spaces.invert(),
146        )
147
148    def to_device(self, xp: ModuleType, device: str | None = None) -> Self:
149        result = copy(self)
150        result.scale = xp.asarray(self.scale, device=device)
151        return result

Scale coordinates by multiplication.

Scale( scale: ArrayLike, *, spaces: transformnd.Spaces = Spaces(source=None, target=None)) View Source

106    def __init__(
107        self,
108        scale: ArrayLike,
109        *,
110        spaces: Spaces = Spaces(None, None),
111    ):
112        """Simple scale transform.
113
114        All points are scaled, i.e. distance from the origin may also change.
115
116        Parameters
117        ----------
118        scale
119            Scaling to apply in all dimensions, or each dimension.
120        spaces
121            Optional source and target spaces
122
123        Raises
124        ------
125        ValueError
126            If scale is the wrong shape.
127        """
128        self.scale = as_floats(scale)
129        if self.scale.ndim != 1:
130            raise ValueError(f"Scale must be 1D, got shape {self.scale.shape}")
131        super().__init__(NDims(len(self.scale), len(self.scale)), spaces=spaces)

Simple scale transform.

All points are scaled, i.e. distance from the origin may also change.

Parameters

scale: Scaling to apply in all dimensions, or each dimension.
spaces: Optional source and target spaces

Raises

ValueError: If scale is the wrong shape.

def to_affine(self) -> Optional[Affine[~ArrayT]]: View Source

133    def to_affine(self) -> Affine[ArrayT] | None:
134        return Affine[ArrayT].scaling(self.scale, spaces=self.spaces)

Convert the transform into affine, if conversion is possible.

Returns

Affine[ArrayT] | None: The affine transformation, if conversion is possible. None otherwise.

def apply(self, coords: ~ArrayT) -> ~ArrayT: View Source

136    def apply(self, coords: ArrayT) -> ArrayT:
137        coords = self._validate_coords(coords)
138        xp = array_namespace(coords)
139        d = xp_device(coords)
140        return coords * xp.asarray(self.scale, device=d)

Apply transformation.

Parameters

coords: NxD array of N D-dimensional coordinates.

Returns

ArrayT: Transformed coordinates in the same shape.

def invert(self) -> Optional[Self]: View Source

142    def invert(self) -> Self | None:
143        return type(self)(
144            1 / self.scale,
145            spaces=self.spaces.invert(),
146        )

Invert the transformation, returning None if not possible.

def to_device(self, xp: module, device: str | None = None) -> Self: View Source

148    def to_device(self, xp: ModuleType, device: str | None = None) -> Self:
149        result = copy(self)
150        result.scale = xp.asarray(self.scale, device=device)
151        return result

Return a copy of this transform with array parameters placed on the given device.

Useful for pre-allocating parameters on GPU before a tight apply() loop, avoiding per-call host-to-device transfers.

Parameters

xp: The target array namespace (e.g. jax.numpy, torch).
device: Target device (e.g. from array_api_compat.device(array)). If None, uses xp's default device.

Returns

Self: A new transform instance with parameters on the target device, or NotImplemented if the subclass does not support device placement.

class Translate(transformnd.base.Transform[~ArrayT]): View Source

 53class Translate(Transform[ArrayT]):
 54    """Translate coordinates by addition."""
 55
 56    def __init__(
 57        self,
 58        translation: ArrayLike,
 59        *,
 60        spaces: Spaces = Spaces(None, None),
 61    ):
 62        """Simple translation.
 63
 64        Parameters
 65        ----------
 66        translation
 67            Translation to apply in all dimensions, or each dimension.
 68        spaces
 69            Optional source and target spaces
 70
 71        Raises
 72        ------
 73        ValueError
 74            If the translation is the wrong shape
 75        """
 76        self.translation = as_floats(translation)
 77        if self.translation.ndim != 1:
 78            raise ValueError(
 79                f"Translation must be 1D, got shape {self.translation.shape}"
 80            )
 81        super().__init__(
 82            NDims(len(self.translation), len(self.translation)), spaces=spaces
 83        )
 84
 85    def to_affine(self) -> Affine[ArrayT] | None:
 86        return Affine[ArrayT].translation(self.translation, spaces=self.spaces)
 87
 88    def apply(self, coords: ArrayT) -> ArrayT:
 89        coords = self._validate_coords(coords)
 90        xp = array_namespace(coords)
 91        d = xp_device(coords)
 92        return coords + xp.asarray(self.translation, device=d)
 93
 94    def invert(self) -> Transform | None:
 95        return type(self)(-self.translation, spaces=self.spaces.invert())
 96
 97    def to_device(self, xp: ModuleType, device: str | None = None) -> Self:
 98        result = copy(self)
 99        result.translation = xp.asarray(self.translation, device=device)
100        return result

Translate coordinates by addition.

Translate( translation: ArrayLike, *, spaces: transformnd.Spaces = Spaces(source=None, target=None)) View Source

56    def __init__(
57        self,
58        translation: ArrayLike,
59        *,
60        spaces: Spaces = Spaces(None, None),
61    ):
62        """Simple translation.
63
64        Parameters
65        ----------
66        translation
67            Translation to apply in all dimensions, or each dimension.
68        spaces
69            Optional source and target spaces
70
71        Raises
72        ------
73        ValueError
74            If the translation is the wrong shape
75        """
76        self.translation = as_floats(translation)
77        if self.translation.ndim != 1:
78            raise ValueError(
79                f"Translation must be 1D, got shape {self.translation.shape}"
80            )
81        super().__init__(
82            NDims(len(self.translation), len(self.translation)), spaces=spaces
83        )

Simple translation.

Parameters

translation: Translation to apply in all dimensions, or each dimension.
spaces: Optional source and target spaces

Raises

ValueError: If the translation is the wrong shape

def to_affine(self) -> Optional[Affine[~ArrayT]]: View Source

85    def to_affine(self) -> Affine[ArrayT] | None:
86        return Affine[ArrayT].translation(self.translation, spaces=self.spaces)

Convert the transform into affine, if conversion is possible.

Returns

Affine[ArrayT] | None: The affine transformation, if conversion is possible. None otherwise.

def apply(self, coords: ~ArrayT) -> ~ArrayT: View Source

88    def apply(self, coords: ArrayT) -> ArrayT:
89        coords = self._validate_coords(coords)
90        xp = array_namespace(coords)
91        d = xp_device(coords)
92        return coords + xp.asarray(self.translation, device=d)

Apply transformation.

Parameters

coords: NxD array of N D-dimensional coordinates.

Returns

ArrayT: Transformed coordinates in the same shape.

def invert(self) -> transformnd.Transform | None: View Source

94    def invert(self) -> Transform | None:
95        return type(self)(-self.translation, spaces=self.spaces.invert())

Invert the transformation, returning None if not possible.

def to_device(self, xp: module, device: str | None = None) -> Self: View Source

 97    def to_device(self, xp: ModuleType, device: str | None = None) -> Self:
 98        result = copy(self)
 99        result.translation = xp.asarray(self.translation, device=device)
100        return result

Return a copy of this transform with array parameters placed on the given device.

Useful for pre-allocating parameters on GPU before a tight apply() loop, avoiding per-call host-to-device transfers.

Parameters

xp: The target array namespace (e.g. jax.numpy, torch).
device: Target device (e.g. from array_api_compat.device(array)). If None, uses xp's default device.

Returns

Self: A new transform instance with parameters on the target device, or NotImplemented if the subclass does not support device placement.

class MapAxis(transformnd.base.Transform[~ArrayT]): View Source

12class MapAxis(Transform[ArrayT]):
13    """Map coordinates from one axis to another.
14
15    For example, x -> y and y -> x"""
16
17    def __init__(
18        self,
19        permutation: list[int],
20        *,
21        spaces: Spaces = Spaces(None, None),
22    ):
23        """Base class for transformations.
24
25        Parameters
26        ----------
27        permutation
28            New order of column axis. For example, [1, 0] means x -> y and y -> x.
29        spaces
30            Optional source and target spaces
31
32        Raises
33        ------
34        ValueError
35            If permutation does not contain all dimensions [0, N) exactly once.
36        """
37        s_perm = sorted(permutation)
38        if any(a != b for a, b in enumerate(s_perm)):
39            raise ValueError(
40                "N-D permutation must contain all dimensions [0, N) exactly once"
41            )
42        self.permutation = permutation
43        super().__init__(NDims(len(permutation), len(permutation)), spaces=spaces)
44
45    def is_identity(self) -> bool:
46        return all(a == b for a, b in enumerate(self.permutation))
47
48    def to_affine(self) -> Affine[ArrayT] | None:
49        m = np.eye(self.ndims.source)
50        m = m[self.permutation, :]
51        return Affine.from_linear_map(m, spaces=self.spaces)  # type: ignore
52
53    def apply(self, coords: ArrayT) -> ArrayT:
54        """Apply transformation to coordinates.
55
56        For example:
57        2-D with permutation [1, 0] will give you
58        [[x1, y1], [x2, y2]] -> [[y1, x1], [y2, x2]]
59        """
60
61        coords = self._validate_coords(coords)
62        xp = array_namespace(coords)
63        return xp.take(coords, self.permutation, 1)
64
65    def invert(self) -> Self | None:
66        return type(self)(
67            list(np.argsort(self.permutation)),
68            spaces=self.spaces.invert(),
69        )

Map coordinates from one axis to another.

For example, x -> y and y -> x

MapAxis( permutation: list[int], *, spaces: transformnd.Spaces = Spaces(source=None, target=None)) View Source

17    def __init__(
18        self,
19        permutation: list[int],
20        *,
21        spaces: Spaces = Spaces(None, None),
22    ):
23        """Base class for transformations.
24
25        Parameters
26        ----------
27        permutation
28            New order of column axis. For example, [1, 0] means x -> y and y -> x.
29        spaces
30            Optional source and target spaces
31
32        Raises
33        ------
34        ValueError
35            If permutation does not contain all dimensions [0, N) exactly once.
36        """
37        s_perm = sorted(permutation)
38        if any(a != b for a, b in enumerate(s_perm)):
39            raise ValueError(
40                "N-D permutation must contain all dimensions [0, N) exactly once"
41            )
42        self.permutation = permutation
43        super().__init__(NDims(len(permutation), len(permutation)), spaces=spaces)

Base class for transformations.

Parameters

permutation: New order of column axis. For example, [1, 0] means x -> y and y -> x.
spaces: Optional source and target spaces

Raises

ValueError: If permutation does not contain all dimensions [0, N) exactly once.

def is_identity(self) -> bool: View Source

45    def is_identity(self) -> bool:
46        return all(a == b for a, b in enumerate(self.permutation))

Whether this is a no-op transformation.

def to_affine(self) -> Optional[Affine[~ArrayT]]: View Source

48    def to_affine(self) -> Affine[ArrayT] | None:
49        m = np.eye(self.ndims.source)
50        m = m[self.permutation, :]
51        return Affine.from_linear_map(m, spaces=self.spaces)  # type: ignore

Convert the transform into affine, if conversion is possible.

Returns

Affine[ArrayT] | None: The affine transformation, if conversion is possible. None otherwise.

def apply(self, coords: ~ArrayT) -> ~ArrayT: View Source

53    def apply(self, coords: ArrayT) -> ArrayT:
54        """Apply transformation to coordinates.
55
56        For example:
57        2-D with permutation [1, 0] will give you
58        [[x1, y1], [x2, y2]] -> [[y1, x1], [y2, x2]]
59        """
60
61        coords = self._validate_coords(coords)
62        xp = array_namespace(coords)
63        return xp.take(coords, self.permutation, 1)

Apply transformation to coordinates.

For example: 2-D with permutation [1, 0] will give you [[x1, y1], [x2, y2]] -> [[y1, x1], [y2, x2]]

def invert(self) -> Optional[Self]: View Source

65    def invert(self) -> Self | None:
66        return type(self)(
67            list(np.argsort(self.permutation)),
68            spaces=self.spaces.invert(),
69        )

Invert the transformation, returning None if not possible.

class Bijection(transformnd.base.Transform[~ArrayT]): View Source

13class Bijection(Transform[ArrayT]):
14    """Map coordinates from one axis to another.
15
16    For example, x -> y and y -> x"""
17
18    def __init__(
19        self,
20        forward: Transform[ArrayT],
21        inverse: Transform[ArrayT],
22        *,
23        spaces: Spaces = Spaces(None, None),
24    ):
25        """Base class for transformations.
26
27        Parameters
28        ----------
29        forward
30            The forward transformation.
31        inverse
32            The inverse transformation.
33        spaces
34            Optional source and target spaces
35
36        Raises
37        ------
38        ValueError
39            If the forward and inverse dimensionalities don't match.
40        """
41        src = same_or_none(
42            spaces.source, forward.spaces.source, inverse.spaces.target, default=None
43        )
44        tgt = same_or_none(
45            spaces.target, forward.spaces.target, inverse.spaces.source, default=None
46        )
47
48        self.forward = forward
49        self.inverse = inverse
50        if forward.ndims != inverse.ndims.invert():
51            raise ValueError(
52                f"Bijection dimensionalities mismatch: fwd:{forward.ndims}, inv:{inverse.ndims}"
53            )
54        super().__init__(self.forward.ndims, spaces=Spaces(src, tgt))
55
56    def apply(self, coords: ArrayT) -> ArrayT:
57        return self.forward.apply(coords)
58
59    def invert(self) -> Self | None:
60        return type(self)(self.inverse, self.forward, spaces=self.spaces.invert())
61
62    def is_identity(self) -> bool:
63        return self.forward.is_identity() and self.inverse.is_identity()
64
65    def to_affine(self) -> Affine[ArrayT] | None:
66        fwd = self.forward.to_affine()
67        if fwd is None:
68            return None
69        inv = self.inverse.to_affine()
70        if inv is None:
71            return None
72
73        inv_inv = inv.invert()
74        if inv_inv is None:
75            return None
76
77        xp = array_namespace(fwd.matrix)
78        if xp.equal(fwd.matrix, inv_inv.matrix):
79            return fwd
80
81        return None

Map coordinates from one axis to another.

For example, x -> y and y -> x

Bijection( forward: transformnd.Transform[~ArrayT], inverse: transformnd.Transform[~ArrayT], *, spaces: transformnd.Spaces = Spaces(source=None, target=None)) View Source

18    def __init__(
19        self,
20        forward: Transform[ArrayT],
21        inverse: Transform[ArrayT],
22        *,
23        spaces: Spaces = Spaces(None, None),
24    ):
25        """Base class for transformations.
26
27        Parameters
28        ----------
29        forward
30            The forward transformation.
31        inverse
32            The inverse transformation.
33        spaces
34            Optional source and target spaces
35
36        Raises
37        ------
38        ValueError
39            If the forward and inverse dimensionalities don't match.
40        """
41        src = same_or_none(
42            spaces.source, forward.spaces.source, inverse.spaces.target, default=None
43        )
44        tgt = same_or_none(
45            spaces.target, forward.spaces.target, inverse.spaces.source, default=None
46        )
47
48        self.forward = forward
49        self.inverse = inverse
50        if forward.ndims != inverse.ndims.invert():
51            raise ValueError(
52                f"Bijection dimensionalities mismatch: fwd:{forward.ndims}, inv:{inverse.ndims}"
53            )
54        super().__init__(self.forward.ndims, spaces=Spaces(src, tgt))

Base class for transformations.

Parameters

forward: The forward transformation.
inverse: The inverse transformation.
spaces: Optional source and target spaces

Raises

ValueError: If the forward and inverse dimensionalities don't match.

def apply(self, coords: ~ArrayT) -> ~ArrayT: View Source

56    def apply(self, coords: ArrayT) -> ArrayT:
57        return self.forward.apply(coords)

Apply transformation.

Parameters

coords: NxD array of N D-dimensional coordinates.

Returns

ArrayT: Transformed coordinates in the same shape.

def invert(self) -> Optional[Self]: View Source

59    def invert(self) -> Self | None:
60        return type(self)(self.inverse, self.forward, spaces=self.spaces.invert())

Invert the transformation, returning None if not possible.

def is_identity(self) -> bool: View Source

62    def is_identity(self) -> bool:
63        return self.forward.is_identity() and self.inverse.is_identity()

Whether this is a no-op transformation.

def to_affine(self) -> Optional[Affine[~ArrayT]]: View Source

65    def to_affine(self) -> Affine[ArrayT] | None:
66        fwd = self.forward.to_affine()
67        if fwd is None:
68            return None
69        inv = self.inverse.to_affine()
70        if inv is None:
71            return None
72
73        inv_inv = inv.invert()
74        if inv_inv is None:
75            return None
76
77        xp = array_namespace(fwd.matrix)
78        if xp.equal(fwd.matrix, inv_inv.matrix):
79            return fwd
80
81        return None

Convert the transform into affine, if conversion is possible.

Returns

Affine[ArrayT] | None: The affine transformation, if conversion is possible. None otherwise.

class ByDimension(transformnd.base.Transform[~ArrayT]): View Source

 63class ByDimension(Transform[ArrayT]):
 64    """Apply transformations to subsets of the coordinates' dimensions.
 65
 66    Adapted from: https://ngff.openmicroscopy.org/specifications/dev/index.html#bydimension
 67    """
 68
 69    def __init__(
 70        self,
 71        subtransforms: list[SubTransform[ArrayT]],
 72        fill_identity: int | None = None,
 73        *,
 74        spaces: Spaces = Spaces(None, None),
 75    ):
 76        """
 77        Parameters
 78        ----------
 79        subtransforms
 80            Transformations applying to subsets of the given coordinates.
 81        fill_identity
 82            If not None, fill any missing input and output axes with identity transforms in order, up to a maximum number of dimensions.
 83            e.g. if you have XYT imates which you only want to transform in XY, provide the XY subtransformations and `fill_identity=3`.
 84        spaces
 85            Optional source and target spaces
 86
 87        Raises
 88        ------
 89        ValueError
 90            If input or output axes are not valid.
 91        """
 92        if fill_identity is not None:
 93            to_fill_in = set(range(fill_identity))
 94            to_fill_out = set(range(fill_identity))
 95            for t in subtransforms:
 96                for i in t.input_axes:
 97                    try:
 98                        to_fill_in.remove(i)
 99                    except KeyError:
100                        pass
101                for i in t.output_axes:
102                    try:
103                        to_fill_out.remove(i)
104                    except KeyError:
105                        pass
106            subtransforms.append(
107                SubTransform(
108                    Identity(len(to_fill_in)), sorted(to_fill_in), sorted(to_fill_out)
109                )
110            )
111
112        # check that input and output axes of sub transforms are disjoint
113        sorted_in = sorted(ax for t in subtransforms for ax in t.input_axes)
114        if sorted_in != list(range(len(sorted_in))):
115            raise ValueError("N-length input axes must go from 0 to N-1")
116
117        sorted_out = sorted(ax for t in subtransforms for ax in t.output_axes)
118
119        if sorted_out != list(range(len(sorted_out))):
120            raise ValueError("N-length output axes must go from 0 to N-1")
121
122        super().__init__(NDims(len(sorted_in), len(sorted_out)), spaces=spaces)
123        self.subtransforms = subtransforms
124
125    def apply(self, coords: ArrayT) -> ArrayT:
126        """Apply transformation to subset of coordinates."""
127        coords = self._validate_coords(coords)
128        xp = array_namespace(coords)
129        output = xp.empty_like(coords)
130        for t in self.subtransforms:
131            transformed = t.transform.apply(xp.take(coords, t.input_axes, 1))
132            for idx, o in enumerate(t.output_axes):
133                output[:, o] = transformed[:, idx]  # type: ignore
134        return output
135
136    def invert(self) -> Transform[ArrayT] | None:
137        try:
138            inverted_transforms = [
139                SubTransform[ArrayT](
140                    input_axes=t.output_axes,
141                    output_axes=t.input_axes,
142                    transform=~t.transform,
143                )
144                for t in reversed(self.subtransforms)
145            ]
146        except NotImplementedError:
147            return None
148
149        return type(self)(
150            subtransforms=inverted_transforms,
151            spaces=self.spaces.invert(),
152        )
153
154    def is_identity(self) -> bool:
155        for t in self.subtransforms:
156            if t.input_axes != t.output_axes or not t.transform.is_identity():
157                return False
158        return True

Apply transformations to subsets of the coordinates' dimensions.

Adapted from: https://ngff.openmicroscopy.org/specifications/dev/index.html#bydimension

ByDimension( subtransforms: list[SubTransform[~ArrayT]], fill_identity: int | None = None, *, spaces: transformnd.Spaces = Spaces(source=None, target=None)) View Source

 69    def __init__(
 70        self,
 71        subtransforms: list[SubTransform[ArrayT]],
 72        fill_identity: int | None = None,
 73        *,
 74        spaces: Spaces = Spaces(None, None),
 75    ):
 76        """
 77        Parameters
 78        ----------
 79        subtransforms
 80            Transformations applying to subsets of the given coordinates.
 81        fill_identity
 82            If not None, fill any missing input and output axes with identity transforms in order, up to a maximum number of dimensions.
 83            e.g. if you have XYT imates which you only want to transform in XY, provide the XY subtransformations and `fill_identity=3`.
 84        spaces
 85            Optional source and target spaces
 86
 87        Raises
 88        ------
 89        ValueError
 90            If input or output axes are not valid.
 91        """
 92        if fill_identity is not None:
 93            to_fill_in = set(range(fill_identity))
 94            to_fill_out = set(range(fill_identity))
 95            for t in subtransforms:
 96                for i in t.input_axes:
 97                    try:
 98                        to_fill_in.remove(i)
 99                    except KeyError:
100                        pass
101                for i in t.output_axes:
102                    try:
103                        to_fill_out.remove(i)
104                    except KeyError:
105                        pass
106            subtransforms.append(
107                SubTransform(
108                    Identity(len(to_fill_in)), sorted(to_fill_in), sorted(to_fill_out)
109                )
110            )
111
112        # check that input and output axes of sub transforms are disjoint
113        sorted_in = sorted(ax for t in subtransforms for ax in t.input_axes)
114        if sorted_in != list(range(len(sorted_in))):
115            raise ValueError("N-length input axes must go from 0 to N-1")
116
117        sorted_out = sorted(ax for t in subtransforms for ax in t.output_axes)
118
119        if sorted_out != list(range(len(sorted_out))):
120            raise ValueError("N-length output axes must go from 0 to N-1")
121
122        super().__init__(NDims(len(sorted_in), len(sorted_out)), spaces=spaces)
123        self.subtransforms = subtransforms

Parameters

subtransforms: Transformations applying to subsets of the given coordinates.
fill_identity: If not None, fill any missing input and output axes with identity transforms in order, up to a maximum number of dimensions. e.g. if you have XYT imates which you only want to transform in XY, provide the XY subtransformations and fill_identity=3.
spaces: Optional source and target spaces

Raises

ValueError: If input or output axes are not valid.

def apply(self, coords: ~ArrayT) -> ~ArrayT: View Source

125    def apply(self, coords: ArrayT) -> ArrayT:
126        """Apply transformation to subset of coordinates."""
127        coords = self._validate_coords(coords)
128        xp = array_namespace(coords)
129        output = xp.empty_like(coords)
130        for t in self.subtransforms:
131            transformed = t.transform.apply(xp.take(coords, t.input_axes, 1))
132            for idx, o in enumerate(t.output_axes):
133                output[:, o] = transformed[:, idx]  # type: ignore
134        return output

Apply transformation to subset of coordinates.

def invert(self) -> Optional[transformnd.Transform[~ArrayT]]: View Source

136    def invert(self) -> Transform[ArrayT] | None:
137        try:
138            inverted_transforms = [
139                SubTransform[ArrayT](
140                    input_axes=t.output_axes,
141                    output_axes=t.input_axes,
142                    transform=~t.transform,
143                )
144                for t in reversed(self.subtransforms)
145            ]
146        except NotImplementedError:
147            return None
148
149        return type(self)(
150            subtransforms=inverted_transforms,
151            spaces=self.spaces.invert(),
152        )

Invert the transformation, returning None if not possible.

def is_identity(self) -> bool: View Source

154    def is_identity(self) -> bool:
155        for t in self.subtransforms:
156            if t.input_axes != t.output_axes or not t.transform.is_identity():
157                return False
158        return True

Whether this is a no-op transformation.

class SubTransform(typing.Generic[ArrayT]): View Source

11class SubTransform[ArrayT]:
12    """Component of the `ByDimension` transformation.
13
14    Transformation to apply to subsets of the input dimensions and which output dimensions they calculate.
15    """
16
17    def __init__(
18        self,
19        transform: Transform[ArrayT],
20        input_axes: list[int],
21        output_axes: list[int] | None = None,
22    ):
23        """
24        Parameters
25        ----------
26        transform
27            Transformation to apply to the subset of axes.
28        input_axes
29            Which axes to apply the transformation to, in order.
30            The length must match the input dimensionality of `transform`.
31        output_axes
32            Which axes to apply the transformation to, in order.
33            The length must match the input dimensionality of `transform`.
34            If None, re-use the input axes.
35
36        Raises
37        ------
38        ValueError
39            `transform`'s dimensionality does not match the input/output axes.
40        """
41
42        self.input_axes = input_axes
43        if output_axes is None:
44            self.output_axes = input_axes
45        else:
46            self.output_axes = output_axes
47
48        in_ndim = len(self.input_axes)
49        out_ndim = len(self.output_axes)
50
51        if transform.ndims.source != in_ndim:
52            raise ValueError(
53                f"Subtransform input dimensionality ({transform.ndims.source}) must match length of input_axes"
54            )
55        if transform.ndims.target != out_ndim:
56            raise ValueError(
57                f"Subtransform output dimensionality ({transform.ndims.target}) must match length of output_axes"
58            )
59
60        self.transform = transform

Component of the ByDimension transformation.

Transformation to apply to subsets of the input dimensions and which output dimensions they calculate.

SubTransform( transform: transformnd.Transform[ArrayT], input_axes: list[int], output_axes: list[int] | None = None) View Source

17    def __init__(
18        self,
19        transform: Transform[ArrayT],
20        input_axes: list[int],
21        output_axes: list[int] | None = None,
22    ):
23        """
24        Parameters
25        ----------
26        transform
27            Transformation to apply to the subset of axes.
28        input_axes
29            Which axes to apply the transformation to, in order.
30            The length must match the input dimensionality of `transform`.
31        output_axes
32            Which axes to apply the transformation to, in order.
33            The length must match the input dimensionality of `transform`.
34            If None, re-use the input axes.
35
36        Raises
37        ------
38        ValueError
39            `transform`'s dimensionality does not match the input/output axes.
40        """
41
42        self.input_axes = input_axes
43        if output_axes is None:
44            self.output_axes = input_axes
45        else:
46            self.output_axes = output_axes
47
48        in_ndim = len(self.input_axes)
49        out_ndim = len(self.output_axes)
50
51        if transform.ndims.source != in_ndim:
52            raise ValueError(
53                f"Subtransform input dimensionality ({transform.ndims.source}) must match length of input_axes"
54            )
55        if transform.ndims.target != out_ndim:
56            raise ValueError(
57                f"Subtransform output dimensionality ({transform.ndims.target}) must match length of output_axes"
58            )
59
60        self.transform = transform

Parameters

transform: Transformation to apply to the subset of axes.
input_axes: Which axes to apply the transformation to, in order. The length must match the input dimensionality of transform.
output_axes: Which axes to apply the transformation to, in order. The length must match the input dimensionality of transform. If None, re-use the input axes.

Raises

ValueError: transform's dimensionality does not match the input/output axes.

class Coordinates(transformnd.transforms.vector_field.BaseVectorField[~ArrayT]): View Source

130class Coordinates(BaseVectorField[ArrayT]):
131    """Look up the output coordinates in an array.
132
133    For input coordinate `(a, b, c)` and `vector_axis=-1`,
134    the output coordinate is `vector_field[a, b, c, :].
135
136    Input coordinates outside the vector field return NaN.
137
138    REQUIRES: `vectorfield` extra for in-memory,
139    or `vectorfield-dask` extra for lazy chunked vector fields.
140    """
141
142    def __init__(
143        self,
144        vector_field: ArrayT,
145        index_transform: Transform[ArrayT] | None = None,
146        interpolation_order: int = 3,
147        vector_axis: int = -1,
148        *,
149        spaces: Spaces = Spaces(None, None),
150    ):
151        """Use the input coordinates as array indices to look up output coordinates.
152
153        For input coordinate `(a, b, c)`, the output coordinate is `coordinates[a, b, c, :]`.
154
155        Input coordinates outside of the `vector_field` array return `NaN` output coordinates.
156
157        Parameters
158        ----------
159        vector_field
160            Array with `Di + 1` dimensions, where `Di` is the input dimensionality.
161        index_transform
162            Transform the source coordinates into an array index
163        interpolation_order
164            Order of the spline interpolation used for coordinates which are not integer array indices.
165        vector_axis
166            Which axis of the `vector_field` contains the vector values; defaults to the last (`-1`).
167        spaces
168            References for source and target spaces
169        """
170        super().__init__(
171            vector_field,
172            index_transform,
173            interpolation_order,
174            vector_axis,
175            spaces=spaces,
176        )
177
178    def apply(self, coords: ArrayT) -> ArrayT:
179        return self._get_vectors(coords)

Look up the output coordinates in an array.

For input coordinate (a, b, c) and vector_axis=-1, the output coordinate is `vector_field[a, b, c, :].

Input coordinates outside the vector field return NaN.

REQUIRES: vectorfield extra for in-memory, or vectorfield-dask extra for lazy chunked vector fields.

Coordinates( vector_field: ~ArrayT, index_transform: Optional[transformnd.Transform[~ArrayT]] = None, interpolation_order: int = 3, vector_axis: int = -1, *, spaces: transformnd.Spaces = Spaces(source=None, target=None)) View Source

142    def __init__(
143        self,
144        vector_field: ArrayT,
145        index_transform: Transform[ArrayT] | None = None,
146        interpolation_order: int = 3,
147        vector_axis: int = -1,
148        *,
149        spaces: Spaces = Spaces(None, None),
150    ):
151        """Use the input coordinates as array indices to look up output coordinates.
152
153        For input coordinate `(a, b, c)`, the output coordinate is `coordinates[a, b, c, :]`.
154
155        Input coordinates outside of the `vector_field` array return `NaN` output coordinates.
156
157        Parameters
158        ----------
159        vector_field
160            Array with `Di + 1` dimensions, where `Di` is the input dimensionality.
161        index_transform
162            Transform the source coordinates into an array index
163        interpolation_order
164            Order of the spline interpolation used for coordinates which are not integer array indices.
165        vector_axis
166            Which axis of the `vector_field` contains the vector values; defaults to the last (`-1`).
167        spaces
168            References for source and target spaces
169        """
170        super().__init__(
171            vector_field,
172            index_transform,
173            interpolation_order,
174            vector_axis,
175            spaces=spaces,
176        )

Use the input coordinates as array indices to look up output coordinates.

For input coordinate (a, b, c), the output coordinate is coordinates[a, b, c, :].

Input coordinates outside of the vector_field array return NaN output coordinates.

Parameters

vector_field: Array with Di + 1 dimensions, where Di is the input dimensionality.
index_transform: Transform the source coordinates into an array index
interpolation_order: Order of the spline interpolation used for coordinates which are not integer array indices.
vector_axis: Which axis of the vector_field contains the vector values; defaults to the last (-1).
spaces: References for source and target spaces

def apply(self, coords: ~ArrayT) -> ~ArrayT: View Source

178    def apply(self, coords: ArrayT) -> ArrayT:
179        return self._get_vectors(coords)

Apply transformation.

Parameters

coords: NxD array of N D-dimensional coordinates.

Returns

ArrayT: Transformed coordinates in the same shape.

class Displacements(transformnd.transforms.vector_field.BaseVectorField[~ArrayT]): View Source

182class Displacements(BaseVectorField[ArrayT]):
183    """Look up a translation in an array and apply it to the input coordinates.
184
185    For input coordinate `(a, b, c)` and `vector_axis=-1`,
186    the output coordinate is `(a, b, c) + vector_field[a, b, c, :].
187
188    Input coordinates outside the vector field return NaN.
189
190    REQUIRES: `vectorfield` extra for in-memory,
191    or `vectorfield-dask` extra for lazy chunked vector fields.
192    """
193
194    def __init__(
195        self,
196        vector_field: ArrayT,
197        index_transform: Transform[ArrayT] | None = None,
198        interpolation_order: int = 3,
199        vector_axis: int = -1,
200        *,
201        spaces: Spaces = Spaces(None, None),
202    ):
203        """
204        Parameters
205        ----------
206        vector_field
207            Array with `Di + 1` dimensions, where `Di` is the input dimensionality.
208        index_transform
209            Transformation from source coordinate to array indices.
210        interpolation_order
211            Order of the spline interpolation used for coordinates which are not integer array indices.
212        vector_axis
213            Which axis of the `vector_field` contains the vector values; defaults to the last (`-1`).
214        spaces
215            References for source and target spaces
216
217        Raises
218        ------
219        ValueError
220            If the index transform and vector field would change the coordinates' dimensionality,
221            or the index transform's dimensionality does not match the vector field's.
222        """
223        super().__init__(
224            vector_field,
225            index_transform,
226            interpolation_order,
227            vector_axis,
228            spaces=spaces,
229        )
230        if self.ndims.source != self.ndims.target:
231            raise ValueError("Displacements cannot change dimensionality")
232
233    def apply(self, coords: ArrayT) -> ArrayT:
234        coords = self._validate_coords(coords)
235        vecs = self._get_vectors(coords)
236        return coords + vecs  # type:ignore

Look up a translation in an array and apply it to the input coordinates.

For input coordinate (a, b, c) and vector_axis=-1, the output coordinate is `(a, b, c) + vector_field[a, b, c, :].

Input coordinates outside the vector field return NaN.

REQUIRES: vectorfield extra for in-memory, or vectorfield-dask extra for lazy chunked vector fields.

Displacements( vector_field: ~ArrayT, index_transform: Optional[transformnd.Transform[~ArrayT]] = None, interpolation_order: int = 3, vector_axis: int = -1, *, spaces: transformnd.Spaces = Spaces(source=None, target=None)) View Source

194    def __init__(
195        self,
196        vector_field: ArrayT,
197        index_transform: Transform[ArrayT] | None = None,
198        interpolation_order: int = 3,
199        vector_axis: int = -1,
200        *,
201        spaces: Spaces = Spaces(None, None),
202    ):
203        """
204        Parameters
205        ----------
206        vector_field
207            Array with `Di + 1` dimensions, where `Di` is the input dimensionality.
208        index_transform
209            Transformation from source coordinate to array indices.
210        interpolation_order
211            Order of the spline interpolation used for coordinates which are not integer array indices.
212        vector_axis
213            Which axis of the `vector_field` contains the vector values; defaults to the last (`-1`).
214        spaces
215            References for source and target spaces
216
217        Raises
218        ------
219        ValueError
220            If the index transform and vector field would change the coordinates' dimensionality,
221            or the index transform's dimensionality does not match the vector field's.
222        """
223        super().__init__(
224            vector_field,
225            index_transform,
226            interpolation_order,
227            vector_axis,
228            spaces=spaces,
229        )
230        if self.ndims.source != self.ndims.target:
231            raise ValueError("Displacements cannot change dimensionality")

Parameters

vector_field: Array with Di + 1 dimensions, where Di is the input dimensionality.
index_transform: Transformation from source coordinate to array indices.
interpolation_order: Order of the spline interpolation used for coordinates which are not integer array indices.
vector_axis: Which axis of the vector_field contains the vector values; defaults to the last (-1).
spaces: References for source and target spaces

Raises

ValueError: If the index transform and vector field would change the coordinates' dimensionality, or the index transform's dimensionality does not match the vector field's.

def apply(self, coords: ~ArrayT) -> ~ArrayT: View Source

233    def apply(self, coords: ArrayT) -> ArrayT:
234        coords = self._validate_coords(coords)
235        vecs = self._get_vectors(coords)
236        return coords + vecs  # type:ignore

Apply transformation.

Parameters

coords: NxD array of N D-dimensional coordinates.

Returns

ArrayT: Transformed coordinates in the same shape.

class MovingLeastSquares(transformnd.base.Transform[numpy.ndarray]): View Source

17class MovingLeastSquares(Transform[np.ndarray]):
18    """Moving least squares transformation.
19
20    Deform based on a matched pairs of source and target control points; see <https://dl.acm.org/doi/10.1145/1141911.1141920>
21
22    REQUIRES: `movingleastsquares` extra.
23    """
24
25    def __init__(
26        self,
27        source_control_points: np.ndarray,
28        target_control_points: np.ndarray,
29        *,
30        spaces: Spaces = Spaces(None, None),
31    ):
32        """Non-rigid transforms powered by molesq package.
33
34        Parameters
35        ----------
36        source_control_points
37            NxD array of control point coordinates in the source space.
38        target_control_points
39            NxD array of coordinates of the corresponding control points
40            in the target (deformed) space.
41        spaces
42            Optional source and target spaces
43        """
44        from molesq.transform import Transformer
45
46        s = as_floats(source_control_points)
47        t = as_floats(target_control_points)
48        self._transformer = Transformer(s, t)
49        super().__init__(
50            NDims(
51                s.shape[1],
52                t.shape[1],
53            ),
54            spaces=spaces,
55        )
56
57    def apply(self, coords: np.ndarray) -> np.ndarray:
58        coords = self._validate_coords(coords)
59        return self._transformer.transform(coords)
60
61    def is_identity(self) -> bool:
62        xp = array_namespace(self._transformer.control_points)
63        return xp.all(
64            xp.equal(
65                self._transformer.control_points,
66                self._transformer.deformed_control_points,
67            )
68        )
69
70    def invert(self) -> Self | None:
71        return type(self)(
72            self._transformer.deformed_control_points,
73            self._transformer.control_points,
74            spaces=self.spaces.invert(),
75        )

Moving least squares transformation.

Deform based on a matched pairs of source and target control points; see https://dl.acm.org/doi/10.1145/1141911.1141920

REQUIRES: movingleastsquares extra.

MovingLeastSquares( source_control_points: numpy.ndarray, target_control_points: numpy.ndarray, *, spaces: transformnd.Spaces = Spaces(source=None, target=None)) View Source

25    def __init__(
26        self,
27        source_control_points: np.ndarray,
28        target_control_points: np.ndarray,
29        *,
30        spaces: Spaces = Spaces(None, None),
31    ):
32        """Non-rigid transforms powered by molesq package.
33
34        Parameters
35        ----------
36        source_control_points
37            NxD array of control point coordinates in the source space.
38        target_control_points
39            NxD array of coordinates of the corresponding control points
40            in the target (deformed) space.
41        spaces
42            Optional source and target spaces
43        """
44        from molesq.transform import Transformer
45
46        s = as_floats(source_control_points)
47        t = as_floats(target_control_points)
48        self._transformer = Transformer(s, t)
49        super().__init__(
50            NDims(
51                s.shape[1],
52                t.shape[1],
53            ),
54            spaces=spaces,
55        )

Non-rigid transforms powered by molesq package.

Parameters

source_control_points: NxD array of control point coordinates in the source space.
target_control_points: NxD array of coordinates of the corresponding control points in the target (deformed) space.
spaces: Optional source and target spaces

def apply(self, coords: numpy.ndarray) -> numpy.ndarray: View Source

57    def apply(self, coords: np.ndarray) -> np.ndarray:
58        coords = self._validate_coords(coords)
59        return self._transformer.transform(coords)

Apply transformation.

Parameters

coords: NxD array of N D-dimensional coordinates.

Returns

ArrayT: Transformed coordinates in the same shape.

def is_identity(self) -> bool: View Source

61    def is_identity(self) -> bool:
62        xp = array_namespace(self._transformer.control_points)
63        return xp.all(
64            xp.equal(
65                self._transformer.control_points,
66                self._transformer.deformed_control_points,
67            )
68        )

Whether this is a no-op transformation.

def invert(self) -> Optional[Self]: View Source

70    def invert(self) -> Self | None:
71        return type(self)(
72            self._transformer.deformed_control_points,
73            self._transformer.control_points,
74            spaces=self.spaces.invert(),
75        )

Invert the transformation, returning None if not possible.

class ThinPlateSplines(transformnd.base.Transform[numpy.ndarray]): View Source

19class ThinPlateSplines(Transform[np.ndarray]):
20    """Thin plate splines transforms.
21
22    Deform based on matched pairs of control points.
23
24    REQUIRES: `thinplatesplines` extra.
25    """
26
27    def __init__(
28        self,
29        source_control_points: np.ndarray,
30        target_control_points: np.ndarray,
31        *,
32        spaces: Spaces = Spaces(None, None),
33    ):
34        """Non-rigid control point based transforms in 2/3D.
35
36        Adapted from
37        https://github.com/schlegelp/navis/blob/master/navis/transforms/thinplate.py
38
39        Parameters
40        ----------
41        source_control_points
42            NxD array of control point coordinates in the source space.
43        target_control_points
44            NxD array of control point coordinates in the target (deformed) space.
45        spaces
46            Optional source and target spaces
47
48        Raises
49        ------
50        ValueError
51            Invalid control points.
52        """
53        import morphops
54
55        self.source_control_points = as_floats(source_control_points)
56        self.target_control_points = as_floats(target_control_points)
57
58        if self.source_control_points.shape != self.target_control_points.shape:
59            raise ValueError("Control point arrays must be the same shape")
60
61        if self.source_control_points.ndim != 2:
62            raise ValueError("Control points array must be 2D")
63
64        ndim = self.source_control_points.shape[1]
65
66        self.W, self.A = morphops.tps_coefs(
67            self.source_control_points,
68            self.target_control_points,
69        )
70        super().__init__(NDims(ndim, ndim), spaces=spaces)
71
72    def invert(self) -> Transform[np.ndarray] | None:
73        return type(self)(
74            self.target_control_points,
75            self.source_control_points,
76            spaces=self.spaces.invert(),
77        )
78
79    def apply(self, coords: np.ndarray) -> np.ndarray:
80        import morphops
81
82        coords = self._validate_coords(coords)
83        U = morphops.K_matrix(coords, self.source_control_points)
84        P = morphops.P_matrix(coords)
85        # The warped pts are the affine part + the non-uniform part
86        return P @ self.A + U @ self.W

Thin plate splines transforms.

Deform based on matched pairs of control points.

REQUIRES: thinplatesplines extra.

ThinPlateSplines( source_control_points: numpy.ndarray, target_control_points: numpy.ndarray, *, spaces: transformnd.Spaces = Spaces(source=None, target=None)) View Source

27    def __init__(
28        self,
29        source_control_points: np.ndarray,
30        target_control_points: np.ndarray,
31        *,
32        spaces: Spaces = Spaces(None, None),
33    ):
34        """Non-rigid control point based transforms in 2/3D.
35
36        Adapted from
37        https://github.com/schlegelp/navis/blob/master/navis/transforms/thinplate.py
38
39        Parameters
40        ----------
41        source_control_points
42            NxD array of control point coordinates in the source space.
43        target_control_points
44            NxD array of control point coordinates in the target (deformed) space.
45        spaces
46            Optional source and target spaces
47
48        Raises
49        ------
50        ValueError
51            Invalid control points.
52        """
53        import morphops
54
55        self.source_control_points = as_floats(source_control_points)
56        self.target_control_points = as_floats(target_control_points)
57
58        if self.source_control_points.shape != self.target_control_points.shape:
59            raise ValueError("Control point arrays must be the same shape")
60
61        if self.source_control_points.ndim != 2:
62            raise ValueError("Control points array must be 2D")
63
64        ndim = self.source_control_points.shape[1]
65
66        self.W, self.A = morphops.tps_coefs(
67            self.source_control_points,
68            self.target_control_points,
69        )
70        super().__init__(NDims(ndim, ndim), spaces=spaces)

Non-rigid control point based transforms in 2/3D.

Adapted from https://github.com/schlegelp/navis/blob/master/navis/transforms/thinplate.py

Parameters

source_control_points: NxD array of control point coordinates in the source space.
target_control_points: NxD array of control point coordinates in the target (deformed) space.
spaces: Optional source and target spaces

Raises

ValueError: Invalid control points.

def invert(self) -> Optional[transformnd.Transform[numpy.ndarray]]: View Source

72    def invert(self) -> Transform[np.ndarray] | None:
73        return type(self)(
74            self.target_control_points,
75            self.source_control_points,
76            spaces=self.spaces.invert(),
77        )

Invert the transformation, returning None if not possible.

def apply(self, coords: numpy.ndarray) -> numpy.ndarray: View Source

79    def apply(self, coords: np.ndarray) -> np.ndarray:
80        import morphops
81
82        coords = self._validate_coords(coords)
83        U = morphops.K_matrix(coords, self.source_control_points)
84        P = morphops.P_matrix(coords)
85        # The warped pts are the affine part + the non-uniform part
86        return P @ self.A + U @ self.W

Apply transformation.

Parameters

coords: NxD array of N D-dimensional coordinates.

Returns

ArrayT: Transformed coordinates in the same shape.