Movie Processing Functions#

massphoto.movie_process.normalize_frames(movie, target_mean=None)[source]#

Normalize frame means to remove slow illumination drift.

Note

Available as both massphoto.normalize_frames and massphoto.movie_process.normalize_frames.

Each frame is scaled so that its mean equals target_mean. When target_mean is not provided, the target is the global mean across all frame means.

Parameters:

  • movie (np.ndarray) – 3D movie array with shape (frames, height, width).

  • target_mean (float | None, default=None) – Mean intensity that each frame should be scaled to.

Returns:

Normalized movie with the same shape as movie.

Return type:

np.ndarray

massphoto.movie_process.calc_ratiometric(img, navg=10, ngap=1, medfilt_kernel_size=15, illumination_correction=True)[source]#

Calculate ratiometric movie to reveal contrast changes over time.

Note

Available as both massphoto.calc_ratiometric and massphoto.movie_process.calc_ratiometric.

Parameters:

  • img (np.ndarray) – Input image sequence with shape (frames, height, width).

  • navg (int) – Number of frames to average for noise reduction.

  • ngap (int, default=1) – Temporal offset between signal and reference windows.

  • medfilt_kernel_size (int, default=15) – Size of the median filter kernel. 0 disables filtering.

  • illumination_correction (bool or float, default=True) – Apply correction for uneven illumination: - True: Uses default Gaussian smoothing (sigma=9) - float: Uses specified sigma value for Gaussian smoothing

Returns:

Ratiometric image with the same shape as input. First and last navg+ngap/2 frames contain NaN values.

Return type:

np.ndarray

massphoto.movie_process.calc_differential(img, navg, ngap=1)[source]#

Calculate the differential image based on the given parameters.

Note

Available as both massphoto.calc_differential and massphoto.movie_process.calc_differential.

Parameters:

  • img (np.ndarray) – The input image as a numpy array.

  • navg (int) – The number of frames to average.

  • ngap (int, optional) – The offset between windows. Defaults to 1.

Returns:

The differential image as a numpy array.

Return type:

np.ndarray

massphoto.movie_process.calc_mobileframes(frames, local_bg_halfsize, medfilt_kernel_size=0)[source]#

Calculate “mobile frames” by local median background subtraction.

Note

Available as both massphoto.calc_mobileframes and massphoto.movie_process.calc_mobileframes.

Parameters:

  • frames (np.ndarray) – Input movie with shape (frames, y, x).

  • local_bg_halfsize (int) – Half-size (in frames) of the moving-median background window.

  • medfilt_kernel_size (int, optional) – 2D median-filter kernel size (pixels); 0 disables.

Returns:

Mobile frames with the same shape as frames.

Return type:

np.ndarray

massphoto.movie_process.rebin_movie(frames: ndarray, pixel_binning: int = 1, frame_binning: int = 1, metadata: None = None) → ndarray[source]#
massphoto.movie_process.rebin_movie(frames: ndarray, pixel_binning: int = 1, frame_binning: int = 1, *, metadata: dict) → tuple[ndarray, dict]

Rebin a 2D image or 3D movie by averaging blocks.

Note

Available as both massphoto.rebin_movie and massphoto.movie_process.rebin_movie.

Parameters:

  • frames (np.ndarray) – 2D array (y, x) or 3D array (frames, y, x).

  • pixel_binning (int, optional) – Spatial binning factor (applied to y and x).

  • frame_binning (int, optional) – Temporal binning factor (3D input only).

  • metadata (dict, optional) – Standardized metadata dictionary (as returned by massphoto.metadata.convert_metadata()). If provided, a copied and updated metadata dictionary is returned together with the rebinned frames.

Returns:

Rebinned array. Any remainder pixels/frames are trimmed before binning. If metadata is provided, returns (rebinned, updated_metadata).

Return type:

np.ndarray or tuple[np.ndarray, dict]

massphoto.movie_process.calc_frame_sharpness(movie, medfilt_size=15)[source]#

Calculate relative sharpness for each frame.

Note

Available as both massphoto.calc_frame_sharpness and massphoto.movie_process.calc_frame_sharpness.

Sharpness is measured as the standard deviation of the median-filter background-subtracted frame divided by the frame mean.

Parameters:

  • movie (np.ndarray) – Movie array with shape (frames, y, x) or 2D image (y, x).

  • medfilt_size (int, default=15) – Kernel size for the separable median filter.

Returns:

1D array of sharpness values per frame.

Return type:

np.ndarray