uniGradICON

For a web-based interface that allows direct access and visualization of the uniGradICON network output without local installation, use the provided Google Colab notebook.

https://colab.research.google.com/drive/1O4F0j_ZaRHxyFJ-pfApl2E1_47-wzxMj#offline=true&sandboxMode=true

To use uniGradICON, create a virtual environment and install the package using pip. The model weights will be downloaded automatically during the first use.

python3 -m venv unigradicon_virtualenv
source unigradicon_virtualenv/bin/activate
pip install unigradicon

uniGradICON is available as an official extension for 3D Slicer.

Requirements:

• 3D Slicer version >= 5.7.0
• The Slicer PyTorch extension must be installed via the Slicer Extension Manager before installing the uniGradICON extension.

Installation: Search for and install the extension via the 3D Slicer Extensions Manager.

The unigradicon-warp CLI command applies a previously computed transform to an image or a label map.

Warp an Image

Use --linear for standard image warping.

Warp a Label Map

Use --nearest_neighbor to ensure label values are preserved during warping.

Required arguments:

• --fixed: The fixed image file.
• --moving: The moving image or segmentation file to be warped.
• --transform: The path to the .hdf5 transform file.
• --warped_moving_out: The output file path.

unigradicon-warp --fixed [fixed_image_file_name] --moving [moving_image_file_name]  --transform trans.hdf5 --warped_moving_out warped.nii.gz --linear

Use get_model_from_model_zoo to easily load either the unigradicon or multigradicon foundation models. This function automatically handles downloading the weights from GitHub if they are not found locally in the network_weights/ directory.

Available models:

• unigradicon: The primary foundation model.
• multigradicon: An alternative model.

You can also specify a custom similarity measure and enable intensity conservation loss (only supported for CT modality).

from unigradicon import get_model_from_model_zoo, make_sim
import icon_registration as icon

# Example: Loading the unigradicon model with LNCC similarity
model = get_model_from_model_zoo(
    model_name="unigradicon", 
    loss_fn=icon.LNCC(sigma=5),
    apply_intensity_conservation_loss=False
)

The preprocess function prepares CT or MRI images for registration by normalizing intensities and optionally applying a segmentation mask.

• CT Modality: Clamps intensities to the range [-1000, 1000] and scales them to [0, 1].
• MRI Modality: Casts to float, calculates the 99th percentile intensity, clamps the image to that value, and scales it to [0, 1].
• Segmentation: If a segmentation mask is provided, the image is masked using apply_mask before intensity scaling.

from unigradicon import preprocess
import itk

# Load an ITK image
image = itk.imread("path/to/image.nii.gz")

# Preprocess as CT
processed_ct = preprocess(image, modality="ct")

# Preprocess as MRI with a segmentation mask
segmentation = itk.imread("path/to/mask.nii.gz")
processed_mri = preprocess(image, modality="mri", segmentation=segmentation)

The following arguments are available for the unicarl.py command-line interface:

--fixed (required): The path of the fixed image.
--moving (required): The path of the moving image.
--transform_out (required): The path to save the transform.
--warped_moving_out (optional): The path to save the warped image.
--io_iterations (optional): The number of IO iterations. Default is 50. Set to 'None' to disable IO.

The CLI provides a utility to apply an existing transform to a moving image using specified interpolation methods.

Arguments:

• --fixed: Path to the fixed image (used as reference for the output grid).
• --moving: Path to the moving image to be warped.
• --transform: Path to the transform file. If omitted, an Identity transform is used.
• --warped_moving_out: Path to save the resulting warped image.
• --linear: Use linear interpolation.
• --nearest_neighbor: Use nearest neighbor interpolation.

# Warp using linear interpolation
python -m unigradicon.warp \
    --fixed fixed.nii.gz \
    --moving moving.nii.gz \
    --transform transform.tfm \
    --warped_moving_out warped.nii.gz \
    --linear

The unicarl.py script provides a command-line interface to register two images using the uniCARL model. It automatically downloads pretrained weights if they are not found in network_weights/unicarl_preview/longleaf_unicarl_8.

Registration is performed using itk (Insight Toolkit) and outputs a transform file. You can optionally specify a path to save the resulting warped moving image.

python src/unigradicon/unicarl.py --fixed <path_to_fixed_image> --moving <path_to_moving_image> --transform_out <path_to_save_transform> [--warped_moving_out <path_to_save_warped_image>] [--io_iterations <number_of_iterations>]

Use the CLI command to compute the Jacobian determinant of a given transform file. This is useful for analyzing local expansion or contraction in the registration field.

Arguments:

• --transform: Path to the transform file.
• --fixed: Path to the fixed image used during registration.
• --jacob: Path to save the output Jacobian map.
• --log_jacob: (Optional) Path to save the log-transformed Jacobian map.

python -m unigradicon.jacobian_map \
    --transform transform.tfm \
    --fixed fixed.nii.gz \
    --jacob output_jacobian.nii.gz \
    --log_jacob output_log_jacobian.nii.gz