MotionCorrect#

class petpal.preproc.motion_corr.MotionCorrect(image_loader: petpal.io.image.ImageLoader | None = None, table_saver: petpal.io.table.TableSaver | None = None)#

Bases: petpal.preproc.register.RegisterBase

Run windowed motion correction on an image and save the result.

Variables:

  • image_loader – ImageLoader() instance or injectable replacement

  • table_saver – TableSaver() instance or injectable replacement

  • input_img – (ants.ANTsImage) Dynamic PET image

  • target_img – (ants.ANTsImage) Static target image

  • scan_timing – ScanTimingInfo() Dynamic PET scan timing.

  • half_life – (float) Half life of the PET tracer in seconds.

Ivar:

reg_kwargs: (dict) Keyword arguments passed on to registration()

window_index_pairs(window_duration: float = 300) → numpy.ndarray#

The pair of indices corresponding to each window in the image.

Parameters:

window_duration (float) – Scan will be divided into windows of this duration in seconds.

Returns:

window_index_pairs (np.ndarray) –

Array of start and end frame indices for each

window.

See also

window_target_img(start_index: int, end_index: int) → ants.ANTsImage#

Calculates the sum over frames in the target image within the provided time window.

Parameters:

  • start_index (int) – Index for the frame that the window begins on.

  • end_index (int) – Index for the frame that the window ends on.

Returns:

window_img (ants.ANTsImage) –

Sum of frames in the input image between start_index

and end_index.

static ants_xfm_to_rigid_pars(ants_xfm: ants.ANTsTransform)#

Convert an ants transform object to six parameters (3 translation, 3 rotation) and the center reference point.

register_windows(window_duration: float = 300, transform_type: str = 'DenseRigid') → list[ants.ANTsTransform]#

Run motion correction on the input image to the target image.

Creates “windows” by summing over frames with total length equal to window_duration and registering the window to the target image. Returns the calculated transforms for each frame.

Parameters:

window_duration (float) – Duration of each window to sum over.

Returns:

window_xfm_stack (list[ants.ANTsTransform]) –

The transform to apply to each frame

calculated based on the window the frame is in.

apply_motion_correction(frame_xfms: list[ants.ANTsTransform]) → ants.ANTsImage#

Apply transforms to input image.

Parameters:

frame_xfms (list[ants.ANTsTransform]) – Transforms for each frame in the input image.

Returns:

moco_img (ants.ANTsImage) – Motion corrected dynamic PET image.

plot_motion(frame_xfm_pars: pandas.DataFrame, out_plot_path: str)#

Plot the six motion parameters in rigid transformations over time (‘motionogram’).

Parameters:

  • frame_xfm_pars (pd.DataFrame) – The six motion parameters for each frame, as well as the center coordinates.

  • out_plot_path (str) – Path to where motion plot is saved, typically a .png file.

save_xfm_parameters(frame_xfms: list[ants.ANTsTransform], filename: str, transform_type: str)#

Save frame transform parameters as a table.

Parameters:

  • frame_xfms (np.ndarray) – Rigid transform parameters ordered as rotation, translation, centerpoint, then X, Y, Z axis, totalling 9 parameters for each frame.

  • filename (str) – Path to where table will be saved, including extension.

Raises:

ValueError – If transform type does not containt ‘Rigid’. Saving transform parameters is currently only available for rigid transforms.

__call__(input_image_path: str, out_image_path: str, motion_target_path: str, window_duration: float = 300, transform_type: str = 'DenseRigid', **reg_kwargs) → ants.ANTsImage#

Motion correct a dynamic PET image.

Divides image into segments of duration in seconds window_duration and register each frame to a target image, using the same transformation on for every frame in each window.

Parameters:

  • input_image_path (str) – Path to dynamic PET image.

  • out_image_path (str) – Path to which motion corrected image is saved.

  • motion_target_path (str) – Path to motion target image, a static target representing the dynamic PET image. See determine_motion_target().

  • transform_type (str) – Type of transform used in ants.registration. See https://antspyx.readthedocs.io/en/latest/registration.html. Default DenseRigid.

  • window_duration (float) – Duration of each window in seconds. Default 300.

  • reg_kwargs (keyword arguments) – Keyword arguments to pass on to the registration function. See registration().

Returns:

moco_img (ants.ANTsImage) – Motion corrected dynamic PET image.

property default_reg_kwargs: dict#

Default registration arguments passed on to registration().

set_reg_kwargs(**reg_kwargs)#

Modify the registration arguments passed on to registration().

set_input_scan_properties(input_image_path: str)#

Load input image and get half life and scan timing. Set as MotionCorrect attributes.

Parameters:

input_image_path (str) – Path to dynamic PET image.

set_target_img(motion_target_path: str)#

Get the motion target, load it as an image, and set as an attribute.

Parameters:

  • input_image_path (str) – Path to dynamic PET image.

  • motion_target_option (str | tuple) – Option for motion target. See () for details.