clearex.registration

Image registration module.

This module provides high-level registration functions that combine linear and nonlinear transformations. Implementation details are in submodules: - linear: Linear/affine registration - nonlinear: Deformable registration - common: Shared utilities

Functions

register_round(fixed_image_path, ...[, ...])

Register a moving image to a fixed image using linear and nonlinear transformations.

Classes

ChunkInfo(chunk_id, z_start, z_end, y_start, ...)

Information about a chunk in the volume.

ChunkedImageRegistration(fixed_image_path, ...)

A class for performing image registration using linear and nonlinear transformations.

ImageRegistration(fixed_image_path, ...[, ...])

A class for performing image registration using linear and nonlinear transformations.

ParallelChunkedImageRegistration(...[, ...])

A class for performing chunked image registration in parallel.
class clearex.registration.ImageRegistration(fixed_image_path, moving_image_path, save_directory, imaging_round=0, pixel_size=(0.15, 0.15, 0.15), crop=False, enable_logging=True, force_override=False)

Bases: object

A class for performing image registration using linear and nonlinear transformations.

This class handles the complete registration workflow for whole images, including loading images, performing linear (affine) registration, followed by nonlinear (deformable) registration. It manages transform caching and logging.

Variables:

  • pixel_size (tuple) – The pixel size (spacing) of the images in micrometers.

  • fixed_image_path (str or Path) – Path to the fixed reference image.

  • fixed_image (ants.ANTsImage) – The fixed reference image.

  • fixed_mask (ants.ANTsImage) – The mask that eliminates zero-valued background in the fixed image.

  • moving_image_path (str or PathLike[str]) – Path to the moving image to be registered.

  • moving_image (ants.ANTsImage) – The moving image to be registered.

  • moving_mask (ants.ANTsImage) – The mask that eliminates zero-valued background in the moving image.

  • linear_accuracy (str) – The accuracy level for linear registration.

  • nonlinear_accuracy (str) – The accuracy level for nonlinear registration.

  • save_directory (str or PathLike[str]) – Directory where transformation results are saved.

  • imaging_round (int) – The round number for identifying transformation files.

  • crop (bool) – Whether to crop the moving image before registration.

  • force_override (bool) – Whether to force re-registration even if transforms already exist.

  • _log (Logger) – Logger instance for this registration.

  • _image_opener (ImageOpener) – Image opener for loading image data.

Parameters:

  • fixed_image_path (str | os.PathLike[str]) –

  • moving_image_path (str | os.PathLike[str]) –

  • save_directory (str | os.PathLike[str]) –

  • imaging_round (int) –

  • pixel_size (tuple[float, float, float]) –

  • crop (bool) –

  • enable_logging (bool) –

  • force_override (bool) –

pixel_size

The pixel size (spacing) of the images in micrometers.

Type:

tuple

fixed_image_path

Path to the fixed reference image.

Type:

str or os.PathLike

moving_image_path

Path to the moving image to be registered.

Type:

str or os.PathLike

save_directory

Directory where transformation results are saved.

Type:

str or os.PathLike

imaging_round

The round number for identifying transformation files.

Type:

int

crop

Whether to crop the moving image before registration.

Type:

bool

force_override

Whether to force re-registration even if transforms already exist.

Type:

bool

linear_accuracy

Linear registration accuracy level.

Type:

str

nonlinear_accuracy

Nonlinear registration accuracy level.

Type:

str

fixed_mask

Mask that eliminates zero-valued background in the fixed image.

Type:

ants.ANTsTransform

moving_mask

Mask that eliminates zero-valued background in the moving image.

Type:

ants.ANTsTransform

register()

Register a moving image to a fixed image using linear and nonlinear transformations.

Returns:

The function saves the registration results to disk.

Return type:

None

Raises:

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

  • ValueError – If required paths are not provided either as arguments or instance attributes.

mask_zero_valued_data()

Create binary masks for fixed and moving images by masking zero-valued data.

Return type:

None

calculate_and_save_metrics(registration_stage='pre-registration')

Calculate and save image similarity metrics between fixed and moving images.

Parameters:

registration_stage (str) – The stage of registration for which metrics are being calculated. Options: “pre-registration”, “linearly-registered”, “nonlinear-registered”.

Returns:

The function saves the metrics to a text file in the save directory.

Return type:

None

class clearex.registration.ChunkInfo(chunk_id, z_start, z_end, y_start, y_end, x_start, x_end, z_start_ext, z_end_ext, y_start_ext, y_end_ext, x_start_ext, x_end_ext, linear_transform_path=None, nonlinear_transform_path=None)

Bases: object

Information about a chunk in the volume.

Parameters:

  • chunk_id (int) –

  • z_start (int) –

  • z_end (int) –

  • y_start (int) –

  • y_end (int) –

  • x_start (int) –

  • x_end (int) –

  • z_start_ext (int) –

  • z_end_ext (int) –

  • y_start_ext (int) –

  • y_end_ext (int) –

  • x_start_ext (int) –

  • x_end_ext (int) –

  • linear_transform_path (Optional[Path]) –

  • nonlinear_transform_path (Optional[Path]) –

chunk_id: int
z_start: int
z_end: int
y_start: int
y_end: int
x_start: int
x_end: int
z_start_ext: int
z_end_ext: int
y_start_ext: int
y_end_ext: int
x_start_ext: int
x_end_ext: int
linear_transform_path: Optional[Path] = None
nonlinear_transform_path: Optional[Path] = None
class clearex.registration.ChunkedImageRegistration(fixed_image_path, moving_image_path, save_directory, imaging_round=0, pixel_size=(0.15, 0.15, 0.15), crop=False, enable_logging=True, force_override=False)

Bases: ImageRegistration

A class for performing image registration using linear and nonlinear transformations.

This class handles the complete registration workflow for chunked images, including loading images, performing linear (affine) registration, followed by nonlinear (deformable) registration. It manages transform caching and logging.

Variables:

  • fixed_image_path (str or Path) – Path to the fixed reference image.

  • moving_image_path (str or Path) – Path to the moving image to be registered.

  • save_directory (str or Path) – Directory where transformation results are saved.

  • imaging_round (int) – The round number for identifying transformation files.

  • crop (bool) – Whether to crop the moving image before registration.

  • enable_logging (bool) – Whether to enable logging.

  • force_override (bool) – Whether to force re-registration even if transforms already exist.

Parameters:

  • fixed_image_path (str | os.PathLike[str]) –

  • moving_image_path (str | os.PathLike[str]) –

  • save_directory (str | os.PathLike[str]) –

  • imaging_round (int) –

  • pixel_size (tuple[float, float, float]) –

  • crop (bool) –

  • enable_logging (bool) –

  • force_override (bool) –

register_chunk(chunk, fixed_image, moving_image, nonlinear_type='SyNOnly', nonlinear_accuracy='high')

Register a single chunk with fine registration.

Parameters:

  • chunk (ChunkInfo) – Information about the chunk to register.

  • fixed_image (np.ndarray) – The full fixed image.

  • moving_image (np.ndarray) – The full moving image.

  • nonlinear_type (str, optional) – Type of nonlinear registration (default: “SyNOnly”).

  • nonlinear_accuracy (str, optional) – Accuracy level for nonlinear registration (default: “high”).

Returns:

  • moving_chunk (np.ndarray) – Updated chunk with transform applied.

  • warp (np.ndarray) – The warp field for the chunk.

Return type:

Tuple[ndarray, ndarray]

extract_chunk(chunk, fixed_image, moving_image)

Extract corresponding chunks from fixed and moving images.

This method extracts overlapping regions from both the fixed and moving images based on the chunk’s extended boundaries. The extended boundaries include overlap regions to prevent registration artifacts at chunk boundaries.

Parameters:

  • chunk (ChunkInfo) – Chunk information containing boundary coordinates.

  • fixed_image (np.ndarray) – The fixed (reference) image.

  • moving_image (np.ndarray) – The moving image to be registered.

Returns:

  • fixed_chunk (ants.core.ants_image.ANTsImage) – Extracted chunk from the fixed image.

  • moving_chunk (ants.core.ants_image.ANTsImage) – Extracted chunk from the moving image.

Return type:

Tuple[_install_ants_stub.<locals>.ANTsImage, _install_ants_stub.<locals>.ANTsImage]

class clearex.registration.ParallelChunkedImageRegistration(fixed_image_path, moving_image_path, save_directory, imaging_round=0, pixel_size=(0.15, 0.15, 0.15), crop=False, enable_logging=True, force_override=False, num_workers=4)

Bases: ChunkedImageRegistration

A class for performing chunked image registration in parallel.

This class extends ChunkedImageRegistration to support parallel processing of chunks for improved performance on large datasets.

Variables:

  • fixed_image_path (str or os.PathLike[str]) – Path to the fixed reference image.

  • moving_image_path (str or os.PathLike[str]) – Path to the moving image to be registered.

  • save_directory (str or os.PathLike[str]) – Directory where transformation results are saved.

  • imaging_round (int) – The round number for identifying transformation files.

  • crop (bool) – Whether to crop the moving image before registration.

  • force_override (bool) – Whether to force re-registration even if transforms already exist.

  • num_workers (int) – Number of parallel workers to use.

Parameters:

  • fixed_image_path (str | os.PathLike[str]) –

  • moving_image_path (str | os.PathLike[str]) –

  • save_directory (str | os.PathLike[str]) –

  • imaging_round (int) –

  • pixel_size (tuple[float, float, float]) –

  • crop (bool) –

  • enable_logging (bool) –

  • force_override (bool) –

  • num_workers (int) –

clearex.registration.register_round(fixed_image_path, moving_image_path, save_directory, imaging_round=0, crop=False, enable_logging=True)

Register a moving image to a fixed image using linear and nonlinear transformations.

This is a convenience function that creates an ImageRegistration instance and calls its register method. For more control, consider using the ImageRegistration class directly.

Parameters:

  • fixed_image_path (str or os.PathLike[str]) – The path to the fixed reference image (TIFF file).

  • moving_image_path (str or os.PathLike[str]) – The path to the moving image to be registered (TIFF file).

  • save_directory (str or os.PathLike[str]) – Directory where the transformation results will be saved.

  • imaging_round (int, optional) – The round number used to identify transformation files (default is 0).

  • crop (bool, optional) – Whether to crop the moving image before registration (default is False).

  • enable_logging (bool, optional) – Whether to enable logging (default is True).

Returns:

The function saves the registration results to disk and does not return anything.

Return type:

None

Raises:

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

Examples

>>> from clearex.registration import register_round
>>> register_round(
...     fixed_image_path="reference.tif",
...     moving_image_path="round_1.tif",
...     save_directory="./results",
...     imaging_round=1
... )