diff --git a/ANTs_SyN/Prediction.yml b/ANTs_SyN/Prediction.yml new file mode 100644 index 0000000000000000000000000000000000000000..1f2cf5d3cfb03af75fbb42d5af1e529fd51063cc --- /dev/null +++ b/ANTs_SyN/Prediction.yml @@ -0,0 +1,91 @@ +Predictor: + Model: + classpath: model:RegistrationNet + RegistrationNet: + transform: SyN[0.2,3,0] + metric: CC[FIXED,MOVING,1,2] + convergence: '[100x70x50x20,1e-6,10]' + shrink_factors: 8x4x2x1 + smoothing_sigmas: 3x2x1x0vox + seed: 1 + threads: 0 + outputs_criterions: None + Dataset: + groups_src: + Volume_0: + groups_dest: + Fixed: + transforms: + TensorCast: + dtype: float32 + inverse: false + patch_transforms: None + is_input: true + Volume_1: + groups_dest: + Moving: + transforms: + TensorCast: + dtype: float32 + inverse: false + patch_transforms: None + is_input: true + Volume_2: + groups_dest: + FixedMask: + transforms: + TensorCast: + dtype: float32 + inverse: false + patch_transforms: None + is_input: true + Volume_3: + groups_dest: + MovingMask: + transforms: + TensorCast: + dtype: float32 + inverse: false + patch_transforms: None + is_input: true + augmentations: None + Patch: + patch_size: + - 0 + - 0 + - 0 + overlap: 0 + pad_value: None + extend_slice: 0 + mode: resample + max_voxels: None + subset: None + dataset_filenames: + - ./Dataset/:mha + batch_size: 1 + num_workers: None + pin_memory: false + prefetch_factor: None + persistent_workers: None + outputs_dataset: + DisplacementField: + OutputDataset: + name_class: OutputDataset + before_reduction_transforms: None + after_reduction_transforms: None + final_transforms: + TensorCast: + dtype: float32 + inverse: false + dataset_filename: DisplacementField:mha + group: DisplacementField + same_as_group: Volume_0:Fixed + patch_combine: Cosinus + reduction: Mean + Mean: {} + train_name: Baselines-ANTs_SyN + manual_seed: 42 + gpu_checkpoints: None + combine: Mean + autocast: false + data_log: None diff --git a/ANTs_SyN/app.json b/ANTs_SyN/app.json new file mode 100644 index 0000000000000000000000000000000000000000..9c39adb1752396c1c89871237d14b882aa0b34c5 --- /dev/null +++ b/ANTs_SyN/app.json @@ -0,0 +1,40 @@ +{ + "display_name": "ANTs SyN", + "short_description": "SyN as the Learn2Reg 2024 organisers ran it for LUMIR (antsRegistrationSyN[so]): cross-correlation of radius 2, from the identity, 100x70x50x20 iterations, single precision, on the ANTs 2.6.5 release binaries fetched on first use. The ImagingBenchmarks baseline ants. CPU.", + "description": "SyN as the Learn2Reg 2024 organisers ran it for LUMIR (antsRegistrationSyN[so]): cross-correlation of radius 2, from the identity, 100x70x50x20 iterations, single precision, on the ANTs 2.6.5 release binaries fetched on first use. The ImagingBenchmarks baseline ants. CPU. The pair must be aligned (rigidly for one patient, by an affine transform between two subjects): only the deformable stage runs. Masks are ignored by this baseline. Output: the displacement field on the fixed grid, in mm along the world axes (ITK, LPS).", + "task": "registration", + "tta": 0, + "mc_dropout": 0, + "models": [], + "inputs": { + "Fixed": { + "display_name": "Fixed image", + "volume_type": "VOLUME", + "required": true + }, + "Moving": { + "display_name": "Moving image", + "volume_type": "VOLUME", + "required": true + }, + "FixedMask": { + "display_name": "Fixed mask (ignored by this baseline)", + "volume_type": "SEGMENTATION", + "required": false, + "default": "ones" + }, + "MovingMask": { + "display_name": "Moving mask (ignored by this baseline)", + "volume_type": "SEGMENTATION", + "required": false, + "default": "ones" + } + }, + "outputs": { + "DisplacementField": { + "display_name": "Displacement field", + "volume_type": "VOLUME", + "required": true + } + } +} diff --git a/ANTs_SyN/baselines.py b/ANTs_SyN/baselines.py new file mode 100644 index 0000000000000000000000000000000000000000..691b6d9c745cf4c64ab8e323b21b5c76b251af72 --- /dev/null +++ b/ANTs_SyN/baselines.py @@ -0,0 +1,206 @@ +# Copyright (c) 2025 Valentin Boussot +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +# +# SPDX-License-Identifier: Apache-2.0 + +"""What every baseline app shares (a copy of the repository's baselines.py, kept by build.py): the authors' code fetched at its pin, the graph module that hands a pair to an +engine and gets a displacement field back, and the field's convention. + +The field is the benchmark's: one component per spatial axis, in mm along the world (ITK, LPS) axes, on the fixed +image's grid, such that the fixed point ``x`` matches ``x + u(x)`` in the moving image. The predictor attaches the +fixed image's geometry to the output (``same_as_group: Volume_0:Fixed`` in the app's ``Prediction.yml``). + +NOTE: do NOT add ``from __future__ import annotations``: KonfAI's config engine relies on runtime-evaluated +annotations (``get_origin``); PEP 563 stringized annotations break binding. +""" + +import hashlib +import os +import shutil +import subprocess # nosec B404 +import urllib.request +import zipfile +from collections.abc import Callable +from pathlib import Path + +import numpy as np +import SimpleITK as sitk +import torch +from konfai.network import network +from konfai.utils.dataset import Attribute, data_to_image + +#: An engine: (fixed, moving, fixed mask or None, moving mask or None, CUDA device index or -1) -> the field, +#: ``[D, *spatial]`` in mm along the world axes on the fixed grid. +Engine = Callable[[sitk.Image, sitk.Image, sitk.Image | None, sitk.Image | None, int], np.ndarray] + + +def cache_dir() -> Path: + """Where the authors' code and binaries live, once fetched: ``$BASELINES_KONFAI_CACHE`` or + ``~/.cache/baselines-konfai``.""" + return Path(os.environ.get("BASELINES_KONFAI_CACHE", Path.home() / ".cache" / "baselines-konfai")) + + +def pinned_source(name: str, url: str, commit: str) -> Path: + """The authors' repository at ``commit``, cloned once into the cache: a baseline runs the code it was + measured with, never a moving branch.""" + target = cache_dir() / f"{name}-{commit[:12]}" + if not (target / ".git").exists(): + target.parent.mkdir(parents=True, exist_ok=True) + subprocess.run(["git", "clone", "--quiet", url, str(target)], check=True) # nosec B603 B607 + subprocess.run(["git", "-C", str(target), "checkout", "--quiet", commit], check=True) # nosec B603 B607 + return target + + +def fetch(url: str, target: Path, sha256: str | None = None) -> Path: + """``url`` downloaded once to ``target`` and, when a hash is given, checked against it.""" + if not target.exists(): + target.parent.mkdir(parents=True, exist_ok=True) + part = target.with_name(target.name + ".part") + urllib.request.urlretrieve(url, part) # nosec B310 - the authors' release, checked below + with part.open("rb") as stream: + digest = hashlib.file_digest(stream, "sha256").hexdigest() + if sha256 and digest != sha256: + part.unlink() + raise RuntimeError(f"{url} does not match its recorded hash") + part.rename(target) + return target + + +def pinned_archive(name: str, url: str, sha256: str) -> Path: + """A release archive at ``url``, downloaded once into the cache, checked against ``sha256`` and unpacked: the + binaries a baseline was measured with.""" + target = cache_dir() / f"{name}-{sha256[:12]}" + if not (target / ".unpacked").exists(): + archive = fetch(url, target / "archive", sha256) + if zipfile.is_zipfile(archive): + with zipfile.ZipFile(archive) as packed: + packed.extractall(target) # nosec B202 - our own pinned archive + for entry in packed.infolist(): # zipfile drops the modes: the binaries must stay executable + if mode := (entry.external_attr >> 16) & 0o777: + (target / entry.filename).chmod(mode) + else: + shutil.unpack_archive(str(archive), str(target), "gztar") + archive.unlink() + (target / ".unpacked").touch() + return target + + +def pinned_environment(root: Path, python: str, installs: list[list[str]]) -> Path: + """A virtual environment at ``root/venv`` on its own Python, made once by uv (``pip install uv``): for the tools + whose pins do not run on the host's Python. ``installs`` are ``pip install`` argument lists, run in order.""" + try: + import uv + + command = uv.find_uv_bin() + except ImportError: + command = shutil.which("uv") or "" + if not command: + raise RuntimeError("this baseline builds its own Python environment with uv: pip install uv") + venv = root / "venv" + if not (venv / ".ready").exists(): + subprocess.run([command, "venv", "--quiet", "--clear", "--python", python, str(venv)], check=True) # nosec B603 + for arguments in installs: + subprocess.run( # nosec B603 + [ + command, + "pip", + "install", + "--quiet", + "--no-cache", + "--python", + str(venv / "bin" / "python"), + *arguments, + ], + check=True, + ) + (venv / ".ready").touch() + return venv + + +def built_source(name: str, url: str, commit: str, build: Callable[[Path], None]) -> Path: + """The authors' repository at ``commit``, built once by ``build`` (a marker says it is done).""" + source = pinned_source(name, url, commit) + if not (source / ".built").exists(): + build(source) + (source / ".built").touch() + return source + + +def field_from_voxels(displacement: np.ndarray, fixed: sitk.Image) -> np.ndarray: + """A displacement in voxels along the index axes, ``[i, j, k, D]``, as the benchmark's field ``[D, k, j, i]`` + in mm along the world axes: ``u = D S d``, with ``D`` the direction and ``S`` the spacing of the fixed image.""" + n = fixed.GetDimension() + to_world = np.array(fixed.GetDirection()).reshape(n, n) @ np.diag(fixed.GetSpacing()) + world = displacement.astype(np.float64) @ to_world.T # [i, j, k, D] + return np.ascontiguousarray(np.moveaxis(world, -1, 0).transpose(0, *reversed(range(1, n + 1))), dtype=np.float32) + + +def to_index_array(image: sitk.Image) -> np.ndarray: + """The image as a ``[i, j, k]`` array, the index axes in ITK's order, which the tools indexed that way read.""" + return np.ascontiguousarray(sitk.GetArrayFromImage(image).transpose(*reversed(range(image.GetDimension())))) + + +class Registration(torch.nn.Module): + """Graph module: the pair's tensors and their geometry in, the field out, through the engine, one sample at + a time. ``accepts_attributes = True`` opts it into the per-branch ``Attribute`` list (the convention of + ``CriterionWithAttribute``): registration needs the physical geometry.""" + + accepts_attributes = True + + def __init__(self, engine: Engine) -> None: + super().__init__() + self._engine = engine + + def forward( + self, + fixed: torch.Tensor, + moving: torch.Tensor, + fixed_mask: torch.Tensor, + moving_mask: torch.Tensor, + attributes: list[list[Attribute]], + ) -> torch.Tensor: + fixed_attrs, moving_attrs, fixed_mask_attrs, moving_mask_attrs = attributes + device_index = fixed.device.index if fixed.device.type == "cuda" else -1 + fields = [] + # the engines optimise with autograd; the predictor calls forward under inference mode + with torch.inference_mode(False), torch.enable_grad(): + for b in range(fixed.shape[0]): + images = [ + data_to_image(t[b].detach().cpu().numpy(), attrs[b]) + for t, attrs in ((fixed, fixed_attrs), (moving, moving_attrs)) + ] + masks = [ + data_to_image(t[b].detach().cpu().numpy(), attrs[b]) if not bool((t[b] == 1).all()) else None + for t, attrs in ((fixed_mask, fixed_mask_attrs), (moving_mask, moving_mask_attrs)) + ] + fields.append(torch.from_numpy(self._engine(images[0], images[1], masks[0], masks[1], device_index))) + return torch.stack(fields, dim=0).to(fixed.device) + + +class BaselineNet(network.Network): + """A baseline as an ``add_module`` graph: fixed = branch 0, moving = branch 1, the masks branches 2 and 3 (a + mask of ones means none). The one output is ``DisplacementField``, on the fixed grid.""" + + def __init__( + self, + engine: Engine, + dim: int, + optimizer: network.OptimizerLoader, + schedulers: dict[str, network.LRSchedulersLoader], + outputs_criterions: dict[str, network.TargetCriterionsLoader], + ) -> None: + super().__init__( + in_channels=1, optimizer=optimizer, schedulers=schedulers, outputs_criterions=outputs_criterions, dim=dim + ) + self.add_module("DisplacementField", Registration(engine), in_branch=[0, 1, 2, 3], out_branch=["dvf"]) diff --git a/ANTs_SyN/model.py b/ANTs_SyN/model.py new file mode 100644 index 0000000000000000000000000000000000000000..405eb5a43ba1773505c9e3645cae70ad4ae01def --- /dev/null +++ b/ANTs_SyN/model.py @@ -0,0 +1,172 @@ +# Copyright (c) 2025 Valentin Boussot +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +# +# SPDX-License-Identifier: Apache-2.0 + +"""ANTs SyN as the Learn2Reg 2024 organisers ran it for LUMIR, ``ants.registration(..., "antsRegistrationSyN[so]")``: +the ``antsRegistration`` command ANTsPy builds for it, on the ANTs release binaries at a pinned version. SyN alone +from the identity, cross-correlation of radius 2, 100x70x50x20 iterations at shrink factors 8x4x2x1, single precision, +a fixed random seed; then ``antsApplyTransforms`` writes the field on the fixed grid. Modalities and masks are +accepted and ignored: the organisers' call uses neither. + +NOTE: do NOT add ``from __future__ import annotations``: KonfAI's config engine relies on runtime-evaluated +annotations (``get_origin``); PEP 563 stringized annotations break binding. +""" + +import os +import subprocess # nosec B404 +import tempfile +from pathlib import Path +from typing import Annotated + +import numpy as np +import SimpleITK as sitk +from konfai.network import network + +from baselines import BaselineNet, pinned_archive + +VERSION = "2.6.5" +RELEASE = ( + "https://github.com/ANTsX/ANTs/releases/download/v2.6.5/ants-2.6.5-ubuntu-24.04-X64-gcc.zip", + "9f6a2c8881d6c94ea17171c0502e55cb898ad9afd50e4e23fde9a8c0997aa04b", +) + + +def binaries() -> Path: + """The release's ``bin/``, fetched once.""" + return pinned_archive("ants", *RELEASE) / f"ants-{VERSION}" + + +class AntsSyN: + def __init__( + self, + transform: str, + metric: str, + convergence: str, + shrink_factors: str, + smoothing_sigmas: str, + seed: int, + threads: int, + ) -> None: + self._transform, self._metric, self._convergence = transform, metric, convergence + self._shrink, self._smoothing, self._seed, self._threads = shrink_factors, smoothing_sigmas, seed, threads + + def __call__( + self, + fixed: sitk.Image, + moving: sitk.Image, + fixed_mask: sitk.Image | None, + moving_mask: sitk.Image | None, + device: int, + ) -> np.ndarray: + root = binaries() + environment = { + **os.environ, + "PATH": f"{root / 'bin'}:{os.environ.get('PATH', '')}", + "LD_LIBRARY_PATH": f"{root / 'lib'}:{os.environ.get('LD_LIBRARY_PATH', '')}", + "ITK_GLOBAL_DEFAULT_NUMBER_OF_THREADS": str(self._threads or os.cpu_count() or 1), + } + with tempfile.TemporaryDirectory(prefix="ants_") as scratch: + work = Path(scratch) + sitk.WriteImage(fixed, str(work / "fixed.nii.gz")) + sitk.WriteImage(moving, str(work / "moving.nii.gz")) + metric = self._metric.replace("FIXED", str(work / "fixed.nii.gz")).replace( + "MOVING", str(work / "moving.nii.gz") + ) + subprocess.run( # nosec B603 B607 + [ + "antsRegistration", + "--dimensionality", + "3", + "-r", + "Identity", + "--output", + str(work / "ants"), + "--transform", + self._transform, + "--metric", + metric, + "--convergence", + self._convergence, + "--shrink-factors", + self._shrink, + "--smoothing-sigmas", + self._smoothing, + "-x", + "[NA,NA]", + "--random-seed", + str(self._seed), + "--float", + "1", + "--write-composite-transform", + "0", + ], + check=True, + env=environment, + ) + # the warp's number follows the stages, the identity initialisation counted or not as the version chooses + warp = next(p for p in sorted(work.glob("ants*Warp.nii.gz")) if "InverseWarp" not in p.name) + subprocess.run( # nosec B603 B607 + [ + "antsApplyTransforms", + "-d", + "3", + "-r", + str(work / "fixed.nii.gz"), + "-t", + str(warp), + "-o", + f"DisplacementField[{work / 'field.nii.gz'}]", + "--float", + "1", + ], + check=True, + env=environment, + ) + field = sitk.ReadImage(str(work / "field.nii.gz"), sitk.sitkVectorFloat32) + return np.ascontiguousarray(np.moveaxis(sitk.GetArrayFromImage(field), -1, 0), dtype=np.float32) + + +class RegistrationNet(BaselineNet): + """ANTs SyN, the Learn2Reg 2024 organisers' call. CPU.""" + + def __init__( + self, + optimizer: network.OptimizerLoader = network.OptimizerLoader(), + schedulers: dict[str, network.LRSchedulersLoader] = { + "default:ReduceLROnPlateau": network.LRSchedulersLoader(0) + }, + outputs_criterions: dict[str, network.TargetCriterionsLoader] = {"default": network.TargetCriterionsLoader()}, + transform: Annotated[ + str, "antsRegistration's --transform: SyN[gradient step, update field variance, total field variance]." + ] = "SyN[0.2,3,0]", + metric: Annotated[ + str, + "antsRegistration's --metric, FIXED and MOVING standing for the images: CC[fixed, moving, weight, radius].", + ] = "CC[FIXED,MOVING,1,2]", + convergence: Annotated[ + str, "antsRegistration's --convergence: iterations per level, threshold, window." + ] = "[100x70x50x20,1e-6,10]", + shrink_factors: Annotated[str, "antsRegistration's --shrink-factors."] = "8x4x2x1", + smoothing_sigmas: Annotated[str, "antsRegistration's --smoothing-sigmas."] = "3x2x1x0vox", + seed: Annotated[int, "antsRegistration's --random-seed, the one setting not in ANTsPy's call."] = 1, + threads: Annotated[int, "ITK threads; 0 takes every core."] = 0, + ) -> None: + super().__init__( + AntsSyN(transform, metric, convergence, shrink_factors, smoothing_sigmas, seed, threads), + 3, + optimizer, + schedulers, + outputs_criterions, + ) diff --git a/ANTs_SyN/requirements.txt b/ANTs_SyN/requirements.txt new file mode 100644 index 0000000000000000000000000000000000000000..7f5e98e3f968b22748bf799bc7f38e5b2fe45da3 --- /dev/null +++ b/ANTs_SyN/requirements.txt @@ -0,0 +1 @@ +SimpleITK diff --git a/Anatomix_ConvexAdam/Prediction.yml b/Anatomix_ConvexAdam/Prediction.yml new file mode 100644 index 0000000000000000000000000000000000000000..2f1720a3da98fc67f7d6e0467d0bb58810942b14 --- /dev/null +++ b/Anatomix_ConvexAdam/Prediction.yml @@ -0,0 +1,86 @@ +Predictor: + Model: + classpath: model:RegistrationNet + RegistrationNet: + fixed_modality: auto + moving_modality: auto + outputs_criterions: None + Dataset: + groups_src: + Volume_0: + groups_dest: + Fixed: + transforms: + TensorCast: + dtype: float32 + inverse: false + patch_transforms: None + is_input: true + Volume_1: + groups_dest: + Moving: + transforms: + TensorCast: + dtype: float32 + inverse: false + patch_transforms: None + is_input: true + Volume_2: + groups_dest: + FixedMask: + transforms: + TensorCast: + dtype: float32 + inverse: false + patch_transforms: None + is_input: true + Volume_3: + groups_dest: + MovingMask: + transforms: + TensorCast: + dtype: float32 + inverse: false + patch_transforms: None + is_input: true + augmentations: None + Patch: + patch_size: + - 0 + - 0 + - 0 + overlap: 0 + pad_value: None + extend_slice: 0 + mode: resample + max_voxels: None + subset: None + dataset_filenames: + - ./Dataset/:mha + batch_size: 1 + num_workers: None + pin_memory: false + prefetch_factor: None + persistent_workers: None + outputs_dataset: + DisplacementField: + OutputDataset: + name_class: OutputDataset + before_reduction_transforms: None + after_reduction_transforms: None + final_transforms: + TensorCast: + dtype: float32 + inverse: false + dataset_filename: DisplacementField:mha + group: DisplacementField + same_as_group: Volume_0:Fixed + patch_combine: Cosinus + reduction: Mean + Mean: {} + train_name: Baselines-Anatomix_ConvexAdam + manual_seed: 42 + gpu_checkpoints: None + combine: Mean + autocast: false + data_log: None diff --git a/Anatomix_ConvexAdam/app.json b/Anatomix_ConvexAdam/app.json new file mode 100644 index 0000000000000000000000000000000000000000..ab3e6b9379d53f2aa6677a2fff2e99497af26f03 --- /dev/null +++ b/Anatomix_ConvexAdam/app.json @@ -0,0 +1,40 @@ +{ + "display_name": "anatomix + ConvexAdam", + "short_description": "The ICLR 2025 pipeline of neel-dey/anatomix at a pinned commit, through its own convex_adam() with the defaults of its script: 16 anatomix and 12 MIND-SSC channels compared by SSD, diffusion weight 0.75, convex grid 2 with search half-width 1, 80 Adam steps on a grid of 2; CT clipped to [-450, 450] HU. The ImagingBenchmarks baseline anatomix_convexadam.", + "description": "The ICLR 2025 pipeline of neel-dey/anatomix at a pinned commit, through its own convex_adam() with the defaults of its script: 16 anatomix and 12 MIND-SSC channels compared by SSD, diffusion weight 0.75, convex grid 2 with search half-width 1, 80 Adam steps on a grid of 2; CT clipped to [-450, 450] HU. The ImagingBenchmarks baseline anatomix_convexadam. The pair must be aligned (rigidly for one patient, by an affine transform between two subjects): only the deformable stage runs. The weights come from the authors' Hugging Face repository at a pinned revision. A GPU is needed. Output: the displacement field on the fixed grid, in mm along the world axes (ITK, LPS).", + "task": "registration", + "tta": 0, + "mc_dropout": 0, + "models": [], + "inputs": { + "Fixed": { + "display_name": "Fixed image", + "volume_type": "VOLUME", + "required": true + }, + "Moving": { + "display_name": "Moving image", + "volume_type": "VOLUME", + "required": true + }, + "FixedMask": { + "display_name": "Fixed mask (ignored by this baseline)", + "volume_type": "SEGMENTATION", + "required": false, + "default": "ones" + }, + "MovingMask": { + "display_name": "Moving mask (ignored by this baseline)", + "volume_type": "SEGMENTATION", + "required": false, + "default": "ones" + } + }, + "outputs": { + "DisplacementField": { + "display_name": "Displacement field", + "volume_type": "VOLUME", + "required": true + } + } +} diff --git a/Anatomix_ConvexAdam/baselines.py b/Anatomix_ConvexAdam/baselines.py new file mode 100644 index 0000000000000000000000000000000000000000..691b6d9c745cf4c64ab8e323b21b5c76b251af72 --- /dev/null +++ b/Anatomix_ConvexAdam/baselines.py @@ -0,0 +1,206 @@ +# Copyright (c) 2025 Valentin Boussot +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +# +# SPDX-License-Identifier: Apache-2.0 + +"""What every baseline app shares (a copy of the repository's baselines.py, kept by build.py): the authors' code fetched at its pin, the graph module that hands a pair to an +engine and gets a displacement field back, and the field's convention. + +The field is the benchmark's: one component per spatial axis, in mm along the world (ITK, LPS) axes, on the fixed +image's grid, such that the fixed point ``x`` matches ``x + u(x)`` in the moving image. The predictor attaches the +fixed image's geometry to the output (``same_as_group: Volume_0:Fixed`` in the app's ``Prediction.yml``). + +NOTE: do NOT add ``from __future__ import annotations``: KonfAI's config engine relies on runtime-evaluated +annotations (``get_origin``); PEP 563 stringized annotations break binding. +""" + +import hashlib +import os +import shutil +import subprocess # nosec B404 +import urllib.request +import zipfile +from collections.abc import Callable +from pathlib import Path + +import numpy as np +import SimpleITK as sitk +import torch +from konfai.network import network +from konfai.utils.dataset import Attribute, data_to_image + +#: An engine: (fixed, moving, fixed mask or None, moving mask or None, CUDA device index or -1) -> the field, +#: ``[D, *spatial]`` in mm along the world axes on the fixed grid. +Engine = Callable[[sitk.Image, sitk.Image, sitk.Image | None, sitk.Image | None, int], np.ndarray] + + +def cache_dir() -> Path: + """Where the authors' code and binaries live, once fetched: ``$BASELINES_KONFAI_CACHE`` or + ``~/.cache/baselines-konfai``.""" + return Path(os.environ.get("BASELINES_KONFAI_CACHE", Path.home() / ".cache" / "baselines-konfai")) + + +def pinned_source(name: str, url: str, commit: str) -> Path: + """The authors' repository at ``commit``, cloned once into the cache: a baseline runs the code it was + measured with, never a moving branch.""" + target = cache_dir() / f"{name}-{commit[:12]}" + if not (target / ".git").exists(): + target.parent.mkdir(parents=True, exist_ok=True) + subprocess.run(["git", "clone", "--quiet", url, str(target)], check=True) # nosec B603 B607 + subprocess.run(["git", "-C", str(target), "checkout", "--quiet", commit], check=True) # nosec B603 B607 + return target + + +def fetch(url: str, target: Path, sha256: str | None = None) -> Path: + """``url`` downloaded once to ``target`` and, when a hash is given, checked against it.""" + if not target.exists(): + target.parent.mkdir(parents=True, exist_ok=True) + part = target.with_name(target.name + ".part") + urllib.request.urlretrieve(url, part) # nosec B310 - the authors' release, checked below + with part.open("rb") as stream: + digest = hashlib.file_digest(stream, "sha256").hexdigest() + if sha256 and digest != sha256: + part.unlink() + raise RuntimeError(f"{url} does not match its recorded hash") + part.rename(target) + return target + + +def pinned_archive(name: str, url: str, sha256: str) -> Path: + """A release archive at ``url``, downloaded once into the cache, checked against ``sha256`` and unpacked: the + binaries a baseline was measured with.""" + target = cache_dir() / f"{name}-{sha256[:12]}" + if not (target / ".unpacked").exists(): + archive = fetch(url, target / "archive", sha256) + if zipfile.is_zipfile(archive): + with zipfile.ZipFile(archive) as packed: + packed.extractall(target) # nosec B202 - our own pinned archive + for entry in packed.infolist(): # zipfile drops the modes: the binaries must stay executable + if mode := (entry.external_attr >> 16) & 0o777: + (target / entry.filename).chmod(mode) + else: + shutil.unpack_archive(str(archive), str(target), "gztar") + archive.unlink() + (target / ".unpacked").touch() + return target + + +def pinned_environment(root: Path, python: str, installs: list[list[str]]) -> Path: + """A virtual environment at ``root/venv`` on its own Python, made once by uv (``pip install uv``): for the tools + whose pins do not run on the host's Python. ``installs`` are ``pip install`` argument lists, run in order.""" + try: + import uv + + command = uv.find_uv_bin() + except ImportError: + command = shutil.which("uv") or "" + if not command: + raise RuntimeError("this baseline builds its own Python environment with uv: pip install uv") + venv = root / "venv" + if not (venv / ".ready").exists(): + subprocess.run([command, "venv", "--quiet", "--clear", "--python", python, str(venv)], check=True) # nosec B603 + for arguments in installs: + subprocess.run( # nosec B603 + [ + command, + "pip", + "install", + "--quiet", + "--no-cache", + "--python", + str(venv / "bin" / "python"), + *arguments, + ], + check=True, + ) + (venv / ".ready").touch() + return venv + + +def built_source(name: str, url: str, commit: str, build: Callable[[Path], None]) -> Path: + """The authors' repository at ``commit``, built once by ``build`` (a marker says it is done).""" + source = pinned_source(name, url, commit) + if not (source / ".built").exists(): + build(source) + (source / ".built").touch() + return source + + +def field_from_voxels(displacement: np.ndarray, fixed: sitk.Image) -> np.ndarray: + """A displacement in voxels along the index axes, ``[i, j, k, D]``, as the benchmark's field ``[D, k, j, i]`` + in mm along the world axes: ``u = D S d``, with ``D`` the direction and ``S`` the spacing of the fixed image.""" + n = fixed.GetDimension() + to_world = np.array(fixed.GetDirection()).reshape(n, n) @ np.diag(fixed.GetSpacing()) + world = displacement.astype(np.float64) @ to_world.T # [i, j, k, D] + return np.ascontiguousarray(np.moveaxis(world, -1, 0).transpose(0, *reversed(range(1, n + 1))), dtype=np.float32) + + +def to_index_array(image: sitk.Image) -> np.ndarray: + """The image as a ``[i, j, k]`` array, the index axes in ITK's order, which the tools indexed that way read.""" + return np.ascontiguousarray(sitk.GetArrayFromImage(image).transpose(*reversed(range(image.GetDimension())))) + + +class Registration(torch.nn.Module): + """Graph module: the pair's tensors and their geometry in, the field out, through the engine, one sample at + a time. ``accepts_attributes = True`` opts it into the per-branch ``Attribute`` list (the convention of + ``CriterionWithAttribute``): registration needs the physical geometry.""" + + accepts_attributes = True + + def __init__(self, engine: Engine) -> None: + super().__init__() + self._engine = engine + + def forward( + self, + fixed: torch.Tensor, + moving: torch.Tensor, + fixed_mask: torch.Tensor, + moving_mask: torch.Tensor, + attributes: list[list[Attribute]], + ) -> torch.Tensor: + fixed_attrs, moving_attrs, fixed_mask_attrs, moving_mask_attrs = attributes + device_index = fixed.device.index if fixed.device.type == "cuda" else -1 + fields = [] + # the engines optimise with autograd; the predictor calls forward under inference mode + with torch.inference_mode(False), torch.enable_grad(): + for b in range(fixed.shape[0]): + images = [ + data_to_image(t[b].detach().cpu().numpy(), attrs[b]) + for t, attrs in ((fixed, fixed_attrs), (moving, moving_attrs)) + ] + masks = [ + data_to_image(t[b].detach().cpu().numpy(), attrs[b]) if not bool((t[b] == 1).all()) else None + for t, attrs in ((fixed_mask, fixed_mask_attrs), (moving_mask, moving_mask_attrs)) + ] + fields.append(torch.from_numpy(self._engine(images[0], images[1], masks[0], masks[1], device_index))) + return torch.stack(fields, dim=0).to(fixed.device) + + +class BaselineNet(network.Network): + """A baseline as an ``add_module`` graph: fixed = branch 0, moving = branch 1, the masks branches 2 and 3 (a + mask of ones means none). The one output is ``DisplacementField``, on the fixed grid.""" + + def __init__( + self, + engine: Engine, + dim: int, + optimizer: network.OptimizerLoader, + schedulers: dict[str, network.LRSchedulersLoader], + outputs_criterions: dict[str, network.TargetCriterionsLoader], + ) -> None: + super().__init__( + in_channels=1, optimizer=optimizer, schedulers=schedulers, outputs_criterions=outputs_criterions, dim=dim + ) + self.add_module("DisplacementField", Registration(engine), in_branch=[0, 1, 2, 3], out_branch=["dvf"]) diff --git a/Anatomix_ConvexAdam/model.py b/Anatomix_ConvexAdam/model.py new file mode 100644 index 0000000000000000000000000000000000000000..abf9f6f129e8758f11d197ecfa1a3f69ef669213 --- /dev/null +++ b/Anatomix_ConvexAdam/model.py @@ -0,0 +1,165 @@ +# Copyright (c) 2025 Valentin Boussot +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +# +# SPDX-License-Identifier: Apache-2.0 + +"""anatomix features in ConvexAdam, the ICLR 2025 pipeline of neel-dey/anatomix at a pinned commit, through its own +``convex_adam()`` with the defaults of its command-line script: 16 anatomix channels and 12 MIND-SSC channels compared +by SSD, diffusion weight 0.75, convex grid 2 with search half-width 1, 80 Adam steps on a grid of 2; CT clipped to +[-450, 450] HU as in the README. The weights come from the authors' Hugging Face repository at a pinned revision. + +NOTE: do NOT add ``from __future__ import annotations``: KonfAI's config engine relies on runtime-evaluated +annotations (``get_origin``); PEP 563 stringized annotations break binding. +""" + +import glob +import hashlib +import os +import sys +import tempfile +from typing import Annotated + +import numpy as np +import SimpleITK as sitk +from konfai.network import network +from konfai.utils.config import Choices + +from baselines import BaselineNet, cache_dir, pinned_source + +REPOSITORY = "https://github.com/neel-dey/anatomix" +COMMIT = "4c86aeeca5e4bf712d9e5775a01fadb37b30c13a" # main, 2026-09-19 +WEIGHTS = ("neeldey/anatomix", "anatomix.pth", "842cfe9", None) # repo, file, revision, sha256 (checked when known) +CT_WINDOW = (-450.0, 450.0) +SETTINGS = { + "hf_variant": "anatomix", + "lambda_weight": 0.75, + "grid_sp": 2, + "disp_hw": 1, + "selected_niter": 80, + "selected_smooth": 0, + "grid_sp_adam": 2, + "ic": True, + "use_mask": False, +} + + +def to_field(displacement: np.ndarray, fixed: sitk.Image) -> np.ndarray: + """The backend's displacement, ``(I, J, K, 3)`` on the even-padded fixed grid in voxels, as the field on the + unpadded fixed grid in mm along the world axes: the backend's grid_sample convention scales by n / (n - 1).""" + n = np.array(displacement.shape[:3], float) + d = (displacement * (n / (n - 1)))[tuple(slice(s) for s in fixed.GetSize())] + u = (d * fixed.GetSpacing()) @ np.reshape(fixed.GetDirection(), (3, 3)).T + return np.ascontiguousarray(np.moveaxis(u.transpose(2, 1, 0, 3), -1, 0), dtype=np.float32) + + +def weights_home() -> str: + """A Hugging Face home of our own, with the authors' weights at the pinned revision and refs/main pointing at + it: the pipeline loads them with ``revision=None`` and would otherwise follow their main branch.""" + from huggingface_hub import hf_hub_download + + home = cache_dir() / "anatomix" / "hf_home" + repo, filename, revision, digest = WEIGHTS + os.environ.setdefault("HF_HOME", str(home)) + path = hf_hub_download(repo, filename, revision=revision, cache_dir=str(home / "hub")) + if digest and hashlib.sha256(open(path, "rb").read()).hexdigest() != digest: + raise RuntimeError("the anatomix weights do not match their published hash") + refs = home / "hub" / f"models--{repo.replace('/', '--')}" / "refs" + refs.mkdir(parents=True, exist_ok=True) + (refs / "main").write_text(revision) + return str(home) + + +class AnatomixConvexAdam: + def __init__(self, fixed_modality: str, moving_modality: str) -> None: + self._modalities = (fixed_modality, moving_modality) + + def __call__( + self, + fixed: sitk.Image, + moving: sitk.Image, + fixed_mask: sitk.Image | None, + moving_mask: sitk.Image | None, + device: int, + ) -> np.ndarray: + import nibabel as nib + + source = pinned_source("anatomix", REPOSITORY, COMMIT) + if str(source) not in sys.path: + sys.path.insert(0, str(source)) + os.environ["HF_HOME"] = weights_home() + os.environ["HF_HUB_OFFLINE"] = "1" + from anatomix.registration.registration_backend.convexadam import convex_adam + + fixed, moving = sitk.Cast(fixed, sitk.sitkFloat32), sitk.Cast(moving, sitk.sitkFloat32) + if min(fixed.GetSize()) < 8: + raise ValueError(f"anatomix ConvexAdam needs at least 8 voxels per axis: {fixed.GetSize()}") + moving = sitk.Resample( + moving, + fixed, + sitk.Transform(), + sitk.sitkLinear, + float(sitk.GetArrayViewFromImage(moving).min()), + sitk.sitkFloat32, + ) + pad = [(0, s % 2) for s in fixed.GetSize()] + modalities = [ + m if m != "auto" else ("ct" if float(sitk.GetArrayViewFromImage(i).min()) < -200 else "mr") + for m, i in zip(self._modalities, (fixed, moving), strict=True) + ] + clips = [CT_WINDOW if m == "ct" else (None, None) for m in modalities] + with tempfile.TemporaryDirectory(prefix="anatomix_") as scratch: + paths = [] + for name, image in (("fixed", fixed), ("moving", moving)): + array = np.pad(sitk.GetArrayFromImage(image).transpose(2, 1, 0), pad, mode="edge") + paths.append(os.path.join(scratch, f"{name}.nii")) + nib.save(nib.Nifti1Image(array, np.eye(4)), paths[-1]) + convex_adam( + expname="bench", + result_path=scratch, + fixed_image=paths[0], + moving_image=paths[1], + fixed_minclip=clips[0][0], + fixed_maxclip=clips[0][1], + moving_minclip=clips[1][0], + moving_maxclip=clips[1][1], + **SETTINGS, + ) + displacement = nib.load(glob.glob(os.path.join(scratch, "disp_*.nii.gz"))[0]).get_fdata(dtype=np.float32) + return to_field(displacement, fixed) + + +class RegistrationNet(BaselineNet): + """anatomix + ConvexAdam, the authors' pipeline with the defaults of their script. A GPU is needed.""" + + def __init__( + self, + optimizer: network.OptimizerLoader = network.OptimizerLoader(), + schedulers: dict[str, network.LRSchedulersLoader] = { + "default:ReduceLROnPlateau": network.LRSchedulersLoader(0) + }, + outputs_criterions: dict[str, network.TargetCriterionsLoader] = {"default": network.TargetCriterionsLoader()}, + fixed_modality: Annotated[ + str, + Choices(["auto", "ct", "mr"]), + "ct clips the fixed image to [-450, 450] HU; auto reads it off the intensities.", + ] = "auto", + moving_modality: Annotated[ + str, + Choices(["auto", "ct", "mr"]), + "ct clips the moving image to [-450, 450] HU; auto reads it off the intensities.", + ] = "auto", + ) -> None: + super().__init__( + AnatomixConvexAdam(fixed_modality, moving_modality), 3, optimizer, schedulers, outputs_criterions + ) diff --git a/Anatomix_ConvexAdam/requirements.txt b/Anatomix_ConvexAdam/requirements.txt new file mode 100644 index 0000000000000000000000000000000000000000..7f260e22be74258775e024032ae8a752c4b4a842 --- /dev/null +++ b/Anatomix_ConvexAdam/requirements.txt @@ -0,0 +1,5 @@ +SimpleITK +nibabel +monai==1.6.1 +huggingface_hub +scikit-learn diff --git a/BrainMorph/Prediction.yml b/BrainMorph/Prediction.yml new file mode 100644 index 0000000000000000000000000000000000000000..f1cc571ffba5530220884b65edff3067d15abe42 --- /dev/null +++ b/BrainMorph/Prediction.yml @@ -0,0 +1,87 @@ +Predictor: + Model: + classpath: model:RegistrationNet + RegistrationNet: + keypoints: 512 + variant: H + align: tps_0 + outputs_criterions: None + Dataset: + groups_src: + Volume_0: + groups_dest: + Fixed: + transforms: + TensorCast: + dtype: float32 + inverse: false + patch_transforms: None + is_input: true + Volume_1: + groups_dest: + Moving: + transforms: + TensorCast: + dtype: float32 + inverse: false + patch_transforms: None + is_input: true + Volume_2: + groups_dest: + FixedMask: + transforms: + TensorCast: + dtype: float32 + inverse: false + patch_transforms: None + is_input: true + Volume_3: + groups_dest: + MovingMask: + transforms: + TensorCast: + dtype: float32 + inverse: false + patch_transforms: None + is_input: true + augmentations: None + Patch: + patch_size: + - 0 + - 0 + - 0 + overlap: 0 + pad_value: None + extend_slice: 0 + mode: resample + max_voxels: None + subset: None + dataset_filenames: + - ./Dataset/:mha + batch_size: 1 + num_workers: None + pin_memory: false + prefetch_factor: None + persistent_workers: None + outputs_dataset: + DisplacementField: + OutputDataset: + name_class: OutputDataset + before_reduction_transforms: None + after_reduction_transforms: None + final_transforms: + TensorCast: + dtype: float32 + inverse: false + dataset_filename: DisplacementField:mha + group: DisplacementField + same_as_group: Volume_0:Fixed + patch_combine: Cosinus + reduction: Mean + Mean: {} + train_name: Baselines-BrainMorph + manual_seed: 42 + gpu_checkpoints: None + combine: Mean + autocast: false + data_log: None diff --git a/BrainMorph/app.json b/BrainMorph/app.json new file mode 100644 index 0000000000000000000000000000000000000000..b3c7924993bfedfc10c43e3722b29d264d1d738b --- /dev/null +++ b/BrainMorph/app.json @@ -0,0 +1,40 @@ +{ + "display_name": "BrainMorph", + "short_description": "BrainMorph as the LUMIR organisers run it: 512 keypoints, the H model, thin-plate splines without regularisation; a keypoint network trained on 100,000 brain MR images. The ImagingBenchmarks baseline brainmorph.", + "description": "BrainMorph as the LUMIR organisers run it: 512 keypoints, the H model, thin-plate splines without regularisation; a keypoint network trained on 100,000 brain MR images. The ImagingBenchmarks baseline brainmorph. Brain MR, aligned pairs. The authors' repository at the commit of the LUMIR call (later commits dropped the H model), with its dependencies at versions of that date (torch 2.3 on Python 3.11) in an environment uv builds on first use (5 GB), and the weights checked against their hash. A GPU is recommended, up to the Ada generation: torch 2.3 has no kernels for Blackwell GPUs, so there the app runs on the CPU (no --gpu). Masks are ignored by this baseline. Output: the displacement field on the fixed grid, in mm along the world axes (ITK, LPS).

How to cite:
A. Q. Wang et al., BrainMorph: A foundational keypoint model for robust and flexible brain MRI registration, MELBA 2025.", + "task": "registration", + "tta": 0, + "mc_dropout": 0, + "models": [], + "inputs": { + "Fixed": { + "display_name": "Fixed image", + "volume_type": "VOLUME", + "required": true + }, + "Moving": { + "display_name": "Moving image", + "volume_type": "VOLUME", + "required": true + }, + "FixedMask": { + "display_name": "Fixed mask (ignored by this baseline)", + "volume_type": "SEGMENTATION", + "required": false, + "default": "ones" + }, + "MovingMask": { + "display_name": "Moving mask (ignored by this baseline)", + "volume_type": "SEGMENTATION", + "required": false, + "default": "ones" + } + }, + "outputs": { + "DisplacementField": { + "display_name": "Displacement field", + "volume_type": "VOLUME", + "required": true + } + } +} diff --git a/BrainMorph/baselines.py b/BrainMorph/baselines.py new file mode 100644 index 0000000000000000000000000000000000000000..691b6d9c745cf4c64ab8e323b21b5c76b251af72 --- /dev/null +++ b/BrainMorph/baselines.py @@ -0,0 +1,206 @@ +# Copyright (c) 2025 Valentin Boussot +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +# +# SPDX-License-Identifier: Apache-2.0 + +"""What every baseline app shares (a copy of the repository's baselines.py, kept by build.py): the authors' code fetched at its pin, the graph module that hands a pair to an +engine and gets a displacement field back, and the field's convention. + +The field is the benchmark's: one component per spatial axis, in mm along the world (ITK, LPS) axes, on the fixed +image's grid, such that the fixed point ``x`` matches ``x + u(x)`` in the moving image. The predictor attaches the +fixed image's geometry to the output (``same_as_group: Volume_0:Fixed`` in the app's ``Prediction.yml``). + +NOTE: do NOT add ``from __future__ import annotations``: KonfAI's config engine relies on runtime-evaluated +annotations (``get_origin``); PEP 563 stringized annotations break binding. +""" + +import hashlib +import os +import shutil +import subprocess # nosec B404 +import urllib.request +import zipfile +from collections.abc import Callable +from pathlib import Path + +import numpy as np +import SimpleITK as sitk +import torch +from konfai.network import network +from konfai.utils.dataset import Attribute, data_to_image + +#: An engine: (fixed, moving, fixed mask or None, moving mask or None, CUDA device index or -1) -> the field, +#: ``[D, *spatial]`` in mm along the world axes on the fixed grid. +Engine = Callable[[sitk.Image, sitk.Image, sitk.Image | None, sitk.Image | None, int], np.ndarray] + + +def cache_dir() -> Path: + """Where the authors' code and binaries live, once fetched: ``$BASELINES_KONFAI_CACHE`` or + ``~/.cache/baselines-konfai``.""" + return Path(os.environ.get("BASELINES_KONFAI_CACHE", Path.home() / ".cache" / "baselines-konfai")) + + +def pinned_source(name: str, url: str, commit: str) -> Path: + """The authors' repository at ``commit``, cloned once into the cache: a baseline runs the code it was + measured with, never a moving branch.""" + target = cache_dir() / f"{name}-{commit[:12]}" + if not (target / ".git").exists(): + target.parent.mkdir(parents=True, exist_ok=True) + subprocess.run(["git", "clone", "--quiet", url, str(target)], check=True) # nosec B603 B607 + subprocess.run(["git", "-C", str(target), "checkout", "--quiet", commit], check=True) # nosec B603 B607 + return target + + +def fetch(url: str, target: Path, sha256: str | None = None) -> Path: + """``url`` downloaded once to ``target`` and, when a hash is given, checked against it.""" + if not target.exists(): + target.parent.mkdir(parents=True, exist_ok=True) + part = target.with_name(target.name + ".part") + urllib.request.urlretrieve(url, part) # nosec B310 - the authors' release, checked below + with part.open("rb") as stream: + digest = hashlib.file_digest(stream, "sha256").hexdigest() + if sha256 and digest != sha256: + part.unlink() + raise RuntimeError(f"{url} does not match its recorded hash") + part.rename(target) + return target + + +def pinned_archive(name: str, url: str, sha256: str) -> Path: + """A release archive at ``url``, downloaded once into the cache, checked against ``sha256`` and unpacked: the + binaries a baseline was measured with.""" + target = cache_dir() / f"{name}-{sha256[:12]}" + if not (target / ".unpacked").exists(): + archive = fetch(url, target / "archive", sha256) + if zipfile.is_zipfile(archive): + with zipfile.ZipFile(archive) as packed: + packed.extractall(target) # nosec B202 - our own pinned archive + for entry in packed.infolist(): # zipfile drops the modes: the binaries must stay executable + if mode := (entry.external_attr >> 16) & 0o777: + (target / entry.filename).chmod(mode) + else: + shutil.unpack_archive(str(archive), str(target), "gztar") + archive.unlink() + (target / ".unpacked").touch() + return target + + +def pinned_environment(root: Path, python: str, installs: list[list[str]]) -> Path: + """A virtual environment at ``root/venv`` on its own Python, made once by uv (``pip install uv``): for the tools + whose pins do not run on the host's Python. ``installs`` are ``pip install`` argument lists, run in order.""" + try: + import uv + + command = uv.find_uv_bin() + except ImportError: + command = shutil.which("uv") or "" + if not command: + raise RuntimeError("this baseline builds its own Python environment with uv: pip install uv") + venv = root / "venv" + if not (venv / ".ready").exists(): + subprocess.run([command, "venv", "--quiet", "--clear", "--python", python, str(venv)], check=True) # nosec B603 + for arguments in installs: + subprocess.run( # nosec B603 + [ + command, + "pip", + "install", + "--quiet", + "--no-cache", + "--python", + str(venv / "bin" / "python"), + *arguments, + ], + check=True, + ) + (venv / ".ready").touch() + return venv + + +def built_source(name: str, url: str, commit: str, build: Callable[[Path], None]) -> Path: + """The authors' repository at ``commit``, built once by ``build`` (a marker says it is done).""" + source = pinned_source(name, url, commit) + if not (source / ".built").exists(): + build(source) + (source / ".built").touch() + return source + + +def field_from_voxels(displacement: np.ndarray, fixed: sitk.Image) -> np.ndarray: + """A displacement in voxels along the index axes, ``[i, j, k, D]``, as the benchmark's field ``[D, k, j, i]`` + in mm along the world axes: ``u = D S d``, with ``D`` the direction and ``S`` the spacing of the fixed image.""" + n = fixed.GetDimension() + to_world = np.array(fixed.GetDirection()).reshape(n, n) @ np.diag(fixed.GetSpacing()) + world = displacement.astype(np.float64) @ to_world.T # [i, j, k, D] + return np.ascontiguousarray(np.moveaxis(world, -1, 0).transpose(0, *reversed(range(1, n + 1))), dtype=np.float32) + + +def to_index_array(image: sitk.Image) -> np.ndarray: + """The image as a ``[i, j, k]`` array, the index axes in ITK's order, which the tools indexed that way read.""" + return np.ascontiguousarray(sitk.GetArrayFromImage(image).transpose(*reversed(range(image.GetDimension())))) + + +class Registration(torch.nn.Module): + """Graph module: the pair's tensors and their geometry in, the field out, through the engine, one sample at + a time. ``accepts_attributes = True`` opts it into the per-branch ``Attribute`` list (the convention of + ``CriterionWithAttribute``): registration needs the physical geometry.""" + + accepts_attributes = True + + def __init__(self, engine: Engine) -> None: + super().__init__() + self._engine = engine + + def forward( + self, + fixed: torch.Tensor, + moving: torch.Tensor, + fixed_mask: torch.Tensor, + moving_mask: torch.Tensor, + attributes: list[list[Attribute]], + ) -> torch.Tensor: + fixed_attrs, moving_attrs, fixed_mask_attrs, moving_mask_attrs = attributes + device_index = fixed.device.index if fixed.device.type == "cuda" else -1 + fields = [] + # the engines optimise with autograd; the predictor calls forward under inference mode + with torch.inference_mode(False), torch.enable_grad(): + for b in range(fixed.shape[0]): + images = [ + data_to_image(t[b].detach().cpu().numpy(), attrs[b]) + for t, attrs in ((fixed, fixed_attrs), (moving, moving_attrs)) + ] + masks = [ + data_to_image(t[b].detach().cpu().numpy(), attrs[b]) if not bool((t[b] == 1).all()) else None + for t, attrs in ((fixed_mask, fixed_mask_attrs), (moving_mask, moving_mask_attrs)) + ] + fields.append(torch.from_numpy(self._engine(images[0], images[1], masks[0], masks[1], device_index))) + return torch.stack(fields, dim=0).to(fixed.device) + + +class BaselineNet(network.Network): + """A baseline as an ``add_module`` graph: fixed = branch 0, moving = branch 1, the masks branches 2 and 3 (a + mask of ones means none). The one output is ``DisplacementField``, on the fixed grid.""" + + def __init__( + self, + engine: Engine, + dim: int, + optimizer: network.OptimizerLoader, + schedulers: dict[str, network.LRSchedulersLoader], + outputs_criterions: dict[str, network.TargetCriterionsLoader], + ) -> None: + super().__init__( + in_channels=1, optimizer=optimizer, schedulers=schedulers, outputs_criterions=outputs_criterions, dim=dim + ) + self.add_module("DisplacementField", Registration(engine), in_branch=[0, 1, 2, 3], out_branch=["dvf"]) diff --git a/BrainMorph/model.py b/BrainMorph/model.py new file mode 100644 index 0000000000000000000000000000000000000000..8151573ed0cac3117514bc119d483f9cca34bb14 --- /dev/null +++ b/BrainMorph/model.py @@ -0,0 +1,181 @@ +# Copyright (c) 2025 Valentin Boussot +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +# +# SPDX-License-Identifier: Apache-2.0 + +"""BrainMorph (Wang et al.), called as the LUMIR organisers call it in Learn2Reg 2024 +(``LUMIR_L2R/BrainMorph/infer_BrainMorph.py``): 512 keypoints, the "H" model, thin-plate splines with no +regularisation. The authors' repository at the commit of that date, since later commits dropped the H model, with its +dependencies at versions of that date (torch 2.3 on Python 3.11) in an environment uv builds in the cache on first use, +and the weights checked against their hash. Brain MR only. Masks and modalities are accepted and ignored. + +BrainMorph brings each image to RAS, 1 mm and a centred 256^3 box. Both images are put on one such box around the fixed +image first (the pairs are aligned), so that the saved ``grid_sample`` grid of the fixed box is a field there, then +resampled onto the fixed grid. + +NOTE: do NOT add ``from __future__ import annotations``: KonfAI's config engine relies on runtime-evaluated +annotations (``get_origin``); PEP 563 stringized annotations break binding. +""" + +import glob +import hashlib +import os +import subprocess # nosec B404 +import tempfile +from pathlib import Path +from typing import Annotated + +import numpy as np +import SimpleITK as sitk +from konfai.network import network + +from baselines import BaselineNet, pinned_environment, pinned_source + +REPOSITORY = "https://github.com/alanqrwang/brainmorph" +COMMIT = "106b029d6048d3d9d2f73cf7996a0b0813cbc4ae" # 2024-05-23, "gdown fix and switching to variants" +# what its setup.py asks for, and what keymorph imports without declaring, at versions of that date +PACKAGES = [ + "torch==2.3.1", + "torchvision==0.18.1", + "numpy==1.26.4", + "keymorph==1.0.1", + "torchio==0.19.6", + "nibabel==5.2.1", + "scipy==1.13.1", + "scikit-learn==1.5.0", + "pandas==2.2.2", + "pytz==2024.1", + "ogb==1.3.6", + "outdated==0.2.2", + "matplotlib==3.9.0", + "scikit-image==0.24.0", + "h5py==3.11.0", + "pyyaml==6.0.1", + "SimpleITK==2.5.6", + "gdown==5.2.0", +] +WEIGHTS = ( + "foundation-numkey512-numlevels7.pth.tar", + "https://drive.google.com/uc?id=1o_XG1FL4O3rsoCZvH2gzbzsCzd79uKnD", + "ae8947ea266ed1c2218c2b1449fbc4362f9b116c6afc5dfb24be0e17711da680", +) +RAS = (-1.0, 0.0, 0.0, 0.0, -1.0, 0.0, 0.0, 0.0, 1.0) # what torchio's ToCanonical leaves untouched + + +def home() -> tuple[Path, Path]: + """The authors' code with its environment and weights, fetched once into the cache: (source, venv).""" + source = pinned_source("brainmorph", REPOSITORY, COMMIT) + venv = pinned_environment(source, "3.11", [PACKAGES, ["--no-deps", "-e", str(source)]]) + weights = source / "weights" / WEIGHTS[0] + if not weights.exists(): + weights.parent.mkdir(exist_ok=True) + subprocess.run([str(venv / "bin" / "gdown"), "--quiet", WEIGHTS[1], "-O", str(weights)], check=True) # nosec B603 + with weights.open("rb") as stream: + digest = hashlib.file_digest(stream, "sha256").hexdigest() + if digest != WEIGHTS[2]: + weights.unlink() + raise RuntimeError(f"{WEIGHTS[1]} does not match its recorded hash") + return source, venv + + +def box_around(fixed: sitk.Image, extent: int) -> sitk.Image: + """The RAS, 1 mm, ``extent``^3 box centred on the fixed image, which BrainMorph's own resampling then keeps.""" + box = sitk.Image([extent] * 3, sitk.sitkFloat32) + box.SetDirection(RAS) + centre = np.array(fixed.TransformContinuousIndexToPhysicalPoint([(s - 1) / 2 for s in fixed.GetSize()])) + box.SetOrigin((centre - np.array(RAS).reshape(3, 3) @ np.full(3, (extent - 1) / 2)).tolist()) + return box + + +class BrainMorph: + def __init__(self, keypoints: int, variant: str, align: str) -> None: + self._keypoints, self._variant, self._align = keypoints, variant, align + + def __call__( + self, + fixed: sitk.Image, + moving: sitk.Image, + fixed_mask: sitk.Image | None, + moving_mask: sitk.Image | None, + device: int, + ) -> np.ndarray: + source, venv = home() + extent = 256 + box = box_around(fixed, extent) + environment = {**os.environ, "PYTHONPATH": str(source)} # its scripts import scripts.* + if device < 0: + environment["CUDA_VISIBLE_DEVICES"] = "" + with tempfile.TemporaryDirectory(prefix="brainmorph_") as scratch: + work = Path(scratch) + for name, image in (("y", fixed), ("x", moving)): # the organisers' names: x moving, y fixed + image = sitk.Cast(image, sitk.sitkFloat32) + fill = float(sitk.GetArrayViewFromImage(image).min()) + sitk.WriteImage( + sitk.Resample(image, box, sitk.Transform(), sitk.sitkLinear, fill), str(work / f"{name}.nii.gz") + ) + subprocess.run( # nosec B603 + [ + str(venv / "bin" / "python"), + "scripts/register.py", + "--num_keypoints", + str(self._keypoints), + "--variant", + self._variant, + "--weights_dir", + f"{source / 'weights'}/", + "--moving", + str(work / "x.nii.gz"), + "--fixed", + str(work / "y.nii.gz"), + "--list_of_aligns", + self._align, + "--list_of_metrics", + "mse", + "--save_eval_to_disk", + "--save_dir", + str(work / "bm"), + ], + cwd=source, + check=True, + env=environment, + ) + pattern = f"{work}/bm/eval_numkey{self._keypoints}_variant{self._variant}/*/grid_0-fixed_0-moving-rot0-{self._align}.npy" + grid = np.load(glob.glob(pattern)[0]) + # the grid_sample grid of the fixed box, (i, j, k, 3) normalised with align_corners, its axes reversed + index = (np.squeeze(grid)[..., [2, 1, 0]] + 1) / 2 * (extent - 1) + d = index - np.stack(np.meshgrid(*[np.arange(extent)] * 3, indexing="ij"), -1) # voxels of the box + u = d * np.array([-1.0, -1.0, 1.0]) # 1 mm voxels along R, A, S: mm along L, P, S + field = sitk.GetImageFromArray(np.ascontiguousarray(u.transpose(2, 1, 0, 3)).astype(np.float64), isVector=True) + field.CopyInformation(box) + field = sitk.Resample(field, fixed, sitk.Transform(), sitk.sitkLinear, 0.0, sitk.sitkVectorFloat64) + return np.ascontiguousarray(np.moveaxis(sitk.GetArrayFromImage(field), -1, 0), dtype=np.float32) + + +class RegistrationNet(BaselineNet): + """BrainMorph, the LUMIR organisers' call. Brain MR.""" + + def __init__( + self, + optimizer: network.OptimizerLoader = network.OptimizerLoader(), + schedulers: dict[str, network.LRSchedulersLoader] = { + "default:ReduceLROnPlateau": network.LRSchedulersLoader(0) + }, + outputs_criterions: dict[str, network.TargetCriterionsLoader] = {"default": network.TargetCriterionsLoader()}, + keypoints: Annotated[int, "register.py's --num_keypoints: 128, 256 or 512."] = 512, + variant: Annotated[str, "register.py's --variant: S, M, L or H."] = "H", + align: Annotated[ + str, "register.py's --list_of_aligns: tps_0 for thin-plate splines without regularisation, affine, rigid." + ] = "tps_0", + ) -> None: + super().__init__(BrainMorph(keypoints, variant, align), 3, optimizer, schedulers, outputs_criterions) diff --git a/BrainMorph/requirements.txt b/BrainMorph/requirements.txt new file mode 100644 index 0000000000000000000000000000000000000000..00eb295d2cccfc52393970efc29a3f5a54cc3481 --- /dev/null +++ b/BrainMorph/requirements.txt @@ -0,0 +1,2 @@ +SimpleITK +uv==0.12.10 diff --git a/ConvexAdam_MIND/Prediction.yml b/ConvexAdam_MIND/Prediction.yml new file mode 100644 index 0000000000000000000000000000000000000000..c5420814fd3dc02a477df5e08d0a5fbf2f8ee520 --- /dev/null +++ b/ConvexAdam_MIND/Prediction.yml @@ -0,0 +1,85 @@ +Predictor: + Model: + classpath: model:RegistrationNet + RegistrationNet: + threads: 0 + outputs_criterions: None + Dataset: + groups_src: + Volume_0: + groups_dest: + Fixed: + transforms: + TensorCast: + dtype: float32 + inverse: false + patch_transforms: None + is_input: true + Volume_1: + groups_dest: + Moving: + transforms: + TensorCast: + dtype: float32 + inverse: false + patch_transforms: None + is_input: true + Volume_2: + groups_dest: + FixedMask: + transforms: + TensorCast: + dtype: float32 + inverse: false + patch_transforms: None + is_input: true + Volume_3: + groups_dest: + MovingMask: + transforms: + TensorCast: + dtype: float32 + inverse: false + patch_transforms: None + is_input: true + augmentations: None + Patch: + patch_size: + - 0 + - 0 + - 0 + overlap: 0 + pad_value: None + extend_slice: 0 + mode: resample + max_voxels: None + subset: None + dataset_filenames: + - ./Dataset/:mha + batch_size: 1 + num_workers: None + pin_memory: false + prefetch_factor: None + persistent_workers: None + outputs_dataset: + DisplacementField: + OutputDataset: + name_class: OutputDataset + before_reduction_transforms: None + after_reduction_transforms: None + final_transforms: + TensorCast: + dtype: float32 + inverse: false + dataset_filename: DisplacementField:mha + group: DisplacementField + same_as_group: Volume_0:Fixed + patch_combine: Cosinus + reduction: Mean + Mean: {} + train_name: Baselines-ConvexAdam_MIND + manual_seed: 42 + gpu_checkpoints: None + combine: Mean + autocast: false + data_log: None diff --git a/ConvexAdam_MIND/app.json b/ConvexAdam_MIND/app.json new file mode 100644 index 0000000000000000000000000000000000000000..928a29d5ed595f2ce89b1c3648e023aca9d43181 --- /dev/null +++ b/ConvexAdam_MIND/app.json @@ -0,0 +1,18 @@ +{ + "display_name": "ConvexAdam (MIND)", + "short_description": "ConvexAdam with MIND-SSC features, the authors' code at a pinned commit with its defaults: the ImagingBenchmarks baseline convexadam_mind.", + "description": "Siebert et al.'s ConvexAdam: a coupled-convex initialisation on a coarse grid, then Adam instance optimisation on a finer one, both on MIND-SSC features. This app runs the authors' repository at commit b229e52 with convex_adam_pt(fixed, moving) and every setting at its default, exactly as the ImagingBenchmarks leaderboards run it. The pair must be aligned (rigidly for one patient, by an affine transform between two subjects): only the deformable stage runs. A GPU is needed. Output: the displacement field on the fixed grid, in mm along the world axes (ITK, LPS): the fixed point x matches x + u(x) in the moving image.

How to cite:
H. Siebert, L. Hansen, M. P. Heinrich, Fast 3D registration with accurate optimisation and little learning for Learn2Reg 2021, MICCAI Workshops 2021.", + "task": "registration", + "tta": 0, + "mc_dropout": 0, + "models": [], + "inputs": { + "Fixed": {"display_name": "Fixed image", "volume_type": "VOLUME", "required": true}, + "Moving": {"display_name": "Moving image", "volume_type": "VOLUME", "required": true}, + "FixedMask": {"display_name": "Fixed mask (ignored by this baseline)", "volume_type": "SEGMENTATION", "required": false, "default": "ones"}, + "MovingMask": {"display_name": "Moving mask (ignored by this baseline)", "volume_type": "SEGMENTATION", "required": false, "default": "ones"} + }, + "outputs": { + "DisplacementField": {"display_name": "Displacement field", "volume_type": "VOLUME", "required": true} + } +} diff --git a/ConvexAdam_MIND/baselines.py b/ConvexAdam_MIND/baselines.py new file mode 100644 index 0000000000000000000000000000000000000000..691b6d9c745cf4c64ab8e323b21b5c76b251af72 --- /dev/null +++ b/ConvexAdam_MIND/baselines.py @@ -0,0 +1,206 @@ +# Copyright (c) 2025 Valentin Boussot +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +# +# SPDX-License-Identifier: Apache-2.0 + +"""What every baseline app shares (a copy of the repository's baselines.py, kept by build.py): the authors' code fetched at its pin, the graph module that hands a pair to an +engine and gets a displacement field back, and the field's convention. + +The field is the benchmark's: one component per spatial axis, in mm along the world (ITK, LPS) axes, on the fixed +image's grid, such that the fixed point ``x`` matches ``x + u(x)`` in the moving image. The predictor attaches the +fixed image's geometry to the output (``same_as_group: Volume_0:Fixed`` in the app's ``Prediction.yml``). + +NOTE: do NOT add ``from __future__ import annotations``: KonfAI's config engine relies on runtime-evaluated +annotations (``get_origin``); PEP 563 stringized annotations break binding. +""" + +import hashlib +import os +import shutil +import subprocess # nosec B404 +import urllib.request +import zipfile +from collections.abc import Callable +from pathlib import Path + +import numpy as np +import SimpleITK as sitk +import torch +from konfai.network import network +from konfai.utils.dataset import Attribute, data_to_image + +#: An engine: (fixed, moving, fixed mask or None, moving mask or None, CUDA device index or -1) -> the field, +#: ``[D, *spatial]`` in mm along the world axes on the fixed grid. +Engine = Callable[[sitk.Image, sitk.Image, sitk.Image | None, sitk.Image | None, int], np.ndarray] + + +def cache_dir() -> Path: + """Where the authors' code and binaries live, once fetched: ``$BASELINES_KONFAI_CACHE`` or + ``~/.cache/baselines-konfai``.""" + return Path(os.environ.get("BASELINES_KONFAI_CACHE", Path.home() / ".cache" / "baselines-konfai")) + + +def pinned_source(name: str, url: str, commit: str) -> Path: + """The authors' repository at ``commit``, cloned once into the cache: a baseline runs the code it was + measured with, never a moving branch.""" + target = cache_dir() / f"{name}-{commit[:12]}" + if not (target / ".git").exists(): + target.parent.mkdir(parents=True, exist_ok=True) + subprocess.run(["git", "clone", "--quiet", url, str(target)], check=True) # nosec B603 B607 + subprocess.run(["git", "-C", str(target), "checkout", "--quiet", commit], check=True) # nosec B603 B607 + return target + + +def fetch(url: str, target: Path, sha256: str | None = None) -> Path: + """``url`` downloaded once to ``target`` and, when a hash is given, checked against it.""" + if not target.exists(): + target.parent.mkdir(parents=True, exist_ok=True) + part = target.with_name(target.name + ".part") + urllib.request.urlretrieve(url, part) # nosec B310 - the authors' release, checked below + with part.open("rb") as stream: + digest = hashlib.file_digest(stream, "sha256").hexdigest() + if sha256 and digest != sha256: + part.unlink() + raise RuntimeError(f"{url} does not match its recorded hash") + part.rename(target) + return target + + +def pinned_archive(name: str, url: str, sha256: str) -> Path: + """A release archive at ``url``, downloaded once into the cache, checked against ``sha256`` and unpacked: the + binaries a baseline was measured with.""" + target = cache_dir() / f"{name}-{sha256[:12]}" + if not (target / ".unpacked").exists(): + archive = fetch(url, target / "archive", sha256) + if zipfile.is_zipfile(archive): + with zipfile.ZipFile(archive) as packed: + packed.extractall(target) # nosec B202 - our own pinned archive + for entry in packed.infolist(): # zipfile drops the modes: the binaries must stay executable + if mode := (entry.external_attr >> 16) & 0o777: + (target / entry.filename).chmod(mode) + else: + shutil.unpack_archive(str(archive), str(target), "gztar") + archive.unlink() + (target / ".unpacked").touch() + return target + + +def pinned_environment(root: Path, python: str, installs: list[list[str]]) -> Path: + """A virtual environment at ``root/venv`` on its own Python, made once by uv (``pip install uv``): for the tools + whose pins do not run on the host's Python. ``installs`` are ``pip install`` argument lists, run in order.""" + try: + import uv + + command = uv.find_uv_bin() + except ImportError: + command = shutil.which("uv") or "" + if not command: + raise RuntimeError("this baseline builds its own Python environment with uv: pip install uv") + venv = root / "venv" + if not (venv / ".ready").exists(): + subprocess.run([command, "venv", "--quiet", "--clear", "--python", python, str(venv)], check=True) # nosec B603 + for arguments in installs: + subprocess.run( # nosec B603 + [ + command, + "pip", + "install", + "--quiet", + "--no-cache", + "--python", + str(venv / "bin" / "python"), + *arguments, + ], + check=True, + ) + (venv / ".ready").touch() + return venv + + +def built_source(name: str, url: str, commit: str, build: Callable[[Path], None]) -> Path: + """The authors' repository at ``commit``, built once by ``build`` (a marker says it is done).""" + source = pinned_source(name, url, commit) + if not (source / ".built").exists(): + build(source) + (source / ".built").touch() + return source + + +def field_from_voxels(displacement: np.ndarray, fixed: sitk.Image) -> np.ndarray: + """A displacement in voxels along the index axes, ``[i, j, k, D]``, as the benchmark's field ``[D, k, j, i]`` + in mm along the world axes: ``u = D S d``, with ``D`` the direction and ``S`` the spacing of the fixed image.""" + n = fixed.GetDimension() + to_world = np.array(fixed.GetDirection()).reshape(n, n) @ np.diag(fixed.GetSpacing()) + world = displacement.astype(np.float64) @ to_world.T # [i, j, k, D] + return np.ascontiguousarray(np.moveaxis(world, -1, 0).transpose(0, *reversed(range(1, n + 1))), dtype=np.float32) + + +def to_index_array(image: sitk.Image) -> np.ndarray: + """The image as a ``[i, j, k]`` array, the index axes in ITK's order, which the tools indexed that way read.""" + return np.ascontiguousarray(sitk.GetArrayFromImage(image).transpose(*reversed(range(image.GetDimension())))) + + +class Registration(torch.nn.Module): + """Graph module: the pair's tensors and their geometry in, the field out, through the engine, one sample at + a time. ``accepts_attributes = True`` opts it into the per-branch ``Attribute`` list (the convention of + ``CriterionWithAttribute``): registration needs the physical geometry.""" + + accepts_attributes = True + + def __init__(self, engine: Engine) -> None: + super().__init__() + self._engine = engine + + def forward( + self, + fixed: torch.Tensor, + moving: torch.Tensor, + fixed_mask: torch.Tensor, + moving_mask: torch.Tensor, + attributes: list[list[Attribute]], + ) -> torch.Tensor: + fixed_attrs, moving_attrs, fixed_mask_attrs, moving_mask_attrs = attributes + device_index = fixed.device.index if fixed.device.type == "cuda" else -1 + fields = [] + # the engines optimise with autograd; the predictor calls forward under inference mode + with torch.inference_mode(False), torch.enable_grad(): + for b in range(fixed.shape[0]): + images = [ + data_to_image(t[b].detach().cpu().numpy(), attrs[b]) + for t, attrs in ((fixed, fixed_attrs), (moving, moving_attrs)) + ] + masks = [ + data_to_image(t[b].detach().cpu().numpy(), attrs[b]) if not bool((t[b] == 1).all()) else None + for t, attrs in ((fixed_mask, fixed_mask_attrs), (moving_mask, moving_mask_attrs)) + ] + fields.append(torch.from_numpy(self._engine(images[0], images[1], masks[0], masks[1], device_index))) + return torch.stack(fields, dim=0).to(fixed.device) + + +class BaselineNet(network.Network): + """A baseline as an ``add_module`` graph: fixed = branch 0, moving = branch 1, the masks branches 2 and 3 (a + mask of ones means none). The one output is ``DisplacementField``, on the fixed grid.""" + + def __init__( + self, + engine: Engine, + dim: int, + optimizer: network.OptimizerLoader, + schedulers: dict[str, network.LRSchedulersLoader], + outputs_criterions: dict[str, network.TargetCriterionsLoader], + ) -> None: + super().__init__( + in_channels=1, optimizer=optimizer, schedulers=schedulers, outputs_criterions=outputs_criterions, dim=dim + ) + self.add_module("DisplacementField", Registration(engine), in_branch=[0, 1, 2, 3], out_branch=["dvf"]) diff --git a/ConvexAdam_MIND/model.py b/ConvexAdam_MIND/model.py new file mode 100644 index 0000000000000000000000000000000000000000..d81fc79f302af0af89b884b339762a7f7eed4b3b --- /dev/null +++ b/ConvexAdam_MIND/model.py @@ -0,0 +1,99 @@ +# Copyright (c) 2025 Valentin Boussot +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +# +# SPDX-License-Identifier: Apache-2.0 + +"""ConvexAdam with MIND-SSC features: the authors' repository (multimodallearning/convexAdam) at a pinned commit, +``convex_adam_pt(fixed, moving)`` with its defaults, as the ImagingBenchmarks line ``convexadam_mind`` runs it. + +NOTE: do NOT add ``from __future__ import annotations``: KonfAI's config engine relies on runtime-evaluated +annotations (``get_origin``); PEP 563 stringized annotations break binding. +""" + +import sys +from typing import Annotated + +import numpy as np +import SimpleITK as sitk +import torch +from konfai.network import network + +from baselines import BaselineNet, field_from_voxels, pinned_source, to_index_array + +REPOSITORY = "https://github.com/multimodallearning/convexAdam" +COMMIT = "b229e52e44b114e2040a503334c92269750c16b2" # main, 2025-11-17 + + +def _authors_code(): + """The authors' functions, imported from their repository at the pin (it is not a package).""" + source = pinned_source("convexAdam", REPOSITORY, COMMIT) / "src" + if str(source) not in sys.path: + sys.path.insert(0, str(source)) + from convexAdam.convex_adam_MIND import convex_adam_pt + from convexAdam.convex_adam_utils import resample_moving_to_fixed + + return convex_adam_pt, resample_moving_to_fixed + + +class ConvexAdamMind: + def __init__(self, threads: int) -> None: + self._threads = threads + + def __call__( + self, + fixed: sitk.Image, + moving: sitk.Image, + fixed_mask: sitk.Image | None, + moving_mask: sitk.Image | None, + device: int, + ) -> np.ndarray: + convex_adam_pt, resample_moving_to_fixed = _authors_code() + if self._threads: + torch.set_num_threads(self._threads) + fixed, moving = sitk.Cast(fixed, sitk.sitkFloat32), sitk.Cast(moving, sitk.sitkFloat32) + if fixed.GetDimension() != 3 or min(fixed.GetSize()) < 12: + raise ValueError( + f"ConvexAdam needs 3D images of at least 12 voxels per axis (grid spacing 6): {fixed.GetSize()}" + ) + + def geometry(image: sitk.Image) -> tuple: + return image.GetSize(), image.GetSpacing(), image.GetOrigin(), image.GetDirection() + + if geometry(moving) != geometry(fixed): + moving = resample_moving_to_fixed(fixed, moving) # the repository's helper: identity, linear, 0 outside + # the repository's defaults; the displacement comes back as [i, j, k, 3], fixed -> moving, in voxels + displacement = convex_adam_pt(torch.from_numpy(to_index_array(fixed)), torch.from_numpy(to_index_array(moving))) + displacement = np.asarray(displacement) + if not np.isfinite(displacement).all(): + raise ValueError("ConvexAdam returned a field with non-finite values") + return field_from_voxels(displacement, fixed) + + +class RegistrationNet(BaselineNet): + """ConvexAdam (MIND-SSC) at the authors' defaults: MIND radius 1 and dilation 2, a convex stage on a 6-voxel + grid with a search half-width of 4 and inverse consistency, then 80 Adam steps on a 2-voxel grid with a + diffusion weight of 1.25, half precision. A GPU is needed.""" + + def __init__( + self, + optimizer: network.OptimizerLoader = network.OptimizerLoader(), + schedulers: dict[str, network.LRSchedulersLoader] = { + "default:ReduceLROnPlateau": network.LRSchedulersLoader(0) + }, + outputs_criterions: dict[str, network.TargetCriterionsLoader] = {"default": network.TargetCriterionsLoader()}, + threads: Annotated[ + int, "CPU threads torch may use for the parts that run on the CPU; 0 leaves the default." + ] = 0, + ) -> None: + super().__init__(ConvexAdamMind(threads), 3, optimizer, schedulers, outputs_criterions) diff --git a/ConvexAdam_MIND/requirements.txt b/ConvexAdam_MIND/requirements.txt new file mode 100644 index 0000000000000000000000000000000000000000..b61857171c4e02b972b6ce6bcd13fe6507f47499 --- /dev/null +++ b/ConvexAdam_MIND/requirements.txt @@ -0,0 +1,3 @@ +SimpleITK +nibabel +scipy diff --git a/CorrField/Prediction.yml b/CorrField/Prediction.yml new file mode 100644 index 0000000000000000000000000000000000000000..a64a5c7f422aa3fe1581b43676fa1ddc10d0bbbd --- /dev/null +++ b/CorrField/Prediction.yml @@ -0,0 +1,86 @@ +Predictor: + Model: + classpath: model:RegistrationNet + RegistrationNet: + max_voxels: 50000000.0 + min_spacing: 1.0 + outputs_criterions: None + Dataset: + groups_src: + Volume_0: + groups_dest: + Fixed: + transforms: + TensorCast: + dtype: float32 + inverse: false + patch_transforms: None + is_input: true + Volume_1: + groups_dest: + Moving: + transforms: + TensorCast: + dtype: float32 + inverse: false + patch_transforms: None + is_input: true + Volume_2: + groups_dest: + FixedMask: + transforms: + TensorCast: + dtype: float32 + inverse: false + patch_transforms: None + is_input: true + Volume_3: + groups_dest: + MovingMask: + transforms: + TensorCast: + dtype: float32 + inverse: false + patch_transforms: None + is_input: true + augmentations: None + Patch: + patch_size: + - 0 + - 0 + - 0 + overlap: 0 + pad_value: None + extend_slice: 0 + mode: resample + max_voxels: None + subset: None + dataset_filenames: + - ./Dataset/:mha + batch_size: 1 + num_workers: None + pin_memory: false + prefetch_factor: None + persistent_workers: None + outputs_dataset: + DisplacementField: + OutputDataset: + name_class: OutputDataset + before_reduction_transforms: None + after_reduction_transforms: None + final_transforms: + TensorCast: + dtype: float32 + inverse: false + dataset_filename: DisplacementField:mha + group: DisplacementField + same_as_group: Volume_0:Fixed + patch_combine: Cosinus + reduction: Mean + Mean: {} + train_name: Baselines-CorrField + manual_seed: 42 + gpu_checkpoints: None + combine: Mean + autocast: false + data_log: None diff --git a/CorrField/app.json b/CorrField/app.json new file mode 100644 index 0000000000000000000000000000000000000000..7d78f87b2ebcf80947011071ed32db2b31a637dc --- /dev/null +++ b/CorrField/app.json @@ -0,0 +1,39 @@ +{ + "display_name": "corrField", + "short_description": "corrField as the Lung250M-4B authors ship it, at a pinned commit, with its defaults: Foerstner keypoints inside the fixed image's lung mask, MIND-SSC, discrete matching, thin-plate splines. The ImagingBenchmarks baseline corrfield, lungs only: the fixed mask is required.", + "description": "corrField as the Lung250M-4B authors ship it, at a pinned commit, with its defaults: Foerstner keypoints inside the fixed image's lung mask, MIND-SSC, discrete matching, thin-plate splines. The ImagingBenchmarks baseline corrfield, lungs only: the fixed mask is required. The pair must be aligned (rigidly for one patient, by an affine transform between two subjects): only the deformable stage runs. The pair is brought to a grid of at least 1 mm and at most 50 million voxels, and the field back onto the fixed grid. A GPU is needed. Output: the displacement field on the fixed grid, in mm along the world axes (ITK, LPS).", + "task": "registration", + "tta": 0, + "mc_dropout": 0, + "models": [], + "inputs": { + "Fixed": { + "display_name": "Fixed image", + "volume_type": "VOLUME", + "required": true + }, + "Moving": { + "display_name": "Moving image", + "volume_type": "VOLUME", + "required": true + }, + "FixedMask": { + "display_name": "Fixed mask (the lungs)", + "volume_type": "SEGMENTATION", + "required": true + }, + "MovingMask": { + "display_name": "Moving mask (ignored by this baseline)", + "volume_type": "SEGMENTATION", + "required": false, + "default": "ones" + } + }, + "outputs": { + "DisplacementField": { + "display_name": "Displacement field", + "volume_type": "VOLUME", + "required": true + } + } +} diff --git a/CorrField/baselines.py b/CorrField/baselines.py new file mode 100644 index 0000000000000000000000000000000000000000..691b6d9c745cf4c64ab8e323b21b5c76b251af72 --- /dev/null +++ b/CorrField/baselines.py @@ -0,0 +1,206 @@ +# Copyright (c) 2025 Valentin Boussot +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +# +# SPDX-License-Identifier: Apache-2.0 + +"""What every baseline app shares (a copy of the repository's baselines.py, kept by build.py): the authors' code fetched at its pin, the graph module that hands a pair to an +engine and gets a displacement field back, and the field's convention. + +The field is the benchmark's: one component per spatial axis, in mm along the world (ITK, LPS) axes, on the fixed +image's grid, such that the fixed point ``x`` matches ``x + u(x)`` in the moving image. The predictor attaches the +fixed image's geometry to the output (``same_as_group: Volume_0:Fixed`` in the app's ``Prediction.yml``). + +NOTE: do NOT add ``from __future__ import annotations``: KonfAI's config engine relies on runtime-evaluated +annotations (``get_origin``); PEP 563 stringized annotations break binding. +""" + +import hashlib +import os +import shutil +import subprocess # nosec B404 +import urllib.request +import zipfile +from collections.abc import Callable +from pathlib import Path + +import numpy as np +import SimpleITK as sitk +import torch +from konfai.network import network +from konfai.utils.dataset import Attribute, data_to_image + +#: An engine: (fixed, moving, fixed mask or None, moving mask or None, CUDA device index or -1) -> the field, +#: ``[D, *spatial]`` in mm along the world axes on the fixed grid. +Engine = Callable[[sitk.Image, sitk.Image, sitk.Image | None, sitk.Image | None, int], np.ndarray] + + +def cache_dir() -> Path: + """Where the authors' code and binaries live, once fetched: ``$BASELINES_KONFAI_CACHE`` or + ``~/.cache/baselines-konfai``.""" + return Path(os.environ.get("BASELINES_KONFAI_CACHE", Path.home() / ".cache" / "baselines-konfai")) + + +def pinned_source(name: str, url: str, commit: str) -> Path: + """The authors' repository at ``commit``, cloned once into the cache: a baseline runs the code it was + measured with, never a moving branch.""" + target = cache_dir() / f"{name}-{commit[:12]}" + if not (target / ".git").exists(): + target.parent.mkdir(parents=True, exist_ok=True) + subprocess.run(["git", "clone", "--quiet", url, str(target)], check=True) # nosec B603 B607 + subprocess.run(["git", "-C", str(target), "checkout", "--quiet", commit], check=True) # nosec B603 B607 + return target + + +def fetch(url: str, target: Path, sha256: str | None = None) -> Path: + """``url`` downloaded once to ``target`` and, when a hash is given, checked against it.""" + if not target.exists(): + target.parent.mkdir(parents=True, exist_ok=True) + part = target.with_name(target.name + ".part") + urllib.request.urlretrieve(url, part) # nosec B310 - the authors' release, checked below + with part.open("rb") as stream: + digest = hashlib.file_digest(stream, "sha256").hexdigest() + if sha256 and digest != sha256: + part.unlink() + raise RuntimeError(f"{url} does not match its recorded hash") + part.rename(target) + return target + + +def pinned_archive(name: str, url: str, sha256: str) -> Path: + """A release archive at ``url``, downloaded once into the cache, checked against ``sha256`` and unpacked: the + binaries a baseline was measured with.""" + target = cache_dir() / f"{name}-{sha256[:12]}" + if not (target / ".unpacked").exists(): + archive = fetch(url, target / "archive", sha256) + if zipfile.is_zipfile(archive): + with zipfile.ZipFile(archive) as packed: + packed.extractall(target) # nosec B202 - our own pinned archive + for entry in packed.infolist(): # zipfile drops the modes: the binaries must stay executable + if mode := (entry.external_attr >> 16) & 0o777: + (target / entry.filename).chmod(mode) + else: + shutil.unpack_archive(str(archive), str(target), "gztar") + archive.unlink() + (target / ".unpacked").touch() + return target + + +def pinned_environment(root: Path, python: str, installs: list[list[str]]) -> Path: + """A virtual environment at ``root/venv`` on its own Python, made once by uv (``pip install uv``): for the tools + whose pins do not run on the host's Python. ``installs`` are ``pip install`` argument lists, run in order.""" + try: + import uv + + command = uv.find_uv_bin() + except ImportError: + command = shutil.which("uv") or "" + if not command: + raise RuntimeError("this baseline builds its own Python environment with uv: pip install uv") + venv = root / "venv" + if not (venv / ".ready").exists(): + subprocess.run([command, "venv", "--quiet", "--clear", "--python", python, str(venv)], check=True) # nosec B603 + for arguments in installs: + subprocess.run( # nosec B603 + [ + command, + "pip", + "install", + "--quiet", + "--no-cache", + "--python", + str(venv / "bin" / "python"), + *arguments, + ], + check=True, + ) + (venv / ".ready").touch() + return venv + + +def built_source(name: str, url: str, commit: str, build: Callable[[Path], None]) -> Path: + """The authors' repository at ``commit``, built once by ``build`` (a marker says it is done).""" + source = pinned_source(name, url, commit) + if not (source / ".built").exists(): + build(source) + (source / ".built").touch() + return source + + +def field_from_voxels(displacement: np.ndarray, fixed: sitk.Image) -> np.ndarray: + """A displacement in voxels along the index axes, ``[i, j, k, D]``, as the benchmark's field ``[D, k, j, i]`` + in mm along the world axes: ``u = D S d``, with ``D`` the direction and ``S`` the spacing of the fixed image.""" + n = fixed.GetDimension() + to_world = np.array(fixed.GetDirection()).reshape(n, n) @ np.diag(fixed.GetSpacing()) + world = displacement.astype(np.float64) @ to_world.T # [i, j, k, D] + return np.ascontiguousarray(np.moveaxis(world, -1, 0).transpose(0, *reversed(range(1, n + 1))), dtype=np.float32) + + +def to_index_array(image: sitk.Image) -> np.ndarray: + """The image as a ``[i, j, k]`` array, the index axes in ITK's order, which the tools indexed that way read.""" + return np.ascontiguousarray(sitk.GetArrayFromImage(image).transpose(*reversed(range(image.GetDimension())))) + + +class Registration(torch.nn.Module): + """Graph module: the pair's tensors and their geometry in, the field out, through the engine, one sample at + a time. ``accepts_attributes = True`` opts it into the per-branch ``Attribute`` list (the convention of + ``CriterionWithAttribute``): registration needs the physical geometry.""" + + accepts_attributes = True + + def __init__(self, engine: Engine) -> None: + super().__init__() + self._engine = engine + + def forward( + self, + fixed: torch.Tensor, + moving: torch.Tensor, + fixed_mask: torch.Tensor, + moving_mask: torch.Tensor, + attributes: list[list[Attribute]], + ) -> torch.Tensor: + fixed_attrs, moving_attrs, fixed_mask_attrs, moving_mask_attrs = attributes + device_index = fixed.device.index if fixed.device.type == "cuda" else -1 + fields = [] + # the engines optimise with autograd; the predictor calls forward under inference mode + with torch.inference_mode(False), torch.enable_grad(): + for b in range(fixed.shape[0]): + images = [ + data_to_image(t[b].detach().cpu().numpy(), attrs[b]) + for t, attrs in ((fixed, fixed_attrs), (moving, moving_attrs)) + ] + masks = [ + data_to_image(t[b].detach().cpu().numpy(), attrs[b]) if not bool((t[b] == 1).all()) else None + for t, attrs in ((fixed_mask, fixed_mask_attrs), (moving_mask, moving_mask_attrs)) + ] + fields.append(torch.from_numpy(self._engine(images[0], images[1], masks[0], masks[1], device_index))) + return torch.stack(fields, dim=0).to(fixed.device) + + +class BaselineNet(network.Network): + """A baseline as an ``add_module`` graph: fixed = branch 0, moving = branch 1, the masks branches 2 and 3 (a + mask of ones means none). The one output is ``DisplacementField``, on the fixed grid.""" + + def __init__( + self, + engine: Engine, + dim: int, + optimizer: network.OptimizerLoader, + schedulers: dict[str, network.LRSchedulersLoader], + outputs_criterions: dict[str, network.TargetCriterionsLoader], + ) -> None: + super().__init__( + in_channels=1, optimizer=optimizer, schedulers=schedulers, outputs_criterions=outputs_criterions, dim=dim + ) + self.add_module("DisplacementField", Registration(engine), in_branch=[0, 1, 2, 3], out_branch=["dvf"]) diff --git a/CorrField/model.py b/CorrField/model.py new file mode 100644 index 0000000000000000000000000000000000000000..cd3e90e6372cd25784f11ebb192e740f18457c3c --- /dev/null +++ b/CorrField/model.py @@ -0,0 +1,150 @@ +# Copyright (c) 2025 Valentin Boussot +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +# +# SPDX-License-Identifier: Apache-2.0 + +"""corrField as the Lung250M-4B authors ship it (``corrfield.py`` at a pinned commit) with its defaults: Foerstner +keypoints inside the fixed image's mask (the lungs), MIND-SSC, discrete matching, thin-plate splines. The pair is +brought to a grid of at least 1 mm and at most 50 million voxels, as the benchmark runs it, and the field back +onto the fixed grid. + +NOTE: do NOT add ``from __future__ import annotations``: KonfAI's config engine relies on runtime-evaluated +annotations (``get_origin``); PEP 563 stringized annotations break binding. +""" + +import os +import subprocess # nosec B404 +import sys +import tempfile +from pathlib import Path +from typing import Annotated + +import nibabel as nib +import numpy as np +import SimpleITK as sitk +from konfai.network import network + +from baselines import BaselineNet, field_from_voxels, pinned_source + +REPOSITORY = "https://github.com/multimodallearning/Lung250M-4B" +COMMIT = "53598ca8f64b13aeb774bc6e6ace486f78d73688" # main, 2024-01-25 + + +def geometry(image: sitk.Image) -> tuple: + return image.GetSize(), image.GetSpacing(), image.GetOrigin(), image.GetDirection() + + +class CorrField: + def __init__(self, max_voxels: float, min_spacing: float) -> None: + self._max_voxels, self._min_spacing = max_voxels, min_spacing + + def __call__( + self, + fixed: sitk.Image, + moving: sitk.Image, + fixed_mask: sitk.Image | None, + moving_mask: sitk.Image | None, + device: int, + ) -> np.ndarray: + if fixed_mask is None: + raise ValueError("corrField needs a mask of the fixed image (the lungs): its keypoints are taken inside it") + script = pinned_source("Lung250M-4B", REPOSITORY, COMMIT) / "corrfield" / "corrfield.py" + fixed, moving = sitk.Cast(fixed, sitk.sitkFloat32), sitk.Cast(moving, sitk.sitkFloat32) + mask = sitk.Cast(fixed_mask != 0, sitk.sitkUInt8) + # the running grid: at least min_spacing, and coarser if the volume exceeds max_voxels + spacing = np.maximum(fixed.GetSpacing(), self._min_spacing) + spacing = tuple( + spacing + * max( + 1.0, (np.prod(np.array(fixed.GetSize()) * fixed.GetSpacing() / spacing) / self._max_voxels) ** (1 / 3) + ) + ) + grid = fixed + if spacing != fixed.GetSpacing(): + grid = sitk.Image( + [ + max(1, round(n * s / t)) + for n, s, t in zip(fixed.GetSize(), fixed.GetSpacing(), spacing, strict=True) + ], + sitk.sitkUInt8, + ) + grid.SetSpacing(spacing), grid.SetOrigin(fixed.GetOrigin()), grid.SetDirection(fixed.GetDirection()) + + def on_grid(image: sitk.Image, how: int, outside: float) -> sitk.Image: + return ( + image + if geometry(image) == geometry(grid) + else sitk.Resample(image, grid, sitk.Transform(), how, outside, image.GetPixelID()) + ) + + lowest = lambda image: float(sitk.GetArrayViewFromImage(image).min()) # noqa: E731 + fixed_run, moving_run = ( + on_grid(fixed, sitk.sitkLinear, lowest(fixed)), + on_grid(moving, sitk.sitkLinear, lowest(moving)), + ) + mask_run = on_grid(mask, sitk.sitkNearestNeighbor, 0.0) + with tempfile.TemporaryDirectory(prefix="corrfield_") as scratch: + work = Path(scratch) + for name, image in {"fixed": fixed_run, "moving": moving_run, "mask": mask_run}.items(): + sitk.WriteImage(image, str(work / f"{name}.nii.gz")) + environment = {**os.environ, "CUDA_VISIBLE_DEVICES": str(device) if device >= 0 else ""} + subprocess.run( # nosec B603 + [ + sys.executable, + str(script), + "-F", + str(work / "fixed.nii.gz"), + "-M", + str(work / "moving.nii.gz"), + "-m", + str(work / "mask.nii.gz"), + "-O", + str(work / "corrfield"), + ], + check=True, + env=environment, + timeout=1800, + ) + displacement = np.asarray(nib.load(str(work / "corrfield.nii.gz")).dataobj)[0] # (I, J, K, 3), voxels + if not np.isfinite(displacement).all(): + raise ValueError("corrField returned a non-finite displacement") + field = sitk.GetImageFromArray(np.moveaxis(field_from_voxels(displacement, grid), 0, -1), isVector=True) + field.CopyInformation(grid) + if grid is not fixed: # back onto the fixed grid, linear, the nearest value past the grid's last sample + resample = sitk.ResampleImageFilter() + ( + resample.SetReferenceImage(fixed), + resample.SetInterpolator(sitk.sitkLinear), + resample.SetUseNearestNeighborExtrapolator(True), + ) + field = resample.Execute(field) + return np.ascontiguousarray(np.moveaxis(sitk.GetArrayFromImage(field), -1, 0), dtype=np.float32) + + +class RegistrationNet(BaselineNet): + """corrField with its defaults, on lungs: a mask of the fixed image is required.""" + + def __init__( + self, + optimizer: network.OptimizerLoader = network.OptimizerLoader(), + schedulers: dict[str, network.LRSchedulersLoader] = { + "default:ReduceLROnPlateau": network.LRSchedulersLoader(0) + }, + outputs_criterions: dict[str, network.TargetCriterionsLoader] = {"default": network.TargetCriterionsLoader()}, + max_voxels: Annotated[ + float, "The pair is brought to a coarser grid when it holds more voxels than this." + ] = 50e6, + min_spacing: Annotated[float, "The finest spacing the pair runs at, in mm."] = 1.0, + ) -> None: + super().__init__(CorrField(max_voxels, min_spacing), 3, optimizer, schedulers, outputs_criterions) diff --git a/CorrField/requirements.txt b/CorrField/requirements.txt new file mode 100644 index 0000000000000000000000000000000000000000..b61857171c4e02b972b6ce6bcd13fe6507f47499 --- /dev/null +++ b/CorrField/requirements.txt @@ -0,0 +1,3 @@ +SimpleITK +nibabel +scipy diff --git a/Deeds/Prediction.yml b/Deeds/Prediction.yml new file mode 100644 index 0000000000000000000000000000000000000000..0ab71da029611428b13e9f70db2fc6dc90dc4929 --- /dev/null +++ b/Deeds/Prediction.yml @@ -0,0 +1,85 @@ +Predictor: + Model: + classpath: model:RegistrationNet + RegistrationNet: + arguments: [] + outputs_criterions: None + Dataset: + groups_src: + Volume_0: + groups_dest: + Fixed: + transforms: + TensorCast: + dtype: float32 + inverse: false + patch_transforms: None + is_input: true + Volume_1: + groups_dest: + Moving: + transforms: + TensorCast: + dtype: float32 + inverse: false + patch_transforms: None + is_input: true + Volume_2: + groups_dest: + FixedMask: + transforms: + TensorCast: + dtype: float32 + inverse: false + patch_transforms: None + is_input: true + Volume_3: + groups_dest: + MovingMask: + transforms: + TensorCast: + dtype: float32 + inverse: false + patch_transforms: None + is_input: true + augmentations: None + Patch: + patch_size: + - 0 + - 0 + - 0 + overlap: 0 + pad_value: None + extend_slice: 0 + mode: resample + max_voxels: None + subset: None + dataset_filenames: + - ./Dataset/:mha + batch_size: 1 + num_workers: None + pin_memory: false + prefetch_factor: None + persistent_workers: None + outputs_dataset: + DisplacementField: + OutputDataset: + name_class: OutputDataset + before_reduction_transforms: None + after_reduction_transforms: None + final_transforms: + TensorCast: + dtype: float32 + inverse: false + dataset_filename: DisplacementField:mha + group: DisplacementField + same_as_group: Volume_0:Fixed + patch_combine: Cosinus + reduction: Mean + Mean: {} + train_name: Baselines-Deeds + manual_seed: 42 + gpu_checkpoints: None + combine: Mean + autocast: false + data_log: None diff --git a/Deeds/app.json b/Deeds/app.json new file mode 100644 index 0000000000000000000000000000000000000000..79a5f290e227abb4f7d858de55afdae58a3b6e2e --- /dev/null +++ b/Deeds/app.json @@ -0,0 +1,40 @@ +{ + "display_name": "deeds", + "short_description": "deedsBCV with its defaults: 5 levels, grid 8x7x6x5x4, search radius 8x7x6x5x4, quantisation 5x4x3x2x1, regularisation 1.6, symmetric; built from the authors' repository at a pinned commit on first use (make and a C++ compiler needed). The ImagingBenchmarks baseline deeds. CPU.", + "description": "deedsBCV with its defaults: 5 levels, grid 8x7x6x5x4, search radius 8x7x6x5x4, quantisation 5x4x3x2x1, regularisation 1.6, symmetric; built from the authors' repository at a pinned commit on first use (make and a C++ compiler needed). The ImagingBenchmarks baseline deeds. CPU. The pair must be aligned (rigidly for one patient, by an affine transform between two subjects): only the deformable stage runs. Masks are ignored by this baseline. Output: the displacement field on the fixed grid, in mm along the world axes (ITK, LPS).", + "task": "registration", + "tta": 0, + "mc_dropout": 0, + "models": [], + "inputs": { + "Fixed": { + "display_name": "Fixed image", + "volume_type": "VOLUME", + "required": true + }, + "Moving": { + "display_name": "Moving image", + "volume_type": "VOLUME", + "required": true + }, + "FixedMask": { + "display_name": "Fixed mask (ignored by this baseline)", + "volume_type": "SEGMENTATION", + "required": false, + "default": "ones" + }, + "MovingMask": { + "display_name": "Moving mask (ignored by this baseline)", + "volume_type": "SEGMENTATION", + "required": false, + "default": "ones" + } + }, + "outputs": { + "DisplacementField": { + "display_name": "Displacement field", + "volume_type": "VOLUME", + "required": true + } + } +} diff --git a/Deeds/baselines.py b/Deeds/baselines.py new file mode 100644 index 0000000000000000000000000000000000000000..691b6d9c745cf4c64ab8e323b21b5c76b251af72 --- /dev/null +++ b/Deeds/baselines.py @@ -0,0 +1,206 @@ +# Copyright (c) 2025 Valentin Boussot +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +# +# SPDX-License-Identifier: Apache-2.0 + +"""What every baseline app shares (a copy of the repository's baselines.py, kept by build.py): the authors' code fetched at its pin, the graph module that hands a pair to an +engine and gets a displacement field back, and the field's convention. + +The field is the benchmark's: one component per spatial axis, in mm along the world (ITK, LPS) axes, on the fixed +image's grid, such that the fixed point ``x`` matches ``x + u(x)`` in the moving image. The predictor attaches the +fixed image's geometry to the output (``same_as_group: Volume_0:Fixed`` in the app's ``Prediction.yml``). + +NOTE: do NOT add ``from __future__ import annotations``: KonfAI's config engine relies on runtime-evaluated +annotations (``get_origin``); PEP 563 stringized annotations break binding. +""" + +import hashlib +import os +import shutil +import subprocess # nosec B404 +import urllib.request +import zipfile +from collections.abc import Callable +from pathlib import Path + +import numpy as np +import SimpleITK as sitk +import torch +from konfai.network import network +from konfai.utils.dataset import Attribute, data_to_image + +#: An engine: (fixed, moving, fixed mask or None, moving mask or None, CUDA device index or -1) -> the field, +#: ``[D, *spatial]`` in mm along the world axes on the fixed grid. +Engine = Callable[[sitk.Image, sitk.Image, sitk.Image | None, sitk.Image | None, int], np.ndarray] + + +def cache_dir() -> Path: + """Where the authors' code and binaries live, once fetched: ``$BASELINES_KONFAI_CACHE`` or + ``~/.cache/baselines-konfai``.""" + return Path(os.environ.get("BASELINES_KONFAI_CACHE", Path.home() / ".cache" / "baselines-konfai")) + + +def pinned_source(name: str, url: str, commit: str) -> Path: + """The authors' repository at ``commit``, cloned once into the cache: a baseline runs the code it was + measured with, never a moving branch.""" + target = cache_dir() / f"{name}-{commit[:12]}" + if not (target / ".git").exists(): + target.parent.mkdir(parents=True, exist_ok=True) + subprocess.run(["git", "clone", "--quiet", url, str(target)], check=True) # nosec B603 B607 + subprocess.run(["git", "-C", str(target), "checkout", "--quiet", commit], check=True) # nosec B603 B607 + return target + + +def fetch(url: str, target: Path, sha256: str | None = None) -> Path: + """``url`` downloaded once to ``target`` and, when a hash is given, checked against it.""" + if not target.exists(): + target.parent.mkdir(parents=True, exist_ok=True) + part = target.with_name(target.name + ".part") + urllib.request.urlretrieve(url, part) # nosec B310 - the authors' release, checked below + with part.open("rb") as stream: + digest = hashlib.file_digest(stream, "sha256").hexdigest() + if sha256 and digest != sha256: + part.unlink() + raise RuntimeError(f"{url} does not match its recorded hash") + part.rename(target) + return target + + +def pinned_archive(name: str, url: str, sha256: str) -> Path: + """A release archive at ``url``, downloaded once into the cache, checked against ``sha256`` and unpacked: the + binaries a baseline was measured with.""" + target = cache_dir() / f"{name}-{sha256[:12]}" + if not (target / ".unpacked").exists(): + archive = fetch(url, target / "archive", sha256) + if zipfile.is_zipfile(archive): + with zipfile.ZipFile(archive) as packed: + packed.extractall(target) # nosec B202 - our own pinned archive + for entry in packed.infolist(): # zipfile drops the modes: the binaries must stay executable + if mode := (entry.external_attr >> 16) & 0o777: + (target / entry.filename).chmod(mode) + else: + shutil.unpack_archive(str(archive), str(target), "gztar") + archive.unlink() + (target / ".unpacked").touch() + return target + + +def pinned_environment(root: Path, python: str, installs: list[list[str]]) -> Path: + """A virtual environment at ``root/venv`` on its own Python, made once by uv (``pip install uv``): for the tools + whose pins do not run on the host's Python. ``installs`` are ``pip install`` argument lists, run in order.""" + try: + import uv + + command = uv.find_uv_bin() + except ImportError: + command = shutil.which("uv") or "" + if not command: + raise RuntimeError("this baseline builds its own Python environment with uv: pip install uv") + venv = root / "venv" + if not (venv / ".ready").exists(): + subprocess.run([command, "venv", "--quiet", "--clear", "--python", python, str(venv)], check=True) # nosec B603 + for arguments in installs: + subprocess.run( # nosec B603 + [ + command, + "pip", + "install", + "--quiet", + "--no-cache", + "--python", + str(venv / "bin" / "python"), + *arguments, + ], + check=True, + ) + (venv / ".ready").touch() + return venv + + +def built_source(name: str, url: str, commit: str, build: Callable[[Path], None]) -> Path: + """The authors' repository at ``commit``, built once by ``build`` (a marker says it is done).""" + source = pinned_source(name, url, commit) + if not (source / ".built").exists(): + build(source) + (source / ".built").touch() + return source + + +def field_from_voxels(displacement: np.ndarray, fixed: sitk.Image) -> np.ndarray: + """A displacement in voxels along the index axes, ``[i, j, k, D]``, as the benchmark's field ``[D, k, j, i]`` + in mm along the world axes: ``u = D S d``, with ``D`` the direction and ``S`` the spacing of the fixed image.""" + n = fixed.GetDimension() + to_world = np.array(fixed.GetDirection()).reshape(n, n) @ np.diag(fixed.GetSpacing()) + world = displacement.astype(np.float64) @ to_world.T # [i, j, k, D] + return np.ascontiguousarray(np.moveaxis(world, -1, 0).transpose(0, *reversed(range(1, n + 1))), dtype=np.float32) + + +def to_index_array(image: sitk.Image) -> np.ndarray: + """The image as a ``[i, j, k]`` array, the index axes in ITK's order, which the tools indexed that way read.""" + return np.ascontiguousarray(sitk.GetArrayFromImage(image).transpose(*reversed(range(image.GetDimension())))) + + +class Registration(torch.nn.Module): + """Graph module: the pair's tensors and their geometry in, the field out, through the engine, one sample at + a time. ``accepts_attributes = True`` opts it into the per-branch ``Attribute`` list (the convention of + ``CriterionWithAttribute``): registration needs the physical geometry.""" + + accepts_attributes = True + + def __init__(self, engine: Engine) -> None: + super().__init__() + self._engine = engine + + def forward( + self, + fixed: torch.Tensor, + moving: torch.Tensor, + fixed_mask: torch.Tensor, + moving_mask: torch.Tensor, + attributes: list[list[Attribute]], + ) -> torch.Tensor: + fixed_attrs, moving_attrs, fixed_mask_attrs, moving_mask_attrs = attributes + device_index = fixed.device.index if fixed.device.type == "cuda" else -1 + fields = [] + # the engines optimise with autograd; the predictor calls forward under inference mode + with torch.inference_mode(False), torch.enable_grad(): + for b in range(fixed.shape[0]): + images = [ + data_to_image(t[b].detach().cpu().numpy(), attrs[b]) + for t, attrs in ((fixed, fixed_attrs), (moving, moving_attrs)) + ] + masks = [ + data_to_image(t[b].detach().cpu().numpy(), attrs[b]) if not bool((t[b] == 1).all()) else None + for t, attrs in ((fixed_mask, fixed_mask_attrs), (moving_mask, moving_mask_attrs)) + ] + fields.append(torch.from_numpy(self._engine(images[0], images[1], masks[0], masks[1], device_index))) + return torch.stack(fields, dim=0).to(fixed.device) + + +class BaselineNet(network.Network): + """A baseline as an ``add_module`` graph: fixed = branch 0, moving = branch 1, the masks branches 2 and 3 (a + mask of ones means none). The one output is ``DisplacementField``, on the fixed grid.""" + + def __init__( + self, + engine: Engine, + dim: int, + optimizer: network.OptimizerLoader, + schedulers: dict[str, network.LRSchedulersLoader], + outputs_criterions: dict[str, network.TargetCriterionsLoader], + ) -> None: + super().__init__( + in_channels=1, optimizer=optimizer, schedulers=schedulers, outputs_criterions=outputs_criterions, dim=dim + ) + self.add_module("DisplacementField", Registration(engine), in_branch=[0, 1, 2, 3], out_branch=["dvf"]) diff --git a/Deeds/model.py b/Deeds/model.py new file mode 100644 index 0000000000000000000000000000000000000000..bdf6b945dc1b44e8344cfae54bf4bf5874cfbe71 --- /dev/null +++ b/Deeds/model.py @@ -0,0 +1,141 @@ +# Copyright (c) 2025 Valentin Boussot +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +# +# SPDX-License-Identifier: Apache-2.0 + +"""deeds (``deedsBCV``) with its defaults: 5 levels, grid 8x7x6x5x4, search radius 8x7x6x5x4, quantisation +5x4x3x2x1, regularisation 1.6, symmetric; built from the authors' repository at a pinned commit on first use. deeds +reads two arrays of one size without geometry, so an anisotropic fixed image is first brought to an isotropic grid, +the moving image onto it, and the field back onto the fixed grid. + +NOTE: do NOT add ``from __future__ import annotations``: KonfAI's config engine relies on runtime-evaluated +annotations (``get_origin``); PEP 563 stringized annotations break binding. +""" + +import subprocess # nosec B404 +import tempfile +from pathlib import Path +from typing import Annotated + +import numpy as np +import SimpleITK as sitk +from konfai.network import network + +from baselines import BaselineNet, built_source + +REPOSITORY = "https://github.com/mattiaspaul/deedsBCV" +COMMIT = "00b46539aa03d23988a241173d8f1f6c0c68dc6a" # master, 2025-09-09 + + +def _build(source: Path) -> None: + subprocess.run(["make", "-C", str(source), "linear", "deeds", "applyFloat"], check=True) # nosec B603 B607 + + +def geometry(image: sitk.Image) -> tuple: + return image.GetSize(), image.GetSpacing(), image.GetOrigin(), image.GetDirection() + + +def upsample(coarse: np.ndarray, full: tuple[int, int, int]) -> np.ndarray: + """deeds' ``upsampleDeformationsCL``: voxel p samples the control grid at p * coarse / full, indices clamped.""" + for axis, (extent, size) in enumerate(zip(full, coarse.shape, strict=True)): + x = np.arange(extent) * size / extent + low = np.floor(x).astype(int) + weight = (x - low).astype(np.float32).reshape([-1 if a == axis else 1 for a in range(3)]) + coarse = ( + np.take(coarse, low, axis) * (1 - weight) + np.take(coarse, np.minimum(low + 1, size - 1), axis) * weight + ) + return coarse + + +class Deeds: + def __init__(self, arguments: list[str]) -> None: + self._arguments = arguments + + def __call__( + self, + fixed: sitk.Image, + moving: sitk.Image, + fixed_mask: sitk.Image | None, + moving_mask: sitk.Image | None, + device: int, + ) -> np.ndarray: + binaries = built_source("deedsBCV", REPOSITORY, COMMIT, _build) + original, moving = sitk.Cast(fixed, sitk.sitkFloat32), sitk.Cast(moving, sitk.sitkFloat32) + fixed = original + spacing = np.array(original.GetSpacing()) + if spacing.max() > 1.01 * spacing.min(): + iso = float(np.prod(spacing) ** (1 / 3)) + size = [int(np.ceil((n - 1) * s / iso)) + 1 for n, s in zip(original.GetSize(), spacing, strict=True)] + fixed = sitk.Resample( + original, + size, + sitk.Transform(), + sitk.sitkLinear, + original.GetOrigin(), + (iso,) * 3, + original.GetDirection(), + float(sitk.GetArrayViewFromImage(original).min()), + ) + if min(fixed.GetSize()) < 16: + raise ValueError(f"deeds needs at least 16 voxels per fixed axis (grid 8): {fixed.GetSize()}") + if geometry(moving) != geometry(fixed): + moving = sitk.Resample( + moving, fixed, sitk.Transform(), sitk.sitkLinear, float(sitk.GetArrayViewFromImage(moving).min()) + ) + with tempfile.TemporaryDirectory(prefix="deeds_") as scratch: + work = Path(scratch) + sitk.WriteImage(fixed, str(work / "fixed.nii.gz")) + sitk.WriteImage(moving, str(work / "moving.nii.gz")) + del moving + subprocess.run( + [ + str(binaries / "deedsBCV"), + "-F", + str(work / "fixed.nii.gz"), + "-M", + str(work / "moving.nii.gz"), # nosec B603 + "-O", + str(work / "deeds"), + *self._arguments, + ], + check=True, + ) + flow = np.fromfile(work / "deeds_displacements.dat", np.float32) + m, n, o = fixed.GetSize() + step = round((m * n * o / (flow.size // 3)) ** (1 / 3)) + u, v, w = flow.reshape(3, o // step, n // step, m // step) # arrays as (k, j, i) + displacement = np.stack([upsample(c, (o, n, m)) for c in (v, u, w)], -1) # (k, j, i, 3): voxels along i, j, k + if not np.isfinite(displacement).all(): + raise ValueError("deeds returned a non-finite displacement") + to_world = np.array(fixed.GetDirection()).reshape(3, 3) @ np.diag(fixed.GetSpacing()) + field = sitk.GetImageFromArray((displacement @ to_world.T).astype(np.float32), isVector=True) + field.CopyInformation(fixed) + if fixed is not original: # world vectors: a plain linear resampling onto the fixed grid + field = sitk.Resample(field, original, sitk.Transform(), sitk.sitkLinear, 0.0, sitk.sitkVectorFloat32) + return np.ascontiguousarray(np.moveaxis(sitk.GetArrayFromImage(field), -1, 0), dtype=np.float32) + + +class RegistrationNet(BaselineNet): + """deedsBCV, defaults. CPU.""" + + def __init__( + self, + optimizer: network.OptimizerLoader = network.OptimizerLoader(), + schedulers: dict[str, network.LRSchedulersLoader] = { + "default:ReduceLROnPlateau": network.LRSchedulersLoader(0) + }, + outputs_criterions: dict[str, network.TargetCriterionsLoader] = {"default": network.TargetCriterionsLoader()}, + arguments: Annotated[list[str], "Extra deedsBCV arguments (-G, -L, -Q, -a); none for the defaults."] = [], + ) -> None: + super().__init__(Deeds(list(arguments)), 3, optimizer, schedulers, outputs_criterions) diff --git a/Deeds/requirements.txt b/Deeds/requirements.txt new file mode 100644 index 0000000000000000000000000000000000000000..7f5e98e3f968b22748bf799bc7f38e5b2fe45da3 --- /dev/null +++ b/Deeds/requirements.txt @@ -0,0 +1 @@ +SimpleITK diff --git a/Demons/Prediction.yml b/Demons/Prediction.yml new file mode 100644 index 0000000000000000000000000000000000000000..00ecbe4910eafbf6a8aec11984cb94038197511a --- /dev/null +++ b/Demons/Prediction.yml @@ -0,0 +1,94 @@ +Predictor: + Model: + classpath: model:RegistrationNet + RegistrationNet: + iterations: 20 + standard_deviation: 2.0 + shrinks: + - 4 + - 2 + sigmas: + - 8.0 + - 4.0 + modality: auto + threads: 0 + outputs_criterions: None + Dataset: + groups_src: + Volume_0: + groups_dest: + Fixed: + transforms: + TensorCast: + dtype: float32 + inverse: false + patch_transforms: None + is_input: true + Volume_1: + groups_dest: + Moving: + transforms: + TensorCast: + dtype: float32 + inverse: false + patch_transforms: None + is_input: true + Volume_2: + groups_dest: + FixedMask: + transforms: + TensorCast: + dtype: float32 + inverse: false + patch_transforms: None + is_input: true + Volume_3: + groups_dest: + MovingMask: + transforms: + TensorCast: + dtype: float32 + inverse: false + patch_transforms: None + is_input: true + augmentations: None + Patch: + patch_size: + - 0 + - 0 + - 0 + overlap: 0 + pad_value: None + extend_slice: 0 + mode: resample + max_voxels: None + subset: None + dataset_filenames: + - ./Dataset/:mha + batch_size: 1 + num_workers: None + pin_memory: false + prefetch_factor: None + persistent_workers: None + outputs_dataset: + DisplacementField: + OutputDataset: + name_class: OutputDataset + before_reduction_transforms: None + after_reduction_transforms: None + final_transforms: + TensorCast: + dtype: float32 + inverse: false + dataset_filename: DisplacementField:mha + group: DisplacementField + same_as_group: Volume_0:Fixed + patch_combine: Cosinus + reduction: Mean + Mean: {} + train_name: Baselines-Demons + manual_seed: 42 + gpu_checkpoints: None + combine: Mean + autocast: false + data_log: None diff --git a/Demons/app.json b/Demons/app.json new file mode 100644 index 0000000000000000000000000000000000000000..fb3ebb815f9cff24d5a5c56865ca8c776552da4a --- /dev/null +++ b/Demons/app.json @@ -0,0 +1,40 @@ +{ + "display_name": "Demons", + "short_description": "Demons as SimpleITK's registration notebook runs it: fast symmetric forces, 20 iterations, the field smoothed with a standard deviation of 2, two coarse levels then full resolution, histogram matching first for MR. One modality only. The ImagingBenchmarks baseline demons.", + "description": "Demons as SimpleITK's registration notebook runs it: fast symmetric forces, 20 iterations, the field smoothed with a standard deviation of 2, two coarse levels then full resolution, histogram matching first for MR. One modality only. The ImagingBenchmarks baseline demons. The pair must be aligned (rigidly for one patient, by an affine transform between two subjects): only the deformable stage runs. SimpleITK (CPU). Output: the displacement field on the fixed grid, in mm along the world axes (ITK, LPS).", + "task": "registration", + "tta": 0, + "mc_dropout": 0, + "models": [], + "inputs": { + "Fixed": { + "display_name": "Fixed image", + "volume_type": "VOLUME", + "required": true + }, + "Moving": { + "display_name": "Moving image", + "volume_type": "VOLUME", + "required": true + }, + "FixedMask": { + "display_name": "Fixed mask (ignored by this baseline)", + "volume_type": "SEGMENTATION", + "required": false, + "default": "ones" + }, + "MovingMask": { + "display_name": "Moving mask (ignored by this baseline)", + "volume_type": "SEGMENTATION", + "required": false, + "default": "ones" + } + }, + "outputs": { + "DisplacementField": { + "display_name": "Displacement field", + "volume_type": "VOLUME", + "required": true + } + } +} diff --git a/Demons/baselines.py b/Demons/baselines.py new file mode 100644 index 0000000000000000000000000000000000000000..691b6d9c745cf4c64ab8e323b21b5c76b251af72 --- /dev/null +++ b/Demons/baselines.py @@ -0,0 +1,206 @@ +# Copyright (c) 2025 Valentin Boussot +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +# +# SPDX-License-Identifier: Apache-2.0 + +"""What every baseline app shares (a copy of the repository's baselines.py, kept by build.py): the authors' code fetched at its pin, the graph module that hands a pair to an +engine and gets a displacement field back, and the field's convention. + +The field is the benchmark's: one component per spatial axis, in mm along the world (ITK, LPS) axes, on the fixed +image's grid, such that the fixed point ``x`` matches ``x + u(x)`` in the moving image. The predictor attaches the +fixed image's geometry to the output (``same_as_group: Volume_0:Fixed`` in the app's ``Prediction.yml``). + +NOTE: do NOT add ``from __future__ import annotations``: KonfAI's config engine relies on runtime-evaluated +annotations (``get_origin``); PEP 563 stringized annotations break binding. +""" + +import hashlib +import os +import shutil +import subprocess # nosec B404 +import urllib.request +import zipfile +from collections.abc import Callable +from pathlib import Path + +import numpy as np +import SimpleITK as sitk +import torch +from konfai.network import network +from konfai.utils.dataset import Attribute, data_to_image + +#: An engine: (fixed, moving, fixed mask or None, moving mask or None, CUDA device index or -1) -> the field, +#: ``[D, *spatial]`` in mm along the world axes on the fixed grid. +Engine = Callable[[sitk.Image, sitk.Image, sitk.Image | None, sitk.Image | None, int], np.ndarray] + + +def cache_dir() -> Path: + """Where the authors' code and binaries live, once fetched: ``$BASELINES_KONFAI_CACHE`` or + ``~/.cache/baselines-konfai``.""" + return Path(os.environ.get("BASELINES_KONFAI_CACHE", Path.home() / ".cache" / "baselines-konfai")) + + +def pinned_source(name: str, url: str, commit: str) -> Path: + """The authors' repository at ``commit``, cloned once into the cache: a baseline runs the code it was + measured with, never a moving branch.""" + target = cache_dir() / f"{name}-{commit[:12]}" + if not (target / ".git").exists(): + target.parent.mkdir(parents=True, exist_ok=True) + subprocess.run(["git", "clone", "--quiet", url, str(target)], check=True) # nosec B603 B607 + subprocess.run(["git", "-C", str(target), "checkout", "--quiet", commit], check=True) # nosec B603 B607 + return target + + +def fetch(url: str, target: Path, sha256: str | None = None) -> Path: + """``url`` downloaded once to ``target`` and, when a hash is given, checked against it.""" + if not target.exists(): + target.parent.mkdir(parents=True, exist_ok=True) + part = target.with_name(target.name + ".part") + urllib.request.urlretrieve(url, part) # nosec B310 - the authors' release, checked below + with part.open("rb") as stream: + digest = hashlib.file_digest(stream, "sha256").hexdigest() + if sha256 and digest != sha256: + part.unlink() + raise RuntimeError(f"{url} does not match its recorded hash") + part.rename(target) + return target + + +def pinned_archive(name: str, url: str, sha256: str) -> Path: + """A release archive at ``url``, downloaded once into the cache, checked against ``sha256`` and unpacked: the + binaries a baseline was measured with.""" + target = cache_dir() / f"{name}-{sha256[:12]}" + if not (target / ".unpacked").exists(): + archive = fetch(url, target / "archive", sha256) + if zipfile.is_zipfile(archive): + with zipfile.ZipFile(archive) as packed: + packed.extractall(target) # nosec B202 - our own pinned archive + for entry in packed.infolist(): # zipfile drops the modes: the binaries must stay executable + if mode := (entry.external_attr >> 16) & 0o777: + (target / entry.filename).chmod(mode) + else: + shutil.unpack_archive(str(archive), str(target), "gztar") + archive.unlink() + (target / ".unpacked").touch() + return target + + +def pinned_environment(root: Path, python: str, installs: list[list[str]]) -> Path: + """A virtual environment at ``root/venv`` on its own Python, made once by uv (``pip install uv``): for the tools + whose pins do not run on the host's Python. ``installs`` are ``pip install`` argument lists, run in order.""" + try: + import uv + + command = uv.find_uv_bin() + except ImportError: + command = shutil.which("uv") or "" + if not command: + raise RuntimeError("this baseline builds its own Python environment with uv: pip install uv") + venv = root / "venv" + if not (venv / ".ready").exists(): + subprocess.run([command, "venv", "--quiet", "--clear", "--python", python, str(venv)], check=True) # nosec B603 + for arguments in installs: + subprocess.run( # nosec B603 + [ + command, + "pip", + "install", + "--quiet", + "--no-cache", + "--python", + str(venv / "bin" / "python"), + *arguments, + ], + check=True, + ) + (venv / ".ready").touch() + return venv + + +def built_source(name: str, url: str, commit: str, build: Callable[[Path], None]) -> Path: + """The authors' repository at ``commit``, built once by ``build`` (a marker says it is done).""" + source = pinned_source(name, url, commit) + if not (source / ".built").exists(): + build(source) + (source / ".built").touch() + return source + + +def field_from_voxels(displacement: np.ndarray, fixed: sitk.Image) -> np.ndarray: + """A displacement in voxels along the index axes, ``[i, j, k, D]``, as the benchmark's field ``[D, k, j, i]`` + in mm along the world axes: ``u = D S d``, with ``D`` the direction and ``S`` the spacing of the fixed image.""" + n = fixed.GetDimension() + to_world = np.array(fixed.GetDirection()).reshape(n, n) @ np.diag(fixed.GetSpacing()) + world = displacement.astype(np.float64) @ to_world.T # [i, j, k, D] + return np.ascontiguousarray(np.moveaxis(world, -1, 0).transpose(0, *reversed(range(1, n + 1))), dtype=np.float32) + + +def to_index_array(image: sitk.Image) -> np.ndarray: + """The image as a ``[i, j, k]`` array, the index axes in ITK's order, which the tools indexed that way read.""" + return np.ascontiguousarray(sitk.GetArrayFromImage(image).transpose(*reversed(range(image.GetDimension())))) + + +class Registration(torch.nn.Module): + """Graph module: the pair's tensors and their geometry in, the field out, through the engine, one sample at + a time. ``accepts_attributes = True`` opts it into the per-branch ``Attribute`` list (the convention of + ``CriterionWithAttribute``): registration needs the physical geometry.""" + + accepts_attributes = True + + def __init__(self, engine: Engine) -> None: + super().__init__() + self._engine = engine + + def forward( + self, + fixed: torch.Tensor, + moving: torch.Tensor, + fixed_mask: torch.Tensor, + moving_mask: torch.Tensor, + attributes: list[list[Attribute]], + ) -> torch.Tensor: + fixed_attrs, moving_attrs, fixed_mask_attrs, moving_mask_attrs = attributes + device_index = fixed.device.index if fixed.device.type == "cuda" else -1 + fields = [] + # the engines optimise with autograd; the predictor calls forward under inference mode + with torch.inference_mode(False), torch.enable_grad(): + for b in range(fixed.shape[0]): + images = [ + data_to_image(t[b].detach().cpu().numpy(), attrs[b]) + for t, attrs in ((fixed, fixed_attrs), (moving, moving_attrs)) + ] + masks = [ + data_to_image(t[b].detach().cpu().numpy(), attrs[b]) if not bool((t[b] == 1).all()) else None + for t, attrs in ((fixed_mask, fixed_mask_attrs), (moving_mask, moving_mask_attrs)) + ] + fields.append(torch.from_numpy(self._engine(images[0], images[1], masks[0], masks[1], device_index))) + return torch.stack(fields, dim=0).to(fixed.device) + + +class BaselineNet(network.Network): + """A baseline as an ``add_module`` graph: fixed = branch 0, moving = branch 1, the masks branches 2 and 3 (a + mask of ones means none). The one output is ``DisplacementField``, on the fixed grid.""" + + def __init__( + self, + engine: Engine, + dim: int, + optimizer: network.OptimizerLoader, + schedulers: dict[str, network.LRSchedulersLoader], + outputs_criterions: dict[str, network.TargetCriterionsLoader], + ) -> None: + super().__init__( + in_channels=1, optimizer=optimizer, schedulers=schedulers, outputs_criterions=outputs_criterions, dim=dim + ) + self.add_module("DisplacementField", Registration(engine), in_branch=[0, 1, 2, 3], out_branch=["dvf"]) diff --git a/Demons/model.py b/Demons/model.py new file mode 100644 index 0000000000000000000000000000000000000000..bb5e6331fedd69cb05abc32da1f9300e08fc696f --- /dev/null +++ b/Demons/model.py @@ -0,0 +1,152 @@ +# Copyright (c) 2025 Valentin Boussot +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +# +# SPDX-License-Identifier: Apache-2.0 + +"""Demons as SimpleITK's own registration notebook runs it (SimpleITK-Notebooks, 66_Registration_Demons): +fast symmetric forces, 20 iterations, the field smoothed with a standard deviation of 2, over two coarse levels +(shrink 4 and 2, smoothing 8 and 4) then full resolution; for MR, the notebook's histogram matching first. Demons +compares intensities: one modality only. + +NOTE: do NOT add ``from __future__ import annotations``: KonfAI's config engine relies on runtime-evaluated +annotations (``get_origin``); PEP 563 stringized annotations break binding. +""" + +import os +from typing import Annotated + +import numpy as np +import SimpleITK as sitk +from konfai.network import network +from konfai.utils.config import Choices + +from baselines import BaselineNet + + +def smooth_and_resample(image: sitk.Image, shrink: float, sigma: float) -> sitk.Image: + """The notebook's function, verbatim in substance.""" + smoothed = sitk.SmoothingRecursiveGaussian(image, [sigma] * image.GetDimension()) + size = [int(sz / float(shrink) + 0.5) for sz in image.GetSize()] + spacing = [ + ((sz - 1) * sp) / (new - 1) for sz, sp, new in zip(image.GetSize(), image.GetSpacing(), size, strict=True) + ] + return sitk.Resample( + smoothed, + size, + sitk.Transform(), + sitk.sitkLinear, + image.GetOrigin(), + spacing, + image.GetDirection(), + 0.0, + image.GetPixelID(), + ) + + +def multiscale_demons( + algorithm: sitk.ImageFilter, fixed: sitk.Image, moving: sitk.Image, shrinks: list[int], sigmas: list[float] +) -> sitk.Image: + """The notebook's multiscale loop: the field found at a coarse level starts the next, finer one.""" + size = [int(sz / float(shrinks[0]) + 0.5) for sz in fixed.GetSize()] + spacing = [ + ((sz - 1) * sp) / (new - 1) for sz, sp, new in zip(fixed.GetSize(), fixed.GetSpacing(), size, strict=True) + ] + field = sitk.Image(size, sitk.sitkVectorFloat64, fixed.GetDimension()) + field.SetSpacing(spacing) + field.SetOrigin(fixed.GetOrigin()) + pairs = [ + (smooth_and_resample(fixed, s, g), smooth_and_resample(moving, s, g)) + for s, g in zip(shrinks, sigmas, strict=True) + ] + for f, m in [*pairs, (fixed, moving)]: + field = sitk.Resample(field, f) + field = algorithm.Execute(f, m, field) + return field + + +class Demons: + def __init__( + self, + iterations: int, + standard_deviation: float, + shrinks: list[int], + sigmas: list[float], + modality: str, + threads: int, + ) -> None: + self._iterations, self._standard_deviation = iterations, standard_deviation + self._shrinks, self._sigmas, self._modality, self._threads = shrinks, sigmas, modality, threads + + def __call__( + self, + fixed: sitk.Image, + moving: sitk.Image, + fixed_mask: sitk.Image | None, + moving_mask: sitk.Image | None, + device: int, + ) -> np.ndarray: + sitk.ProcessObject.SetGlobalDefaultNumberOfThreads( + self._threads or int(os.environ.get("ITK_GLOBAL_DEFAULT_NUMBER_OF_THREADS", "8")) + ) + fixed, moving = sitk.Cast(fixed, sitk.sitkFloat32), sitk.Cast(moving, sitk.sitkFloat32) + moving = sitk.Resample( + moving, fixed, sitk.Transform(), sitk.sitkLinear, float(sitk.GetArrayViewFromImage(moving).min()) + ) + modality = ( + self._modality + if self._modality != "auto" + else ("ct" if float(sitk.GetArrayViewFromImage(fixed).min()) < -200 else "mr") + ) + if modality == "mr": # the notebook's histogram matching: Demons assumes equal intensities, MR breaks that + matcher = sitk.HistogramMatchingImageFilter() + matcher.SetNumberOfHistogramLevels(1024) + matcher.SetNumberOfMatchPoints(7) + matcher.ThresholdAtMeanIntensityOn() + moving = matcher.Execute(moving, fixed) + demons = sitk.FastSymmetricForcesDemonsRegistrationFilter() + demons.SetNumberOfIterations(self._iterations) + demons.SetSmoothDisplacementField(True) + demons.SetStandardDeviations(self._standard_deviation) + field = multiscale_demons(demons, fixed, moving, self._shrinks, self._sigmas) + return np.ascontiguousarray(np.moveaxis(sitk.GetArrayFromImage(field), -1, 0), dtype=np.float32) + + +class RegistrationNet(BaselineNet): + """Demons, the SimpleITK notebook's settings.""" + + def __init__( + self, + optimizer: network.OptimizerLoader = network.OptimizerLoader(), + schedulers: dict[str, network.LRSchedulersLoader] = { + "default:ReduceLROnPlateau": network.LRSchedulersLoader(0) + }, + outputs_criterions: dict[str, network.TargetCriterionsLoader] = {"default": network.TargetCriterionsLoader()}, + iterations: Annotated[int, "Demons iterations at each level."] = 20, + standard_deviation: Annotated[float, "Standard deviation of the field's smoothing, in voxels."] = 2.0, + shrinks: Annotated[list[int], "Shrink factor of each coarse level, before full resolution."] = [4, 2], + sigmas: Annotated[list[float], "Smoothing of each coarse level, in voxels."] = [8.0, 4.0], + modality: Annotated[ + str, + Choices(["auto", "ct", "mr"]), + "mr matches the moving histogram to the fixed first; auto reads it off the intensities.", + ] = "auto", + threads: Annotated[int, "ITK threads; 0 takes ITK_GLOBAL_DEFAULT_NUMBER_OF_THREADS or 8."] = 0, + ) -> None: + super().__init__( + Demons(iterations, standard_deviation, shrinks, sigmas, modality, threads), + 3, + optimizer, + schedulers, + outputs_criterions, + ) diff --git a/Demons/requirements.txt b/Demons/requirements.txt new file mode 100644 index 0000000000000000000000000000000000000000..7f5e98e3f968b22748bf799bc7f38e5b2fe45da3 --- /dev/null +++ b/Demons/requirements.txt @@ -0,0 +1 @@ +SimpleITK diff --git a/Greedy/Prediction.yml b/Greedy/Prediction.yml new file mode 100644 index 0000000000000000000000000000000000000000..2b7f1d07495f4f2c98c502f4a94641ecc4dbcbca --- /dev/null +++ b/Greedy/Prediction.yml @@ -0,0 +1,87 @@ +Predictor: + Model: + classpath: model:RegistrationNet + RegistrationNet: + metric: NCC 2x2x2 + iterations: 100x50x10 + threads: 0 + outputs_criterions: None + Dataset: + groups_src: + Volume_0: + groups_dest: + Fixed: + transforms: + TensorCast: + dtype: float32 + inverse: false + patch_transforms: None + is_input: true + Volume_1: + groups_dest: + Moving: + transforms: + TensorCast: + dtype: float32 + inverse: false + patch_transforms: None + is_input: true + Volume_2: + groups_dest: + FixedMask: + transforms: + TensorCast: + dtype: float32 + inverse: false + patch_transforms: None + is_input: true + Volume_3: + groups_dest: + MovingMask: + transforms: + TensorCast: + dtype: float32 + inverse: false + patch_transforms: None + is_input: true + augmentations: None + Patch: + patch_size: + - 0 + - 0 + - 0 + overlap: 0 + pad_value: None + extend_slice: 0 + mode: resample + max_voxels: None + subset: None + dataset_filenames: + - ./Dataset/:mha + batch_size: 1 + num_workers: None + pin_memory: false + prefetch_factor: None + persistent_workers: None + outputs_dataset: + DisplacementField: + OutputDataset: + name_class: OutputDataset + before_reduction_transforms: None + after_reduction_transforms: None + final_transforms: + TensorCast: + dtype: float32 + inverse: false + dataset_filename: DisplacementField:mha + group: DisplacementField + same_as_group: Volume_0:Fixed + patch_combine: Cosinus + reduction: Mean + Mean: {} + train_name: Baselines-Greedy + manual_seed: 42 + gpu_checkpoints: None + combine: Mean + autocast: false + data_log: None diff --git a/Greedy/app.json b/Greedy/app.json new file mode 100644 index 0000000000000000000000000000000000000000..80d46c6f702a2c76becdb8169d4543270b1ad943 --- /dev/null +++ b/Greedy/app.json @@ -0,0 +1,40 @@ +{ + "display_name": "greedy", + "short_description": "greedy as its Quick Start runs it: normalised cross-correlation over a 2x2x2 window, 100x50x10 iterations, the deformable stage alone; the picsl_greedy package at a pinned version. One modality only. The ImagingBenchmarks baseline greedy. CPU.", + "description": "greedy as its Quick Start runs it: normalised cross-correlation over a 2x2x2 window, 100x50x10 iterations, the deformable stage alone; the picsl_greedy package at a pinned version. One modality only. The ImagingBenchmarks baseline greedy. CPU. The pair must be aligned (rigidly for one patient, by an affine transform between two subjects): only the deformable stage runs. Masks are ignored by this baseline. Output: the displacement field on the fixed grid, in mm along the world axes (ITK, LPS).", + "task": "registration", + "tta": 0, + "mc_dropout": 0, + "models": [], + "inputs": { + "Fixed": { + "display_name": "Fixed image", + "volume_type": "VOLUME", + "required": true + }, + "Moving": { + "display_name": "Moving image", + "volume_type": "VOLUME", + "required": true + }, + "FixedMask": { + "display_name": "Fixed mask (ignored by this baseline)", + "volume_type": "SEGMENTATION", + "required": false, + "default": "ones" + }, + "MovingMask": { + "display_name": "Moving mask (ignored by this baseline)", + "volume_type": "SEGMENTATION", + "required": false, + "default": "ones" + } + }, + "outputs": { + "DisplacementField": { + "display_name": "Displacement field", + "volume_type": "VOLUME", + "required": true + } + } +} diff --git a/Greedy/baselines.py b/Greedy/baselines.py new file mode 100644 index 0000000000000000000000000000000000000000..691b6d9c745cf4c64ab8e323b21b5c76b251af72 --- /dev/null +++ b/Greedy/baselines.py @@ -0,0 +1,206 @@ +# Copyright (c) 2025 Valentin Boussot +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +# +# SPDX-License-Identifier: Apache-2.0 + +"""What every baseline app shares (a copy of the repository's baselines.py, kept by build.py): the authors' code fetched at its pin, the graph module that hands a pair to an +engine and gets a displacement field back, and the field's convention. + +The field is the benchmark's: one component per spatial axis, in mm along the world (ITK, LPS) axes, on the fixed +image's grid, such that the fixed point ``x`` matches ``x + u(x)`` in the moving image. The predictor attaches the +fixed image's geometry to the output (``same_as_group: Volume_0:Fixed`` in the app's ``Prediction.yml``). + +NOTE: do NOT add ``from __future__ import annotations``: KonfAI's config engine relies on runtime-evaluated +annotations (``get_origin``); PEP 563 stringized annotations break binding. +""" + +import hashlib +import os +import shutil +import subprocess # nosec B404 +import urllib.request +import zipfile +from collections.abc import Callable +from pathlib import Path + +import numpy as np +import SimpleITK as sitk +import torch +from konfai.network import network +from konfai.utils.dataset import Attribute, data_to_image + +#: An engine: (fixed, moving, fixed mask or None, moving mask or None, CUDA device index or -1) -> the field, +#: ``[D, *spatial]`` in mm along the world axes on the fixed grid. +Engine = Callable[[sitk.Image, sitk.Image, sitk.Image | None, sitk.Image | None, int], np.ndarray] + + +def cache_dir() -> Path: + """Where the authors' code and binaries live, once fetched: ``$BASELINES_KONFAI_CACHE`` or + ``~/.cache/baselines-konfai``.""" + return Path(os.environ.get("BASELINES_KONFAI_CACHE", Path.home() / ".cache" / "baselines-konfai")) + + +def pinned_source(name: str, url: str, commit: str) -> Path: + """The authors' repository at ``commit``, cloned once into the cache: a baseline runs the code it was + measured with, never a moving branch.""" + target = cache_dir() / f"{name}-{commit[:12]}" + if not (target / ".git").exists(): + target.parent.mkdir(parents=True, exist_ok=True) + subprocess.run(["git", "clone", "--quiet", url, str(target)], check=True) # nosec B603 B607 + subprocess.run(["git", "-C", str(target), "checkout", "--quiet", commit], check=True) # nosec B603 B607 + return target + + +def fetch(url: str, target: Path, sha256: str | None = None) -> Path: + """``url`` downloaded once to ``target`` and, when a hash is given, checked against it.""" + if not target.exists(): + target.parent.mkdir(parents=True, exist_ok=True) + part = target.with_name(target.name + ".part") + urllib.request.urlretrieve(url, part) # nosec B310 - the authors' release, checked below + with part.open("rb") as stream: + digest = hashlib.file_digest(stream, "sha256").hexdigest() + if sha256 and digest != sha256: + part.unlink() + raise RuntimeError(f"{url} does not match its recorded hash") + part.rename(target) + return target + + +def pinned_archive(name: str, url: str, sha256: str) -> Path: + """A release archive at ``url``, downloaded once into the cache, checked against ``sha256`` and unpacked: the + binaries a baseline was measured with.""" + target = cache_dir() / f"{name}-{sha256[:12]}" + if not (target / ".unpacked").exists(): + archive = fetch(url, target / "archive", sha256) + if zipfile.is_zipfile(archive): + with zipfile.ZipFile(archive) as packed: + packed.extractall(target) # nosec B202 - our own pinned archive + for entry in packed.infolist(): # zipfile drops the modes: the binaries must stay executable + if mode := (entry.external_attr >> 16) & 0o777: + (target / entry.filename).chmod(mode) + else: + shutil.unpack_archive(str(archive), str(target), "gztar") + archive.unlink() + (target / ".unpacked").touch() + return target + + +def pinned_environment(root: Path, python: str, installs: list[list[str]]) -> Path: + """A virtual environment at ``root/venv`` on its own Python, made once by uv (``pip install uv``): for the tools + whose pins do not run on the host's Python. ``installs`` are ``pip install`` argument lists, run in order.""" + try: + import uv + + command = uv.find_uv_bin() + except ImportError: + command = shutil.which("uv") or "" + if not command: + raise RuntimeError("this baseline builds its own Python environment with uv: pip install uv") + venv = root / "venv" + if not (venv / ".ready").exists(): + subprocess.run([command, "venv", "--quiet", "--clear", "--python", python, str(venv)], check=True) # nosec B603 + for arguments in installs: + subprocess.run( # nosec B603 + [ + command, + "pip", + "install", + "--quiet", + "--no-cache", + "--python", + str(venv / "bin" / "python"), + *arguments, + ], + check=True, + ) + (venv / ".ready").touch() + return venv + + +def built_source(name: str, url: str, commit: str, build: Callable[[Path], None]) -> Path: + """The authors' repository at ``commit``, built once by ``build`` (a marker says it is done).""" + source = pinned_source(name, url, commit) + if not (source / ".built").exists(): + build(source) + (source / ".built").touch() + return source + + +def field_from_voxels(displacement: np.ndarray, fixed: sitk.Image) -> np.ndarray: + """A displacement in voxels along the index axes, ``[i, j, k, D]``, as the benchmark's field ``[D, k, j, i]`` + in mm along the world axes: ``u = D S d``, with ``D`` the direction and ``S`` the spacing of the fixed image.""" + n = fixed.GetDimension() + to_world = np.array(fixed.GetDirection()).reshape(n, n) @ np.diag(fixed.GetSpacing()) + world = displacement.astype(np.float64) @ to_world.T # [i, j, k, D] + return np.ascontiguousarray(np.moveaxis(world, -1, 0).transpose(0, *reversed(range(1, n + 1))), dtype=np.float32) + + +def to_index_array(image: sitk.Image) -> np.ndarray: + """The image as a ``[i, j, k]`` array, the index axes in ITK's order, which the tools indexed that way read.""" + return np.ascontiguousarray(sitk.GetArrayFromImage(image).transpose(*reversed(range(image.GetDimension())))) + + +class Registration(torch.nn.Module): + """Graph module: the pair's tensors and their geometry in, the field out, through the engine, one sample at + a time. ``accepts_attributes = True`` opts it into the per-branch ``Attribute`` list (the convention of + ``CriterionWithAttribute``): registration needs the physical geometry.""" + + accepts_attributes = True + + def __init__(self, engine: Engine) -> None: + super().__init__() + self._engine = engine + + def forward( + self, + fixed: torch.Tensor, + moving: torch.Tensor, + fixed_mask: torch.Tensor, + moving_mask: torch.Tensor, + attributes: list[list[Attribute]], + ) -> torch.Tensor: + fixed_attrs, moving_attrs, fixed_mask_attrs, moving_mask_attrs = attributes + device_index = fixed.device.index if fixed.device.type == "cuda" else -1 + fields = [] + # the engines optimise with autograd; the predictor calls forward under inference mode + with torch.inference_mode(False), torch.enable_grad(): + for b in range(fixed.shape[0]): + images = [ + data_to_image(t[b].detach().cpu().numpy(), attrs[b]) + for t, attrs in ((fixed, fixed_attrs), (moving, moving_attrs)) + ] + masks = [ + data_to_image(t[b].detach().cpu().numpy(), attrs[b]) if not bool((t[b] == 1).all()) else None + for t, attrs in ((fixed_mask, fixed_mask_attrs), (moving_mask, moving_mask_attrs)) + ] + fields.append(torch.from_numpy(self._engine(images[0], images[1], masks[0], masks[1], device_index))) + return torch.stack(fields, dim=0).to(fixed.device) + + +class BaselineNet(network.Network): + """A baseline as an ``add_module`` graph: fixed = branch 0, moving = branch 1, the masks branches 2 and 3 (a + mask of ones means none). The one output is ``DisplacementField``, on the fixed grid.""" + + def __init__( + self, + engine: Engine, + dim: int, + optimizer: network.OptimizerLoader, + schedulers: dict[str, network.LRSchedulersLoader], + outputs_criterions: dict[str, network.TargetCriterionsLoader], + ) -> None: + super().__init__( + in_channels=1, optimizer=optimizer, schedulers=schedulers, outputs_criterions=outputs_criterions, dim=dim + ) + self.add_module("DisplacementField", Registration(engine), in_branch=[0, 1, 2, 3], out_branch=["dvf"]) diff --git a/Greedy/model.py b/Greedy/model.py new file mode 100644 index 0000000000000000000000000000000000000000..c644e777a6da6449e326294f071d5f1c90563fca --- /dev/null +++ b/Greedy/model.py @@ -0,0 +1,79 @@ +# Copyright (c) 2025 Valentin Boussot +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +# +# SPDX-License-Identifier: Apache-2.0 + +"""greedy as its Quick Start runs it (the ``picsl_greedy`` package at a pinned version): normalised cross-correlation +over a 2x2x2 window, 100x50x10 iterations, the deformable stage alone. One modality only. + +NOTE: do NOT add ``from __future__ import annotations``: KonfAI's config engine relies on runtime-evaluated +annotations (``get_origin``); PEP 563 stringized annotations break binding. +""" + +import os +import tempfile +from pathlib import Path +from typing import Annotated + +import numpy as np +import SimpleITK as sitk +from konfai.network import network + +from baselines import BaselineNet + +VERSION = "1.4.0.3" # the picsl_greedy package; the bundle's requirements pin it + + +class Greedy: + def __init__(self, metric: str, iterations: str, threads: int) -> None: + self._metric, self._iterations, self._threads = metric, iterations, threads + + def __call__( + self, + fixed: sitk.Image, + moving: sitk.Image, + fixed_mask: sitk.Image | None, + moving_mask: sitk.Image | None, + device: int, + ) -> np.ndarray: + from picsl_greedy import Greedy3D + + threads = self._threads or int(os.environ.get("ITK_GLOBAL_DEFAULT_NUMBER_OF_THREADS", "8")) + with tempfile.TemporaryDirectory(prefix="greedy_") as scratch: + work = Path(scratch) + sitk.WriteImage(fixed, str(work / "fixed.nii.gz")) + sitk.WriteImage(moving, str(work / "moving.nii.gz")) + Greedy3D().execute( + f"-d 3 -threads {threads} -m {self._metric} -i {work / 'fixed.nii.gz'} {work / 'moving.nii.gz'} " + f"-n {self._iterations} -o {work / 'warp.nii.gz'}" + ) + warp = sitk.ReadImage(str(work / "warp.nii.gz"), sitk.sitkVectorFloat32) + return np.ascontiguousarray(np.moveaxis(sitk.GetArrayFromImage(warp), -1, 0), dtype=np.float32) + + +class RegistrationNet(BaselineNet): + """greedy, the Quick Start's deformable call. CPU.""" + + def __init__( + self, + optimizer: network.OptimizerLoader = network.OptimizerLoader(), + schedulers: dict[str, network.LRSchedulersLoader] = { + "default:ReduceLROnPlateau": network.LRSchedulersLoader(0) + }, + outputs_criterions: dict[str, network.TargetCriterionsLoader] = {"default": network.TargetCriterionsLoader()}, + metric: Annotated[str, "greedy's -m: the similarity, NCC with its window."] = "NCC 2x2x2", + iterations: Annotated[str, "greedy's -n: iterations per level."] = "100x50x10", + threads: Annotated[int, "greedy's -threads; 0 takes ITK_GLOBAL_DEFAULT_NUMBER_OF_THREADS or 8."] = 0, + ) -> None: + super().__init__(Greedy(metric, iterations, threads), 3, optimizer, schedulers, outputs_criterions) diff --git a/Greedy/requirements.txt b/Greedy/requirements.txt new file mode 100644 index 0000000000000000000000000000000000000000..8971d6eef22de62dfb00aae5a0b5fec62f348506 --- /dev/null +++ b/Greedy/requirements.txt @@ -0,0 +1,2 @@ +SimpleITK +picsl_greedy==1.4.0.3 diff --git a/MultiGradICON/Prediction.yml b/MultiGradICON/Prediction.yml new file mode 100644 index 0000000000000000000000000000000000000000..d53a206e1b81c42682ca1420936a4c0a8121fedc --- /dev/null +++ b/MultiGradICON/Prediction.yml @@ -0,0 +1,90 @@ +Predictor: + Model: + classpath: model:RegistrationNet + RegistrationNet: + model: multigradicon + masks: false + fixed_modality: auto + moving_modality: auto + iterations: 50 + similarity: lncc + outputs_criterions: None + Dataset: + groups_src: + Volume_0: + groups_dest: + Fixed: + transforms: + TensorCast: + dtype: float32 + inverse: false + patch_transforms: None + is_input: true + Volume_1: + groups_dest: + Moving: + transforms: + TensorCast: + dtype: float32 + inverse: false + patch_transforms: None + is_input: true + Volume_2: + groups_dest: + FixedMask: + transforms: + TensorCast: + dtype: float32 + inverse: false + patch_transforms: None + is_input: true + Volume_3: + groups_dest: + MovingMask: + transforms: + TensorCast: + dtype: float32 + inverse: false + patch_transforms: None + is_input: true + augmentations: None + Patch: + patch_size: + - 0 + - 0 + - 0 + overlap: 0 + pad_value: None + extend_slice: 0 + mode: resample + max_voxels: None + subset: None + dataset_filenames: + - ./Dataset/:mha + batch_size: 1 + num_workers: None + pin_memory: false + prefetch_factor: None + persistent_workers: None + outputs_dataset: + DisplacementField: + OutputDataset: + name_class: OutputDataset + before_reduction_transforms: None + after_reduction_transforms: None + final_transforms: + TensorCast: + dtype: float32 + inverse: false + dataset_filename: DisplacementField:mha + group: DisplacementField + same_as_group: Volume_0:Fixed + patch_combine: Cosinus + reduction: Mean + Mean: {} + train_name: Baselines-MultiGradICON + manual_seed: 42 + gpu_checkpoints: None + combine: Mean + autocast: false + data_log: None diff --git a/MultiGradICON/app.json b/MultiGradICON/app.json new file mode 100644 index 0000000000000000000000000000000000000000..040ca9b57c3ce53f373e2bd741bf066b9aaaeb47 --- /dev/null +++ b/MultiGradICON/app.json @@ -0,0 +1,40 @@ +{ + "display_name": "multiGradICON", + "short_description": "The multiGradICON network's prediction, then 50 steps of instance optimisation on LNCC: unigradicon-register --model multigradicon with its defaults, the ImagingBenchmarks baseline multigradicon.", + "description": "The multiGradICON network's prediction, then 50 steps of instance optimisation on LNCC: unigradicon-register --model multigradicon with its defaults, the ImagingBenchmarks baseline multigradicon. With --set masks=true each image is multiplied by its lung mask, the authors' Learn2Reg lung protocol (the ImagingBenchmarks line multigradicon_lungmask). The pair must be aligned (rigidly for one patient, by an affine transform between two subjects): only the deformable stage runs. The command knows two modalities, ct (clamped to [-1000, 1000] HU) and mri (minimum to the 99th percentile), read off the intensities. The weights come from the authors' release, checked against their hash; the package is pinned at 1.0.5. A GPU is needed. Output: the displacement field on the fixed grid, in mm along the world axes (ITK, LPS).

How to cite:
L. Tian et al., uniGradICON: A foundation model for medical image registration, MICCAI 2024; B. Demir et al., multiGradICON, WBIR 2024.", + "task": "registration", + "tta": 0, + "mc_dropout": 0, + "models": [], + "inputs": { + "Fixed": { + "display_name": "Fixed image", + "volume_type": "VOLUME", + "required": true + }, + "Moving": { + "display_name": "Moving image", + "volume_type": "VOLUME", + "required": true + }, + "FixedMask": { + "display_name": "Fixed lung mask (used with masks=true)", + "volume_type": "SEGMENTATION", + "required": false, + "default": "ones" + }, + "MovingMask": { + "display_name": "Moving lung mask (used with masks=true)", + "volume_type": "SEGMENTATION", + "required": false, + "default": "ones" + } + }, + "outputs": { + "DisplacementField": { + "display_name": "Displacement field", + "volume_type": "VOLUME", + "required": true + } + } +} diff --git a/MultiGradICON/baselines.py b/MultiGradICON/baselines.py new file mode 100644 index 0000000000000000000000000000000000000000..691b6d9c745cf4c64ab8e323b21b5c76b251af72 --- /dev/null +++ b/MultiGradICON/baselines.py @@ -0,0 +1,206 @@ +# Copyright (c) 2025 Valentin Boussot +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +# +# SPDX-License-Identifier: Apache-2.0 + +"""What every baseline app shares (a copy of the repository's baselines.py, kept by build.py): the authors' code fetched at its pin, the graph module that hands a pair to an +engine and gets a displacement field back, and the field's convention. + +The field is the benchmark's: one component per spatial axis, in mm along the world (ITK, LPS) axes, on the fixed +image's grid, such that the fixed point ``x`` matches ``x + u(x)`` in the moving image. The predictor attaches the +fixed image's geometry to the output (``same_as_group: Volume_0:Fixed`` in the app's ``Prediction.yml``). + +NOTE: do NOT add ``from __future__ import annotations``: KonfAI's config engine relies on runtime-evaluated +annotations (``get_origin``); PEP 563 stringized annotations break binding. +""" + +import hashlib +import os +import shutil +import subprocess # nosec B404 +import urllib.request +import zipfile +from collections.abc import Callable +from pathlib import Path + +import numpy as np +import SimpleITK as sitk +import torch +from konfai.network import network +from konfai.utils.dataset import Attribute, data_to_image + +#: An engine: (fixed, moving, fixed mask or None, moving mask or None, CUDA device index or -1) -> the field, +#: ``[D, *spatial]`` in mm along the world axes on the fixed grid. +Engine = Callable[[sitk.Image, sitk.Image, sitk.Image | None, sitk.Image | None, int], np.ndarray] + + +def cache_dir() -> Path: + """Where the authors' code and binaries live, once fetched: ``$BASELINES_KONFAI_CACHE`` or + ``~/.cache/baselines-konfai``.""" + return Path(os.environ.get("BASELINES_KONFAI_CACHE", Path.home() / ".cache" / "baselines-konfai")) + + +def pinned_source(name: str, url: str, commit: str) -> Path: + """The authors' repository at ``commit``, cloned once into the cache: a baseline runs the code it was + measured with, never a moving branch.""" + target = cache_dir() / f"{name}-{commit[:12]}" + if not (target / ".git").exists(): + target.parent.mkdir(parents=True, exist_ok=True) + subprocess.run(["git", "clone", "--quiet", url, str(target)], check=True) # nosec B603 B607 + subprocess.run(["git", "-C", str(target), "checkout", "--quiet", commit], check=True) # nosec B603 B607 + return target + + +def fetch(url: str, target: Path, sha256: str | None = None) -> Path: + """``url`` downloaded once to ``target`` and, when a hash is given, checked against it.""" + if not target.exists(): + target.parent.mkdir(parents=True, exist_ok=True) + part = target.with_name(target.name + ".part") + urllib.request.urlretrieve(url, part) # nosec B310 - the authors' release, checked below + with part.open("rb") as stream: + digest = hashlib.file_digest(stream, "sha256").hexdigest() + if sha256 and digest != sha256: + part.unlink() + raise RuntimeError(f"{url} does not match its recorded hash") + part.rename(target) + return target + + +def pinned_archive(name: str, url: str, sha256: str) -> Path: + """A release archive at ``url``, downloaded once into the cache, checked against ``sha256`` and unpacked: the + binaries a baseline was measured with.""" + target = cache_dir() / f"{name}-{sha256[:12]}" + if not (target / ".unpacked").exists(): + archive = fetch(url, target / "archive", sha256) + if zipfile.is_zipfile(archive): + with zipfile.ZipFile(archive) as packed: + packed.extractall(target) # nosec B202 - our own pinned archive + for entry in packed.infolist(): # zipfile drops the modes: the binaries must stay executable + if mode := (entry.external_attr >> 16) & 0o777: + (target / entry.filename).chmod(mode) + else: + shutil.unpack_archive(str(archive), str(target), "gztar") + archive.unlink() + (target / ".unpacked").touch() + return target + + +def pinned_environment(root: Path, python: str, installs: list[list[str]]) -> Path: + """A virtual environment at ``root/venv`` on its own Python, made once by uv (``pip install uv``): for the tools + whose pins do not run on the host's Python. ``installs`` are ``pip install`` argument lists, run in order.""" + try: + import uv + + command = uv.find_uv_bin() + except ImportError: + command = shutil.which("uv") or "" + if not command: + raise RuntimeError("this baseline builds its own Python environment with uv: pip install uv") + venv = root / "venv" + if not (venv / ".ready").exists(): + subprocess.run([command, "venv", "--quiet", "--clear", "--python", python, str(venv)], check=True) # nosec B603 + for arguments in installs: + subprocess.run( # nosec B603 + [ + command, + "pip", + "install", + "--quiet", + "--no-cache", + "--python", + str(venv / "bin" / "python"), + *arguments, + ], + check=True, + ) + (venv / ".ready").touch() + return venv + + +def built_source(name: str, url: str, commit: str, build: Callable[[Path], None]) -> Path: + """The authors' repository at ``commit``, built once by ``build`` (a marker says it is done).""" + source = pinned_source(name, url, commit) + if not (source / ".built").exists(): + build(source) + (source / ".built").touch() + return source + + +def field_from_voxels(displacement: np.ndarray, fixed: sitk.Image) -> np.ndarray: + """A displacement in voxels along the index axes, ``[i, j, k, D]``, as the benchmark's field ``[D, k, j, i]`` + in mm along the world axes: ``u = D S d``, with ``D`` the direction and ``S`` the spacing of the fixed image.""" + n = fixed.GetDimension() + to_world = np.array(fixed.GetDirection()).reshape(n, n) @ np.diag(fixed.GetSpacing()) + world = displacement.astype(np.float64) @ to_world.T # [i, j, k, D] + return np.ascontiguousarray(np.moveaxis(world, -1, 0).transpose(0, *reversed(range(1, n + 1))), dtype=np.float32) + + +def to_index_array(image: sitk.Image) -> np.ndarray: + """The image as a ``[i, j, k]`` array, the index axes in ITK's order, which the tools indexed that way read.""" + return np.ascontiguousarray(sitk.GetArrayFromImage(image).transpose(*reversed(range(image.GetDimension())))) + + +class Registration(torch.nn.Module): + """Graph module: the pair's tensors and their geometry in, the field out, through the engine, one sample at + a time. ``accepts_attributes = True`` opts it into the per-branch ``Attribute`` list (the convention of + ``CriterionWithAttribute``): registration needs the physical geometry.""" + + accepts_attributes = True + + def __init__(self, engine: Engine) -> None: + super().__init__() + self._engine = engine + + def forward( + self, + fixed: torch.Tensor, + moving: torch.Tensor, + fixed_mask: torch.Tensor, + moving_mask: torch.Tensor, + attributes: list[list[Attribute]], + ) -> torch.Tensor: + fixed_attrs, moving_attrs, fixed_mask_attrs, moving_mask_attrs = attributes + device_index = fixed.device.index if fixed.device.type == "cuda" else -1 + fields = [] + # the engines optimise with autograd; the predictor calls forward under inference mode + with torch.inference_mode(False), torch.enable_grad(): + for b in range(fixed.shape[0]): + images = [ + data_to_image(t[b].detach().cpu().numpy(), attrs[b]) + for t, attrs in ((fixed, fixed_attrs), (moving, moving_attrs)) + ] + masks = [ + data_to_image(t[b].detach().cpu().numpy(), attrs[b]) if not bool((t[b] == 1).all()) else None + for t, attrs in ((fixed_mask, fixed_mask_attrs), (moving_mask, moving_mask_attrs)) + ] + fields.append(torch.from_numpy(self._engine(images[0], images[1], masks[0], masks[1], device_index))) + return torch.stack(fields, dim=0).to(fixed.device) + + +class BaselineNet(network.Network): + """A baseline as an ``add_module`` graph: fixed = branch 0, moving = branch 1, the masks branches 2 and 3 (a + mask of ones means none). The one output is ``DisplacementField``, on the fixed grid.""" + + def __init__( + self, + engine: Engine, + dim: int, + optimizer: network.OptimizerLoader, + schedulers: dict[str, network.LRSchedulersLoader], + outputs_criterions: dict[str, network.TargetCriterionsLoader], + ) -> None: + super().__init__( + in_channels=1, optimizer=optimizer, schedulers=schedulers, outputs_criterions=outputs_criterions, dim=dim + ) + self.add_module("DisplacementField", Registration(engine), in_branch=[0, 1, 2, 3], out_branch=["dvf"]) diff --git a/MultiGradICON/model.py b/MultiGradICON/model.py new file mode 100644 index 0000000000000000000000000000000000000000..96ee77e1e351e1043713c6adc518062796416047 --- /dev/null +++ b/MultiGradICON/model.py @@ -0,0 +1,194 @@ +# Copyright (c) 2025 Valentin Boussot +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +# +# SPDX-License-Identifier: Apache-2.0 + +"""uniGradICON and multiGradICON through the authors' command, ``unigradicon-register`` (the ``unigradicon`` +package at a pinned version), with its defaults: the network's prediction, then 50 steps of instance optimisation +on LNCC; the weights fetched from the authors' release and checked against their hash. The authors' lung protocol +(``masks``) multiplies each image by its mask, as their Learn2Reg submissions did. + +NOTE: do NOT add ``from __future__ import annotations``: KonfAI's config engine relies on runtime-evaluated +annotations (``get_origin``); PEP 563 stringized annotations break binding. +""" + +import hashlib +import os +import shutil +import subprocess # nosec B404 +import tempfile +import urllib.request +from pathlib import Path +from typing import Annotated + +import numpy as np +import SimpleITK as sitk +from konfai.network import network +from konfai.utils.config import Choices + +from baselines import BaselineNet, cache_dir + +VERSION = "1.0.5" # the unigradicon package; the bundle's requirements pin it +WEIGHTS = { # the authors' release, sha256 of each file + "unigradicon": ( + "https://github.com/uncbiag/uniGradICON/releases/download/unigradicon_weights/Step_2_final.trch", + "1fcfa02214540915cad7b768570add2b4247c22c516d75a21e0e8258f50254a6", + ), + "multigradicon": ( + "https://github.com/uncbiag/uniGradICON/releases/download/multigradicon_weights/Step_2_final.trch", + "c37a7cf5c0576f24b03418f3f659eedde9aaf6b9c1e42469d3fe3eacbb901e01", + ), +} + + +def weights_dir(model: str) -> Path: + """Where the command finds ``network_weights/1.0/Step_2_final.trch``: it reads them relative to its + working directory, so the engine runs it from here.""" + root = cache_dir() / "unigradicon" + target = root / "network_weights" / f"{model}1.0" / "Step_2_final.trch" + url, digest = WEIGHTS[model] + if not target.exists() or hashlib.sha256(target.read_bytes()).hexdigest() != digest: + target.parent.mkdir(parents=True, exist_ok=True) + urllib.request.urlretrieve(url, target) # nosec B310 - the authors' release, checked below + if hashlib.sha256(target.read_bytes()).hexdigest() != digest: + raise RuntimeError(f"the {model} weights do not match their published hash") + return root + + +def modality_of(image: sitk.Image, declared: str) -> str: + """The command's modality: ``ct`` (clamped to [-1000, 1000] HU) or ``mri`` (minimum to the 99th percentile). + ``auto`` reads it off the intensities: Hounsfield units go below -200.""" + if declared in ("ct", "mri"): + return declared + return "ct" if float(sitk.GetArrayViewFromImage(image).min()) < -200 else "mri" + + +def _on_grid(mask: sitk.Image, image: sitk.Image) -> sitk.Image: + """The mask on its image's grid: the command multiplies the two and refuses the slightest header difference.""" + if mask.GetSize() == image.GetSize(): + mask.CopyInformation(image) + return mask + return sitk.Resample(mask, image, sitk.Transform(), sitk.sitkNearestNeighbor, 0) + + +class GradICON: + def __init__( + self, model: str, masks: bool, fixed_modality: str, moving_modality: str, iterations: int, similarity: str + ) -> None: + self._model, self._masks = model, masks + self._modalities = (fixed_modality, moving_modality) + self._iterations, self._similarity = iterations, similarity + + def __call__( + self, + fixed: sitk.Image, + moving: sitk.Image, + fixed_mask: sitk.Image | None, + moving_mask: sitk.Image | None, + device: int, + ) -> np.ndarray: + command = os.environ.get("UNIGRADICON_REGISTER") or shutil.which("unigradicon-register") + if not command: + raise RuntimeError(f"unigradicon-register was not found: pip install unigradicon=={VERSION}") + with tempfile.TemporaryDirectory(prefix="gradicon_") as scratch: + work = Path(scratch) + sitk.WriteImage(fixed, str(work / "fixed.nii.gz")) + sitk.WriteImage(moving, str(work / "moving.nii.gz")) + arguments = [ + command, + "--fixed", + str(work / "fixed.nii.gz"), + "--fixed_modality", + modality_of(fixed, self._modalities[0]), + "--moving", + str(work / "moving.nii.gz"), + "--moving_modality", + modality_of(moving, self._modalities[1]), + "--transform_out", + str(work / "transform.hdf5"), + "--model", + self._model, + "--io_iterations", + str(self._iterations), + "--io_sim", + self._similarity, + ] + if self._masks: + if fixed_mask is None or moving_mask is None: + raise ValueError("the lung protocol needs the fixed and the moving mask") + sitk.WriteImage(_on_grid(fixed_mask, fixed), str(work / "fixed_mask.nii.gz")) + sitk.WriteImage(_on_grid(moving_mask, moving), str(work / "moving_mask.nii.gz")) + arguments += [ + "--fixed_segmentation", + str(work / "fixed_mask.nii.gz"), + "--moving_segmentation", + str(work / "moving_mask.nii.gz"), + ] + environment = {**os.environ, "CUDA_VISIBLE_DEVICES": str(device) if device >= 0 else ""} + subprocess.run(arguments, check=True, cwd=weights_dir(self._model), env=environment) # nosec B603 + transform = sitk.ReadTransform(str(work / "transform.hdf5")) + # the command's transform maps a fixed point to its moving point: sampled on the fixed grid it is the field + field = sitk.TransformToDisplacementField( + transform, + sitk.sitkVectorFloat64, + fixed.GetSize(), + fixed.GetOrigin(), + fixed.GetSpacing(), + fixed.GetDirection(), + ) + return np.ascontiguousarray(np.moveaxis(sitk.GetArrayFromImage(field), -1, 0), dtype=np.float32) + + +class RegistrationNet(BaselineNet): + """uniGradICON or multiGradICON as the authors' command runs them.""" + + def __init__( + self, + optimizer: network.OptimizerLoader = network.OptimizerLoader(), + schedulers: dict[str, network.LRSchedulersLoader] = { + "default:ReduceLROnPlateau": network.LRSchedulersLoader(0) + }, + outputs_criterions: dict[str, network.TargetCriterionsLoader] = {"default": network.TargetCriterionsLoader()}, + model: Annotated[ + str, Choices(["unigradicon", "multigradicon"]), "The network: uniGradICON or multiGradICON." + ] = "unigradicon", + masks: Annotated[ + bool, "The authors' lung protocol: each image multiplied by its mask before registration." + ] = False, + fixed_modality: Annotated[ + str, + Choices(["auto", "ct", "mri"]), + "The command's modality of the fixed image; auto reads it off the intensities.", + ] = "auto", + moving_modality: Annotated[ + str, + Choices(["auto", "ct", "mri"]), + "The command's modality of the moving image; auto reads it off the intensities.", + ] = "auto", + iterations: Annotated[ + int, "Steps of instance optimisation after the network's prediction (the command's default)." + ] = 50, + similarity: Annotated[ + str, + Choices(["lncc", "lncc2", "mind"]), + "The similarity of the instance optimisation (the command's default).", + ] = "lncc", + ) -> None: + super().__init__( + GradICON(model, masks, fixed_modality, moving_modality, iterations, similarity), + 3, + optimizer, + schedulers, + outputs_criterions, + ) diff --git a/MultiGradICON/requirements.txt b/MultiGradICON/requirements.txt new file mode 100644 index 0000000000000000000000000000000000000000..0d8852d2fa98d5111eb80c6938ad904eb87d133b --- /dev/null +++ b/MultiGradICON/requirements.txt @@ -0,0 +1,4 @@ +SimpleITK +unigradicon==1.0.5 +icon_registration==1.1.8 +itk==6.0b2 diff --git a/NiftyReg/Prediction.yml b/NiftyReg/Prediction.yml new file mode 100644 index 0000000000000000000000000000000000000000..80d50c7b7737493003ed6534bf1cb62c3c9f7873 --- /dev/null +++ b/NiftyReg/Prediction.yml @@ -0,0 +1,86 @@ +Predictor: + Model: + classpath: model:RegistrationNet + RegistrationNet: + arguments: [] + threads: 0 + outputs_criterions: None + Dataset: + groups_src: + Volume_0: + groups_dest: + Fixed: + transforms: + TensorCast: + dtype: float32 + inverse: false + patch_transforms: None + is_input: true + Volume_1: + groups_dest: + Moving: + transforms: + TensorCast: + dtype: float32 + inverse: false + patch_transforms: None + is_input: true + Volume_2: + groups_dest: + FixedMask: + transforms: + TensorCast: + dtype: float32 + inverse: false + patch_transforms: None + is_input: true + Volume_3: + groups_dest: + MovingMask: + transforms: + TensorCast: + dtype: float32 + inverse: false + patch_transforms: None + is_input: true + augmentations: None + Patch: + patch_size: + - 0 + - 0 + - 0 + overlap: 0 + pad_value: None + extend_slice: 0 + mode: resample + max_voxels: None + subset: None + dataset_filenames: + - ./Dataset/:mha + batch_size: 1 + num_workers: None + pin_memory: false + prefetch_factor: None + persistent_workers: None + outputs_dataset: + DisplacementField: + OutputDataset: + name_class: OutputDataset + before_reduction_transforms: None + after_reduction_transforms: None + final_transforms: + TensorCast: + dtype: float32 + inverse: false + dataset_filename: DisplacementField:mha + group: DisplacementField + same_as_group: Volume_0:Fixed + patch_combine: Cosinus + reduction: Mean + Mean: {} + train_name: Baselines-NiftyReg + manual_seed: 42 + gpu_checkpoints: None + combine: Mean + autocast: false + data_log: None diff --git a/NiftyReg/app.json b/NiftyReg/app.json new file mode 100644 index 0000000000000000000000000000000000000000..1389cc8164543158d09ade0e9f45ab9834cbc410 --- /dev/null +++ b/NiftyReg/app.json @@ -0,0 +1,40 @@ +{ + "display_name": "NiftyReg", + "short_description": "reg_f3d with its defaults: cubic B-spline with control points every 5 voxels, NMI with 64 bins, bending energy 0.001, first-order penalty 0.01, no Jacobian penalty, 3 levels; NiftyReg v2.0.0 built from the authors' repository on first use (cmake and a C++ compiler needed). The ImagingBenchmarks baseline niftyreg. CPU.", + "description": "reg_f3d with its defaults: cubic B-spline with control points every 5 voxels, NMI with 64 bins, bending energy 0.001, first-order penalty 0.01, no Jacobian penalty, 3 levels; NiftyReg v2.0.0 built from the authors' repository on first use (cmake and a C++ compiler needed). The ImagingBenchmarks baseline niftyreg. CPU. The pair must be aligned (rigidly for one patient, by an affine transform between two subjects): only the deformable stage runs. Masks are ignored by this baseline. Output: the displacement field on the fixed grid, in mm along the world axes (ITK, LPS).", + "task": "registration", + "tta": 0, + "mc_dropout": 0, + "models": [], + "inputs": { + "Fixed": { + "display_name": "Fixed image", + "volume_type": "VOLUME", + "required": true + }, + "Moving": { + "display_name": "Moving image", + "volume_type": "VOLUME", + "required": true + }, + "FixedMask": { + "display_name": "Fixed mask (ignored by this baseline)", + "volume_type": "SEGMENTATION", + "required": false, + "default": "ones" + }, + "MovingMask": { + "display_name": "Moving mask (ignored by this baseline)", + "volume_type": "SEGMENTATION", + "required": false, + "default": "ones" + } + }, + "outputs": { + "DisplacementField": { + "display_name": "Displacement field", + "volume_type": "VOLUME", + "required": true + } + } +} diff --git a/NiftyReg/baselines.py b/NiftyReg/baselines.py new file mode 100644 index 0000000000000000000000000000000000000000..691b6d9c745cf4c64ab8e323b21b5c76b251af72 --- /dev/null +++ b/NiftyReg/baselines.py @@ -0,0 +1,206 @@ +# Copyright (c) 2025 Valentin Boussot +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +# +# SPDX-License-Identifier: Apache-2.0 + +"""What every baseline app shares (a copy of the repository's baselines.py, kept by build.py): the authors' code fetched at its pin, the graph module that hands a pair to an +engine and gets a displacement field back, and the field's convention. + +The field is the benchmark's: one component per spatial axis, in mm along the world (ITK, LPS) axes, on the fixed +image's grid, such that the fixed point ``x`` matches ``x + u(x)`` in the moving image. The predictor attaches the +fixed image's geometry to the output (``same_as_group: Volume_0:Fixed`` in the app's ``Prediction.yml``). + +NOTE: do NOT add ``from __future__ import annotations``: KonfAI's config engine relies on runtime-evaluated +annotations (``get_origin``); PEP 563 stringized annotations break binding. +""" + +import hashlib +import os +import shutil +import subprocess # nosec B404 +import urllib.request +import zipfile +from collections.abc import Callable +from pathlib import Path + +import numpy as np +import SimpleITK as sitk +import torch +from konfai.network import network +from konfai.utils.dataset import Attribute, data_to_image + +#: An engine: (fixed, moving, fixed mask or None, moving mask or None, CUDA device index or -1) -> the field, +#: ``[D, *spatial]`` in mm along the world axes on the fixed grid. +Engine = Callable[[sitk.Image, sitk.Image, sitk.Image | None, sitk.Image | None, int], np.ndarray] + + +def cache_dir() -> Path: + """Where the authors' code and binaries live, once fetched: ``$BASELINES_KONFAI_CACHE`` or + ``~/.cache/baselines-konfai``.""" + return Path(os.environ.get("BASELINES_KONFAI_CACHE", Path.home() / ".cache" / "baselines-konfai")) + + +def pinned_source(name: str, url: str, commit: str) -> Path: + """The authors' repository at ``commit``, cloned once into the cache: a baseline runs the code it was + measured with, never a moving branch.""" + target = cache_dir() / f"{name}-{commit[:12]}" + if not (target / ".git").exists(): + target.parent.mkdir(parents=True, exist_ok=True) + subprocess.run(["git", "clone", "--quiet", url, str(target)], check=True) # nosec B603 B607 + subprocess.run(["git", "-C", str(target), "checkout", "--quiet", commit], check=True) # nosec B603 B607 + return target + + +def fetch(url: str, target: Path, sha256: str | None = None) -> Path: + """``url`` downloaded once to ``target`` and, when a hash is given, checked against it.""" + if not target.exists(): + target.parent.mkdir(parents=True, exist_ok=True) + part = target.with_name(target.name + ".part") + urllib.request.urlretrieve(url, part) # nosec B310 - the authors' release, checked below + with part.open("rb") as stream: + digest = hashlib.file_digest(stream, "sha256").hexdigest() + if sha256 and digest != sha256: + part.unlink() + raise RuntimeError(f"{url} does not match its recorded hash") + part.rename(target) + return target + + +def pinned_archive(name: str, url: str, sha256: str) -> Path: + """A release archive at ``url``, downloaded once into the cache, checked against ``sha256`` and unpacked: the + binaries a baseline was measured with.""" + target = cache_dir() / f"{name}-{sha256[:12]}" + if not (target / ".unpacked").exists(): + archive = fetch(url, target / "archive", sha256) + if zipfile.is_zipfile(archive): + with zipfile.ZipFile(archive) as packed: + packed.extractall(target) # nosec B202 - our own pinned archive + for entry in packed.infolist(): # zipfile drops the modes: the binaries must stay executable + if mode := (entry.external_attr >> 16) & 0o777: + (target / entry.filename).chmod(mode) + else: + shutil.unpack_archive(str(archive), str(target), "gztar") + archive.unlink() + (target / ".unpacked").touch() + return target + + +def pinned_environment(root: Path, python: str, installs: list[list[str]]) -> Path: + """A virtual environment at ``root/venv`` on its own Python, made once by uv (``pip install uv``): for the tools + whose pins do not run on the host's Python. ``installs`` are ``pip install`` argument lists, run in order.""" + try: + import uv + + command = uv.find_uv_bin() + except ImportError: + command = shutil.which("uv") or "" + if not command: + raise RuntimeError("this baseline builds its own Python environment with uv: pip install uv") + venv = root / "venv" + if not (venv / ".ready").exists(): + subprocess.run([command, "venv", "--quiet", "--clear", "--python", python, str(venv)], check=True) # nosec B603 + for arguments in installs: + subprocess.run( # nosec B603 + [ + command, + "pip", + "install", + "--quiet", + "--no-cache", + "--python", + str(venv / "bin" / "python"), + *arguments, + ], + check=True, + ) + (venv / ".ready").touch() + return venv + + +def built_source(name: str, url: str, commit: str, build: Callable[[Path], None]) -> Path: + """The authors' repository at ``commit``, built once by ``build`` (a marker says it is done).""" + source = pinned_source(name, url, commit) + if not (source / ".built").exists(): + build(source) + (source / ".built").touch() + return source + + +def field_from_voxels(displacement: np.ndarray, fixed: sitk.Image) -> np.ndarray: + """A displacement in voxels along the index axes, ``[i, j, k, D]``, as the benchmark's field ``[D, k, j, i]`` + in mm along the world axes: ``u = D S d``, with ``D`` the direction and ``S`` the spacing of the fixed image.""" + n = fixed.GetDimension() + to_world = np.array(fixed.GetDirection()).reshape(n, n) @ np.diag(fixed.GetSpacing()) + world = displacement.astype(np.float64) @ to_world.T # [i, j, k, D] + return np.ascontiguousarray(np.moveaxis(world, -1, 0).transpose(0, *reversed(range(1, n + 1))), dtype=np.float32) + + +def to_index_array(image: sitk.Image) -> np.ndarray: + """The image as a ``[i, j, k]`` array, the index axes in ITK's order, which the tools indexed that way read.""" + return np.ascontiguousarray(sitk.GetArrayFromImage(image).transpose(*reversed(range(image.GetDimension())))) + + +class Registration(torch.nn.Module): + """Graph module: the pair's tensors and their geometry in, the field out, through the engine, one sample at + a time. ``accepts_attributes = True`` opts it into the per-branch ``Attribute`` list (the convention of + ``CriterionWithAttribute``): registration needs the physical geometry.""" + + accepts_attributes = True + + def __init__(self, engine: Engine) -> None: + super().__init__() + self._engine = engine + + def forward( + self, + fixed: torch.Tensor, + moving: torch.Tensor, + fixed_mask: torch.Tensor, + moving_mask: torch.Tensor, + attributes: list[list[Attribute]], + ) -> torch.Tensor: + fixed_attrs, moving_attrs, fixed_mask_attrs, moving_mask_attrs = attributes + device_index = fixed.device.index if fixed.device.type == "cuda" else -1 + fields = [] + # the engines optimise with autograd; the predictor calls forward under inference mode + with torch.inference_mode(False), torch.enable_grad(): + for b in range(fixed.shape[0]): + images = [ + data_to_image(t[b].detach().cpu().numpy(), attrs[b]) + for t, attrs in ((fixed, fixed_attrs), (moving, moving_attrs)) + ] + masks = [ + data_to_image(t[b].detach().cpu().numpy(), attrs[b]) if not bool((t[b] == 1).all()) else None + for t, attrs in ((fixed_mask, fixed_mask_attrs), (moving_mask, moving_mask_attrs)) + ] + fields.append(torch.from_numpy(self._engine(images[0], images[1], masks[0], masks[1], device_index))) + return torch.stack(fields, dim=0).to(fixed.device) + + +class BaselineNet(network.Network): + """A baseline as an ``add_module`` graph: fixed = branch 0, moving = branch 1, the masks branches 2 and 3 (a + mask of ones means none). The one output is ``DisplacementField``, on the fixed grid.""" + + def __init__( + self, + engine: Engine, + dim: int, + optimizer: network.OptimizerLoader, + schedulers: dict[str, network.LRSchedulersLoader], + outputs_criterions: dict[str, network.TargetCriterionsLoader], + ) -> None: + super().__init__( + in_channels=1, optimizer=optimizer, schedulers=schedulers, outputs_criterions=outputs_criterions, dim=dim + ) + self.add_module("DisplacementField", Registration(engine), in_branch=[0, 1, 2, 3], out_branch=["dvf"]) diff --git a/NiftyReg/model.py b/NiftyReg/model.py new file mode 100644 index 0000000000000000000000000000000000000000..188eaed393d46c677144f259f8c3cd93ae93afb7 --- /dev/null +++ b/NiftyReg/model.py @@ -0,0 +1,129 @@ +# Copyright (c) 2025 Valentin Boussot +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +# +# SPDX-License-Identifier: Apache-2.0 + +"""NiftyReg's ``reg_f3d`` with its defaults (cubic B-spline with control points every 5 voxels, normalised mutual +information with 64 bins, bending energy 0.001, first-order penalty 0.01, no Jacobian penalty, 3 levels), built from +the authors' repository at a pinned commit (CPU build) on first use; ``reg_transform`` turns the control points into +a displacement field, whose RAS axes are brought to ITK's LPS. + +NOTE: do NOT add ``from __future__ import annotations``: KonfAI's config engine relies on runtime-evaluated +annotations (``get_origin``); PEP 563 stringized annotations break binding. +""" + +import subprocess # nosec B404 +import tempfile +from pathlib import Path +from typing import Annotated + +import numpy as np +import SimpleITK as sitk +from konfai.network import network + +from baselines import BaselineNet, built_source + +REPOSITORY = "https://github.com/KCL-BMEIS/niftyreg" +COMMIT = "ee6a92d71263a4b1eb29b829fdeb3961d26d8a13" # v2.0.0, 2025-11-21 + + +def _build(source: Path) -> None: + """cmake, CPU only, into ``install/`` next to the sources: what the benchmark's setup.sh does.""" + build, install = source.parent / f"{source.name}-build", source / "install" + subprocess.run( + [ + "cmake", + "-S", + str(source), + "-B", + str(build), + "-DCMAKE_BUILD_TYPE=Release", # nosec B603 B607 + f"-DCMAKE_INSTALL_PREFIX={install}", + "-DUSE_CUDA=OFF", + "-DUSE_OPENCL=OFF", + "-DCHECK_GPU=OFF", + ], + check=True, + ) + subprocess.run(["cmake", "--build", str(build), "-j", "8", "--target", "install"], check=True) # nosec B603 B607 + + +class NiftyReg: + def __init__(self, arguments: list[str], threads: int) -> None: + self._arguments, self._threads = arguments, threads + + def __call__( + self, + fixed: sitk.Image, + moving: sitk.Image, + fixed_mask: sitk.Image | None, + moving_mask: sitk.Image | None, + device: int, + ) -> np.ndarray: + binaries = built_source("niftyreg", REPOSITORY, COMMIT, _build) / "install" / "bin" + fixed, moving = sitk.Cast(fixed, sitk.sitkFloat32), sitk.Cast(moving, sitk.sitkFloat32) + with tempfile.TemporaryDirectory(prefix="niftyreg_") as scratch: + work = Path(scratch) + ref, flo = work / "fixed.nii.gz", work / "moving.nii.gz" # NiftyReg reads NIfTI only + sitk.WriteImage(fixed, str(ref)) + sitk.WriteImage(moving, str(flo)) + threads = ["-omp", str(self._threads)] if self._threads else [] + subprocess.run( + [ + str(binaries / "reg_f3d"), + "-ref", + str(ref), + "-flo", + str(flo), + "-cpp", + str(work / "cpp.nii.gz"), # nosec B603 + "-res", + str(work / "moved.nii.gz"), + *threads, + *self._arguments, + ], + check=True, + ) + subprocess.run( + [ + str(binaries / "reg_transform"), + "-ref", + str(ref), + "-disp", + str(work / "cpp.nii.gz"), + str(work / "disp.nii.gz"), + ], + check=True, + ) # nosec B603 + displacement = sitk.GetArrayFromImage(sitk.ReadImage(str(work / "disp.nii.gz"), sitk.sitkVectorFloat32)) + if not np.isfinite(displacement).all(): + raise ValueError("NiftyReg returned a non-finite displacement") + # NiftyReg writes the displacement along the NIfTI (RAS) axes: to ITK's LPS + return np.ascontiguousarray(np.moveaxis(displacement * np.float32([-1, -1, 1]), -1, 0), dtype=np.float32) + + +class RegistrationNet(BaselineNet): + """NiftyReg reg_f3d, defaults. CPU.""" + + def __init__( + self, + optimizer: network.OptimizerLoader = network.OptimizerLoader(), + schedulers: dict[str, network.LRSchedulersLoader] = { + "default:ReduceLROnPlateau": network.LRSchedulersLoader(0) + }, + outputs_criterions: dict[str, network.TargetCriterionsLoader] = {"default": network.TargetCriterionsLoader()}, + arguments: Annotated[list[str], "Extra reg_f3d arguments; none for the defaults."] = [], + threads: Annotated[int, "OpenMP threads (-omp); 0 leaves NiftyReg's default."] = 0, + ) -> None: + super().__init__(NiftyReg(list(arguments), threads), 3, optimizer, schedulers, outputs_criterions) diff --git a/NiftyReg/requirements.txt b/NiftyReg/requirements.txt new file mode 100644 index 0000000000000000000000000000000000000000..7f5e98e3f968b22748bf799bc7f38e5b2fe45da3 --- /dev/null +++ b/NiftyReg/requirements.txt @@ -0,0 +1 @@ +SimpleITK diff --git a/README.md b/README.md index 39d66670bc1b584801c47035337aad94d9fe02f5..e0c18b028dfda71a2aabb8885da849f3ad8ea09e 100644 --- a/README.md +++ b/README.md @@ -56,6 +56,35 @@ impact-reg-konfai register ConvexAdam_Composite -f fixed.nii.gz -m moving.nii.gz > > The `FireANTs_*` presets depend on [`fireants`](https://pypi.org/project/fireants/) (installed at resolve time; **GPU required**). FireANTs is distributed under the **FireANTs License v1.0** — this app calls its public API without copying its source, and ships its license and citation in each preset's `NOTICE`; please cite FireANTs if you use them. `FireANTs_IMPACT` and `FireANTs_Anatomix` additionally drive the deformable stage with the KonfAI **IMPACT** metric, fetching their feature models from `VBoussot/impact-torchscript-models`. +## 📏 Baselines + +The registration baselines of [ImagingBenchmarks](https://github.com/fideus-labs/ImagingBenchmarks) live here too, +next to the presets: each one runs its authors' code at a pinned version, fetched on first use, with the benchmark's +settings in its `Prediction.yml`, and was checked against the benchmark's own line before it was published. Each app folder carries its code +(`model.py`, with `baselines.py` for what the apps share, copied by `build.py`). + +```bash +pip install konfai-apps +konfai-apps infer VBoussot/ImpactReg:ANTs_SyN -i fixed.nii.gz -i moving.nii.gz -o out +``` + +| App | Runs | Pair | Device | +|:--|:--|:--|:--| +| `ANTs_SyN` | ANTs 2.6.5 SyN, the LUMIR organisers' call | any | CPU | +| `NiftyReg` | `reg_f3d`, defaults | any | CPU | +| `Deeds` | `deedsBCV`, defaults | any | CPU | +| `Greedy` | greedy, NCC 2x2x2, 100x50x10 | one modality | CPU | +| `Demons` | ITK fast symmetric forces Demons, SimpleITK's notebook | one modality | CPU | +| `CorrField` | corrField of Lung250M-4B, 1 mm grid | lungs | GPU | +| `ConvexAdam_MIND` | ConvexAdam on MIND-SSC, defaults | any | GPU | +| `UniGradICON`, `MultiGradICON` | uniGradICON / multiGradICON, 50 steps of instance optimisation (`--set masks=true`: the authors' lung protocol) | any | GPU | +| `Anatomix_ConvexAdam` | ConvexAdam on anatomix and MIND features | any | GPU | +| `SynthMorph` | FreeSurfer's `mri_synthmorph`, deformable model | brain MR | GPU up to Ada, else CPU | +| `BrainMorph` | BrainMorph, 512 keypoints, H model, thin-plate splines | brain MR | GPU up to Ada, else CPU | + +Every app takes a fixed and a moving image already aligned (the deformable stage alone runs) and writes the +displacement field on the fixed grid, in mm along the world axes (ITK, LPS). + ## ⚡ Performance & VRAM `ConvexAdam` presets (native, GPU) benchmarked on an **NVIDIA RTX PRO 5000 (24 GB)** with a real diff --git a/SynthMorph/Prediction.yml b/SynthMorph/Prediction.yml new file mode 100644 index 0000000000000000000000000000000000000000..c9297b0d4311dd9077e1565289dfff101adec8cd --- /dev/null +++ b/SynthMorph/Prediction.yml @@ -0,0 +1,89 @@ +Predictor: + Model: + classpath: model:RegistrationNet + RegistrationNet: + model: deform + regularisation: 0.5 + steps: 7 + extent: 256 + threads: 0 + outputs_criterions: None + Dataset: + groups_src: + Volume_0: + groups_dest: + Fixed: + transforms: + TensorCast: + dtype: float32 + inverse: false + patch_transforms: None + is_input: true + Volume_1: + groups_dest: + Moving: + transforms: + TensorCast: + dtype: float32 + inverse: false + patch_transforms: None + is_input: true + Volume_2: + groups_dest: + FixedMask: + transforms: + TensorCast: + dtype: float32 + inverse: false + patch_transforms: None + is_input: true + Volume_3: + groups_dest: + MovingMask: + transforms: + TensorCast: + dtype: float32 + inverse: false + patch_transforms: None + is_input: true + augmentations: None + Patch: + patch_size: + - 0 + - 0 + - 0 + overlap: 0 + pad_value: None + extend_slice: 0 + mode: resample + max_voxels: None + subset: None + dataset_filenames: + - ./Dataset/:mha + batch_size: 1 + num_workers: None + pin_memory: false + prefetch_factor: None + persistent_workers: None + outputs_dataset: + DisplacementField: + OutputDataset: + name_class: OutputDataset + before_reduction_transforms: None + after_reduction_transforms: None + final_transforms: + TensorCast: + dtype: float32 + inverse: false + dataset_filename: DisplacementField:mha + group: DisplacementField + same_as_group: Volume_0:Fixed + patch_combine: Cosinus + reduction: Mean + Mean: {} + train_name: Baselines-SynthMorph + manual_seed: 42 + gpu_checkpoints: None + combine: Mean + autocast: false + data_log: None diff --git a/SynthMorph/app.json b/SynthMorph/app.json new file mode 100644 index 0000000000000000000000000000000000000000..a5fae9fe12e3f287112bbd5b58b84af5db034a03 --- /dev/null +++ b/SynthMorph/app.json @@ -0,0 +1,40 @@ +{ + "display_name": "SynthMorph", + "short_description": "FreeSurfer's mri_synthmorph register with its defaults (regularisation 0.5, 7 integration steps, extent 256), the deformable model alone: a network trained on synthetic brain images of any contrast. The ImagingBenchmarks baseline synthmorph.", + "description": "FreeSurfer's mri_synthmorph register with its defaults (regularisation 0.5, 7 integration steps, extent 256), the deformable model alone: a network trained on synthetic brain images of any contrast. The ImagingBenchmarks baseline synthmorph. Brain MR, aligned pairs: the tool's help says the deformable model assumes prior affine alignment. What the official image freesurfer/synthmorph holds, without a container: the script and its package from FreeSurfer's repository at a pinned commit, the weights (3.5 GB) checked against their hash, and TensorFlow 2.17 on Python 3.12 in an environment uv builds on first use (7 GB). A GPU is recommended, up to the Ada generation: TensorFlow 2.17 has no kernels for Blackwell GPUs, so there the app runs on the CPU (no --gpu). Masks are ignored by this baseline. Output: the displacement field on the fixed grid, in mm along the world axes (ITK, LPS).

How to cite:
M. Hoffmann et al., Anatomy-aware and acquisition-agnostic joint registration with SynthMorph, Imaging Neuroscience 2024.", + "task": "registration", + "tta": 0, + "mc_dropout": 0, + "models": [], + "inputs": { + "Fixed": { + "display_name": "Fixed image", + "volume_type": "VOLUME", + "required": true + }, + "Moving": { + "display_name": "Moving image", + "volume_type": "VOLUME", + "required": true + }, + "FixedMask": { + "display_name": "Fixed mask (ignored by this baseline)", + "volume_type": "SEGMENTATION", + "required": false, + "default": "ones" + }, + "MovingMask": { + "display_name": "Moving mask (ignored by this baseline)", + "volume_type": "SEGMENTATION", + "required": false, + "default": "ones" + } + }, + "outputs": { + "DisplacementField": { + "display_name": "Displacement field", + "volume_type": "VOLUME", + "required": true + } + } +} diff --git a/SynthMorph/baselines.py b/SynthMorph/baselines.py new file mode 100644 index 0000000000000000000000000000000000000000..691b6d9c745cf4c64ab8e323b21b5c76b251af72 --- /dev/null +++ b/SynthMorph/baselines.py @@ -0,0 +1,206 @@ +# Copyright (c) 2025 Valentin Boussot +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +# +# SPDX-License-Identifier: Apache-2.0 + +"""What every baseline app shares (a copy of the repository's baselines.py, kept by build.py): the authors' code fetched at its pin, the graph module that hands a pair to an +engine and gets a displacement field back, and the field's convention. + +The field is the benchmark's: one component per spatial axis, in mm along the world (ITK, LPS) axes, on the fixed +image's grid, such that the fixed point ``x`` matches ``x + u(x)`` in the moving image. The predictor attaches the +fixed image's geometry to the output (``same_as_group: Volume_0:Fixed`` in the app's ``Prediction.yml``). + +NOTE: do NOT add ``from __future__ import annotations``: KonfAI's config engine relies on runtime-evaluated +annotations (``get_origin``); PEP 563 stringized annotations break binding. +""" + +import hashlib +import os +import shutil +import subprocess # nosec B404 +import urllib.request +import zipfile +from collections.abc import Callable +from pathlib import Path + +import numpy as np +import SimpleITK as sitk +import torch +from konfai.network import network +from konfai.utils.dataset import Attribute, data_to_image + +#: An engine: (fixed, moving, fixed mask or None, moving mask or None, CUDA device index or -1) -> the field, +#: ``[D, *spatial]`` in mm along the world axes on the fixed grid. +Engine = Callable[[sitk.Image, sitk.Image, sitk.Image | None, sitk.Image | None, int], np.ndarray] + + +def cache_dir() -> Path: + """Where the authors' code and binaries live, once fetched: ``$BASELINES_KONFAI_CACHE`` or + ``~/.cache/baselines-konfai``.""" + return Path(os.environ.get("BASELINES_KONFAI_CACHE", Path.home() / ".cache" / "baselines-konfai")) + + +def pinned_source(name: str, url: str, commit: str) -> Path: + """The authors' repository at ``commit``, cloned once into the cache: a baseline runs the code it was + measured with, never a moving branch.""" + target = cache_dir() / f"{name}-{commit[:12]}" + if not (target / ".git").exists(): + target.parent.mkdir(parents=True, exist_ok=True) + subprocess.run(["git", "clone", "--quiet", url, str(target)], check=True) # nosec B603 B607 + subprocess.run(["git", "-C", str(target), "checkout", "--quiet", commit], check=True) # nosec B603 B607 + return target + + +def fetch(url: str, target: Path, sha256: str | None = None) -> Path: + """``url`` downloaded once to ``target`` and, when a hash is given, checked against it.""" + if not target.exists(): + target.parent.mkdir(parents=True, exist_ok=True) + part = target.with_name(target.name + ".part") + urllib.request.urlretrieve(url, part) # nosec B310 - the authors' release, checked below + with part.open("rb") as stream: + digest = hashlib.file_digest(stream, "sha256").hexdigest() + if sha256 and digest != sha256: + part.unlink() + raise RuntimeError(f"{url} does not match its recorded hash") + part.rename(target) + return target + + +def pinned_archive(name: str, url: str, sha256: str) -> Path: + """A release archive at ``url``, downloaded once into the cache, checked against ``sha256`` and unpacked: the + binaries a baseline was measured with.""" + target = cache_dir() / f"{name}-{sha256[:12]}" + if not (target / ".unpacked").exists(): + archive = fetch(url, target / "archive", sha256) + if zipfile.is_zipfile(archive): + with zipfile.ZipFile(archive) as packed: + packed.extractall(target) # nosec B202 - our own pinned archive + for entry in packed.infolist(): # zipfile drops the modes: the binaries must stay executable + if mode := (entry.external_attr >> 16) & 0o777: + (target / entry.filename).chmod(mode) + else: + shutil.unpack_archive(str(archive), str(target), "gztar") + archive.unlink() + (target / ".unpacked").touch() + return target + + +def pinned_environment(root: Path, python: str, installs: list[list[str]]) -> Path: + """A virtual environment at ``root/venv`` on its own Python, made once by uv (``pip install uv``): for the tools + whose pins do not run on the host's Python. ``installs`` are ``pip install`` argument lists, run in order.""" + try: + import uv + + command = uv.find_uv_bin() + except ImportError: + command = shutil.which("uv") or "" + if not command: + raise RuntimeError("this baseline builds its own Python environment with uv: pip install uv") + venv = root / "venv" + if not (venv / ".ready").exists(): + subprocess.run([command, "venv", "--quiet", "--clear", "--python", python, str(venv)], check=True) # nosec B603 + for arguments in installs: + subprocess.run( # nosec B603 + [ + command, + "pip", + "install", + "--quiet", + "--no-cache", + "--python", + str(venv / "bin" / "python"), + *arguments, + ], + check=True, + ) + (venv / ".ready").touch() + return venv + + +def built_source(name: str, url: str, commit: str, build: Callable[[Path], None]) -> Path: + """The authors' repository at ``commit``, built once by ``build`` (a marker says it is done).""" + source = pinned_source(name, url, commit) + if not (source / ".built").exists(): + build(source) + (source / ".built").touch() + return source + + +def field_from_voxels(displacement: np.ndarray, fixed: sitk.Image) -> np.ndarray: + """A displacement in voxels along the index axes, ``[i, j, k, D]``, as the benchmark's field ``[D, k, j, i]`` + in mm along the world axes: ``u = D S d``, with ``D`` the direction and ``S`` the spacing of the fixed image.""" + n = fixed.GetDimension() + to_world = np.array(fixed.GetDirection()).reshape(n, n) @ np.diag(fixed.GetSpacing()) + world = displacement.astype(np.float64) @ to_world.T # [i, j, k, D] + return np.ascontiguousarray(np.moveaxis(world, -1, 0).transpose(0, *reversed(range(1, n + 1))), dtype=np.float32) + + +def to_index_array(image: sitk.Image) -> np.ndarray: + """The image as a ``[i, j, k]`` array, the index axes in ITK's order, which the tools indexed that way read.""" + return np.ascontiguousarray(sitk.GetArrayFromImage(image).transpose(*reversed(range(image.GetDimension())))) + + +class Registration(torch.nn.Module): + """Graph module: the pair's tensors and their geometry in, the field out, through the engine, one sample at + a time. ``accepts_attributes = True`` opts it into the per-branch ``Attribute`` list (the convention of + ``CriterionWithAttribute``): registration needs the physical geometry.""" + + accepts_attributes = True + + def __init__(self, engine: Engine) -> None: + super().__init__() + self._engine = engine + + def forward( + self, + fixed: torch.Tensor, + moving: torch.Tensor, + fixed_mask: torch.Tensor, + moving_mask: torch.Tensor, + attributes: list[list[Attribute]], + ) -> torch.Tensor: + fixed_attrs, moving_attrs, fixed_mask_attrs, moving_mask_attrs = attributes + device_index = fixed.device.index if fixed.device.type == "cuda" else -1 + fields = [] + # the engines optimise with autograd; the predictor calls forward under inference mode + with torch.inference_mode(False), torch.enable_grad(): + for b in range(fixed.shape[0]): + images = [ + data_to_image(t[b].detach().cpu().numpy(), attrs[b]) + for t, attrs in ((fixed, fixed_attrs), (moving, moving_attrs)) + ] + masks = [ + data_to_image(t[b].detach().cpu().numpy(), attrs[b]) if not bool((t[b] == 1).all()) else None + for t, attrs in ((fixed_mask, fixed_mask_attrs), (moving_mask, moving_mask_attrs)) + ] + fields.append(torch.from_numpy(self._engine(images[0], images[1], masks[0], masks[1], device_index))) + return torch.stack(fields, dim=0).to(fixed.device) + + +class BaselineNet(network.Network): + """A baseline as an ``add_module`` graph: fixed = branch 0, moving = branch 1, the masks branches 2 and 3 (a + mask of ones means none). The one output is ``DisplacementField``, on the fixed grid.""" + + def __init__( + self, + engine: Engine, + dim: int, + optimizer: network.OptimizerLoader, + schedulers: dict[str, network.LRSchedulersLoader], + outputs_criterions: dict[str, network.TargetCriterionsLoader], + ) -> None: + super().__init__( + in_channels=1, optimizer=optimizer, schedulers=schedulers, outputs_criterions=outputs_criterions, dim=dim + ) + self.add_module("DisplacementField", Registration(engine), in_branch=[0, 1, 2, 3], out_branch=["dvf"]) diff --git a/SynthMorph/model.py b/SynthMorph/model.py new file mode 100644 index 0000000000000000000000000000000000000000..b29a3c1b5e00f0953636518be62c82f266036e38 --- /dev/null +++ b/SynthMorph/model.py @@ -0,0 +1,162 @@ +# Copyright (c) 2025 Valentin Boussot +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +# +# SPDX-License-Identifier: Apache-2.0 + +"""SynthMorph (Hoffmann et al.): FreeSurfer's ``mri_synthmorph register`` at a pinned commit with its defaults +(regularisation 0.5, 7 integration steps, extent 256), the deformable model alone, since the tool's help says it +"assumes prior affine alignment". What the official image ``freesurfer/synthmorph`` holds, without a container: the +script and its package from FreeSurfer's repository, the weights from FreeSurfer's git-annex store checked against the +hash in their key, and the image's Python packages (TensorFlow 2.17 on Python 3.12) in an environment uv builds in the +cache on first use. Brain MR only. Masks and modalities are accepted and ignored: the tool takes neither. + +NOTE: do NOT add ``from __future__ import annotations``: KonfAI's config engine relies on runtime-evaluated +annotations (``get_origin``); PEP 563 stringized annotations break binding. +""" + +import os +import subprocess # nosec B404 +import tempfile +from pathlib import Path +from typing import Annotated + +import numpy as np +import SimpleITK as sitk +from konfai.network import network + +from baselines import BaselineNet, cache_dir, fetch, pinned_environment + +COMMIT = ( + "21b31bf1b58ac195567c7777b21228130e4326e1" # freesurfer/freesurfer dev, last change to mri_synthmorph (2026-02-23) +) +FILES = ("mri_synthmorph", "synthmorph/registration.py", "synthmorph/utils.py") +KEY = "SHA256E-s3508630424--95b367cd30788cc647e4704b650642fc1d70d7e419c20c04f1ba1b2902bc6536.3.h5" +WEIGHTS = ( + "synthmorph.deform.3.h5", + f"https://surfer.nmr.mgh.harvard.edu/pub/dist/freesurfer/repo/annex.git/annex/objects/682/3ad/{KEY}/{KEY}", + "95b367cd30788cc647e4704b650642fc1d70d7e419c20c04f1ba1b2902bc6536", +) +# mri_synthmorph/Dockerfile.gpu at that commit: its base image's TensorFlow, then its pinned commits +PACKAGES = [ + "tensorflow[and-cuda]==2.17.0", + "numpy==1.26.4", + "SimpleITK==2.5.6", + "pystrum @ https://github.com/adalca/pystrum/archive/ba35d4b357f54e5ed577cbd413076a07ef810a21.zip", + "neurite @ https://github.com/adalca/neurite/archive/9ae2f5cec2201eedbcc6929cecf852193cef7646.zip", + "surfa @ https://github.com/freesurfer/surfa/archive/041905fca717447780e0cc211197669e3218de2f.zip", + "voxelmorph @ https://github.com/voxelmorph/voxelmorph/archive/53d1b95fa734648c92fd8af4f3807b09cb56c342.zip", +] +# SynthMorph saves "the transform from moving to fixed" as a field with three frames of shifts along the RAS axes: +# read with its own surfa, negated to LPS, on the fixed grid +CONVERT = """ +import sys +import numpy as np +import SimpleITK as sitk +import surfa as sf + +fixed, out = sitk.ReadImage(sys.argv[1]), sys.argv[2] +warp = sf.load_volume(f"{out}/warp.nii.gz") +if warp.baseshape != fixed.GetSize(): + sys.exit(f"the warp's grid {warp.baseshape} is not the fixed grid {fixed.GetSize()}") +u = np.asarray(warp.data, np.float32).transpose(2, 1, 0, 3) * np.float32([-1, -1, 1]) +dvf = sitk.GetImageFromArray(np.ascontiguousarray(u), isVector=True) +dvf.CopyInformation(fixed) +sitk.WriteImage(dvf, f"{out}/DVF.nii.gz") +""" + + +def home() -> Path: + """FreeSurfer's files, the weights and the environment, fetched once into the cache.""" + root = cache_dir() / f"synthmorph-{COMMIT[:12]}" + for name in FILES: + fetch( + f"https://raw.githubusercontent.com/freesurfer/freesurfer/{COMMIT}/mri_synthmorph/{name}", + root / "fs" / name, + ) + fetch(WEIGHTS[1], root / "fs" / "models" / WEIGHTS[0], WEIGHTS[2]) + pinned_environment(root, "3.12", [PACKAGES]) + return root + + +class SynthMorph: + def __init__(self, model: str, regularisation: float, steps: int, extent: int, threads: int) -> None: + self._model, self._regularisation, self._steps, self._extent = model, regularisation, steps, extent + self._threads = threads + + def __call__( + self, + fixed: sitk.Image, + moving: sitk.Image, + fixed_mask: sitk.Image | None, + moving_mask: sitk.Image | None, + device: int, + ) -> np.ndarray: + root = home() + python = str(root / "venv" / "bin" / "python") + environment = {**os.environ, "FREESURFER_HOME": str(root / "fs"), "TF_CPP_MIN_LOG_LEVEL": "2"} + threads = self._threads or int(os.environ.get("ITK_GLOBAL_DEFAULT_NUMBER_OF_THREADS", "8")) + with tempfile.TemporaryDirectory(prefix="synthmorph_") as scratch: + work = Path(scratch) + sitk.WriteImage(fixed, str(work / "fixed.nii.gz")) + sitk.WriteImage(moving, str(work / "moving.nii.gz")) + subprocess.run( # nosec B603 + [ + python, + str(root / "fs" / "mri_synthmorph"), + "register", + "-m", + self._model, + "-r", + str(self._regularisation), + "-n", + str(self._steps), + "-e", + str(self._extent), + "-j", + str(threads), + *(["-g"] if device >= 0 else []), + "-t", + str(work / "warp.nii.gz"), + str(work / "moving.nii.gz"), + str(work / "fixed.nii.gz"), + ], + check=True, + env=environment, + ) + subprocess.run([python, "-c", CONVERT, str(work / "fixed.nii.gz"), str(work)], check=True) # nosec B603 + field = sitk.ReadImage(str(work / "DVF.nii.gz"), sitk.sitkVectorFloat32) + return np.ascontiguousarray(np.moveaxis(sitk.GetArrayFromImage(field), -1, 0), dtype=np.float32) + + +class RegistrationNet(BaselineNet): + """SynthMorph, the deformable model with its defaults. Brain MR.""" + + def __init__( + self, + optimizer: network.OptimizerLoader = network.OptimizerLoader(), + schedulers: dict[str, network.LRSchedulersLoader] = { + "default:ReduceLROnPlateau": network.LRSchedulersLoader(0) + }, + outputs_criterions: dict[str, network.TargetCriterionsLoader] = {"default": network.TargetCriterionsLoader()}, + model: Annotated[ + str, "mri_synthmorph's -m: deform for aligned pairs, joint to add the affine model." + ] = "deform", + regularisation: Annotated[float, "mri_synthmorph's -r: the deformable model's regularisation weight."] = 0.5, + steps: Annotated[int, "mri_synthmorph's -n: integration steps."] = 7, + extent: Annotated[int, "mri_synthmorph's -e: the registration box, in voxels of 1 mm."] = 256, + threads: Annotated[int, "mri_synthmorph's -j; 0 takes ITK_GLOBAL_DEFAULT_NUMBER_OF_THREADS or 8."] = 0, + ) -> None: + super().__init__( + SynthMorph(model, regularisation, steps, extent, threads), 3, optimizer, schedulers, outputs_criterions + ) diff --git a/SynthMorph/requirements.txt b/SynthMorph/requirements.txt new file mode 100644 index 0000000000000000000000000000000000000000..00eb295d2cccfc52393970efc29a3f5a54cc3481 --- /dev/null +++ b/SynthMorph/requirements.txt @@ -0,0 +1,2 @@ +SimpleITK +uv==0.12.10 diff --git a/UniGradICON/Prediction.yml b/UniGradICON/Prediction.yml new file mode 100644 index 0000000000000000000000000000000000000000..64419d6b8c597f139b9cad0498fa14e60b761a7e --- /dev/null +++ b/UniGradICON/Prediction.yml @@ -0,0 +1,90 @@ +Predictor: + Model: + classpath: model:RegistrationNet + RegistrationNet: + model: unigradicon + masks: false + fixed_modality: auto + moving_modality: auto + iterations: 50 + similarity: lncc + outputs_criterions: None + Dataset: + groups_src: + Volume_0: + groups_dest: + Fixed: + transforms: + TensorCast: + dtype: float32 + inverse: false + patch_transforms: None + is_input: true + Volume_1: + groups_dest: + Moving: + transforms: + TensorCast: + dtype: float32 + inverse: false + patch_transforms: None + is_input: true + Volume_2: + groups_dest: + FixedMask: + transforms: + TensorCast: + dtype: float32 + inverse: false + patch_transforms: None + is_input: true + Volume_3: + groups_dest: + MovingMask: + transforms: + TensorCast: + dtype: float32 + inverse: false + patch_transforms: None + is_input: true + augmentations: None + Patch: + patch_size: + - 0 + - 0 + - 0 + overlap: 0 + pad_value: None + extend_slice: 0 + mode: resample + max_voxels: None + subset: None + dataset_filenames: + - ./Dataset/:mha + batch_size: 1 + num_workers: None + pin_memory: false + prefetch_factor: None + persistent_workers: None + outputs_dataset: + DisplacementField: + OutputDataset: + name_class: OutputDataset + before_reduction_transforms: None + after_reduction_transforms: None + final_transforms: + TensorCast: + dtype: float32 + inverse: false + dataset_filename: DisplacementField:mha + group: DisplacementField + same_as_group: Volume_0:Fixed + patch_combine: Cosinus + reduction: Mean + Mean: {} + train_name: Baselines-UniGradICON + manual_seed: 42 + gpu_checkpoints: None + combine: Mean + autocast: false + data_log: None diff --git a/UniGradICON/app.json b/UniGradICON/app.json new file mode 100644 index 0000000000000000000000000000000000000000..2559bb18d0e1aca1ef7b463d61d0c7029b1bb50b --- /dev/null +++ b/UniGradICON/app.json @@ -0,0 +1,40 @@ +{ + "display_name": "uniGradICON", + "short_description": "The uniGradICON network's prediction, then 50 steps of instance optimisation on LNCC: unigradicon-register with its defaults, the ImagingBenchmarks baseline unigradicon.", + "description": "The uniGradICON network's prediction, then 50 steps of instance optimisation on LNCC: unigradicon-register with its defaults, the ImagingBenchmarks baseline unigradicon. With --set masks=true each image is multiplied by its lung mask, the authors' Learn2Reg lung protocol (the ImagingBenchmarks line unigradicon_lungmask). The pair must be aligned (rigidly for one patient, by an affine transform between two subjects): only the deformable stage runs. The command knows two modalities, ct (clamped to [-1000, 1000] HU) and mri (minimum to the 99th percentile), read off the intensities. The weights come from the authors' release, checked against their hash; the package is pinned at 1.0.5. A GPU is needed. Output: the displacement field on the fixed grid, in mm along the world axes (ITK, LPS).

How to cite:
L. Tian et al., uniGradICON: A foundation model for medical image registration, MICCAI 2024; B. Demir et al., multiGradICON, WBIR 2024.", + "task": "registration", + "tta": 0, + "mc_dropout": 0, + "models": [], + "inputs": { + "Fixed": { + "display_name": "Fixed image", + "volume_type": "VOLUME", + "required": true + }, + "Moving": { + "display_name": "Moving image", + "volume_type": "VOLUME", + "required": true + }, + "FixedMask": { + "display_name": "Fixed lung mask (used with masks=true)", + "volume_type": "SEGMENTATION", + "required": false, + "default": "ones" + }, + "MovingMask": { + "display_name": "Moving lung mask (used with masks=true)", + "volume_type": "SEGMENTATION", + "required": false, + "default": "ones" + } + }, + "outputs": { + "DisplacementField": { + "display_name": "Displacement field", + "volume_type": "VOLUME", + "required": true + } + } +} diff --git a/UniGradICON/baselines.py b/UniGradICON/baselines.py new file mode 100644 index 0000000000000000000000000000000000000000..691b6d9c745cf4c64ab8e323b21b5c76b251af72 --- /dev/null +++ b/UniGradICON/baselines.py @@ -0,0 +1,206 @@ +# Copyright (c) 2025 Valentin Boussot +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +# +# SPDX-License-Identifier: Apache-2.0 + +"""What every baseline app shares (a copy of the repository's baselines.py, kept by build.py): the authors' code fetched at its pin, the graph module that hands a pair to an +engine and gets a displacement field back, and the field's convention. + +The field is the benchmark's: one component per spatial axis, in mm along the world (ITK, LPS) axes, on the fixed +image's grid, such that the fixed point ``x`` matches ``x + u(x)`` in the moving image. The predictor attaches the +fixed image's geometry to the output (``same_as_group: Volume_0:Fixed`` in the app's ``Prediction.yml``). + +NOTE: do NOT add ``from __future__ import annotations``: KonfAI's config engine relies on runtime-evaluated +annotations (``get_origin``); PEP 563 stringized annotations break binding. +""" + +import hashlib +import os +import shutil +import subprocess # nosec B404 +import urllib.request +import zipfile +from collections.abc import Callable +from pathlib import Path + +import numpy as np +import SimpleITK as sitk +import torch +from konfai.network import network +from konfai.utils.dataset import Attribute, data_to_image + +#: An engine: (fixed, moving, fixed mask or None, moving mask or None, CUDA device index or -1) -> the field, +#: ``[D, *spatial]`` in mm along the world axes on the fixed grid. +Engine = Callable[[sitk.Image, sitk.Image, sitk.Image | None, sitk.Image | None, int], np.ndarray] + + +def cache_dir() -> Path: + """Where the authors' code and binaries live, once fetched: ``$BASELINES_KONFAI_CACHE`` or + ``~/.cache/baselines-konfai``.""" + return Path(os.environ.get("BASELINES_KONFAI_CACHE", Path.home() / ".cache" / "baselines-konfai")) + + +def pinned_source(name: str, url: str, commit: str) -> Path: + """The authors' repository at ``commit``, cloned once into the cache: a baseline runs the code it was + measured with, never a moving branch.""" + target = cache_dir() / f"{name}-{commit[:12]}" + if not (target / ".git").exists(): + target.parent.mkdir(parents=True, exist_ok=True) + subprocess.run(["git", "clone", "--quiet", url, str(target)], check=True) # nosec B603 B607 + subprocess.run(["git", "-C", str(target), "checkout", "--quiet", commit], check=True) # nosec B603 B607 + return target + + +def fetch(url: str, target: Path, sha256: str | None = None) -> Path: + """``url`` downloaded once to ``target`` and, when a hash is given, checked against it.""" + if not target.exists(): + target.parent.mkdir(parents=True, exist_ok=True) + part = target.with_name(target.name + ".part") + urllib.request.urlretrieve(url, part) # nosec B310 - the authors' release, checked below + with part.open("rb") as stream: + digest = hashlib.file_digest(stream, "sha256").hexdigest() + if sha256 and digest != sha256: + part.unlink() + raise RuntimeError(f"{url} does not match its recorded hash") + part.rename(target) + return target + + +def pinned_archive(name: str, url: str, sha256: str) -> Path: + """A release archive at ``url``, downloaded once into the cache, checked against ``sha256`` and unpacked: the + binaries a baseline was measured with.""" + target = cache_dir() / f"{name}-{sha256[:12]}" + if not (target / ".unpacked").exists(): + archive = fetch(url, target / "archive", sha256) + if zipfile.is_zipfile(archive): + with zipfile.ZipFile(archive) as packed: + packed.extractall(target) # nosec B202 - our own pinned archive + for entry in packed.infolist(): # zipfile drops the modes: the binaries must stay executable + if mode := (entry.external_attr >> 16) & 0o777: + (target / entry.filename).chmod(mode) + else: + shutil.unpack_archive(str(archive), str(target), "gztar") + archive.unlink() + (target / ".unpacked").touch() + return target + + +def pinned_environment(root: Path, python: str, installs: list[list[str]]) -> Path: + """A virtual environment at ``root/venv`` on its own Python, made once by uv (``pip install uv``): for the tools + whose pins do not run on the host's Python. ``installs`` are ``pip install`` argument lists, run in order.""" + try: + import uv + + command = uv.find_uv_bin() + except ImportError: + command = shutil.which("uv") or "" + if not command: + raise RuntimeError("this baseline builds its own Python environment with uv: pip install uv") + venv = root / "venv" + if not (venv / ".ready").exists(): + subprocess.run([command, "venv", "--quiet", "--clear", "--python", python, str(venv)], check=True) # nosec B603 + for arguments in installs: + subprocess.run( # nosec B603 + [ + command, + "pip", + "install", + "--quiet", + "--no-cache", + "--python", + str(venv / "bin" / "python"), + *arguments, + ], + check=True, + ) + (venv / ".ready").touch() + return venv + + +def built_source(name: str, url: str, commit: str, build: Callable[[Path], None]) -> Path: + """The authors' repository at ``commit``, built once by ``build`` (a marker says it is done).""" + source = pinned_source(name, url, commit) + if not (source / ".built").exists(): + build(source) + (source / ".built").touch() + return source + + +def field_from_voxels(displacement: np.ndarray, fixed: sitk.Image) -> np.ndarray: + """A displacement in voxels along the index axes, ``[i, j, k, D]``, as the benchmark's field ``[D, k, j, i]`` + in mm along the world axes: ``u = D S d``, with ``D`` the direction and ``S`` the spacing of the fixed image.""" + n = fixed.GetDimension() + to_world = np.array(fixed.GetDirection()).reshape(n, n) @ np.diag(fixed.GetSpacing()) + world = displacement.astype(np.float64) @ to_world.T # [i, j, k, D] + return np.ascontiguousarray(np.moveaxis(world, -1, 0).transpose(0, *reversed(range(1, n + 1))), dtype=np.float32) + + +def to_index_array(image: sitk.Image) -> np.ndarray: + """The image as a ``[i, j, k]`` array, the index axes in ITK's order, which the tools indexed that way read.""" + return np.ascontiguousarray(sitk.GetArrayFromImage(image).transpose(*reversed(range(image.GetDimension())))) + + +class Registration(torch.nn.Module): + """Graph module: the pair's tensors and their geometry in, the field out, through the engine, one sample at + a time. ``accepts_attributes = True`` opts it into the per-branch ``Attribute`` list (the convention of + ``CriterionWithAttribute``): registration needs the physical geometry.""" + + accepts_attributes = True + + def __init__(self, engine: Engine) -> None: + super().__init__() + self._engine = engine + + def forward( + self, + fixed: torch.Tensor, + moving: torch.Tensor, + fixed_mask: torch.Tensor, + moving_mask: torch.Tensor, + attributes: list[list[Attribute]], + ) -> torch.Tensor: + fixed_attrs, moving_attrs, fixed_mask_attrs, moving_mask_attrs = attributes + device_index = fixed.device.index if fixed.device.type == "cuda" else -1 + fields = [] + # the engines optimise with autograd; the predictor calls forward under inference mode + with torch.inference_mode(False), torch.enable_grad(): + for b in range(fixed.shape[0]): + images = [ + data_to_image(t[b].detach().cpu().numpy(), attrs[b]) + for t, attrs in ((fixed, fixed_attrs), (moving, moving_attrs)) + ] + masks = [ + data_to_image(t[b].detach().cpu().numpy(), attrs[b]) if not bool((t[b] == 1).all()) else None + for t, attrs in ((fixed_mask, fixed_mask_attrs), (moving_mask, moving_mask_attrs)) + ] + fields.append(torch.from_numpy(self._engine(images[0], images[1], masks[0], masks[1], device_index))) + return torch.stack(fields, dim=0).to(fixed.device) + + +class BaselineNet(network.Network): + """A baseline as an ``add_module`` graph: fixed = branch 0, moving = branch 1, the masks branches 2 and 3 (a + mask of ones means none). The one output is ``DisplacementField``, on the fixed grid.""" + + def __init__( + self, + engine: Engine, + dim: int, + optimizer: network.OptimizerLoader, + schedulers: dict[str, network.LRSchedulersLoader], + outputs_criterions: dict[str, network.TargetCriterionsLoader], + ) -> None: + super().__init__( + in_channels=1, optimizer=optimizer, schedulers=schedulers, outputs_criterions=outputs_criterions, dim=dim + ) + self.add_module("DisplacementField", Registration(engine), in_branch=[0, 1, 2, 3], out_branch=["dvf"]) diff --git a/UniGradICON/model.py b/UniGradICON/model.py new file mode 100644 index 0000000000000000000000000000000000000000..96ee77e1e351e1043713c6adc518062796416047 --- /dev/null +++ b/UniGradICON/model.py @@ -0,0 +1,194 @@ +# Copyright (c) 2025 Valentin Boussot +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +# +# SPDX-License-Identifier: Apache-2.0 + +"""uniGradICON and multiGradICON through the authors' command, ``unigradicon-register`` (the ``unigradicon`` +package at a pinned version), with its defaults: the network's prediction, then 50 steps of instance optimisation +on LNCC; the weights fetched from the authors' release and checked against their hash. The authors' lung protocol +(``masks``) multiplies each image by its mask, as their Learn2Reg submissions did. + +NOTE: do NOT add ``from __future__ import annotations``: KonfAI's config engine relies on runtime-evaluated +annotations (``get_origin``); PEP 563 stringized annotations break binding. +""" + +import hashlib +import os +import shutil +import subprocess # nosec B404 +import tempfile +import urllib.request +from pathlib import Path +from typing import Annotated + +import numpy as np +import SimpleITK as sitk +from konfai.network import network +from konfai.utils.config import Choices + +from baselines import BaselineNet, cache_dir + +VERSION = "1.0.5" # the unigradicon package; the bundle's requirements pin it +WEIGHTS = { # the authors' release, sha256 of each file + "unigradicon": ( + "https://github.com/uncbiag/uniGradICON/releases/download/unigradicon_weights/Step_2_final.trch", + "1fcfa02214540915cad7b768570add2b4247c22c516d75a21e0e8258f50254a6", + ), + "multigradicon": ( + "https://github.com/uncbiag/uniGradICON/releases/download/multigradicon_weights/Step_2_final.trch", + "c37a7cf5c0576f24b03418f3f659eedde9aaf6b9c1e42469d3fe3eacbb901e01", + ), +} + + +def weights_dir(model: str) -> Path: + """Where the command finds ``network_weights/1.0/Step_2_final.trch``: it reads them relative to its + working directory, so the engine runs it from here.""" + root = cache_dir() / "unigradicon" + target = root / "network_weights" / f"{model}1.0" / "Step_2_final.trch" + url, digest = WEIGHTS[model] + if not target.exists() or hashlib.sha256(target.read_bytes()).hexdigest() != digest: + target.parent.mkdir(parents=True, exist_ok=True) + urllib.request.urlretrieve(url, target) # nosec B310 - the authors' release, checked below + if hashlib.sha256(target.read_bytes()).hexdigest() != digest: + raise RuntimeError(f"the {model} weights do not match their published hash") + return root + + +def modality_of(image: sitk.Image, declared: str) -> str: + """The command's modality: ``ct`` (clamped to [-1000, 1000] HU) or ``mri`` (minimum to the 99th percentile). + ``auto`` reads it off the intensities: Hounsfield units go below -200.""" + if declared in ("ct", "mri"): + return declared + return "ct" if float(sitk.GetArrayViewFromImage(image).min()) < -200 else "mri" + + +def _on_grid(mask: sitk.Image, image: sitk.Image) -> sitk.Image: + """The mask on its image's grid: the command multiplies the two and refuses the slightest header difference.""" + if mask.GetSize() == image.GetSize(): + mask.CopyInformation(image) + return mask + return sitk.Resample(mask, image, sitk.Transform(), sitk.sitkNearestNeighbor, 0) + + +class GradICON: + def __init__( + self, model: str, masks: bool, fixed_modality: str, moving_modality: str, iterations: int, similarity: str + ) -> None: + self._model, self._masks = model, masks + self._modalities = (fixed_modality, moving_modality) + self._iterations, self._similarity = iterations, similarity + + def __call__( + self, + fixed: sitk.Image, + moving: sitk.Image, + fixed_mask: sitk.Image | None, + moving_mask: sitk.Image | None, + device: int, + ) -> np.ndarray: + command = os.environ.get("UNIGRADICON_REGISTER") or shutil.which("unigradicon-register") + if not command: + raise RuntimeError(f"unigradicon-register was not found: pip install unigradicon=={VERSION}") + with tempfile.TemporaryDirectory(prefix="gradicon_") as scratch: + work = Path(scratch) + sitk.WriteImage(fixed, str(work / "fixed.nii.gz")) + sitk.WriteImage(moving, str(work / "moving.nii.gz")) + arguments = [ + command, + "--fixed", + str(work / "fixed.nii.gz"), + "--fixed_modality", + modality_of(fixed, self._modalities[0]), + "--moving", + str(work / "moving.nii.gz"), + "--moving_modality", + modality_of(moving, self._modalities[1]), + "--transform_out", + str(work / "transform.hdf5"), + "--model", + self._model, + "--io_iterations", + str(self._iterations), + "--io_sim", + self._similarity, + ] + if self._masks: + if fixed_mask is None or moving_mask is None: + raise ValueError("the lung protocol needs the fixed and the moving mask") + sitk.WriteImage(_on_grid(fixed_mask, fixed), str(work / "fixed_mask.nii.gz")) + sitk.WriteImage(_on_grid(moving_mask, moving), str(work / "moving_mask.nii.gz")) + arguments += [ + "--fixed_segmentation", + str(work / "fixed_mask.nii.gz"), + "--moving_segmentation", + str(work / "moving_mask.nii.gz"), + ] + environment = {**os.environ, "CUDA_VISIBLE_DEVICES": str(device) if device >= 0 else ""} + subprocess.run(arguments, check=True, cwd=weights_dir(self._model), env=environment) # nosec B603 + transform = sitk.ReadTransform(str(work / "transform.hdf5")) + # the command's transform maps a fixed point to its moving point: sampled on the fixed grid it is the field + field = sitk.TransformToDisplacementField( + transform, + sitk.sitkVectorFloat64, + fixed.GetSize(), + fixed.GetOrigin(), + fixed.GetSpacing(), + fixed.GetDirection(), + ) + return np.ascontiguousarray(np.moveaxis(sitk.GetArrayFromImage(field), -1, 0), dtype=np.float32) + + +class RegistrationNet(BaselineNet): + """uniGradICON or multiGradICON as the authors' command runs them.""" + + def __init__( + self, + optimizer: network.OptimizerLoader = network.OptimizerLoader(), + schedulers: dict[str, network.LRSchedulersLoader] = { + "default:ReduceLROnPlateau": network.LRSchedulersLoader(0) + }, + outputs_criterions: dict[str, network.TargetCriterionsLoader] = {"default": network.TargetCriterionsLoader()}, + model: Annotated[ + str, Choices(["unigradicon", "multigradicon"]), "The network: uniGradICON or multiGradICON." + ] = "unigradicon", + masks: Annotated[ + bool, "The authors' lung protocol: each image multiplied by its mask before registration." + ] = False, + fixed_modality: Annotated[ + str, + Choices(["auto", "ct", "mri"]), + "The command's modality of the fixed image; auto reads it off the intensities.", + ] = "auto", + moving_modality: Annotated[ + str, + Choices(["auto", "ct", "mri"]), + "The command's modality of the moving image; auto reads it off the intensities.", + ] = "auto", + iterations: Annotated[ + int, "Steps of instance optimisation after the network's prediction (the command's default)." + ] = 50, + similarity: Annotated[ + str, + Choices(["lncc", "lncc2", "mind"]), + "The similarity of the instance optimisation (the command's default).", + ] = "lncc", + ) -> None: + super().__init__( + GradICON(model, masks, fixed_modality, moving_modality, iterations, similarity), + 3, + optimizer, + schedulers, + outputs_criterions, + ) diff --git a/UniGradICON/requirements.txt b/UniGradICON/requirements.txt new file mode 100644 index 0000000000000000000000000000000000000000..0d8852d2fa98d5111eb80c6938ad904eb87d133b --- /dev/null +++ b/UniGradICON/requirements.txt @@ -0,0 +1,4 @@ +SimpleITK +unigradicon==1.0.5 +icon_registration==1.1.8 +itk==6.0b2 diff --git a/baselines.py b/baselines.py new file mode 100644 index 0000000000000000000000000000000000000000..691b6d9c745cf4c64ab8e323b21b5c76b251af72 --- /dev/null +++ b/baselines.py @@ -0,0 +1,206 @@ +# Copyright (c) 2025 Valentin Boussot +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +# +# SPDX-License-Identifier: Apache-2.0 + +"""What every baseline app shares (a copy of the repository's baselines.py, kept by build.py): the authors' code fetched at its pin, the graph module that hands a pair to an +engine and gets a displacement field back, and the field's convention. + +The field is the benchmark's: one component per spatial axis, in mm along the world (ITK, LPS) axes, on the fixed +image's grid, such that the fixed point ``x`` matches ``x + u(x)`` in the moving image. The predictor attaches the +fixed image's geometry to the output (``same_as_group: Volume_0:Fixed`` in the app's ``Prediction.yml``). + +NOTE: do NOT add ``from __future__ import annotations``: KonfAI's config engine relies on runtime-evaluated +annotations (``get_origin``); PEP 563 stringized annotations break binding. +""" + +import hashlib +import os +import shutil +import subprocess # nosec B404 +import urllib.request +import zipfile +from collections.abc import Callable +from pathlib import Path + +import numpy as np +import SimpleITK as sitk +import torch +from konfai.network import network +from konfai.utils.dataset import Attribute, data_to_image + +#: An engine: (fixed, moving, fixed mask or None, moving mask or None, CUDA device index or -1) -> the field, +#: ``[D, *spatial]`` in mm along the world axes on the fixed grid. +Engine = Callable[[sitk.Image, sitk.Image, sitk.Image | None, sitk.Image | None, int], np.ndarray] + + +def cache_dir() -> Path: + """Where the authors' code and binaries live, once fetched: ``$BASELINES_KONFAI_CACHE`` or + ``~/.cache/baselines-konfai``.""" + return Path(os.environ.get("BASELINES_KONFAI_CACHE", Path.home() / ".cache" / "baselines-konfai")) + + +def pinned_source(name: str, url: str, commit: str) -> Path: + """The authors' repository at ``commit``, cloned once into the cache: a baseline runs the code it was + measured with, never a moving branch.""" + target = cache_dir() / f"{name}-{commit[:12]}" + if not (target / ".git").exists(): + target.parent.mkdir(parents=True, exist_ok=True) + subprocess.run(["git", "clone", "--quiet", url, str(target)], check=True) # nosec B603 B607 + subprocess.run(["git", "-C", str(target), "checkout", "--quiet", commit], check=True) # nosec B603 B607 + return target + + +def fetch(url: str, target: Path, sha256: str | None = None) -> Path: + """``url`` downloaded once to ``target`` and, when a hash is given, checked against it.""" + if not target.exists(): + target.parent.mkdir(parents=True, exist_ok=True) + part = target.with_name(target.name + ".part") + urllib.request.urlretrieve(url, part) # nosec B310 - the authors' release, checked below + with part.open("rb") as stream: + digest = hashlib.file_digest(stream, "sha256").hexdigest() + if sha256 and digest != sha256: + part.unlink() + raise RuntimeError(f"{url} does not match its recorded hash") + part.rename(target) + return target + + +def pinned_archive(name: str, url: str, sha256: str) -> Path: + """A release archive at ``url``, downloaded once into the cache, checked against ``sha256`` and unpacked: the + binaries a baseline was measured with.""" + target = cache_dir() / f"{name}-{sha256[:12]}" + if not (target / ".unpacked").exists(): + archive = fetch(url, target / "archive", sha256) + if zipfile.is_zipfile(archive): + with zipfile.ZipFile(archive) as packed: + packed.extractall(target) # nosec B202 - our own pinned archive + for entry in packed.infolist(): # zipfile drops the modes: the binaries must stay executable + if mode := (entry.external_attr >> 16) & 0o777: + (target / entry.filename).chmod(mode) + else: + shutil.unpack_archive(str(archive), str(target), "gztar") + archive.unlink() + (target / ".unpacked").touch() + return target + + +def pinned_environment(root: Path, python: str, installs: list[list[str]]) -> Path: + """A virtual environment at ``root/venv`` on its own Python, made once by uv (``pip install uv``): for the tools + whose pins do not run on the host's Python. ``installs`` are ``pip install`` argument lists, run in order.""" + try: + import uv + + command = uv.find_uv_bin() + except ImportError: + command = shutil.which("uv") or "" + if not command: + raise RuntimeError("this baseline builds its own Python environment with uv: pip install uv") + venv = root / "venv" + if not (venv / ".ready").exists(): + subprocess.run([command, "venv", "--quiet", "--clear", "--python", python, str(venv)], check=True) # nosec B603 + for arguments in installs: + subprocess.run( # nosec B603 + [ + command, + "pip", + "install", + "--quiet", + "--no-cache", + "--python", + str(venv / "bin" / "python"), + *arguments, + ], + check=True, + ) + (venv / ".ready").touch() + return venv + + +def built_source(name: str, url: str, commit: str, build: Callable[[Path], None]) -> Path: + """The authors' repository at ``commit``, built once by ``build`` (a marker says it is done).""" + source = pinned_source(name, url, commit) + if not (source / ".built").exists(): + build(source) + (source / ".built").touch() + return source + + +def field_from_voxels(displacement: np.ndarray, fixed: sitk.Image) -> np.ndarray: + """A displacement in voxels along the index axes, ``[i, j, k, D]``, as the benchmark's field ``[D, k, j, i]`` + in mm along the world axes: ``u = D S d``, with ``D`` the direction and ``S`` the spacing of the fixed image.""" + n = fixed.GetDimension() + to_world = np.array(fixed.GetDirection()).reshape(n, n) @ np.diag(fixed.GetSpacing()) + world = displacement.astype(np.float64) @ to_world.T # [i, j, k, D] + return np.ascontiguousarray(np.moveaxis(world, -1, 0).transpose(0, *reversed(range(1, n + 1))), dtype=np.float32) + + +def to_index_array(image: sitk.Image) -> np.ndarray: + """The image as a ``[i, j, k]`` array, the index axes in ITK's order, which the tools indexed that way read.""" + return np.ascontiguousarray(sitk.GetArrayFromImage(image).transpose(*reversed(range(image.GetDimension())))) + + +class Registration(torch.nn.Module): + """Graph module: the pair's tensors and their geometry in, the field out, through the engine, one sample at + a time. ``accepts_attributes = True`` opts it into the per-branch ``Attribute`` list (the convention of + ``CriterionWithAttribute``): registration needs the physical geometry.""" + + accepts_attributes = True + + def __init__(self, engine: Engine) -> None: + super().__init__() + self._engine = engine + + def forward( + self, + fixed: torch.Tensor, + moving: torch.Tensor, + fixed_mask: torch.Tensor, + moving_mask: torch.Tensor, + attributes: list[list[Attribute]], + ) -> torch.Tensor: + fixed_attrs, moving_attrs, fixed_mask_attrs, moving_mask_attrs = attributes + device_index = fixed.device.index if fixed.device.type == "cuda" else -1 + fields = [] + # the engines optimise with autograd; the predictor calls forward under inference mode + with torch.inference_mode(False), torch.enable_grad(): + for b in range(fixed.shape[0]): + images = [ + data_to_image(t[b].detach().cpu().numpy(), attrs[b]) + for t, attrs in ((fixed, fixed_attrs), (moving, moving_attrs)) + ] + masks = [ + data_to_image(t[b].detach().cpu().numpy(), attrs[b]) if not bool((t[b] == 1).all()) else None + for t, attrs in ((fixed_mask, fixed_mask_attrs), (moving_mask, moving_mask_attrs)) + ] + fields.append(torch.from_numpy(self._engine(images[0], images[1], masks[0], masks[1], device_index))) + return torch.stack(fields, dim=0).to(fixed.device) + + +class BaselineNet(network.Network): + """A baseline as an ``add_module`` graph: fixed = branch 0, moving = branch 1, the masks branches 2 and 3 (a + mask of ones means none). The one output is ``DisplacementField``, on the fixed grid.""" + + def __init__( + self, + engine: Engine, + dim: int, + optimizer: network.OptimizerLoader, + schedulers: dict[str, network.LRSchedulersLoader], + outputs_criterions: dict[str, network.TargetCriterionsLoader], + ) -> None: + super().__init__( + in_channels=1, optimizer=optimizer, schedulers=schedulers, outputs_criterions=outputs_criterions, dim=dim + ) + self.add_module("DisplacementField", Registration(engine), in_branch=[0, 1, 2, 3], out_branch=["dvf"]) diff --git a/build.py b/build.py new file mode 100644 index 0000000000000000000000000000000000000000..8c09ce2565e7e1afdca4130b09f5dc4242525eb7 --- /dev/null +++ b/build.py @@ -0,0 +1,6 @@ +"""Copies baselines.py, what the baseline apps share, into every app folder that has a model.py.""" +import shutil +from pathlib import Path + +for model in Path(__file__).parent.glob("*/model.py"): + shutil.copy(Path(__file__).with_name("baselines.py"), model.with_name("baselines.py"))