Drift Correction Functions#

Drift correction utilities.

The main entry point is correct_drift(), which estimates (or applies) a per-frame drift trace and returns a drift-corrected movie.

massphoto.movie_drift_correction.get_shift_rfft(movie=None, template=None, movie_rfft=None, template_rfft=None, thumbnail_size=7)[source]#

Estimate a per-frame (y, x) drift trace by FFT cross-correlation.

Provide either movie or movie_rfft. If template is not given, the first frame of the movie is used as the template.

Parameters:

  • movie (np.ndarray | None) – Movie array of shape (frames, y, x).

  • template (np.ndarray | None) – Template image of shape (y, x).

  • movie_rfft (np.ndarray | None) – Pre-computed rfft2 of movie.

  • template_rfft (np.ndarray | None) – Pre-computed rfft2 of template.

  • thumbnail_size (int) – Thumbnail size (pixels) around the correlation peak used for the phasor sub-pixel estimate.

Returns:

Drift trace of shape (frames, 2) as (y, x) shifts in pixels.

Return type:

np.ndarray

massphoto.movie_drift_correction.correct_drift(movie, template=None, drift_yx=None, thumbnail_size=7, pad=0, return_drift=False)[source]#

Correct drift in a movie by applying a per-frame translation.

Note

Available as both massphoto.correct_drift and massphoto.movie_drift_correction.correct_drift.

If drift_yx is not provided, it is estimated with get_shift_rfft().

Parameters:

  • movie (np.ndarray) – Movie array of shape (frames, y, x).

  • template (np.ndarray | None) – Template image used to estimate drift (ignored when drift_yx is given).

  • drift_yx (np.ndarray | None) – Pre-computed drift trace of shape (frames, 2) as (y, x) shifts.

  • thumbnail_size (int) – Thumbnail size used by get_shift_rfft().

  • pad (int) – Symmetric padding (pixels) applied before correction to reduce edge artefacts.

  • return_drift (bool) – If True, also return the drift trace used.

Returns:

Drift-corrected movie, and optionally the drift trace.

Return type:

np.ndarray | tuple[np.ndarray, np.ndarray]

See also

massphoto.detection.detect, massphoto.fitting.fit

massphoto.movie_drift_correction.get_drift_metrics(drift_yx, fps=1.0)[source]#

Calculate drift displacement and instantaneous speed from a drift trace.

Parameters:

  • drift_yx (np.ndarray) – Drift trace of shape (frames, 2) as (y, x) shifts in pixels.

  • fps (float, default=1.0) – Frame rate multiplier. When 1.0 (default), drift_speed is in pixels/frame.

Returns:

Dictionary with keys: - "drift_y": Per-frame y displacement in pixels. - "drift_x": Per-frame x displacement in pixels. - "drift_speed": Instantaneous displacement speed in pixels/frame (or pixels/s if fps given).

Return type:

dict[str, np.ndarray]