transformnd 0.1.0__py3-none-any.whl

transformnd/util.py

@@ -0,0 +1,251 @@
+"""Utilities used elsewhere in the package."""
+
+from collections import deque
+from collections.abc import Callable, Hashable, Iterable, Iterator
+from typing import Any
+
+# required for TypeVar(default=) argument
+from typing_extensions import TypeVar
+
+import numpy as np
+from array_api_compat import array_namespace
+
+UNSPECIFIED_SPACE_NAME = "???"
+
+ArrayT = TypeVar("ArrayT", default=np.ndarray)
+
+TransformSignature = Callable[[ArrayT], ArrayT]
+"""Type annotation of a function which can be used as a transform."""
+
+SpaceRef = Hashable
+"""Type annotation of things which can be used to refer to spaces"""
+
+SpaceTuple = tuple[SpaceRef | None, SpaceRef | None]
+
+
+def none_eq(a: Any | None, b: Any | None) -> bool:
+    """Check whether either is None or both are equal.
+
+    Parameters
+    ----------
+    a : Optional[Any]
+    b : Optional[Any]
+
+    Returns
+    -------
+    bool
+    """
+    return a == b or a is None or b is None
+
+
+NO_DEFAULT = object()
+
+
+def chain_or(*args: Any | None, default=NO_DEFAULT) -> Any:
+    """Return the first of *args which is not None.
+
+    Can either error or return a default if there are no non-None args.
+
+    Parameters
+    ----------
+    default : any, optional
+        By default, raises a ValueError if *args are exhausted.
+        If given, returns the given value instead.
+
+    Returns
+    -------
+    Any
+        One of the given args, or the default.
+
+    Raises
+    ------
+    ValueError
+        If `default` is not given and there are no non-None args.
+    """
+    for arg in args:
+        if arg is not None:
+            return arg
+    if default is NO_DEFAULT:
+        raise ValueError("No non-None arguments")
+    return default
+
+
+def same_or_none(*args: Any, default=NO_DEFAULT) -> Any:
+    """Check args are the same or None.
+
+    If so, return the non-None value.
+    Otherwise, raise a ValueError.
+
+    Parameters
+    ----------
+    default : Any, optional
+        If given, return this instead of an error
+        if all *args are None.
+
+    Returns
+    -------
+    Any
+        The non-None arg value.
+
+    Raises
+    ------
+    ValueError
+        Arguments are not None, or the same.
+    ValueError
+        No non-None arguments found and no default given.
+    """
+    prev = None
+
+    for arg in args:
+        if arg is None:
+            continue
+        if prev is not None and prev != arg:
+            raise ValueError("Arguments are not None or the same")
+        prev = arg
+
+    if prev is None:
+        if default is NO_DEFAULT:
+            raise ValueError("No non-None arguments found")
+        return default
+
+    return prev
+
+
+def window[T](iterable: Iterable[T], length: int) -> Iterator[tuple[T, ...]]:
+    """Sliding window over iterable.
+
+    e.g. `(it[0], it[1]), (it[1], it[2]), (it[2], it[3]), ...`
+
+    Parameters
+    ----------
+    iterable : Iterable
+    length : int
+        Length of windows to return.
+
+    Yields
+    -------
+    Tuple[Any, ...]
+    """
+    it = iter(iterable)
+    q: deque[Any] = deque(maxlen=length)
+    for _ in range(length):
+        try:
+            item = next(it)
+        except StopIteration:
+            return
+        q.append(item)
+    yield tuple(q)
+    for item in it:
+        q.append(item)
+        yield tuple(q)
+
+
+def check_ndim(given_ndim: int, supported_ndim: set[int] | None) -> None:
+    """Raise a ValueError if dimensionality is unsupported.
+
+    Parameters
+    ----------
+    given_ndim : int
+        The dimensionality to check.
+    supported_ndim : Optional[Set[int]]
+        Which dimensions are supported.
+        If None, the check passes.
+
+    Raises
+    ------
+    ValueError
+        If supported dimensions are defined and given_ndim is not in them.
+    """
+    if supported_ndim is not None and given_ndim not in supported_ndim:
+        raise ValueError(
+            f"Transform supported for {format_dims(supported_ndim)}, not {given_ndim}"
+        )
+
+
+def format_dims(supported: set[int] | None) -> str:
+    """Format supported dimensions for e.g. error messages.
+
+    Parameters
+    ----------
+    supported : Iterable[int]
+        The supported dimensions.
+
+    Returns
+    -------
+    str
+        e.g. "2D/3D/4D"
+    """
+    if supported is None:
+        return "ND"
+    if not len(supported):
+        return "nullD"
+    return "/".join(f"{d}D" for d in sorted(supported))
+
+
+def space_str(space: SpaceRef | None) -> str:
+    if space is None:
+        return UNSPECIFIED_SPACE_NAME
+    else:
+        return str(space)
+
+
+def is_square(arr: ArrayT) -> bool:
+    """Check whether an array is 2D and has the same number of rows as columns"""
+    xp = array_namespace(arr)
+    ndim, shape = xp.ndim(arr), xp.shape(arr)
+    return ndim == 2 and shape[0] == shape[1]
+
+
+def dim_intersection(
+    dims1: set[int] | None, dims2: set[int] | None, error_on_empty: bool = False
+) -> set[int] | None:
+    """Find the intersection between two sets of constraints.
+
+    None means no constraints.
+    If `error_on_empty` is truthy and there is no intersection, raise an error.
+    """
+    if dims1 is None:
+        out = dims2
+    elif dims2 is None:
+        out = dims1
+    else:
+        out = dims1.intersection(dims2)
+    if error_on_empty and out is not None and len(out) == 0:
+        raise ValueError(f"incompatible dimensions: {dims1} ∩ {dims2}")
+    return out
+
+
+def invert_spaces(spaces: SpaceTuple) -> SpaceTuple:
+    """Invert the given (source, target) space tuple."""
+    return (spaces[1], spaces[0])
+
+
+def are_coords(coords: ArrayT, ndim: set[int] | None = None):
+    xp = array_namespace(coords)
+    if xp.ndim(coords) != 2:
+        raise ValueError("Coords must be a 2D array")
+    check_ndim(xp.shape(coords)[1], ndim)
+    return coords
+
+
+def to_single_ndim(ndim: None | int = None, ndims: None | set[int] = None) -> int:
+    """Select a single ndim from the given options.
+
+    Error if a single dimension cannot be selected;
+    i.e. both are None or there is a conflict.
+
+    Useful when converting a transformation with multi-dimensionality support
+    (e.g. a scalar translation) into one with single-dimensionality support
+    (e.g. an affine).
+    """
+    if ndim is None:
+        if ndims is None:
+            raise ValueError("no ndims specified")
+        if len(ndims) != 1:
+            raise ValueError(f"needs exactly one ndim, got {ndims}")
+        return list(ndims).pop()
+
+    if ndims is None or ndim in ndims:
+        return ndim
+
+    raise ValueError(f"dimensionality conflict: {ndim} not in {ndims}")

transformnd-0.1.0.dist-info/METADATA

@@ -0,0 +1,133 @@
+Metadata-Version: 2.4
+Name: transformnd
+Version: 0.1.0
+Summary: ND coordinate transformations
+Author: Chris Barnes
+Author-email: Chris Barnes <chris.barnes@gerbi-gmb.de>
+License-Expression: MIT
+Requires-Dist: numpy>=2
+Requires-Dist: networkx>=3
+Requires-Dist: array-api-compat>=1.14
+Requires-Dist: typing-extensions>=4.15.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-Python: >=3.12, <4.0
+Provides-Extra: movingleastsquares
+Provides-Extra: pandas
+Provides-Extra: polars
+Provides-Extra: shapely
+Provides-Extra: thinplatesplines
+Description-Content-Type: text/markdown
+
+# transformnd
+
+[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
+[![GitHub](https://img.shields.io/github/license/clbarnes/transformnd)](https://github.com/clbarnes/transformnd/blob/main/LICENSE)
+[![Test Status](https://img.shields.io/github/workflow/status/clbarnes/transformnd/ci)](https://github.com/clbarnes/transformnd/actions/workflows/ci.yaml)
+[![Docs Status](https://img.shields.io/github/workflow/status/clbarnes/transformnd/docs?label=docs)](https://clbarnes.github.io/transformnd/)
+
+A library providing an API for coordinate transformations,
+as well as some common transforms.
+The goal is to allow downstream applications which require such transformations
+(e.g. image registration) to be generic over anything inheriting from `transformnd.Transform`.
+
+The base classes and utilities are very lightweight with few dependencies, for use as an API; additional transforms and features use extras.
+
+Heavily inspired by/ cribbed directly from
+[Philipp Schlegel's work in navis](https://github.com/schlegelp/navis/tree/master/navis/transforms);
+co-developed with [xform](https://github.com/schlegelp/xform/) as a red team prototype.
+
+`N` coordinates in `D` dimensions are given as a numpy array of shape `(N, D)`.
+
+`Transform` subclasses which are restricted to certain dimensionalities
+can specify this in their `ndim` class variable.
+Instances of `Transform` subclasses can further restrict their `ndim`.
+Use `self._validate_coords(coords)` in `__call__` to ensure the coordinates
+are of valid type and dimensions.
+
+Additionally, `transformnd` provides an interface for transforming types other than NxD numpy arrays,
+and implements these adapters for a few common types.
+
+See the [tutorial here](https://github.com/clbarnes/transformnd/blob/main/examples/tutorial.py).
+It is a [marimo](https://marimo.io) notebook.
+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
+
+Arbitrary transforms can be composed into a `TransformSequence` with `transform1 | transform2`.
+A graph of transforms between defined spaces can be traversed using the `TransformGraph`.
+
+## Implemented adapters
+
+- Numpy arrays of shape `(..., D, ...)` (`transformnd.adapters.ReshapeAdapter`)
+- `meshio.Mesh` (`transformnd.adapters.meshio.MeshAdapter`)
+- `pandas.DataFrame` (`transformnd.adapters.pandas.PandasAdapter`)
+  - Takes a subset of columns as a coordinate array
+- `polars.DataFrame` (`transformnd.adapters.polars.PolarsAdapter`)
+  - Similar to the pandas adapter
+  - Currently, only scalar columns are supported (e.g. not a single struct column with fields `x`, `y`, `z`)
+- Geometries from `shapely` (`transformnd.adapters.shapely.GeometryAdapter`)
+- Objects composed of transformable attributes (`transformnd.adapters.AttrAdapter`).
+
+## Additional transforms and adapters
+
+Contributions of additional transforms and adapters are welcome!
+Even if they're only thin wrappers around an external library,
+the downstream ecosystem benefits from a consistent API.
+
+Such external transformation libraries should be specified as "extras",
+and be contained in a submodule so that they are not immediately imported
+with `transformnd`.
+Dependencies for new adapters do not need to be included in `transformnd`'s dependencies,
+but should be specified in the `requirements.txt` for tests.
+
+Alternatively, consider adopting `transformnd`'s base classes in your own library,
+and have your transformation instantly compatible for downstream users.
+
+Methods which MUST be implemented:
+
+- `__init__`: should validate parameters and set `self.ndim` if the parameters constrain the dimensionality
+- `apply`: should call `_validate_coords` method early to check that the given coordinates are the correct shape
+
+Methods which SHOULD be implemented if applicable:
+
+- `to_device`: if any of the transformation's parameters need to be placed on a specific device (e.g. affine matrices on the GPU)
+- `is_identity`: if you can cheaply check whether your transformation is an identity transformation. The base class implementation returns `False`.
+- `into_affine`: if your transformation can be represented as an affine matrix. The base class implementation returns `None`.
+- `invert`: if your transformation can be inverted (default None if not)
+  - This automatically implements `__invert__` (the `~my_transform` operator), which raises NotImplemented if `invert` would return `None`.
+
+## Contributing
+
+- Use [`uv`](https://docs.astral.sh/uv/) for environment and dependency management.
+  - `uv sync` to set up the environment.
+- Use [`prek`](https://prek.j178.dev/) for running pre-commit hooks.
+  - `prek install-hooks && prek run --all-files` to get started.
+- Use [`just`](https://github.com/casey/just) for common development tasks (format, lint, test, generate docs, run benchmarks).
+  - `just` to list commands.
+- Docs are generated with `pdoc` (use `just doc`) and hosted on ReadTheDocs
+
+## Thanks
+
+Thanks to contributors
+
+- [Francesca Drummer](https://github.com/FrancescaDr)
+- [Lorenzo Cerrone](https://github.com/lorenzocerrone)
+- [Maks Hess](https://github.com/MaksHess)
+- [Silvia Maria Macrì](https://github.com/SilviaMariaMacri)

transformnd-0.1.0.dist-info/RECORD

@@ -0,0 +1,26 @@
+transformnd/__init__.py,sha256=gF4j7VK_dTmzFsPo-SFn3tm7DJb4yHvyHQQA-RL9DcE,531
+transformnd/adapters/__init__.py,sha256=qfMnCnLEs61i0NaiLwR4qfrXzL_4SjdaU7ACwSeuImg,932
+transformnd/adapters/base.py,sha256=jD4Zfc75LCxqAE8b28NCYSnhLFmRmiPlIgbguSsRPl0,5125
+transformnd/adapters/bounding_box.py,sha256=l45aOJj8HYFPFU7TIaoytLGvpyWxff7BqJ9WK_MnB2Y,593
+transformnd/adapters/pandas.py,sha256=b5RMv8DiUy_hxpVoZxzjLtqrt2wNOHE1K-C-8sYCOag,1248
+transformnd/adapters/polars.py,sha256=pNPWJnC0CRa5JWt1jrLoEJ_6b_xq47AMjEt_7L2io1c,1206
+transformnd/adapters/shapely.py,sha256=TPh3vvPH4lfGY8QTo1ICO3WECX01wcJCAFE119ONBeY,4329
+transformnd/base.py,sha256=sQoXBzegpKk_x8wi41wvVaiHso6qOchD2mbwm_9rpys,12498
+transformnd/extents/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+transformnd/extents/base.py,sha256=Wuh6YwaHnV-nAcFAQYG4CuqlJxTBIp7jG3IkshwB9S8,254
+transformnd/extents/bounding_box.py,sha256=FEObnmmFdCA2SMkpTeY5C7_xfyCQZfJzBglRC1X9s7o,1273
+transformnd/graph.py,sha256=EMaM5rn4wtoA7GuWU5XKbkNtlpucf8eiePYKVVLTtYk,5900
+transformnd/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+transformnd/transforms/__init__.py,sha256=0w0GZvSQQHBPGoQsLwhkM-vtXvl19z0WJC9QW6KzZYI,398
+transformnd/transforms/affine.py,sha256=5xEjZVQYbQ2tOqAYmGUF04KWKQTMhPLvn9WuY-OID24,15828
+transformnd/transforms/bijection.py,sha256=WU96sOMkV2GhrVQPoqqvwGx7efumw5FdlimlO2MgAVg,1888
+transformnd/transforms/by_dimension.py,sha256=p5Taiv9ng1A_kzg1OWvbQYv3qkchV9876ndN82aNsRE,4742
+transformnd/transforms/map_axis.py,sha256=oFMC3MZ-lx1oElG3PvwiTeL53UatDmUkAXFmsLa5KRY,2033
+transformnd/transforms/moving_least_squares.py,sha256=CcrtIxMPWu_cIupCWIy0Ia-yeBKA7HSKIO7kqUx7bgg,2121
+transformnd/transforms/reflection.py,sha256=Xt-TfGroTC8VnLhhlVOFfiFZczVDxyc12uwd4vQLAlg,5792
+transformnd/transforms/simple.py,sha256=mgBhVH6vwhOY4-9u7b1y07wGE4VOpElQudJTubuwkTs,5048
+transformnd/transforms/thinplate.py,sha256=Q99q0k_EO9hzkGUOa4mMKO5UqK7n5LmUFDe1XFUws-M,2485
+transformnd/util.py,sha256=-gTuhpWkmJK8sNc6VT50rBU-lwoEL3ncyJMYl8Qfy_c,6451
+transformnd-0.1.0.dist-info/WHEEL,sha256=i9aSRDivn5iP9LaR1BLQX2GNAuriQWPsFwbbWygTX2k,81
+transformnd-0.1.0.dist-info/METADATA,sha256=ufGvhllwl2G0Q8bsGfGlZv75kit-rv0K2hLxlnV5ho8,6775
+transformnd-0.1.0.dist-info/RECORD,,

transformnd-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: uv 0.11.15
+Root-Is-Purelib: true
+Tag: py3-none-any