photon_mosaic.core.motion#

Functions

compute_motion(imaging[, method, settings, ...])

Estimate motion for imaging with the requested backend.

get_registration_class(method)

Return the class that applies motion computed by method.

register_motion_class(motion_class)

Register a Motion subclass under its method_name.

register_registration_class(method, ...)

Register the class that applies motion computed by method.

Classes

Motion(imaging, displacements[, reference, ...])

Algorithm-agnostic container for motion correction artifacts.

photon_mosaic.core.motion.register_motion_class(motion_class)[source]#

Register a 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:

The class, unchanged, so this can be used as a decorator.

Return type:

type[Motion]

photon_mosaic.core.motion.register_registration_class(method, registration_class)[source]#

Register the class that applies motion computed by method.

Backend modules call this at import time, independently of register_motion_class(), so that photon_mosaic.preprocessing.registration.RegisterImaging can find the class that knows how to apply their motion.

Returns:

registration_class, unchanged, so this can be used as a decorator.

Return type:

type

photon_mosaic.core.motion.get_registration_class(method)[source]#

Return the class that applies motion computed by method.

Built-in backends are imported lazily on first use, mirroring _get_motion_class().

Return type:

type

class photon_mosaic.core.motion.Motion(imaging, displacements, reference=None, yranges=None, xranges=None, corrected_badframes=None, metadata=None)[source]#

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 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 register_registration_class(), independently of whether or how it registers its Motion subclass, and photon_mosaic.preprocessing.registration.RegisterImaging resolves it via get_registration_class().

Attributes:
method_name
num_epochs

Number of epochs represented in the stored displacements.

settings_class

Methods

compute(imaging[, method, settings, badframes])

Estimate motion for imaging with the requested backend.

from_dict(motion_dict, imaging)

Rebuild a motion from to_dict() output, as is or reloaded from json.

get_displacement_at_frames(frame_indices[, ...])

Return displacement vectors for the requested frames.

to_dict()

Return a json-serializable description of this motion (with SIJsonEncoder).

method_name: str | None = None#
settings_class: type | None = None#
classmethod compute(imaging, method=None, settings=None, badframes=None, **params)[source]#

Estimate motion for imaging with the requested backend.

Called on 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 (Union[Literal['suite2p', 'jnormcorre'], str, None]) – Registration backend, e.g. "suite2p".

  • settings (Any) – Backend settings. Dicts and None are coerced into the backend’s settings_class.

  • badframes (NDArray | None) – Boolean array of shape (n_frames,) marking frames to exclude from reference image computation.

  • **params (Any) – Extra backend options, overriding settings.

Returns:

A backend-specific Motion subclass instance.

Return type:

Motion

to_dict()[source]#

Return a json-serializable description of this motion (with SIJsonEncoder).

imaging is not included: the owner of the motion (e.g. photon_mosaic.preprocessing.registration.RegisterImaging) serializes it already and passes it back to from_dict().

Return type:

dict[str, Any]

classmethod from_dict(motion_dict, imaging)[source]#

Rebuild a motion from to_dict() output, as is or reloaded from json.

Called on Motion itself, the subclass is resolved from the stored method; called on a subclass, that subclass is used.

Return type:

Motion

property num_epochs: int#

Number of epochs represented in the stored displacements.

get_displacement_at_frames(frame_indices, plane_index=None, epoch_index=0)[source]#

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)).

Return type:

NDArray[floating[Any]]

photon_mosaic.core.motion.compute_motion(imaging, method=None, settings=None, badframes=None, **params)#

Estimate motion for imaging with the requested backend.

Called on 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 (Union[Literal['suite2p', 'jnormcorre'], str, None]) – Registration backend, e.g. "suite2p".

  • settings (Any) – Backend settings. Dicts and None are coerced into the backend’s settings_class.

  • badframes (NDArray | None) – Boolean array of shape (n_frames,) marking frames to exclude from reference image computation.

  • **params (Any) – Extra backend options, overriding settings.

Returns:

A backend-specific Motion subclass instance.

Return type:

Motion