clearex.registration.common

Functions

`bulk_transform_directory`(fixed_image_path, ...)	Apply linear and nonlinear transformations to a list of moving images and save the results.
`calculate_metrics`(fixed, moving[, ...])	Compute normalized cross-correlation band Mattes Mutual Information between two ANTsImage volumes.
`crop_data`(logging_instance, crop, ...[, ...])	Crop an image to its minimal bounding box or load existing crop indices.
`export_affine_transform`(affine_transform, ...)	Export an ants Affine Transform to disk.
`export_tiff`(image, data_path[, min_value, ...])	Export an ants.ANTsImage to a 16-bit tiff file.
`import_affine_transform`(data_path)	Import an ants Affine Transform.
`import_tiff`(data_path)	Import a tiff file and convert to an ANTsImage.
`set_origin_and_spacing`(image[, origin, spacing])	Set origin and spacing to match original images.
`transform_image`(fixed_image_path, ...)	Apply linear and nonlinear transformations to a moving image and save the result.

clearex.registration.common.export_affine_transform(affine_transform, directory)

Export an ants Affine Transform to disk.

Parameters:

affine_transform (ants.core.ants_transform.ANTsTransform) – The affine transform to export.
directory (str) – The directory where the transform will be saved. If it does not exist, it will be created.

Raises:

ValueError – If the affine_transform is not an instance of ANTsTransform.

Return type:

None

clearex.registration.common.export_tiff(image, data_path, min_value=None, max_value=None, max_intensity_project=False)

Export an ants.ANTsImage to a 16-bit tiff file.

Export an ants.ANTsImage to a 16-bit tiff file. If the image min or max values are provided, the image will be scaled to that range. If not provided, the image will be scaled to its own min and max values.

Parameters:

image (ants.core.ants_image.ANTsImage) – Image to export
data_path (str) – The location and name of the file to save the data to.
min_value (float or None) – Minimum value of the reference range to map the image to. Default is None.
max_value (float or None) – Maximum value of the reference range to map the image to. Default is None.
max_intensity_project (bool) – If True, perform a max intensity projection along the z-axis before saving.

Return type:

None

clearex.registration.common.import_tiff(data_path)

Import a tiff file and convert to an ANTsImage.

Parameters:: data_path (str) – The path to the file to import.
Return type:: _install_ants_stub.<locals>.ANTsImage

clearex.registration.common.import_affine_transform(data_path)

Import an ants Affine Transform.

Parameters:: data_path (str) – The path to the Affine Transform.
Returns:: affine_transform – The affine transform.
Return type:: ants.core.ants_transform.ANTsTransform

clearex.registration.common.calculate_metrics(fixed, moving, fixed_mask=None, moving_mask=None, sampling='regular', sampling_pct=1.0)

Compute normalized cross-correlation band Mattes Mutual Information between two ANTsImage volumes.

Parameters:

fixed (_install_ants_stub.<locals>.ANTsImage | numpy.ndarray) –
moving (_install_ants_stub.<locals>.ANTsImage | numpy.ndarray) –
fixed_mask (_install_ants_stub.<locals>.ANTsImage | None) –
moving_mask (_install_ants_stub.<locals>.ANTsImage | None) –
sampling (str) –
sampling_pct (float) –

Return type:

dict

clearex.registration.common.crop_data(logging_instance, crop, imaging_round, image, save_directory, image_type='')

Crop an image to its minimal bounding box or load existing crop indices.

Identifies and applies a minimal bounding box around non-background voxels in the image. Crop indices are saved to disk for reproducibility and reuse.

Parameters:

logging_instance (Logger) – Logger instance for recording crop operations.
crop (bool or None) – Whether to perform cropping. If False or None, returns the image as an ANTsImage without cropping.
imaging_round (int or None) – The round number used to identify the crop indices file. If None, the file is named without a round suffix.
image (NDArray[Any]) – The image array to be cropped.
save_directory (str or os.PathLike[str]) – Directory where crop indices JSON file will be saved or loaded from.
image_type (str, optional) – Type of image being cropped, either “fixed” or “moving”, used for naming the crop indices file. Default is “”.

Returns:

The cropped image as an ANTsImage (if crop=True), or the original image converted to ANTsImage (if crop=False).

Return type:

ants.AnTsImage

Notes

Crop indices are saved as JSON files in the format: - {image_type}_crop_indices_{imaging_round}.json (if imaging_round is provided) - {image_type}_crop_indices.json (if imaging_round is None)

clearex.registration.common.bulk_transform_directory(fixed_image_path, moving_image_paths, save_directory, imaging_round)

Apply linear and nonlinear transformations to a list of moving images and save the results.

Parameters:

fixed_image_path (str or Path) – Path to the fixed reference image (TIFF file).
moving_image_paths (Sequence[str or Path]) – List of paths to moving images to be transformed.
save_directory (str or Path) – Directory where the transformed images will be saved.
imaging_round (int) – The imaging_round number used to identify transformation files.

Returns:

The function saves the transformed images to disk and does not return anything.

Return type:

None

Raises:

FileNotFoundError – If any of the required transformation files do not exist.

clearex.registration.common.transform_image(fixed_image_path, linear_transformation_path, moving_image_path, nonlinear_transformation_path, save_directory)

Apply linear and nonlinear transformations to a moving image and save the result.

Parameters:

fixed_image_path (str or Path) – The path to the fixed reference image (TIFF file).
linear_transformation_path (str or Path) – The path to the linear (affine) transformation file (.mat).
moving_image_path (str or Path) – The path to the moving image to be transformed (TIFF file).
nonlinear_transformation_path (str or Path) – The path to the nonlinear (warp) transformation file (.nii.gz).
save_directory (str or Path) – Directory where the transformed image will be saved.

Returns:

The function saves the transformed image to disk and does not return anything.

Return type:

None

Raises:

FileNotFoundError – If any of the provided file paths do not exist.

clearex.registration.common.set_origin_and_spacing(image, origin=None, spacing=None)

Set origin and spacing to match original images. ants.from_numpy(…) transposes the array when it converts it to an ANTsImage ( data.T.copy(order=’C’)).

NumPy is typically z,y,x; ITK/ANTs is x,y,z convention.

Consequently, when you set the spacing/origin, those values must be supplied in ( X, Y, Z) order (not Z,Y,X).

Parameters:

image (ants.core.ants_image.ANTsImage) – The input ANTsImage.
origin (tuple | None) – The desired origin coordinates. If None, the origin is not modified.
spacing (tuple | None) – The desired spacing values. If None, the spacing is not modified.

Returns:

The ANTsImage with updated origin and/or spacing.

Return type:

ants.core.ants_image.ANTsImage

Notes