affine_registration

Affine registration

When calling register_vols with transformation_type set to affine, any of the available frameworks can be used: SimpleITK, Deep Learning, Test Time Optimiation, and Hyreg (default). The config parameter allows for additional, framework specific settings. For all framework specific arguments, the reader should refer to vireg.inference.configs.configs.py.

Suggested use: For affine registration, HyReg is recommended.

Deep Learning based registration

Currently, the default deep learning network used for affine registration only predict 7 parameters, i.e. it predics a rigid transformation with isotropic scaling. By default, an ensemble of 5 networks is used.

from vicom import Volume
from vireg.inference import register_vols, apply_transform

# Define vicom volumes to register
fixed_volume: Volume = ...
moving_volume: Volume = ...
fixed_mask = None

"""
Possible parameters for config
------------------------------
model_id: str | None = None
model_paths: list[Path | str] | Path | str | None = None
bidirectional: bool = False
"""

# perform affine registration with torch
# the returned transform goes from moving to fixed
registered_vol, transform = register_vols(
    fixed_volume,
    moving_volume,
    fixed_mask,
    registration_method="dl",
    transformation_type="affine",
    interpolation_mode = 'bilinear', # or "bilinear", "nearest"
    config=config,
    return_transform = True,
)

# apply the transform to another image (i.e. a mask)
registered_mask = apply_transform(moving_mask, transform_params=transform, interpolation_mode = 'nearest')

SimpleITK registration

SimpleITK allows for both rigid and full affine transformation, which can be specified through the transformation_type parameter.

from vicom import Volume
from vireg.inference import register_vols, apply_transform

# Define vicom volumes to register
fixed_volume: Volume = ...
moving_volume: Volume = ...
fixed_mask: Volume | None

config: dict | None = ...

"""
Possible parameters for config
------------------------------
n_iterations_affine: int = 140
n_iterations_elastic: int = 140
n_resolutions: int = 1
metric: str = "AdvancedMattesMutualInformation"
n_histogram_bins: int = 128
reg_weight: int = 200
grid_spacing: int = 8
fast_run: bool = False
n_threads: int = 20
"""

# perform affine registration with torch
# the returned transform goes from moving to fixed
registered_vol, transform = register_vols(
    fixed_volume,
    moving_volume,
    fixed_mask,
    registration_method="sitk",
    transformation_type="affine",
    interpolation_mode = 'bspline', # or "bilinear", "nearest", "bspline"
    config=config,
    return_transform = True,
)

# apply the transform to another image (i.e. a mask)
registered_mask = apply_transform(moving_mask, transform_params=transform, interpolation_mode = 'nearest')

TTO / HyReg registration

The test time optimization (TTO) module can be used standalone or as part of HyReg. The difference is that a standalone TTO will optimize the affine transformation parameters starting from unit parameters, while in HyReg, it will use a deep learning network's prediction as initial estimate.

from vicom import Volume
from vireg.inference import register_vols, apply_transform

# Define vicom volumes to register
fixed_volume: Volume = ...
moving_volume: Volume = ...
fixed_mask: Volume | None

config: dict | None = ...

"""
Possible parameters for TTO config
----------------------------------
affine_type: Literal["rigid", "rigid_iso_scale", "rigid_aniso_scale", "affine"] = "affine"
max_nr_iterations: int = 140
optimizer: str = "Adam"
optimizer_params: dict = Field(default_factory=lambda: })
loss: Literal["NMI"] = "NMI"
loss_params: dict = Field(
    default_factory=lambda: {
        "NMI": 
    }
)
use_initial_estimate: bool = True

Possible parameters for HyReg config
------------------------------------
config: dict = 
"""

# perform affine registration with torch
# the returned transform goes from moving to fixed
registered_vol, transform = register_vols(
    fixed_volume,
    moving_volume,
    fixed_mask,
    registration_method="hyreg",
    transformation_type="affine",
    interpolation_mode = 'bilinear', # or "bilinear", "nearest"
    config=config,
    return_transform = True
åå)

# apply the transform to another image (i.e. a mask)
registered_mask = apply_transform(moving_mask, transform_params=transform, interpolation_mode = 'nearest')