Official implementation of "TrICON: Learning Diffeomorphic Lung CT Registration through Triplet Consistency".
TrICON is a deep learning framework for diffeomorphic deformable image registration (DIR) of lung CT scans. It generalizes pairwise inverse consistency to triplet-wise consistency, jointly enforcing invertibility, closed-loop cycle consistency, and transitivity across three images through a stochastic, differentiable formulation. Near-diffeomorphic behavior emerges directly from these consistency constraints, without recourse to an explicit spatial-regularization term.
- Triplet consistency constraint. Extends inverse consistency from image pairs to image triplets, introducing transitivity as a population-level regularizer that pairwise formulations cannot express.
- Implicit regularity. Near-diffeomorphic transformations arise from the consistency losses on perturbed identity grids, without an explicit smoothness penalty.
- Amortized, population-trained inference. A single model is trained across the population and generalizes to unseen subjects at test time, in contrast to classical instance-level optimization.
- Empirical validation. Evaluated against classical (ANTs SyN, deedsBCV) and learning-based (ICON, GradICON) baselines on inter-patient lung CT registration.
Given a triplet of images
Inverse consistency (Eq. 5) enforces invertibility of each pairwise map,
Transitivity loss (Eq. 4) enforces that the direct transformation between two images equals its composition through an auxiliary third image,
Cycle-consistency loss (Eq. 6) enforces closed-loop consistency around the triplet,
where $\mathcal{L}{\text{sim}}$ is the Local Normalized Cross-Correlation (LNCC) similarity term, $\lambda$ is the consistency weight, and the indicators $\mathbb{1}{{\text{inv, cycle, trans}}} \in {0,1}$ toggle each consistency term independently.
| File | Contents |
|---|---|
model.py |
UNet2, a 5-level residual U-Net predicting a dense displacement field, and RegistrationNet(), a factory for the standard configuration |
model_wrappers.py |
RegistrationModule base class; FunctionFromVectorField / FunctionFromMatrix transformation wrappers; TwoStepRegistration + DownsampleRegistration, used by train.py/test.py to build the 2-stage coarse-to-fine registration cascade; SquaringVelocityField |
losses.py |
TrICON, the end-to-end training class implementing the losses above; similarity metrics LNCC, SSD, MINDSSC, AdaptiveNCC, SSDOnlyInterpolated; helpers normalize(), flips(), to_floats() |
mermaidlite.py |
Spatial-transformer network (STN) primitives — compute_warped_image_multiNC(), identity_map_multiN() — supporting 1D, 2D, and 3D transformations |
dataset.py |
InterpatientDataset, the triplet-sampling dataset |
utils.py |
seed_everything(), create_sitk_image(), upsample_to_original_shape(), prepare_registration_outputs() |
train.py |
Training entry point |
test.py |
Per-case evaluation (registration outputs) for a trained experiment |
config.yaml |
Experiment, training, and path configuration |
The reference environment is provided as a conda specification:
conda env create -f torch212_env.yml
conda activate torch212_envThis installs PyTorch, SimpleITK/ITK, and the scientific-Python stack (NumPy, SciPy, pandas) used throughout the codebase.
InterpatientDataset (dataset.py) reads a JSON manifest, not a plain image folder. The manifest path is set per environment under paths.interpatient_json in config.yaml, resolved relative to <project_root>/data/. It must have the form:
{
"cases": [
{
"Image_0": "<DATA_DIR>/path/to/case_001_image.nii.gz",
"Segmentation_0": "<DATA_DIR>/path/to/case_001_segmentation.nii.gz"
},
...
]
}<DATA_DIR> is a placeholder resolved at load time to <project_root>/data; Segmentation_0 is only required for training when --use_segmentation is set. test.py always loads and warps the segmentation, regardless of how the model was trained, to produce the warped segmentation output.
Data requirements
- 3D CT volumes in NIfTI format (
.nii.gz) - Isotropic voxel spacing
- Intensity range clipped to HU
$[-1024, 1500]$ and normalized to$[0, 1]$
Project roots are configured per environment (local / cluster / jeanzay) in config.yaml; edit the paths: section to point at your own project root and JSON manifest location before running any script.
python train.py \
--config config.yaml \
--run_env local \
--fold 0 \
--batch_size 8 \
--epochs 1000 \
--lr 1e-4 \
--weight_consistency 100 \
--inverse_loss --transitivity_lossKey arguments (each defaults to the value given in --config unless overridden on the command line):
| Argument | Description |
|---|---|
--fold |
Cross-validation fold to train (0–4) |
--inverse_loss / --cycle_loss / --transitivity_loss
|
Enable the corresponding consistency term |
--weight_consistency |
Weight |
--use_segmentation |
Load segmentation masks alongside images (required for test.py to also warp and save the segmentation; not currently used as a network input) |
--resume |
Path to a .pth checkpoint to resume training from |
python test.py \
--run_env local \
--input_dir <experiment_folder_name> \
--batch_size 1 \
--verbose--input_dir names the experiment folder created under results/TrICON/ during training; its configuration is read back automatically to reconstruct the model. This step produces per-case registration outputs: warped image, displacement field, Jacobian, and warped segmentation.
- 254 thoracic CT scans.
- Images: Colin, J., Arnaud Arindra, A.S., Traverso, A., Van Ginneken, B. LUNA16: Lung Nodule Analysis 2016. https://luna16.grand-challenge.org/Data/ (2016).
- Expert annotations for six anatomical structures (airways, arteries, veins, lungs). Segmentations: Liu, J., Zhang, Z., Niu, B., Kang, S., Ren, J., Wang, L., Xu, K. A Custom Annotated Dataset for Segmentation of Pulmonary Veins, Arteries, and Airways. Scientific Data 12, 1806 (2025). https://doi.org/10.1038/s41597-025-06074-6
If you use TrICON in your research, please cite:
@inproceedings{marquez2024tricon,
title={TrICON: Learning Diffeomorphic Lung CT Registration through Triplet Consistency},
author={Marquez-Sosa, Maria and Saillard, \'Emile and Basarab, Adrian and Sdika, Micha\"el},
booktitle={Thoracic Image Analysis Workshop, MICCAI},
year={2026},
organization={Springer}
}This project is released under the MIT License; see LICENSE for details.
This repository is a derivative work built on two foundational projects from the UNCBIAG (Ultrasound Neuroimaging and Biomedical Image Computing) lab:
- ICON: Learning Regular Maps Through Inverse Consistency — Greer, H., Kwitt, R., Vialard, F.X., Niethammer, M.
- uniGradICON: A Foundation Model for Medical Image Registration — Tian, L., Greer, H., Kwitt, R., Vialard, F.X., et al.