registration module

registration module#

@author: Théo Lambert, adapted from original code by Gabriel Montaldo

This module regroups all the functions related to data registration. Throughout the documentation, the following acronyms are used:

  • DV: dorso-ventral axis

  • AP: antero-posterior axis

  • LR: left-right axis

registration.flip_dims(data: dict) → ndarray#

Utility function for flipping dimensions in the fUS data when required from the Direction metadata.

Parameters:

data (dict) – A fUS data dict, with fields ‘Data’ (the fUS volume), ‘Size’ (the data ndarray shape), ‘VoxelSize’ (voxel size in mm), ‘Direction’ (axes DV-VD, AP-PA, LR-RL)

Returns:

volume – The volume with correctly flipped dimensions (corresponding to data[‘Data’]), /!the function does not return the full dict!

Return type:

ndarray

registration.interpolate3D(data: dict, atlas_resolution: int, tf_matrix: dict, visualize_interp: bool = False) → dict#

Function for interpolating raw fUS data to the atlas resolution.

Parameters:

  • data (dict) – The fUS data dict, with fields ‘Data’ (the fUS volume), ‘Size’ (the data ndarray shape), ‘VoxelSize’ (voxel size in mm), ‘Direction’ (axes DV-VD, AP-PA, LR-RL)

  • atlas_resolution (int) – Resolution of the atlas to which the data will be registered in µm (ex: 100).

  • tf_matrix (dict) – The transformation matrix dict, with fields ‘M’ (the transform matrix)

  • visualize_data (None | str) – Fed to the visualize_volume function for parameter ‘orientation’, please refer to the associated doc.

Returns:

data_interp – The fUS interpolated data dict, with fields ‘Data’ (the interpolated fUS volume), ‘VoxelSize’ (voxel size in mm), ‘Direction’ (axes DV-VD, AP-PA, LR-RL)

Return type:

dict

registration.load_data_and_tf(data_path: str, tf_path: str, atlas_resolution: int | None = None, visualize_data: None | str = None, reshape: bool = False) -> (<class 'dict'>, <class 'dict'>)#

Function for loading raw fUS data from .mat files and associated transformation matrix. Output format is (DV-VD, AP-PA, LR-RL, time)

Parameters:

  • data_path (str) – Path to the fUS data (ex: C:/tmp/fusi_data.mat).

  • tf_path (str) – Path to the affine transformation matrix used to register the data. (ex: C:/tmp/transf.mat)

  • atlas_resolution (int) – Resolution of the atlas to which the data will be registered in µm (ex: 100). The original estimate is made with the 50µm CCF v3 atlas, so the translations need to be scaled. Set to None if you don’t want any normalization.

  • visualize_data (None | str) – Fed to the visualize_volume function for parameter ‘orientation’, please refer to the associated doc.

Returns:

  • data (ndarray) – The fUS data dict, with fields ‘Data’ (the fUS volume), ‘Size’ (the data ndarray shape), ‘VoxelSize’ (voxel size in mm), ‘Direction’ (axes DV-VD, AP-PA, LR-RL)

  • tf (dict) – The transformation matrix dict, with fields ‘M’ (the transform matrix), the rest is useless

registration.register_data(atlas: ndarray, data: dict, tf_matrix: dict, atlas_resolution: int, visualize_reg: bool = False, overlay: bool = True) → ndarray#

Main function for registering raw fUS data to the selected atlas.

Parameters:

  • atlas (ndarray) – 3D volume of the atlas, where each value is a number indicating to which region a voxel belongs.

  • data (dict) – The fUS data dict, with fields ‘Data’ (the fUS volume), ‘Size’ (the data ndarray shape), ‘VoxelSize’ (voxel size in mm), ‘Direction’ (axes DV-VD, AP-PA, LR-RL).

  • tf_matrix (np.ndarray) – The 4x4 transform matrix.

  • visualize_reg (None | str) – Fed to the visualize_volume function for parameter ‘orientation’, please refer to the associated doc.

  • overlay (bool) – To specify whether the atlas should be overlaid on the registered data. /!if True, you should use the atlas contours as input for variable ‘atlas’

Returns:

data_interp – The fUS interpolated data dict, with fields ‘Data’ (the interpolated fUS volume), ‘VoxelSize’ (voxel size in mm), ‘Direction’ (axes DV-VD, AP-PA, LR-RL)

Return type:

dict

registration.visualize_volume(volume: ndarray, atlas: ndarray | None = None, orientation: str = 'coronal', overlay: bool = True) → None#

Open a window and display consecutive sections of a volume one by one.

Parameters:

  • volume (ndarray) – Volume to be displayed, array-like with dimensions order (DV, AP, LR, time (optional)).

  • atlas (ndarray) – Atlas to be displayed on a second plot, array-like with dimensions order (DV, AP, LR).

  • orientation (str) – Either ‘axial’, ‘coronal’ or ‘sagittal’. Determine which dimensions are displayed.

  • overlay (bool) – Whether to overlay the atlas onto the volume. If atlas is None, nothing happens.

Return type:

None