Source code for photon_mosaic.core.motion

from __future__ import annotations

import importlib
from typing import Any, Literal, Sequence

import numpy as np
from numpy.typing import NDArray

from photon_mosaic.core import BaseImaging
from photon_mosaic.core.core_tools import _coerce_settings

# Editor autocomplete/typo-checking for the built-in methods. Not exhaustive:
# any string registered via ``register_motion_class``/``register_registration_class``
# (including third-party ones) is still accepted at runtime.
KnownMotionMethod = Literal["suite2p", "jnormcorre"]

# Method name -> module that defines (and registers) the backend's Motion
# subclass. Only module *paths* live here, so core imports no backend: the
# module is imported lazily the first time the method is requested.
_builtin_motion_modules: dict[str, str] = {
    "suite2p": "photon_mosaic.preprocessing.suite2p_registration",
    "jnormcorre": "photon_mosaic.preprocessing.jnormcorre_registration",
}

# Method name -> Motion subclass, filled in by ``register_motion_class``.
_registered_motion_classes: dict[str, type["Motion"]] = {}


[docs] def register_motion_class(motion_class: type["Motion"]) -> type["Motion"]: """Register a :class:`Motion` subclass under its ``method_name``. Backend modules call this at import time so that ``Motion.compute(..., method=...)`` can find them. Third-party backends can call it too, which is what makes the set of methods extensible. Parameters ---------- motion_class : type[Motion] Subclass defining ``method_name`` (and usually ``settings_class``). Returns ------- type[Motion] The class, unchanged, so this can be used as a decorator. """ name = motion_class.method_name if not name: raise ValueError(f"{motion_class.__name__} must define a non-empty 'method_name' to be registered.") _registered_motion_classes[name] = motion_class return motion_class
def _get_motion_class(method: str) -> type["Motion"]: """Return the :class:`Motion` subclass implementing ``method``. Built-in backends are imported lazily on first use, so an optional dependency is only required when its method is actually requested. """ if method in _registered_motion_classes: return _registered_motion_classes[method] module_path = _builtin_motion_modules.get(method) if module_path is None: known = sorted(set(_registered_motion_classes) | set(_builtin_motion_modules)) raise ValueError(f"Unknown motion correction method '{method}'. Available methods: {known}.") try: importlib.import_module(module_path) except ImportError as exc: raise ImportError( f"Motion correction method '{method}' requires optional dependencies that are not installed " f"(failed to import '{module_path}': {exc})." ) from exc if method not in _registered_motion_classes: raise ImportError( f"Module '{module_path}' was imported but did not register a Motion class for method '{method}'." ) return _registered_motion_classes[method] # Method name -> registration/epoch class, filled in by # ``register_registration_class``. Kept independent of # ``_registered_motion_classes``: a backend may register a ``Motion`` # subclass without a registration class (e.g. it only produces diagnostics), # or register a registration class for motion produced elsewhere. _registered_registration_classes: dict[str, type] = {}
[docs] def register_registration_class(method: str, registration_class: type) -> type: """Register the class that applies motion computed by ``method``. Backend modules call this at import time, independently of :func:`register_motion_class`, so that :class:`photon_mosaic.preprocessing.registration.RegisterImaging` can find the class that knows how to apply their motion. Returns ------- type ``registration_class``, unchanged, so this can be used as a decorator. """ if not method: raise ValueError("'method' must be a non-empty string to register a registration class.") _registered_registration_classes[method] = registration_class return registration_class
[docs] def get_registration_class(method: str) -> type: """Return the class that applies motion computed by ``method``. Built-in backends are imported lazily on first use, mirroring :func:`_get_motion_class`. """ if method in _registered_registration_classes: return _registered_registration_classes[method] module_path = _builtin_motion_modules.get(method) if module_path is not None: try: importlib.import_module(module_path) except ImportError as exc: raise ImportError( f"Motion correction method '{method}' requires optional dependencies that are not installed " f"(failed to import '{module_path}': {exc})." ) from exc if method not in _registered_registration_classes: raise TypeError( f"Motion correction method '{method}' did not register a 'registration_class', " "so its motion cannot be applied." ) return _registered_registration_classes[method]
def _encode_motion_value(value: Any) -> Any: """Tag ndarrays, torch tensors and tuples so :func:`_decode_motion_value` restores them exactly. JSON turns all three into plain lists, which would lose dtypes (an int16 reference image would come back as int64), shapes of empty arrays, and tuple-ness (suite2p ``blocks``). Arrays are kept as arrays here: ``SIJsonEncoder`` only converts them to lists when dumping to json, and pickling keeps them as they are. """ if isinstance(value, np.ndarray): return {"__ndarray__": value, "dtype": value.dtype.name, "shape": list(value.shape)} if type(value).__module__.split(".")[0] == "torch": array = value.detach().cpu().numpy() return {"__tensor__": array, "dtype": array.dtype.name, "shape": list(array.shape)} if isinstance(value, tuple): return {"__tuple__": [_encode_motion_value(v) for v in value]} if isinstance(value, list): return [_encode_motion_value(v) for v in value] if isinstance(value, dict): return {k: _encode_motion_value(v) for k, v in value.items()} return value def _decode_motion_value(value: Any) -> Any: """Inverse of :func:`_encode_motion_value`, for dicts fresh from json or still holding arrays.""" if isinstance(value, dict): if "__ndarray__" in value: return np.asarray(value["__ndarray__"], dtype=value["dtype"]).reshape(value["shape"]) if "__tensor__" in value: import torch # noqa: PLC0415 array = np.asarray(value["__tensor__"], dtype=value["dtype"]).reshape(value["shape"]) return torch.from_numpy(array.copy()) if "__tuple__" in value: return tuple(_decode_motion_value(v) for v in value["__tuple__"]) return {k: _decode_motion_value(v) for k, v in value.items()} if isinstance(value, list): return [_decode_motion_value(v) for v in value] return value
[docs] class Motion: """Algorithm-agnostic container for motion correction artifacts. Holds outputs that any motion correction backend (Suite2P, CaImAn, ...) is expected to produce. Backend-specific fields (e.g. Suite2P ``ops`` or block-wise non-rigid offsets) belong on dedicated subclasses such as ``Suite2PMotion``. Subclasses declare two class attributes so that they can be reached through :meth:`compute`: ``method_name`` (the string users pass as ``method``) and ``settings_class`` (their pydantic settings model). The class that knows how to apply the stored motion (a ``BasePreprocessorEpoch``) is unrelated to ``Motion`` itself: a backend registers it under the same ``method_name`` via :func:`register_registration_class`, independently of whether or how it registers its ``Motion`` subclass, and :class:`photon_mosaic.preprocessing.registration.RegisterImaging` resolves it via :func:`get_registration_class`. """ method_name: str | None = None settings_class: type | None = None def __init__( self, imaging: BaseImaging, displacements: Sequence[NDArray[np.floating[Any]]], reference: Any = None, yranges: Sequence[Sequence[tuple[int, int]]] | None = None, xranges: Sequence[Sequence[tuple[int, int]]] | None = None, corrected_badframes: Sequence[NDArray[np.bool_]] | None = None, metadata: dict[str, Any] | None = None, ) -> None: """Store displacement fields and shared metadata. Parameters ---------- imaging : BaseImaging Imaging object associated with the computed motion. displacements : Sequence[NDArray] Per-epoch rigid displacement arrays shaped ``(frames, planes, 2)`` or ``(frames, 2)`` in ``(y, x)`` order. reference : Any, optional Per-plane reference image(s) used by the registration algorithm. yranges : Sequence | None, optional Per-epoch, per-plane valid pixel row range ``[epoch][plane] -> (ymin, ymax)``. xranges : Sequence | None, optional Per-epoch, per-plane valid pixel column range ``[epoch][plane] -> (xmin, xmax)``. corrected_badframes : Sequence | None, optional Per-epoch boolean mask of frames to exclude from downstream analysis, shaped ``[epoch] -> (n_frames,)``. Bad frames are treated as a property of the time axis (a corrupted volume frame is bad on all planes), so a single mask per epoch is stored. How the mask is populated depends on the backend. metadata : dict | None, optional Free-form algorithm-agnostic metadata. """ self.imaging = imaging self.displacements = displacements self.reference = reference self.yranges = yranges self.xranges = xranges self.corrected_badframes = corrected_badframes self.metadata = metadata if metadata is not None else {}
[docs] @classmethod def compute( cls, imaging: BaseImaging, method: KnownMotionMethod | str | None = None, settings: Any = None, badframes: NDArray | None = None, **params: Any, ) -> "Motion": """Estimate motion for ``imaging`` with the requested backend. Called on :class:`Motion` itself, ``method`` selects the backend (default ``"suite2p"``); called on a subclass, that subclass is used and ``method``, if given, must match its ``method_name``. Parameters ---------- imaging : BaseImaging Imaging object containing one or more epochs/planes to register. method : str | None, optional Registration backend, e.g. ``"suite2p"``. settings : BaseSettings | dict | None, optional Backend settings. Dicts and ``None`` are coerced into the backend's ``settings_class``. badframes : NDArray | None, optional Boolean array of shape ``(n_frames,)`` marking frames to exclude from reference image computation. **params : Any Extra backend options, overriding ``settings``. Returns ------- Motion A backend-specific :class:`Motion` subclass instance. """ if method is not None and not isinstance(method, str): raise TypeError( f"'method' must be a string naming a registration backend, got {type(method).__name__}. " "Settings must be passed as a keyword argument: compute_motion(imaging, settings=...)." ) if cls is Motion: target = _get_motion_class(method or "suite2p") else: if method is not None and method != cls.method_name: raise ValueError( f"{cls.__name__} implements method '{cls.method_name}', but method='{method}' was requested. " "Call Motion.compute(...) to dispatch on 'method'." ) target = cls resolved_settings = _coerce_settings(settings, target.settings_class) return target._compute(imaging, settings=resolved_settings, badframes=badframes, **params)
@classmethod def _compute( cls, imaging: BaseImaging, *, settings: Any = None, badframes: NDArray | None = None, **params: Any, ) -> "Motion": """Backend-specific estimation. Implemented by each subclass.""" raise NotImplementedError(f"{cls.__name__} does not implement motion estimation.") def _to_dict_kwargs(self) -> dict[str, Any]: """Constructor kwargs, minus ``imaging``, that rebuild this motion. Subclasses with extra constructor arguments extend this via ``super()``. """ return dict( displacements=self.displacements, reference=self.reference, yranges=self.yranges, xranges=self.xranges, corrected_badframes=self.corrected_badframes, metadata=self.metadata, ) @classmethod def _from_dict_kwargs(cls, kwargs: dict[str, Any]) -> dict[str, Any]: """Inverse of :meth:`_to_dict_kwargs`, for subclasses that store a compacted form.""" return kwargs
[docs] def to_dict(self) -> dict[str, Any]: """Return a json-serializable description of this motion (with ``SIJsonEncoder``). ``imaging`` is not included: the owner of the motion (e.g. :class:`photon_mosaic.preprocessing.registration.RegisterImaging`) serializes it already and passes it back to :meth:`from_dict`. """ return { "object": "Motion", "method": self.method_name, "kwargs": _encode_motion_value(self._to_dict_kwargs()), }
[docs] @classmethod def from_dict(cls, motion_dict: dict[str, Any], imaging: BaseImaging) -> "Motion": """Rebuild a motion from :meth:`to_dict` output, as is or reloaded from json. Called on :class:`Motion` itself, the subclass is resolved from the stored ``method``; called on a subclass, that subclass is used. """ method = motion_dict.get("method") target = _get_motion_class(method) if cls is Motion and method is not None else cls return target(imaging=imaging, **target._from_dict_kwargs(_decode_motion_value(motion_dict["kwargs"])))
@property def num_epochs(self) -> int: """Number of epochs represented in the stored displacements.""" return len(self.displacements)
[docs] def get_displacement_at_frames( self, frame_indices: int | NDArray[np.integer], plane_index: int | None = None, epoch_index: int = 0, ) -> NDArray[np.floating[Any]]: """Return displacement vectors for the requested frames. With ``plane_index=None`` the planes axis is preserved (``(..., n_planes, 2)``); with an integer ``plane_index`` it is dropped (``(..., 2)``). """ disps = self.displacements[epoch_index] if plane_index is None: return disps[frame_indices] return disps[frame_indices, plane_index]
compute_motion = Motion.compute