transformnd 0.2.1__tar.gz → 0.4.0__tar.gz

{transformnd-0.2.1 → transformnd-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: transformnd
-Version: 0.2.1
+Version: 0.4.0
 Summary: ND coordinate transformations
 Author: Chris Barnes
 Author-email: Chris Barnes <chris.barnes@gerbi-gmb.de>
@@ -20,11 +20,14 @@ Requires-Dist: numpy>=2
 Requires-Dist: networkx>=3
 Requires-Dist: array-api-compat>=1.14
 Requires-Dist: typing-extensions>=4.15.0
+Requires-Dist: dask[dask]>=2026.3.0
+Requires-Dist: dask-image[dask]>=2026.5.0
 Requires-Dist: molesq>=0.4.0 ; extra == 'movingleastsquares'
 Requires-Dist: pandas>=3.0.2 ; extra == 'pandas'
 Requires-Dist: polars>=1.40.1 ; extra == 'polars'
 Requires-Dist: shapely>=2.1.2 ; extra == 'shapely'
 Requires-Dist: morphops>=0.1.13 ; extra == 'thinplatesplines'
+Requires-Dist: scipy>=1.17.1 ; extra == 'vectorfield'
 Requires-Python: >=3.12, <4.0
 Project-URL: documentation, https://transformnd.readthedocs.io/en/latest/
 Project-URL: source, https://github.com/clbarnes/transformnd
@@ -34,6 +37,7 @@ Provides-Extra: pandas
 Provides-Extra: polars
 Provides-Extra: shapely
 Provides-Extra: thinplatesplines
+Provides-Extra: vectorfield
 Description-Content-Type: text/markdown
 
 # transformnd
@@ -71,18 +75,21 @@ Open it with `uv run --group tutorial marimo edit examples/tutorial.py`.
 
 ## Implemented transforms
 
-- Identity (`transformnd.transforms.Identity`)
-- Translation (`transformnd.transforms.Translate`)
-- Scale (`transformnd.transforms.Scale`)
-- Reflection (`transformnd.transforms.Reflect`)
-- Affine (`transformnd.transforms.Affine`)
-  - Can be composed efficiently with `@` operator; the right hand operand is effectively applied first
-- MapAxis (`transformnd.transforms.MapAxis`): permute coordinate axes
-- ByDimension (`transformnd.transforms.ByDimension`): apply transformations to subsets of coordinate axes
-- Moving Least Squares, affine (`transformnd.transforms.moving_least_squares.MovingLeastSquares`)
-  - uses `movingleastsquares` extra
-- Thin Plate Splines (`transformnd.transforms.thinplate.ThinPlateSplines`)
-  - uses `thinplatesplines` extra
+All transforms are accessed under the `transformnd.transforms` subpackage.
+
+| Transform | Extra | Description |
+| --------- | ----- | ----------- |
+| `Identity` | | No-op transformation |
+| `Translation` | | Add a constant translation to the input coordinates |
+| `Scale` | | Multiply the input coordinates by constant scale factor |
+| `Reflection` | | Reflect coordinates about arbitrary planes |
+| `MapAxis` | | Rearrange axes of the input coordinates |
+| `Affine` | | Multiply augmented coordinates by an affine transformation matrix. Can represent all of the above transformations. Can be composed with matrix multiplication `aff2 @ aff1`. |
+| `ByDimension` | | Apply different transformations to subsets of the input coordinates' dimensions |
+| `moving_least_squares.MovingLeastSquares` | `movingleastsquares` | Landmark-based transformation. |
+| `thin_plate_splines.ThinPlateSplines` | `thinplatesplines` | Landmark-based transformation. |
+| `vector_field.Coordinates` | `vectorfield` | Look up output coordinates in a vector field indexed by the input coordinates |
+| `vector_field.Displacements` | `vectorfield` | Look up translations in a vector field indexed by the input coordinates, and add them to input coordinates |
 
 Arbitrary transforms can be composed into a `TransformSequence` with `transform1 | transform2`.
 A graph of transforms between defined spaces can be traversed using the `TransformGraph`.
@@ -135,12 +142,14 @@ Methods which SHOULD be implemented if applicable:
   - `just` to list commands.
 - Docs are generated with [`pdoc`](https://pdoc.dev/) (use `just doc`) and hosted on ReadTheDocs
 - `just bump` bumps the version, commits, and tags (but does not push); depends on [`schpet/changelog`](https://github.com/schpet/changelog)
+- `just repl` starts an IPython shell with all dependencies installed
 
 ## Thanks
 
 Thanks to contributors
 
 - [Francesca Drummer](https://github.com/FrancescaDr)
+- [Johannes Soltwedel](https://github.com/jo-mueller)
 - [Lorenzo Cerrone](https://github.com/lorenzocerrone)
 - [Maks Hess](https://github.com/MaksHess)
 - [Silvia Maria Macrì](https://github.com/SilviaMariaMacri)

{transformnd-0.2.1 → transformnd-0.4.0}/README.md

@@ -33,18 +33,21 @@ Open it with `uv run --group tutorial marimo edit examples/tutorial.py`.
 
 ## Implemented transforms
 
-- Identity (`transformnd.transforms.Identity`)
-- Translation (`transformnd.transforms.Translate`)
-- Scale (`transformnd.transforms.Scale`)
-- Reflection (`transformnd.transforms.Reflect`)
-- Affine (`transformnd.transforms.Affine`)
-  - Can be composed efficiently with `@` operator; the right hand operand is effectively applied first
-- MapAxis (`transformnd.transforms.MapAxis`): permute coordinate axes
-- ByDimension (`transformnd.transforms.ByDimension`): apply transformations to subsets of coordinate axes
-- Moving Least Squares, affine (`transformnd.transforms.moving_least_squares.MovingLeastSquares`)
-  - uses `movingleastsquares` extra
-- Thin Plate Splines (`transformnd.transforms.thinplate.ThinPlateSplines`)
-  - uses `thinplatesplines` extra
+All transforms are accessed under the `transformnd.transforms` subpackage.
+
+| Transform | Extra | Description |
+| --------- | ----- | ----------- |
+| `Identity` | | No-op transformation |
+| `Translation` | | Add a constant translation to the input coordinates |
+| `Scale` | | Multiply the input coordinates by constant scale factor |
+| `Reflection` | | Reflect coordinates about arbitrary planes |
+| `MapAxis` | | Rearrange axes of the input coordinates |
+| `Affine` | | Multiply augmented coordinates by an affine transformation matrix. Can represent all of the above transformations. Can be composed with matrix multiplication `aff2 @ aff1`. |
+| `ByDimension` | | Apply different transformations to subsets of the input coordinates' dimensions |
+| `moving_least_squares.MovingLeastSquares` | `movingleastsquares` | Landmark-based transformation. |
+| `thin_plate_splines.ThinPlateSplines` | `thinplatesplines` | Landmark-based transformation. |
+| `vector_field.Coordinates` | `vectorfield` | Look up output coordinates in a vector field indexed by the input coordinates |
+| `vector_field.Displacements` | `vectorfield` | Look up translations in a vector field indexed by the input coordinates, and add them to input coordinates |
 
 Arbitrary transforms can be composed into a `TransformSequence` with `transform1 | transform2`.
 A graph of transforms between defined spaces can be traversed using the `TransformGraph`.
@@ -97,12 +100,14 @@ Methods which SHOULD be implemented if applicable:
   - `just` to list commands.
 - Docs are generated with [`pdoc`](https://pdoc.dev/) (use `just doc`) and hosted on ReadTheDocs
 - `just bump` bumps the version, commits, and tags (but does not push); depends on [`schpet/changelog`](https://github.com/schpet/changelog)
+- `just repl` starts an IPython shell with all dependencies installed
 
 ## Thanks
 
 Thanks to contributors
 
 - [Francesca Drummer](https://github.com/FrancescaDr)
+- [Johannes Soltwedel](https://github.com/jo-mueller)
 - [Lorenzo Cerrone](https://github.com/lorenzocerrone)
 - [Maks Hess](https://github.com/MaksHess)
 - [Silvia Maria Macrì](https://github.com/SilviaMariaMacri)

{transformnd-0.2.1 → transformnd-0.4.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "transformnd"
-version = "0.2.1"
+version = "0.4.0"
 description = "ND coordinate transformations"
 readme = "README.md"
 authors = [{ name = "Chris Barnes", email = "chris.barnes@gerbi-gmb.de" }]
@@ -10,6 +10,8 @@ dependencies = [
     "networkx>=3",
     "array_api_compat>=1.14",
     "typing-extensions>=4.15.0",
+    "dask[dask]>=2026.3.0",
+    "dask-image[dask]>=2026.5.0",
 ]
 license = "MIT"
 classifiers = [
@@ -41,6 +43,9 @@ shapely = ["shapely>=2.1.2"]
 polars = [
     "polars>=1.40.1",
 ]
+vectorfield = [
+    "scipy>=1.17.1",
+]
 
 [dependency-groups]
 dev = [
@@ -50,12 +55,17 @@ dev = [
     {include-group = "tutorial"},
     {include-group = "bench"},
 ]
-test = ["pytest", "jax"]
+test = [
+    "pytest",
+    "jax",
+    "dask>=2026.3.0",
+]
 lint = [
     "ruff",
     "mypy",
     "prek>=0.3.9",
     "types-shapely>=2.1.0.20260408",
+    "pydoclint>=0.8.6",
 ]
 doc = [
     "pdoc>=16.0.0",
@@ -80,3 +90,13 @@ check_untyped_defs = true
 [tool.pytest]
 testpaths = ["tests", "bench"]
 addopts = ["--benchmark-skip"]
+
+[tool.pydoclint]
+arg-type-hints-in-docstring = false
+allow-init-docstring = true
+
+[tool.ruff]
+lint.external = [
+    "DOC",  # pydoclint
+    "D",  # pydocstyle
+]

{transformnd-0.2.1 → transformnd-0.4.0}/src/transformnd/adapters/base.py

@@ -14,22 +14,27 @@ ObjectT = TypeVar("ObjectT")
 
 
 class BaseAdapter[ObjectT, ArrayT](ABC):
+    """Base class for adapters that transform non-array objects."""
+
     @abstractmethod
     def apply(self, transform: Transform[ArrayT], obj: ObjectT) -> ObjectT:
         """Apply the given transformation to a non-array object.
 
         Parameters
         ----------
-        transform : Transform
-        obj : T
+        transform
+            The transformation to apply.
+        obj
+            The object to transform.
 
         Returns
         -------
-        T
+        ObjectT
+            The transformed object.
         """
         pass
 
-    def partial(self, *args, **kwargs) -> Callable[..., ObjectT]:
+    def partial(self, *args: Any, **kwargs: Any) -> Callable[..., ObjectT]:
         """Create a partial function with frozen arguments.
 
         Useful for applying the same transform to many objects,
@@ -37,9 +42,17 @@ class BaseAdapter[ObjectT, ArrayT](ABC):
         or for adapters with additional arguments,
         using the same config repeatedly.
 
+        Parameters
+        ----------
+        *args
+            Positional arguments to freeze.
+        **kwargs
+            Keyword arguments to freeze.
+
         Returns
         -------
-        Callable
+        Callable[..., ObjectT]
+            A partial function with the given arguments frozen.
         """
         return partial(self.apply, *args, **kwargs)
 
@@ -52,15 +65,16 @@ class NullAdapter(BaseAdapter[ArrayT, ArrayT]):
 
 
 class FnAdapter(BaseAdapter[ObjectT, ArrayT]):
-    def __init__(self, fn: Callable[[Transform[ArrayT], ObjectT], ObjectT]):
-        """Adapter which simply wraps a function, for typing purposes.
+    """Adapter which simply wraps a function, for typing purposes.
 
-        Parameters
-        ----------
-        fn : Callable[[Transform, T], T]
-            Function which takes the object,
-            and applies the transformation to it.
-        """
+    Parameters
+    ----------
+    fn
+        Function which takes the object,
+        and applies the transformation to it.
+    """
+
+    def __init__(self, fn: Callable[[Transform[ArrayT], ObjectT], ObjectT]):
         self.fn = fn
 
     def apply(self, transform: Transform[ArrayT], obj: ObjectT) -> ObjectT:
@@ -68,18 +82,19 @@ class FnAdapter(BaseAdapter[ObjectT, ArrayT]):
 
 
 class AttrAdapter(BaseAdapter[ObjectT, ArrayT]):
-    def __init__(self, **kwargs: BaseAdapter[Any, ArrayT] | None) -> None:
-        """Adapter which transforms an object by applying transforms to its attributes.
+    """Adapter which transforms an object by applying transforms to its attributes.
+
+    Parameters
+    ----------
+    **kwargs
+        Keys are attribute names, values are adapters with which
+        to apply the transform to those attributes.
+        `None` is shorthand for `NullAdapter()`;
+        i.e. the attribute is an array and can be transformed
+        without being adapted.
+    """
 
-        Parameters
-        ----------
-        adapters : Dict[str, Optional[BaseAdapter]]
-            Keys are attribute names, values are adapters with which
-            to apply the transform to those attributes.
-            `None` is shorthand for `NullAdapter()`;
-            i.e. the attribute is an array and can be transformed
-            without being adapted.
-        """
+    def __init__(self, **kwargs: BaseAdapter[Any, ArrayT] | None) -> None:
         self.adapters = {
             k: NullAdapter[ArrayT]() if v is None else v for k, v in kwargs.items()
         }
@@ -91,15 +106,23 @@ class AttrAdapter(BaseAdapter[ObjectT, ArrayT]):
 
         Parameters
         ----------
-        transform : Transform
-        obj : T
-        in_place : bool, optional
+        transform
+            The transformation to apply.
+        obj
+            The object to transform.
+        in_place
             Whether to mutate the given object in place,
             by default False (i.e. make a deep copy of it).
 
         Returns
         -------
-        T
+        ObjectT
+            The transformed object.
+
+        Raises
+        ------
+        TypeError
+            If the adapter does not support the in_place argument.
         """
         if not in_place:
             obj = deepcopy(obj)
@@ -147,7 +170,7 @@ class ReshapeAdapter(BaseAdapter[ArrayT, ArrayT]):
 
         Parameters
         ----------
-        dim_axis : int, optional
+        dim_axis
             Which axis contains the coordinates' dimensions,
             by default -1 (last)
         """

{transformnd-0.2.1 → transformnd-0.4.0}/src/transformnd/adapters/pandas.py

@@ -15,7 +15,7 @@ class PandasAdapter(BaseAdapter[pd.DataFrame, np.ndarray]):
 
         Parameters
         ----------
-        columns : list of keys
+        columns
             Keys for columns containing coordinates, e.g. `["x", "y", "z"]`
         """
         self.columns = columns
@@ -27,16 +27,18 @@ class PandasAdapter(BaseAdapter[pd.DataFrame, np.ndarray]):
 
         Parameters
         ----------
-        transform : Transform
-        df : pd.DataFrame
-
-        in_place : bool, optional
+        transform
+            The transformation to apply.
+        df
+            The DataFrame to transform.
+        in_place
             Whether to mutate the dataframe in place,
             by default False (i.e. make a copy of it).
 
         Returns
         -------
-        pandas.DataFrame
+        pd.DataFrame
+            The transformed DataFrame.
         """
         coords = df[self.columns].to_numpy()
         transformed = transform.apply(coords)

{transformnd-0.2.1 → transformnd-0.4.0}/src/transformnd/adapters/polars.py

@@ -13,7 +13,7 @@ class PolarsAdapter(BaseAdapter[pl.DataFrame, np.ndarray]):
 
         Parameters
         ----------
-        columns : list of keys
+        columns
             Keys for columns containing coordinates, e.g. `["x", "y", "z"]`
         """
         self.columns = columns
@@ -25,16 +25,18 @@ class PolarsAdapter(BaseAdapter[pl.DataFrame, np.ndarray]):
 
         Parameters
         ----------
-        transform : Transform
-        df : pl.DataFrame
-
-        in_place : bool, optional
+        transform
+            The transformation to apply.
+        df
+            The DataFrame to transform.
+        in_place
             Whether to mutate the dataframe in place,
             by default False (i.e. make a copy of it).
 
         Returns
         -------
-        pandas.DataFrame
+        pl.DataFrame
+            The transformed DataFrame.
         """
         coords = df[self.columns].to_numpy()
         transformed = transform.apply(coords)

transformnd-0.4.0/src/transformnd/adapters/shapely.py

@@ -0,0 +1,64 @@
+import logging
+
+import numpy as np
+import shapely
+from shapely.geometry.base import BaseGeometry
+from shapely.coords import CoordinateSequence
+
+from ..base import Transform, ArrayT
+from .base import BaseAdapter
+
+logger = logging.getLogger(__name__)
+
+
+def as_numpy(coords: CoordinateSequence) -> np.ndarray:
+    return np.asarray(coords)
+
+
+class GeometryAdapter(BaseAdapter[BaseGeometry, ArrayT]):
+    """Transform shapely geometries.
+
+    As well as the generic `apply()`,
+    there are `apply_*()` methods for transforming different geometry subclasses.
+
+    N.B. some transforms may create invalid topologies
+    (incorrect winding, self-intersections etc.).
+
+    N.B. shapely geometries' coordinates are in `XY(Z)` order
+    """
+
+    def apply[T: BaseGeometry](
+        self,
+        transform: Transform,
+        obj: T,
+        *,
+        include_z: bool | None = None,
+    ) -> T:
+        """Transform the shapely geometry.
+
+        Parameters
+        ----------
+        transform
+            The transformation to apply.
+        obj
+            Some shapely geometry in 2 or 3D
+        include_z
+            Force inclusion/ exclusion of Z coordinate.
+            By default (None), checks whether the given geometry has Z coordinates.
+
+        Returns
+        -------
+        T
+            An object of the same type as the input.
+        """
+
+        def fn(coords: np.ndarray) -> np.ndarray:
+            c = coords.copy()
+            return transform.apply(c)
+
+        if include_z is None:
+            inc_z = bool(shapely.has_z(obj))
+        else:
+            inc_z = include_z
+
+        return shapely.transform(obj, fn, include_z=inc_z)

{transformnd-0.2.1 → transformnd-0.4.0}/src/transformnd/base.py

@@ -6,6 +6,7 @@ from abc import ABC, abstractmethod
 from collections.abc import Iterator, Sequence
 from copy import copy
 from typing import Self, TYPE_CHECKING
+from types import ModuleType
 
 from array_api_compat import array_namespace
 
@@ -35,6 +36,8 @@ class Transform[ArrayT](ABC):
         """
         Parameters
         ----------
+        ndims
+            Source and target dimensionality.
         spaces
             Optional source and target spaces
         """
@@ -50,7 +53,7 @@ class Transform[ArrayT](ABC):
 
         Returns
         -------
-        Transform | None:
+        Affine[ArrayT] | None
             The affine transformation, if conversion is possible.
             None otherwise.
         """
@@ -63,9 +66,14 @@ class Transform[ArrayT](ABC):
 
         Parameters
         ----------
-        coords : ArrayT
+        coords
             NxD array of N D-dimensional coordinates.
 
+        Returns
+        -------
+        ArrayT
+            The validated coordinates.
+
         Raises
         ------
         ValueError
@@ -87,12 +95,12 @@ class Transform[ArrayT](ABC):
 
         Parameters
         ----------
-        coords : ArrayT
+        coords
             NxD array of N D-dimensional coordinates.
 
         Returns
         -------
-        np.ndarray
+        ArrayT
             Transformed coordinates in the same shape.
         """
         pass
@@ -116,7 +124,7 @@ class Transform[ArrayT](ABC):
             return NotImplemented
         return t
 
-    def to_device(self, xp, device=None) -> Self:  # noqa: ARG002
+    def to_device(self, xp: ModuleType, device: str | None = None) -> Self:  # noqa: ARG002
         """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,
@@ -124,15 +132,15 @@ class Transform[ArrayT](ABC):
 
         Parameters
         ----------
-        xp : array namespace
+        xp
             The target array namespace (e.g. jax.numpy, torch).
-        device : device object, optional
+        device
             Target device (e.g. from array_api_compat.device(array)).
             If None, uses xp's default device.
 
         Returns
         -------
-        Transform
+        Self
             A new transform instance with parameters on the target device,
             or NotImplemented if the subclass does not support device placement.
         """
@@ -145,11 +153,13 @@ class Transform[ArrayT](ABC):
 
         Parameters
         ----------
-        other : Transform
+        other
+            The transform to compose with.
 
         Returns
         -------
-        TransformSequence
+        TransformSequence[ArrayT]
+            The composed transform sequence.
         """
         if not isinstance(other, Transform):
             return NotImplemented
@@ -166,11 +176,13 @@ class Transform[ArrayT](ABC):
 
         Parameters
         ----------
-        other : Transform
+        other
+            The transform to compose with.
 
         Returns
         -------
-        TransformSequence
+        TransformSequence[ArrayT]
+            The composed transform sequence.
         """
         if not isinstance(other, Transform):
             return NotImplemented
@@ -205,9 +217,13 @@ class TransformWrapper(Transform[ArrayT]):
 
         Parameters
         ----------
-        fn : TransformSignature
+        fn
             Callable.
-        spaces : tuple[SpaceRef, SpaceRef]
+        in_ndim
+            Dimensionality of the input coordinates.
+        out_ndim
+            Dimensionality of the output coordinates.
+        spaces
             Optional source and target spaces
         """
         super().__init__(NDims(in_ndim, out_ndim), spaces=spaces)
@@ -331,22 +347,23 @@ class TransformSequence(Transform[ArrayT], Sequence[Transform[ArrayT]]):
             coords = t.apply(coords)
         return coords
 
-    def to_device(self, xp, device=None) -> Self:
+    def to_device(self, xp: ModuleType, device: str | None = None) -> Self:
         result = copy(self)
         result.transforms = [t.to_device(xp, device) for t in self.transforms]
         return result
 
-    def list_spaces(self, skip_none=False) -> list[SpaceRef]:
+    def list_spaces(self, skip_none: bool = False) -> list[SpaceRef]:
         """List spaces in this transform.
 
         Parameters
         ----------
-        skip_none : bool, optional
+        skip_none
             Whether to skip undefined spaces, default False.
 
         Returns
         -------
-        List[SpaceRef]
+        list[SpaceRef]
+            The list of spaces.
         """
         spaces = [self.spaces.source] + [t.spaces.target for t in self.transforms]
         if skip_none: