VBoussot commited on
Commit
19c25c8
·
verified ·
1 Parent(s): 06efc39

The 12 registration baselines of ImagingBenchmarks as apps, next to the presets

Browse files

ANTs_SyN, NiftyReg, Deeds, Greedy, Demons, CorrField, ConvexAdam_MIND, UniGradICON, MultiGradICON, Anatomix_ConvexAdam, SynthMorph, BrainMorph: each folder carries its model.py, which runs the authors' code at a pinned version fetched on first use (a git checkout, a release archive checked by hash, a cmake or make build, or an environment uv makes on its own Python), with the benchmark's settings in Prediction.yml. baselines.py is what they share, copied into each folder by build.py. Each app was checked against the benchmark's own line on one case.

This view is limited to 50 files because it contains too many changes.   See raw diff
Files changed (50) hide show
  1. ANTs_SyN/Prediction.yml +91 -0
  2. ANTs_SyN/app.json +40 -0
  3. ANTs_SyN/baselines.py +206 -0
  4. ANTs_SyN/model.py +172 -0
  5. ANTs_SyN/requirements.txt +1 -0
  6. Anatomix_ConvexAdam/Prediction.yml +86 -0
  7. Anatomix_ConvexAdam/app.json +40 -0
  8. Anatomix_ConvexAdam/baselines.py +206 -0
  9. Anatomix_ConvexAdam/model.py +165 -0
  10. Anatomix_ConvexAdam/requirements.txt +5 -0
  11. BrainMorph/Prediction.yml +87 -0
  12. BrainMorph/app.json +40 -0
  13. BrainMorph/baselines.py +206 -0
  14. BrainMorph/model.py +181 -0
  15. BrainMorph/requirements.txt +2 -0
  16. ConvexAdam_MIND/Prediction.yml +85 -0
  17. ConvexAdam_MIND/app.json +18 -0
  18. ConvexAdam_MIND/baselines.py +206 -0
  19. ConvexAdam_MIND/model.py +99 -0
  20. ConvexAdam_MIND/requirements.txt +3 -0
  21. CorrField/Prediction.yml +86 -0
  22. CorrField/app.json +39 -0
  23. CorrField/baselines.py +206 -0
  24. CorrField/model.py +150 -0
  25. CorrField/requirements.txt +3 -0
  26. Deeds/Prediction.yml +85 -0
  27. Deeds/app.json +40 -0
  28. Deeds/baselines.py +206 -0
  29. Deeds/model.py +141 -0
  30. Deeds/requirements.txt +1 -0
  31. Demons/Prediction.yml +94 -0
  32. Demons/app.json +40 -0
  33. Demons/baselines.py +206 -0
  34. Demons/model.py +152 -0
  35. Demons/requirements.txt +1 -0
  36. Greedy/Prediction.yml +87 -0
  37. Greedy/app.json +40 -0
  38. Greedy/baselines.py +206 -0
  39. Greedy/model.py +79 -0
  40. Greedy/requirements.txt +2 -0
  41. MultiGradICON/Prediction.yml +90 -0
  42. MultiGradICON/app.json +40 -0
  43. MultiGradICON/baselines.py +206 -0
  44. MultiGradICON/model.py +194 -0
  45. MultiGradICON/requirements.txt +4 -0
  46. NiftyReg/Prediction.yml +86 -0
  47. NiftyReg/app.json +40 -0
  48. NiftyReg/baselines.py +206 -0
  49. NiftyReg/model.py +129 -0
  50. NiftyReg/requirements.txt +1 -0
ANTs_SyN/Prediction.yml ADDED
@@ -0,0 +1,91 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ Predictor:
2
+ Model:
3
+ classpath: model:RegistrationNet
4
+ RegistrationNet:
5
+ transform: SyN[0.2,3,0]
6
+ metric: CC[FIXED,MOVING,1,2]
7
+ convergence: '[100x70x50x20,1e-6,10]'
8
+ shrink_factors: 8x4x2x1
9
+ smoothing_sigmas: 3x2x1x0vox
10
+ seed: 1
11
+ threads: 0
12
+ outputs_criterions: None
13
+ Dataset:
14
+ groups_src:
15
+ Volume_0:
16
+ groups_dest:
17
+ Fixed:
18
+ transforms:
19
+ TensorCast:
20
+ dtype: float32
21
+ inverse: false
22
+ patch_transforms: None
23
+ is_input: true
24
+ Volume_1:
25
+ groups_dest:
26
+ Moving:
27
+ transforms:
28
+ TensorCast:
29
+ dtype: float32
30
+ inverse: false
31
+ patch_transforms: None
32
+ is_input: true
33
+ Volume_2:
34
+ groups_dest:
35
+ FixedMask:
36
+ transforms:
37
+ TensorCast:
38
+ dtype: float32
39
+ inverse: false
40
+ patch_transforms: None
41
+ is_input: true
42
+ Volume_3:
43
+ groups_dest:
44
+ MovingMask:
45
+ transforms:
46
+ TensorCast:
47
+ dtype: float32
48
+ inverse: false
49
+ patch_transforms: None
50
+ is_input: true
51
+ augmentations: None
52
+ Patch:
53
+ patch_size:
54
+ - 0
55
+ - 0
56
+ - 0
57
+ overlap: 0
58
+ pad_value: None
59
+ extend_slice: 0
60
+ mode: resample
61
+ max_voxels: None
62
+ subset: None
63
+ dataset_filenames:
64
+ - ./Dataset/:mha
65
+ batch_size: 1
66
+ num_workers: None
67
+ pin_memory: false
68
+ prefetch_factor: None
69
+ persistent_workers: None
70
+ outputs_dataset:
71
+ DisplacementField:
72
+ OutputDataset:
73
+ name_class: OutputDataset
74
+ before_reduction_transforms: None
75
+ after_reduction_transforms: None
76
+ final_transforms:
77
+ TensorCast:
78
+ dtype: float32
79
+ inverse: false
80
+ dataset_filename: DisplacementField:mha
81
+ group: DisplacementField
82
+ same_as_group: Volume_0:Fixed
83
+ patch_combine: Cosinus
84
+ reduction: Mean
85
+ Mean: {}
86
+ train_name: Baselines-ANTs_SyN
87
+ manual_seed: 42
88
+ gpu_checkpoints: None
89
+ combine: Mean
90
+ autocast: false
91
+ data_log: None
ANTs_SyN/app.json ADDED
@@ -0,0 +1,40 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ {
2
+ "display_name": "ANTs SyN",
3
+ "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 <code>ants</code>. CPU.",
4
+ "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 <code>ants</code>. 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).",
5
+ "task": "registration",
6
+ "tta": 0,
7
+ "mc_dropout": 0,
8
+ "models": [],
9
+ "inputs": {
10
+ "Fixed": {
11
+ "display_name": "Fixed image",
12
+ "volume_type": "VOLUME",
13
+ "required": true
14
+ },
15
+ "Moving": {
16
+ "display_name": "Moving image",
17
+ "volume_type": "VOLUME",
18
+ "required": true
19
+ },
20
+ "FixedMask": {
21
+ "display_name": "Fixed mask (ignored by this baseline)",
22
+ "volume_type": "SEGMENTATION",
23
+ "required": false,
24
+ "default": "ones"
25
+ },
26
+ "MovingMask": {
27
+ "display_name": "Moving mask (ignored by this baseline)",
28
+ "volume_type": "SEGMENTATION",
29
+ "required": false,
30
+ "default": "ones"
31
+ }
32
+ },
33
+ "outputs": {
34
+ "DisplacementField": {
35
+ "display_name": "Displacement field",
36
+ "volume_type": "VOLUME",
37
+ "required": true
38
+ }
39
+ }
40
+ }
ANTs_SyN/baselines.py ADDED
@@ -0,0 +1,206 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ # Copyright (c) 2025 Valentin Boussot
2
+ #
3
+ # Licensed under the Apache License, Version 2.0 (the "License");
4
+ # you may not use this file except in compliance with the License.
5
+ # You may obtain a copy of the License at
6
+ #
7
+ # http://www.apache.org/licenses/LICENSE-2.0
8
+ #
9
+ # Unless required by applicable law or agreed to in writing, software
10
+ # distributed under the License is distributed on an "AS IS" BASIS,
11
+ # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12
+ # See the License for the specific language governing permissions and
13
+ # limitations under the License.
14
+ #
15
+ # SPDX-License-Identifier: Apache-2.0
16
+
17
+ """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
18
+ engine and gets a displacement field back, and the field's convention.
19
+
20
+ The field is the benchmark's: one component per spatial axis, in mm along the world (ITK, LPS) axes, on the fixed
21
+ image's grid, such that the fixed point ``x`` matches ``x + u(x)`` in the moving image. The predictor attaches the
22
+ fixed image's geometry to the output (``same_as_group: Volume_0:Fixed`` in the app's ``Prediction.yml``).
23
+
24
+ NOTE: do NOT add ``from __future__ import annotations``: KonfAI's config engine relies on runtime-evaluated
25
+ annotations (``get_origin``); PEP 563 stringized annotations break binding.
26
+ """
27
+
28
+ import hashlib
29
+ import os
30
+ import shutil
31
+ import subprocess # nosec B404
32
+ import urllib.request
33
+ import zipfile
34
+ from collections.abc import Callable
35
+ from pathlib import Path
36
+
37
+ import numpy as np
38
+ import SimpleITK as sitk
39
+ import torch
40
+ from konfai.network import network
41
+ from konfai.utils.dataset import Attribute, data_to_image
42
+
43
+ #: An engine: (fixed, moving, fixed mask or None, moving mask or None, CUDA device index or -1) -> the field,
44
+ #: ``[D, *spatial]`` in mm along the world axes on the fixed grid.
45
+ Engine = Callable[[sitk.Image, sitk.Image, sitk.Image | None, sitk.Image | None, int], np.ndarray]
46
+
47
+
48
+ def cache_dir() -> Path:
49
+ """Where the authors' code and binaries live, once fetched: ``$BASELINES_KONFAI_CACHE`` or
50
+ ``~/.cache/baselines-konfai``."""
51
+ return Path(os.environ.get("BASELINES_KONFAI_CACHE", Path.home() / ".cache" / "baselines-konfai"))
52
+
53
+
54
+ def pinned_source(name: str, url: str, commit: str) -> Path:
55
+ """The authors' repository at ``commit``, cloned once into the cache: a baseline runs the code it was
56
+ measured with, never a moving branch."""
57
+ target = cache_dir() / f"{name}-{commit[:12]}"
58
+ if not (target / ".git").exists():
59
+ target.parent.mkdir(parents=True, exist_ok=True)
60
+ subprocess.run(["git", "clone", "--quiet", url, str(target)], check=True) # nosec B603 B607
61
+ subprocess.run(["git", "-C", str(target), "checkout", "--quiet", commit], check=True) # nosec B603 B607
62
+ return target
63
+
64
+
65
+ def fetch(url: str, target: Path, sha256: str | None = None) -> Path:
66
+ """``url`` downloaded once to ``target`` and, when a hash is given, checked against it."""
67
+ if not target.exists():
68
+ target.parent.mkdir(parents=True, exist_ok=True)
69
+ part = target.with_name(target.name + ".part")
70
+ urllib.request.urlretrieve(url, part) # nosec B310 - the authors' release, checked below
71
+ with part.open("rb") as stream:
72
+ digest = hashlib.file_digest(stream, "sha256").hexdigest()
73
+ if sha256 and digest != sha256:
74
+ part.unlink()
75
+ raise RuntimeError(f"{url} does not match its recorded hash")
76
+ part.rename(target)
77
+ return target
78
+
79
+
80
+ def pinned_archive(name: str, url: str, sha256: str) -> Path:
81
+ """A release archive at ``url``, downloaded once into the cache, checked against ``sha256`` and unpacked: the
82
+ binaries a baseline was measured with."""
83
+ target = cache_dir() / f"{name}-{sha256[:12]}"
84
+ if not (target / ".unpacked").exists():
85
+ archive = fetch(url, target / "archive", sha256)
86
+ if zipfile.is_zipfile(archive):
87
+ with zipfile.ZipFile(archive) as packed:
88
+ packed.extractall(target) # nosec B202 - our own pinned archive
89
+ for entry in packed.infolist(): # zipfile drops the modes: the binaries must stay executable
90
+ if mode := (entry.external_attr >> 16) & 0o777:
91
+ (target / entry.filename).chmod(mode)
92
+ else:
93
+ shutil.unpack_archive(str(archive), str(target), "gztar")
94
+ archive.unlink()
95
+ (target / ".unpacked").touch()
96
+ return target
97
+
98
+
99
+ def pinned_environment(root: Path, python: str, installs: list[list[str]]) -> Path:
100
+ """A virtual environment at ``root/venv`` on its own Python, made once by uv (``pip install uv``): for the tools
101
+ whose pins do not run on the host's Python. ``installs`` are ``pip install`` argument lists, run in order."""
102
+ try:
103
+ import uv
104
+
105
+ command = uv.find_uv_bin()
106
+ except ImportError:
107
+ command = shutil.which("uv") or ""
108
+ if not command:
109
+ raise RuntimeError("this baseline builds its own Python environment with uv: pip install uv")
110
+ venv = root / "venv"
111
+ if not (venv / ".ready").exists():
112
+ subprocess.run([command, "venv", "--quiet", "--clear", "--python", python, str(venv)], check=True) # nosec B603
113
+ for arguments in installs:
114
+ subprocess.run( # nosec B603
115
+ [
116
+ command,
117
+ "pip",
118
+ "install",
119
+ "--quiet",
120
+ "--no-cache",
121
+ "--python",
122
+ str(venv / "bin" / "python"),
123
+ *arguments,
124
+ ],
125
+ check=True,
126
+ )
127
+ (venv / ".ready").touch()
128
+ return venv
129
+
130
+
131
+ def built_source(name: str, url: str, commit: str, build: Callable[[Path], None]) -> Path:
132
+ """The authors' repository at ``commit``, built once by ``build`` (a marker says it is done)."""
133
+ source = pinned_source(name, url, commit)
134
+ if not (source / ".built").exists():
135
+ build(source)
136
+ (source / ".built").touch()
137
+ return source
138
+
139
+
140
+ def field_from_voxels(displacement: np.ndarray, fixed: sitk.Image) -> np.ndarray:
141
+ """A displacement in voxels along the index axes, ``[i, j, k, D]``, as the benchmark's field ``[D, k, j, i]``
142
+ in mm along the world axes: ``u = D S d``, with ``D`` the direction and ``S`` the spacing of the fixed image."""
143
+ n = fixed.GetDimension()
144
+ to_world = np.array(fixed.GetDirection()).reshape(n, n) @ np.diag(fixed.GetSpacing())
145
+ world = displacement.astype(np.float64) @ to_world.T # [i, j, k, D]
146
+ return np.ascontiguousarray(np.moveaxis(world, -1, 0).transpose(0, *reversed(range(1, n + 1))), dtype=np.float32)
147
+
148
+
149
+ def to_index_array(image: sitk.Image) -> np.ndarray:
150
+ """The image as a ``[i, j, k]`` array, the index axes in ITK's order, which the tools indexed that way read."""
151
+ return np.ascontiguousarray(sitk.GetArrayFromImage(image).transpose(*reversed(range(image.GetDimension()))))
152
+
153
+
154
+ class Registration(torch.nn.Module):
155
+ """Graph module: the pair's tensors and their geometry in, the field out, through the engine, one sample at
156
+ a time. ``accepts_attributes = True`` opts it into the per-branch ``Attribute`` list (the convention of
157
+ ``CriterionWithAttribute``): registration needs the physical geometry."""
158
+
159
+ accepts_attributes = True
160
+
161
+ def __init__(self, engine: Engine) -> None:
162
+ super().__init__()
163
+ self._engine = engine
164
+
165
+ def forward(
166
+ self,
167
+ fixed: torch.Tensor,
168
+ moving: torch.Tensor,
169
+ fixed_mask: torch.Tensor,
170
+ moving_mask: torch.Tensor,
171
+ attributes: list[list[Attribute]],
172
+ ) -> torch.Tensor:
173
+ fixed_attrs, moving_attrs, fixed_mask_attrs, moving_mask_attrs = attributes
174
+ device_index = fixed.device.index if fixed.device.type == "cuda" else -1
175
+ fields = []
176
+ # the engines optimise with autograd; the predictor calls forward under inference mode
177
+ with torch.inference_mode(False), torch.enable_grad():
178
+ for b in range(fixed.shape[0]):
179
+ images = [
180
+ data_to_image(t[b].detach().cpu().numpy(), attrs[b])
181
+ for t, attrs in ((fixed, fixed_attrs), (moving, moving_attrs))
182
+ ]
183
+ masks = [
184
+ data_to_image(t[b].detach().cpu().numpy(), attrs[b]) if not bool((t[b] == 1).all()) else None
185
+ for t, attrs in ((fixed_mask, fixed_mask_attrs), (moving_mask, moving_mask_attrs))
186
+ ]
187
+ fields.append(torch.from_numpy(self._engine(images[0], images[1], masks[0], masks[1], device_index)))
188
+ return torch.stack(fields, dim=0).to(fixed.device)
189
+
190
+
191
+ class BaselineNet(network.Network):
192
+ """A baseline as an ``add_module`` graph: fixed = branch 0, moving = branch 1, the masks branches 2 and 3 (a
193
+ mask of ones means none). The one output is ``DisplacementField``, on the fixed grid."""
194
+
195
+ def __init__(
196
+ self,
197
+ engine: Engine,
198
+ dim: int,
199
+ optimizer: network.OptimizerLoader,
200
+ schedulers: dict[str, network.LRSchedulersLoader],
201
+ outputs_criterions: dict[str, network.TargetCriterionsLoader],
202
+ ) -> None:
203
+ super().__init__(
204
+ in_channels=1, optimizer=optimizer, schedulers=schedulers, outputs_criterions=outputs_criterions, dim=dim
205
+ )
206
+ self.add_module("DisplacementField", Registration(engine), in_branch=[0, 1, 2, 3], out_branch=["dvf"])
ANTs_SyN/model.py ADDED
@@ -0,0 +1,172 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ # Copyright (c) 2025 Valentin Boussot
2
+ #
3
+ # Licensed under the Apache License, Version 2.0 (the "License");
4
+ # you may not use this file except in compliance with the License.
5
+ # You may obtain a copy of the License at
6
+ #
7
+ # http://www.apache.org/licenses/LICENSE-2.0
8
+ #
9
+ # Unless required by applicable law or agreed to in writing, software
10
+ # distributed under the License is distributed on an "AS IS" BASIS,
11
+ # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12
+ # See the License for the specific language governing permissions and
13
+ # limitations under the License.
14
+ #
15
+ # SPDX-License-Identifier: Apache-2.0
16
+
17
+ """ANTs SyN as the Learn2Reg 2024 organisers ran it for LUMIR, ``ants.registration(..., "antsRegistrationSyN[so]")``:
18
+ the ``antsRegistration`` command ANTsPy builds for it, on the ANTs release binaries at a pinned version. SyN alone
19
+ from the identity, cross-correlation of radius 2, 100x70x50x20 iterations at shrink factors 8x4x2x1, single precision,
20
+ a fixed random seed; then ``antsApplyTransforms`` writes the field on the fixed grid. Modalities and masks are
21
+ accepted and ignored: the organisers' call uses neither.
22
+
23
+ NOTE: do NOT add ``from __future__ import annotations``: KonfAI's config engine relies on runtime-evaluated
24
+ annotations (``get_origin``); PEP 563 stringized annotations break binding.
25
+ """
26
+
27
+ import os
28
+ import subprocess # nosec B404
29
+ import tempfile
30
+ from pathlib import Path
31
+ from typing import Annotated
32
+
33
+ import numpy as np
34
+ import SimpleITK as sitk
35
+ from konfai.network import network
36
+
37
+ from baselines import BaselineNet, pinned_archive
38
+
39
+ VERSION = "2.6.5"
40
+ RELEASE = (
41
+ "https://github.com/ANTsX/ANTs/releases/download/v2.6.5/ants-2.6.5-ubuntu-24.04-X64-gcc.zip",
42
+ "9f6a2c8881d6c94ea17171c0502e55cb898ad9afd50e4e23fde9a8c0997aa04b",
43
+ )
44
+
45
+
46
+ def binaries() -> Path:
47
+ """The release's ``bin/``, fetched once."""
48
+ return pinned_archive("ants", *RELEASE) / f"ants-{VERSION}"
49
+
50
+
51
+ class AntsSyN:
52
+ def __init__(
53
+ self,
54
+ transform: str,
55
+ metric: str,
56
+ convergence: str,
57
+ shrink_factors: str,
58
+ smoothing_sigmas: str,
59
+ seed: int,
60
+ threads: int,
61
+ ) -> None:
62
+ self._transform, self._metric, self._convergence = transform, metric, convergence
63
+ self._shrink, self._smoothing, self._seed, self._threads = shrink_factors, smoothing_sigmas, seed, threads
64
+
65
+ def __call__(
66
+ self,
67
+ fixed: sitk.Image,
68
+ moving: sitk.Image,
69
+ fixed_mask: sitk.Image | None,
70
+ moving_mask: sitk.Image | None,
71
+ device: int,
72
+ ) -> np.ndarray:
73
+ root = binaries()
74
+ environment = {
75
+ **os.environ,
76
+ "PATH": f"{root / 'bin'}:{os.environ.get('PATH', '')}",
77
+ "LD_LIBRARY_PATH": f"{root / 'lib'}:{os.environ.get('LD_LIBRARY_PATH', '')}",
78
+ "ITK_GLOBAL_DEFAULT_NUMBER_OF_THREADS": str(self._threads or os.cpu_count() or 1),
79
+ }
80
+ with tempfile.TemporaryDirectory(prefix="ants_") as scratch:
81
+ work = Path(scratch)
82
+ sitk.WriteImage(fixed, str(work / "fixed.nii.gz"))
83
+ sitk.WriteImage(moving, str(work / "moving.nii.gz"))
84
+ metric = self._metric.replace("FIXED", str(work / "fixed.nii.gz")).replace(
85
+ "MOVING", str(work / "moving.nii.gz")
86
+ )
87
+ subprocess.run( # nosec B603 B607
88
+ [
89
+ "antsRegistration",
90
+ "--dimensionality",
91
+ "3",
92
+ "-r",
93
+ "Identity",
94
+ "--output",
95
+ str(work / "ants"),
96
+ "--transform",
97
+ self._transform,
98
+ "--metric",
99
+ metric,
100
+ "--convergence",
101
+ self._convergence,
102
+ "--shrink-factors",
103
+ self._shrink,
104
+ "--smoothing-sigmas",
105
+ self._smoothing,
106
+ "-x",
107
+ "[NA,NA]",
108
+ "--random-seed",
109
+ str(self._seed),
110
+ "--float",
111
+ "1",
112
+ "--write-composite-transform",
113
+ "0",
114
+ ],
115
+ check=True,
116
+ env=environment,
117
+ )
118
+ # the warp's number follows the stages, the identity initialisation counted or not as the version chooses
119
+ warp = next(p for p in sorted(work.glob("ants*Warp.nii.gz")) if "InverseWarp" not in p.name)
120
+ subprocess.run( # nosec B603 B607
121
+ [
122
+ "antsApplyTransforms",
123
+ "-d",
124
+ "3",
125
+ "-r",
126
+ str(work / "fixed.nii.gz"),
127
+ "-t",
128
+ str(warp),
129
+ "-o",
130
+ f"DisplacementField[{work / 'field.nii.gz'}]",
131
+ "--float",
132
+ "1",
133
+ ],
134
+ check=True,
135
+ env=environment,
136
+ )
137
+ field = sitk.ReadImage(str(work / "field.nii.gz"), sitk.sitkVectorFloat32)
138
+ return np.ascontiguousarray(np.moveaxis(sitk.GetArrayFromImage(field), -1, 0), dtype=np.float32)
139
+
140
+
141
+ class RegistrationNet(BaselineNet):
142
+ """ANTs SyN, the Learn2Reg 2024 organisers' call. CPU."""
143
+
144
+ def __init__(
145
+ self,
146
+ optimizer: network.OptimizerLoader = network.OptimizerLoader(),
147
+ schedulers: dict[str, network.LRSchedulersLoader] = {
148
+ "default:ReduceLROnPlateau": network.LRSchedulersLoader(0)
149
+ },
150
+ outputs_criterions: dict[str, network.TargetCriterionsLoader] = {"default": network.TargetCriterionsLoader()},
151
+ transform: Annotated[
152
+ str, "antsRegistration's --transform: SyN[gradient step, update field variance, total field variance]."
153
+ ] = "SyN[0.2,3,0]",
154
+ metric: Annotated[
155
+ str,
156
+ "antsRegistration's --metric, FIXED and MOVING standing for the images: CC[fixed, moving, weight, radius].",
157
+ ] = "CC[FIXED,MOVING,1,2]",
158
+ convergence: Annotated[
159
+ str, "antsRegistration's --convergence: iterations per level, threshold, window."
160
+ ] = "[100x70x50x20,1e-6,10]",
161
+ shrink_factors: Annotated[str, "antsRegistration's --shrink-factors."] = "8x4x2x1",
162
+ smoothing_sigmas: Annotated[str, "antsRegistration's --smoothing-sigmas."] = "3x2x1x0vox",
163
+ seed: Annotated[int, "antsRegistration's --random-seed, the one setting not in ANTsPy's call."] = 1,
164
+ threads: Annotated[int, "ITK threads; 0 takes every core."] = 0,
165
+ ) -> None:
166
+ super().__init__(
167
+ AntsSyN(transform, metric, convergence, shrink_factors, smoothing_sigmas, seed, threads),
168
+ 3,
169
+ optimizer,
170
+ schedulers,
171
+ outputs_criterions,
172
+ )
ANTs_SyN/requirements.txt ADDED
@@ -0,0 +1 @@
 
 
1
+ SimpleITK
Anatomix_ConvexAdam/Prediction.yml ADDED
@@ -0,0 +1,86 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ Predictor:
2
+ Model:
3
+ classpath: model:RegistrationNet
4
+ RegistrationNet:
5
+ fixed_modality: auto
6
+ moving_modality: auto
7
+ outputs_criterions: None
8
+ Dataset:
9
+ groups_src:
10
+ Volume_0:
11
+ groups_dest:
12
+ Fixed:
13
+ transforms:
14
+ TensorCast:
15
+ dtype: float32
16
+ inverse: false
17
+ patch_transforms: None
18
+ is_input: true
19
+ Volume_1:
20
+ groups_dest:
21
+ Moving:
22
+ transforms:
23
+ TensorCast:
24
+ dtype: float32
25
+ inverse: false
26
+ patch_transforms: None
27
+ is_input: true
28
+ Volume_2:
29
+ groups_dest:
30
+ FixedMask:
31
+ transforms:
32
+ TensorCast:
33
+ dtype: float32
34
+ inverse: false
35
+ patch_transforms: None
36
+ is_input: true
37
+ Volume_3:
38
+ groups_dest:
39
+ MovingMask:
40
+ transforms:
41
+ TensorCast:
42
+ dtype: float32
43
+ inverse: false
44
+ patch_transforms: None
45
+ is_input: true
46
+ augmentations: None
47
+ Patch:
48
+ patch_size:
49
+ - 0
50
+ - 0
51
+ - 0
52
+ overlap: 0
53
+ pad_value: None
54
+ extend_slice: 0
55
+ mode: resample
56
+ max_voxels: None
57
+ subset: None
58
+ dataset_filenames:
59
+ - ./Dataset/:mha
60
+ batch_size: 1
61
+ num_workers: None
62
+ pin_memory: false
63
+ prefetch_factor: None
64
+ persistent_workers: None
65
+ outputs_dataset:
66
+ DisplacementField:
67
+ OutputDataset:
68
+ name_class: OutputDataset
69
+ before_reduction_transforms: None
70
+ after_reduction_transforms: None
71
+ final_transforms:
72
+ TensorCast:
73
+ dtype: float32
74
+ inverse: false
75
+ dataset_filename: DisplacementField:mha
76
+ group: DisplacementField
77
+ same_as_group: Volume_0:Fixed
78
+ patch_combine: Cosinus
79
+ reduction: Mean
80
+ Mean: {}
81
+ train_name: Baselines-Anatomix_ConvexAdam
82
+ manual_seed: 42
83
+ gpu_checkpoints: None
84
+ combine: Mean
85
+ autocast: false
86
+ data_log: None
Anatomix_ConvexAdam/app.json ADDED
@@ -0,0 +1,40 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ {
2
+ "display_name": "anatomix + ConvexAdam",
3
+ "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 <code>anatomix_convexadam</code>.",
4
+ "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 <code>anatomix_convexadam</code>. 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).",
5
+ "task": "registration",
6
+ "tta": 0,
7
+ "mc_dropout": 0,
8
+ "models": [],
9
+ "inputs": {
10
+ "Fixed": {
11
+ "display_name": "Fixed image",
12
+ "volume_type": "VOLUME",
13
+ "required": true
14
+ },
15
+ "Moving": {
16
+ "display_name": "Moving image",
17
+ "volume_type": "VOLUME",
18
+ "required": true
19
+ },
20
+ "FixedMask": {
21
+ "display_name": "Fixed mask (ignored by this baseline)",
22
+ "volume_type": "SEGMENTATION",
23
+ "required": false,
24
+ "default": "ones"
25
+ },
26
+ "MovingMask": {
27
+ "display_name": "Moving mask (ignored by this baseline)",
28
+ "volume_type": "SEGMENTATION",
29
+ "required": false,
30
+ "default": "ones"
31
+ }
32
+ },
33
+ "outputs": {
34
+ "DisplacementField": {
35
+ "display_name": "Displacement field",
36
+ "volume_type": "VOLUME",
37
+ "required": true
38
+ }
39
+ }
40
+ }
Anatomix_ConvexAdam/baselines.py ADDED
@@ -0,0 +1,206 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ # Copyright (c) 2025 Valentin Boussot
2
+ #
3
+ # Licensed under the Apache License, Version 2.0 (the "License");
4
+ # you may not use this file except in compliance with the License.
5
+ # You may obtain a copy of the License at
6
+ #
7
+ # http://www.apache.org/licenses/LICENSE-2.0
8
+ #
9
+ # Unless required by applicable law or agreed to in writing, software
10
+ # distributed under the License is distributed on an "AS IS" BASIS,
11
+ # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12
+ # See the License for the specific language governing permissions and
13
+ # limitations under the License.
14
+ #
15
+ # SPDX-License-Identifier: Apache-2.0
16
+
17
+ """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
18
+ engine and gets a displacement field back, and the field's convention.
19
+
20
+ The field is the benchmark's: one component per spatial axis, in mm along the world (ITK, LPS) axes, on the fixed
21
+ image's grid, such that the fixed point ``x`` matches ``x + u(x)`` in the moving image. The predictor attaches the
22
+ fixed image's geometry to the output (``same_as_group: Volume_0:Fixed`` in the app's ``Prediction.yml``).
23
+
24
+ NOTE: do NOT add ``from __future__ import annotations``: KonfAI's config engine relies on runtime-evaluated
25
+ annotations (``get_origin``); PEP 563 stringized annotations break binding.
26
+ """
27
+
28
+ import hashlib
29
+ import os
30
+ import shutil
31
+ import subprocess # nosec B404
32
+ import urllib.request
33
+ import zipfile
34
+ from collections.abc import Callable
35
+ from pathlib import Path
36
+
37
+ import numpy as np
38
+ import SimpleITK as sitk
39
+ import torch
40
+ from konfai.network import network
41
+ from konfai.utils.dataset import Attribute, data_to_image
42
+
43
+ #: An engine: (fixed, moving, fixed mask or None, moving mask or None, CUDA device index or -1) -> the field,
44
+ #: ``[D, *spatial]`` in mm along the world axes on the fixed grid.
45
+ Engine = Callable[[sitk.Image, sitk.Image, sitk.Image | None, sitk.Image | None, int], np.ndarray]
46
+
47
+
48
+ def cache_dir() -> Path:
49
+ """Where the authors' code and binaries live, once fetched: ``$BASELINES_KONFAI_CACHE`` or
50
+ ``~/.cache/baselines-konfai``."""
51
+ return Path(os.environ.get("BASELINES_KONFAI_CACHE", Path.home() / ".cache" / "baselines-konfai"))
52
+
53
+
54
+ def pinned_source(name: str, url: str, commit: str) -> Path:
55
+ """The authors' repository at ``commit``, cloned once into the cache: a baseline runs the code it was
56
+ measured with, never a moving branch."""
57
+ target = cache_dir() / f"{name}-{commit[:12]}"
58
+ if not (target / ".git").exists():
59
+ target.parent.mkdir(parents=True, exist_ok=True)
60
+ subprocess.run(["git", "clone", "--quiet", url, str(target)], check=True) # nosec B603 B607
61
+ subprocess.run(["git", "-C", str(target), "checkout", "--quiet", commit], check=True) # nosec B603 B607
62
+ return target
63
+
64
+
65
+ def fetch(url: str, target: Path, sha256: str | None = None) -> Path:
66
+ """``url`` downloaded once to ``target`` and, when a hash is given, checked against it."""
67
+ if not target.exists():
68
+ target.parent.mkdir(parents=True, exist_ok=True)
69
+ part = target.with_name(target.name + ".part")
70
+ urllib.request.urlretrieve(url, part) # nosec B310 - the authors' release, checked below
71
+ with part.open("rb") as stream:
72
+ digest = hashlib.file_digest(stream, "sha256").hexdigest()
73
+ if sha256 and digest != sha256:
74
+ part.unlink()
75
+ raise RuntimeError(f"{url} does not match its recorded hash")
76
+ part.rename(target)
77
+ return target
78
+
79
+
80
+ def pinned_archive(name: str, url: str, sha256: str) -> Path:
81
+ """A release archive at ``url``, downloaded once into the cache, checked against ``sha256`` and unpacked: the
82
+ binaries a baseline was measured with."""
83
+ target = cache_dir() / f"{name}-{sha256[:12]}"
84
+ if not (target / ".unpacked").exists():
85
+ archive = fetch(url, target / "archive", sha256)
86
+ if zipfile.is_zipfile(archive):
87
+ with zipfile.ZipFile(archive) as packed:
88
+ packed.extractall(target) # nosec B202 - our own pinned archive
89
+ for entry in packed.infolist(): # zipfile drops the modes: the binaries must stay executable
90
+ if mode := (entry.external_attr >> 16) & 0o777:
91
+ (target / entry.filename).chmod(mode)
92
+ else:
93
+ shutil.unpack_archive(str(archive), str(target), "gztar")
94
+ archive.unlink()
95
+ (target / ".unpacked").touch()
96
+ return target
97
+
98
+
99
+ def pinned_environment(root: Path, python: str, installs: list[list[str]]) -> Path:
100
+ """A virtual environment at ``root/venv`` on its own Python, made once by uv (``pip install uv``): for the tools
101
+ whose pins do not run on the host's Python. ``installs`` are ``pip install`` argument lists, run in order."""
102
+ try:
103
+ import uv
104
+
105
+ command = uv.find_uv_bin()
106
+ except ImportError:
107
+ command = shutil.which("uv") or ""
108
+ if not command:
109
+ raise RuntimeError("this baseline builds its own Python environment with uv: pip install uv")
110
+ venv = root / "venv"
111
+ if not (venv / ".ready").exists():
112
+ subprocess.run([command, "venv", "--quiet", "--clear", "--python", python, str(venv)], check=True) # nosec B603
113
+ for arguments in installs:
114
+ subprocess.run( # nosec B603
115
+ [
116
+ command,
117
+ "pip",
118
+ "install",
119
+ "--quiet",
120
+ "--no-cache",
121
+ "--python",
122
+ str(venv / "bin" / "python"),
123
+ *arguments,
124
+ ],
125
+ check=True,
126
+ )
127
+ (venv / ".ready").touch()
128
+ return venv
129
+
130
+
131
+ def built_source(name: str, url: str, commit: str, build: Callable[[Path], None]) -> Path:
132
+ """The authors' repository at ``commit``, built once by ``build`` (a marker says it is done)."""
133
+ source = pinned_source(name, url, commit)
134
+ if not (source / ".built").exists():
135
+ build(source)
136
+ (source / ".built").touch()
137
+ return source
138
+
139
+
140
+ def field_from_voxels(displacement: np.ndarray, fixed: sitk.Image) -> np.ndarray:
141
+ """A displacement in voxels along the index axes, ``[i, j, k, D]``, as the benchmark's field ``[D, k, j, i]``
142
+ in mm along the world axes: ``u = D S d``, with ``D`` the direction and ``S`` the spacing of the fixed image."""
143
+ n = fixed.GetDimension()
144
+ to_world = np.array(fixed.GetDirection()).reshape(n, n) @ np.diag(fixed.GetSpacing())
145
+ world = displacement.astype(np.float64) @ to_world.T # [i, j, k, D]
146
+ return np.ascontiguousarray(np.moveaxis(world, -1, 0).transpose(0, *reversed(range(1, n + 1))), dtype=np.float32)
147
+
148
+
149
+ def to_index_array(image: sitk.Image) -> np.ndarray:
150
+ """The image as a ``[i, j, k]`` array, the index axes in ITK's order, which the tools indexed that way read."""
151
+ return np.ascontiguousarray(sitk.GetArrayFromImage(image).transpose(*reversed(range(image.GetDimension()))))
152
+
153
+
154
+ class Registration(torch.nn.Module):
155
+ """Graph module: the pair's tensors and their geometry in, the field out, through the engine, one sample at
156
+ a time. ``accepts_attributes = True`` opts it into the per-branch ``Attribute`` list (the convention of
157
+ ``CriterionWithAttribute``): registration needs the physical geometry."""
158
+
159
+ accepts_attributes = True
160
+
161
+ def __init__(self, engine: Engine) -> None:
162
+ super().__init__()
163
+ self._engine = engine
164
+
165
+ def forward(
166
+ self,
167
+ fixed: torch.Tensor,
168
+ moving: torch.Tensor,
169
+ fixed_mask: torch.Tensor,
170
+ moving_mask: torch.Tensor,
171
+ attributes: list[list[Attribute]],
172
+ ) -> torch.Tensor:
173
+ fixed_attrs, moving_attrs, fixed_mask_attrs, moving_mask_attrs = attributes
174
+ device_index = fixed.device.index if fixed.device.type == "cuda" else -1
175
+ fields = []
176
+ # the engines optimise with autograd; the predictor calls forward under inference mode
177
+ with torch.inference_mode(False), torch.enable_grad():
178
+ for b in range(fixed.shape[0]):
179
+ images = [
180
+ data_to_image(t[b].detach().cpu().numpy(), attrs[b])
181
+ for t, attrs in ((fixed, fixed_attrs), (moving, moving_attrs))
182
+ ]
183
+ masks = [
184
+ data_to_image(t[b].detach().cpu().numpy(), attrs[b]) if not bool((t[b] == 1).all()) else None
185
+ for t, attrs in ((fixed_mask, fixed_mask_attrs), (moving_mask, moving_mask_attrs))
186
+ ]
187
+ fields.append(torch.from_numpy(self._engine(images[0], images[1], masks[0], masks[1], device_index)))
188
+ return torch.stack(fields, dim=0).to(fixed.device)
189
+
190
+
191
+ class BaselineNet(network.Network):
192
+ """A baseline as an ``add_module`` graph: fixed = branch 0, moving = branch 1, the masks branches 2 and 3 (a
193
+ mask of ones means none). The one output is ``DisplacementField``, on the fixed grid."""
194
+
195
+ def __init__(
196
+ self,
197
+ engine: Engine,
198
+ dim: int,
199
+ optimizer: network.OptimizerLoader,
200
+ schedulers: dict[str, network.LRSchedulersLoader],
201
+ outputs_criterions: dict[str, network.TargetCriterionsLoader],
202
+ ) -> None:
203
+ super().__init__(
204
+ in_channels=1, optimizer=optimizer, schedulers=schedulers, outputs_criterions=outputs_criterions, dim=dim
205
+ )
206
+ self.add_module("DisplacementField", Registration(engine), in_branch=[0, 1, 2, 3], out_branch=["dvf"])
Anatomix_ConvexAdam/model.py ADDED
@@ -0,0 +1,165 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ # Copyright (c) 2025 Valentin Boussot
2
+ #
3
+ # Licensed under the Apache License, Version 2.0 (the "License");
4
+ # you may not use this file except in compliance with the License.
5
+ # You may obtain a copy of the License at
6
+ #
7
+ # http://www.apache.org/licenses/LICENSE-2.0
8
+ #
9
+ # Unless required by applicable law or agreed to in writing, software
10
+ # distributed under the License is distributed on an "AS IS" BASIS,
11
+ # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12
+ # See the License for the specific language governing permissions and
13
+ # limitations under the License.
14
+ #
15
+ # SPDX-License-Identifier: Apache-2.0
16
+
17
+ """anatomix features in ConvexAdam, the ICLR 2025 pipeline of neel-dey/anatomix at a pinned commit, through its own
18
+ ``convex_adam()`` with the defaults of its command-line script: 16 anatomix channels and 12 MIND-SSC channels compared
19
+ 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
20
+ [-450, 450] HU as in the README. The weights come from the authors' Hugging Face repository at a pinned revision.
21
+
22
+ NOTE: do NOT add ``from __future__ import annotations``: KonfAI's config engine relies on runtime-evaluated
23
+ annotations (``get_origin``); PEP 563 stringized annotations break binding.
24
+ """
25
+
26
+ import glob
27
+ import hashlib
28
+ import os
29
+ import sys
30
+ import tempfile
31
+ from typing import Annotated
32
+
33
+ import numpy as np
34
+ import SimpleITK as sitk
35
+ from konfai.network import network
36
+ from konfai.utils.config import Choices
37
+
38
+ from baselines import BaselineNet, cache_dir, pinned_source
39
+
40
+ REPOSITORY = "https://github.com/neel-dey/anatomix"
41
+ COMMIT = "4c86aeeca5e4bf712d9e5775a01fadb37b30c13a" # main, 2026-09-19
42
+ WEIGHTS = ("neeldey/anatomix", "anatomix.pth", "842cfe9", None) # repo, file, revision, sha256 (checked when known)
43
+ CT_WINDOW = (-450.0, 450.0)
44
+ SETTINGS = {
45
+ "hf_variant": "anatomix",
46
+ "lambda_weight": 0.75,
47
+ "grid_sp": 2,
48
+ "disp_hw": 1,
49
+ "selected_niter": 80,
50
+ "selected_smooth": 0,
51
+ "grid_sp_adam": 2,
52
+ "ic": True,
53
+ "use_mask": False,
54
+ }
55
+
56
+
57
+ def to_field(displacement: np.ndarray, fixed: sitk.Image) -> np.ndarray:
58
+ """The backend's displacement, ``(I, J, K, 3)`` on the even-padded fixed grid in voxels, as the field on the
59
+ unpadded fixed grid in mm along the world axes: the backend's grid_sample convention scales by n / (n - 1)."""
60
+ n = np.array(displacement.shape[:3], float)
61
+ d = (displacement * (n / (n - 1)))[tuple(slice(s) for s in fixed.GetSize())]
62
+ u = (d * fixed.GetSpacing()) @ np.reshape(fixed.GetDirection(), (3, 3)).T
63
+ return np.ascontiguousarray(np.moveaxis(u.transpose(2, 1, 0, 3), -1, 0), dtype=np.float32)
64
+
65
+
66
+ def weights_home() -> str:
67
+ """A Hugging Face home of our own, with the authors' weights at the pinned revision and refs/main pointing at
68
+ it: the pipeline loads them with ``revision=None`` and would otherwise follow their main branch."""
69
+ from huggingface_hub import hf_hub_download
70
+
71
+ home = cache_dir() / "anatomix" / "hf_home"
72
+ repo, filename, revision, digest = WEIGHTS
73
+ os.environ.setdefault("HF_HOME", str(home))
74
+ path = hf_hub_download(repo, filename, revision=revision, cache_dir=str(home / "hub"))
75
+ if digest and hashlib.sha256(open(path, "rb").read()).hexdigest() != digest:
76
+ raise RuntimeError("the anatomix weights do not match their published hash")
77
+ refs = home / "hub" / f"models--{repo.replace('/', '--')}" / "refs"
78
+ refs.mkdir(parents=True, exist_ok=True)
79
+ (refs / "main").write_text(revision)
80
+ return str(home)
81
+
82
+
83
+ class AnatomixConvexAdam:
84
+ def __init__(self, fixed_modality: str, moving_modality: str) -> None:
85
+ self._modalities = (fixed_modality, moving_modality)
86
+
87
+ def __call__(
88
+ self,
89
+ fixed: sitk.Image,
90
+ moving: sitk.Image,
91
+ fixed_mask: sitk.Image | None,
92
+ moving_mask: sitk.Image | None,
93
+ device: int,
94
+ ) -> np.ndarray:
95
+ import nibabel as nib
96
+
97
+ source = pinned_source("anatomix", REPOSITORY, COMMIT)
98
+ if str(source) not in sys.path:
99
+ sys.path.insert(0, str(source))
100
+ os.environ["HF_HOME"] = weights_home()
101
+ os.environ["HF_HUB_OFFLINE"] = "1"
102
+ from anatomix.registration.registration_backend.convexadam import convex_adam
103
+
104
+ fixed, moving = sitk.Cast(fixed, sitk.sitkFloat32), sitk.Cast(moving, sitk.sitkFloat32)
105
+ if min(fixed.GetSize()) < 8:
106
+ raise ValueError(f"anatomix ConvexAdam needs at least 8 voxels per axis: {fixed.GetSize()}")
107
+ moving = sitk.Resample(
108
+ moving,
109
+ fixed,
110
+ sitk.Transform(),
111
+ sitk.sitkLinear,
112
+ float(sitk.GetArrayViewFromImage(moving).min()),
113
+ sitk.sitkFloat32,
114
+ )
115
+ pad = [(0, s % 2) for s in fixed.GetSize()]
116
+ modalities = [
117
+ m if m != "auto" else ("ct" if float(sitk.GetArrayViewFromImage(i).min()) < -200 else "mr")
118
+ for m, i in zip(self._modalities, (fixed, moving), strict=True)
119
+ ]
120
+ clips = [CT_WINDOW if m == "ct" else (None, None) for m in modalities]
121
+ with tempfile.TemporaryDirectory(prefix="anatomix_") as scratch:
122
+ paths = []
123
+ for name, image in (("fixed", fixed), ("moving", moving)):
124
+ array = np.pad(sitk.GetArrayFromImage(image).transpose(2, 1, 0), pad, mode="edge")
125
+ paths.append(os.path.join(scratch, f"{name}.nii"))
126
+ nib.save(nib.Nifti1Image(array, np.eye(4)), paths[-1])
127
+ convex_adam(
128
+ expname="bench",
129
+ result_path=scratch,
130
+ fixed_image=paths[0],
131
+ moving_image=paths[1],
132
+ fixed_minclip=clips[0][0],
133
+ fixed_maxclip=clips[0][1],
134
+ moving_minclip=clips[1][0],
135
+ moving_maxclip=clips[1][1],
136
+ **SETTINGS,
137
+ )
138
+ displacement = nib.load(glob.glob(os.path.join(scratch, "disp_*.nii.gz"))[0]).get_fdata(dtype=np.float32)
139
+ return to_field(displacement, fixed)
140
+
141
+
142
+ class RegistrationNet(BaselineNet):
143
+ """anatomix + ConvexAdam, the authors' pipeline with the defaults of their script. A GPU is needed."""
144
+
145
+ def __init__(
146
+ self,
147
+ optimizer: network.OptimizerLoader = network.OptimizerLoader(),
148
+ schedulers: dict[str, network.LRSchedulersLoader] = {
149
+ "default:ReduceLROnPlateau": network.LRSchedulersLoader(0)
150
+ },
151
+ outputs_criterions: dict[str, network.TargetCriterionsLoader] = {"default": network.TargetCriterionsLoader()},
152
+ fixed_modality: Annotated[
153
+ str,
154
+ Choices(["auto", "ct", "mr"]),
155
+ "ct clips the fixed image to [-450, 450] HU; auto reads it off the intensities.",
156
+ ] = "auto",
157
+ moving_modality: Annotated[
158
+ str,
159
+ Choices(["auto", "ct", "mr"]),
160
+ "ct clips the moving image to [-450, 450] HU; auto reads it off the intensities.",
161
+ ] = "auto",
162
+ ) -> None:
163
+ super().__init__(
164
+ AnatomixConvexAdam(fixed_modality, moving_modality), 3, optimizer, schedulers, outputs_criterions
165
+ )
Anatomix_ConvexAdam/requirements.txt ADDED
@@ -0,0 +1,5 @@
 
 
 
 
 
 
1
+ SimpleITK
2
+ nibabel
3
+ monai==1.6.1
4
+ huggingface_hub
5
+ scikit-learn
BrainMorph/Prediction.yml ADDED
@@ -0,0 +1,87 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ Predictor:
2
+ Model:
3
+ classpath: model:RegistrationNet
4
+ RegistrationNet:
5
+ keypoints: 512
6
+ variant: H
7
+ align: tps_0
8
+ outputs_criterions: None
9
+ Dataset:
10
+ groups_src:
11
+ Volume_0:
12
+ groups_dest:
13
+ Fixed:
14
+ transforms:
15
+ TensorCast:
16
+ dtype: float32
17
+ inverse: false
18
+ patch_transforms: None
19
+ is_input: true
20
+ Volume_1:
21
+ groups_dest:
22
+ Moving:
23
+ transforms:
24
+ TensorCast:
25
+ dtype: float32
26
+ inverse: false
27
+ patch_transforms: None
28
+ is_input: true
29
+ Volume_2:
30
+ groups_dest:
31
+ FixedMask:
32
+ transforms:
33
+ TensorCast:
34
+ dtype: float32
35
+ inverse: false
36
+ patch_transforms: None
37
+ is_input: true
38
+ Volume_3:
39
+ groups_dest:
40
+ MovingMask:
41
+ transforms:
42
+ TensorCast:
43
+ dtype: float32
44
+ inverse: false
45
+ patch_transforms: None
46
+ is_input: true
47
+ augmentations: None
48
+ Patch:
49
+ patch_size:
50
+ - 0
51
+ - 0
52
+ - 0
53
+ overlap: 0
54
+ pad_value: None
55
+ extend_slice: 0
56
+ mode: resample
57
+ max_voxels: None
58
+ subset: None
59
+ dataset_filenames:
60
+ - ./Dataset/:mha
61
+ batch_size: 1
62
+ num_workers: None
63
+ pin_memory: false
64
+ prefetch_factor: None
65
+ persistent_workers: None
66
+ outputs_dataset:
67
+ DisplacementField:
68
+ OutputDataset:
69
+ name_class: OutputDataset
70
+ before_reduction_transforms: None
71
+ after_reduction_transforms: None
72
+ final_transforms:
73
+ TensorCast:
74
+ dtype: float32
75
+ inverse: false
76
+ dataset_filename: DisplacementField:mha
77
+ group: DisplacementField
78
+ same_as_group: Volume_0:Fixed
79
+ patch_combine: Cosinus
80
+ reduction: Mean
81
+ Mean: {}
82
+ train_name: Baselines-BrainMorph
83
+ manual_seed: 42
84
+ gpu_checkpoints: None
85
+ combine: Mean
86
+ autocast: false
87
+ data_log: None
BrainMorph/app.json ADDED
@@ -0,0 +1,40 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ {
2
+ "display_name": "BrainMorph",
3
+ "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 <code>brainmorph</code>.",
4
+ "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 <code>brainmorph</code>. Brain MR, aligned pairs. <a href='https://github.com/alanqrwang/brainmorph/tree/106b029d6048d3d9d2f73cf7996a0b0813cbc4ae'>The authors' repository</a> 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 <code>--gpu</code>). Masks are ignored by this baseline. Output: the displacement field on the fixed grid, in mm along the world axes (ITK, LPS).<br><br><b>How to cite:</b><br><cite>A. Q. Wang et al., <i>BrainMorph: A foundational keypoint model for robust and flexible brain MRI registration</i>, MELBA 2025.</cite>",
5
+ "task": "registration",
6
+ "tta": 0,
7
+ "mc_dropout": 0,
8
+ "models": [],
9
+ "inputs": {
10
+ "Fixed": {
11
+ "display_name": "Fixed image",
12
+ "volume_type": "VOLUME",
13
+ "required": true
14
+ },
15
+ "Moving": {
16
+ "display_name": "Moving image",
17
+ "volume_type": "VOLUME",
18
+ "required": true
19
+ },
20
+ "FixedMask": {
21
+ "display_name": "Fixed mask (ignored by this baseline)",
22
+ "volume_type": "SEGMENTATION",
23
+ "required": false,
24
+ "default": "ones"
25
+ },
26
+ "MovingMask": {
27
+ "display_name": "Moving mask (ignored by this baseline)",
28
+ "volume_type": "SEGMENTATION",
29
+ "required": false,
30
+ "default": "ones"
31
+ }
32
+ },
33
+ "outputs": {
34
+ "DisplacementField": {
35
+ "display_name": "Displacement field",
36
+ "volume_type": "VOLUME",
37
+ "required": true
38
+ }
39
+ }
40
+ }
BrainMorph/baselines.py ADDED
@@ -0,0 +1,206 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ # Copyright (c) 2025 Valentin Boussot
2
+ #
3
+ # Licensed under the Apache License, Version 2.0 (the "License");
4
+ # you may not use this file except in compliance with the License.
5
+ # You may obtain a copy of the License at
6
+ #
7
+ # http://www.apache.org/licenses/LICENSE-2.0
8
+ #
9
+ # Unless required by applicable law or agreed to in writing, software
10
+ # distributed under the License is distributed on an "AS IS" BASIS,
11
+ # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12
+ # See the License for the specific language governing permissions and
13
+ # limitations under the License.
14
+ #
15
+ # SPDX-License-Identifier: Apache-2.0
16
+
17
+ """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
18
+ engine and gets a displacement field back, and the field's convention.
19
+
20
+ The field is the benchmark's: one component per spatial axis, in mm along the world (ITK, LPS) axes, on the fixed
21
+ image's grid, such that the fixed point ``x`` matches ``x + u(x)`` in the moving image. The predictor attaches the
22
+ fixed image's geometry to the output (``same_as_group: Volume_0:Fixed`` in the app's ``Prediction.yml``).
23
+
24
+ NOTE: do NOT add ``from __future__ import annotations``: KonfAI's config engine relies on runtime-evaluated
25
+ annotations (``get_origin``); PEP 563 stringized annotations break binding.
26
+ """
27
+
28
+ import hashlib
29
+ import os
30
+ import shutil
31
+ import subprocess # nosec B404
32
+ import urllib.request
33
+ import zipfile
34
+ from collections.abc import Callable
35
+ from pathlib import Path
36
+
37
+ import numpy as np
38
+ import SimpleITK as sitk
39
+ import torch
40
+ from konfai.network import network
41
+ from konfai.utils.dataset import Attribute, data_to_image
42
+
43
+ #: An engine: (fixed, moving, fixed mask or None, moving mask or None, CUDA device index or -1) -> the field,
44
+ #: ``[D, *spatial]`` in mm along the world axes on the fixed grid.
45
+ Engine = Callable[[sitk.Image, sitk.Image, sitk.Image | None, sitk.Image | None, int], np.ndarray]
46
+
47
+
48
+ def cache_dir() -> Path:
49
+ """Where the authors' code and binaries live, once fetched: ``$BASELINES_KONFAI_CACHE`` or
50
+ ``~/.cache/baselines-konfai``."""
51
+ return Path(os.environ.get("BASELINES_KONFAI_CACHE", Path.home() / ".cache" / "baselines-konfai"))
52
+
53
+
54
+ def pinned_source(name: str, url: str, commit: str) -> Path:
55
+ """The authors' repository at ``commit``, cloned once into the cache: a baseline runs the code it was
56
+ measured with, never a moving branch."""
57
+ target = cache_dir() / f"{name}-{commit[:12]}"
58
+ if not (target / ".git").exists():
59
+ target.parent.mkdir(parents=True, exist_ok=True)
60
+ subprocess.run(["git", "clone", "--quiet", url, str(target)], check=True) # nosec B603 B607
61
+ subprocess.run(["git", "-C", str(target), "checkout", "--quiet", commit], check=True) # nosec B603 B607
62
+ return target
63
+
64
+
65
+ def fetch(url: str, target: Path, sha256: str | None = None) -> Path:
66
+ """``url`` downloaded once to ``target`` and, when a hash is given, checked against it."""
67
+ if not target.exists():
68
+ target.parent.mkdir(parents=True, exist_ok=True)
69
+ part = target.with_name(target.name + ".part")
70
+ urllib.request.urlretrieve(url, part) # nosec B310 - the authors' release, checked below
71
+ with part.open("rb") as stream:
72
+ digest = hashlib.file_digest(stream, "sha256").hexdigest()
73
+ if sha256 and digest != sha256:
74
+ part.unlink()
75
+ raise RuntimeError(f"{url} does not match its recorded hash")
76
+ part.rename(target)
77
+ return target
78
+
79
+
80
+ def pinned_archive(name: str, url: str, sha256: str) -> Path:
81
+ """A release archive at ``url``, downloaded once into the cache, checked against ``sha256`` and unpacked: the
82
+ binaries a baseline was measured with."""
83
+ target = cache_dir() / f"{name}-{sha256[:12]}"
84
+ if not (target / ".unpacked").exists():
85
+ archive = fetch(url, target / "archive", sha256)
86
+ if zipfile.is_zipfile(archive):
87
+ with zipfile.ZipFile(archive) as packed:
88
+ packed.extractall(target) # nosec B202 - our own pinned archive
89
+ for entry in packed.infolist(): # zipfile drops the modes: the binaries must stay executable
90
+ if mode := (entry.external_attr >> 16) & 0o777:
91
+ (target / entry.filename).chmod(mode)
92
+ else:
93
+ shutil.unpack_archive(str(archive), str(target), "gztar")
94
+ archive.unlink()
95
+ (target / ".unpacked").touch()
96
+ return target
97
+
98
+
99
+ def pinned_environment(root: Path, python: str, installs: list[list[str]]) -> Path:
100
+ """A virtual environment at ``root/venv`` on its own Python, made once by uv (``pip install uv``): for the tools
101
+ whose pins do not run on the host's Python. ``installs`` are ``pip install`` argument lists, run in order."""
102
+ try:
103
+ import uv
104
+
105
+ command = uv.find_uv_bin()
106
+ except ImportError:
107
+ command = shutil.which("uv") or ""
108
+ if not command:
109
+ raise RuntimeError("this baseline builds its own Python environment with uv: pip install uv")
110
+ venv = root / "venv"
111
+ if not (venv / ".ready").exists():
112
+ subprocess.run([command, "venv", "--quiet", "--clear", "--python", python, str(venv)], check=True) # nosec B603
113
+ for arguments in installs:
114
+ subprocess.run( # nosec B603
115
+ [
116
+ command,
117
+ "pip",
118
+ "install",
119
+ "--quiet",
120
+ "--no-cache",
121
+ "--python",
122
+ str(venv / "bin" / "python"),
123
+ *arguments,
124
+ ],
125
+ check=True,
126
+ )
127
+ (venv / ".ready").touch()
128
+ return venv
129
+
130
+
131
+ def built_source(name: str, url: str, commit: str, build: Callable[[Path], None]) -> Path:
132
+ """The authors' repository at ``commit``, built once by ``build`` (a marker says it is done)."""
133
+ source = pinned_source(name, url, commit)
134
+ if not (source / ".built").exists():
135
+ build(source)
136
+ (source / ".built").touch()
137
+ return source
138
+
139
+
140
+ def field_from_voxels(displacement: np.ndarray, fixed: sitk.Image) -> np.ndarray:
141
+ """A displacement in voxels along the index axes, ``[i, j, k, D]``, as the benchmark's field ``[D, k, j, i]``
142
+ in mm along the world axes: ``u = D S d``, with ``D`` the direction and ``S`` the spacing of the fixed image."""
143
+ n = fixed.GetDimension()
144
+ to_world = np.array(fixed.GetDirection()).reshape(n, n) @ np.diag(fixed.GetSpacing())
145
+ world = displacement.astype(np.float64) @ to_world.T # [i, j, k, D]
146
+ return np.ascontiguousarray(np.moveaxis(world, -1, 0).transpose(0, *reversed(range(1, n + 1))), dtype=np.float32)
147
+
148
+
149
+ def to_index_array(image: sitk.Image) -> np.ndarray:
150
+ """The image as a ``[i, j, k]`` array, the index axes in ITK's order, which the tools indexed that way read."""
151
+ return np.ascontiguousarray(sitk.GetArrayFromImage(image).transpose(*reversed(range(image.GetDimension()))))
152
+
153
+
154
+ class Registration(torch.nn.Module):
155
+ """Graph module: the pair's tensors and their geometry in, the field out, through the engine, one sample at
156
+ a time. ``accepts_attributes = True`` opts it into the per-branch ``Attribute`` list (the convention of
157
+ ``CriterionWithAttribute``): registration needs the physical geometry."""
158
+
159
+ accepts_attributes = True
160
+
161
+ def __init__(self, engine: Engine) -> None:
162
+ super().__init__()
163
+ self._engine = engine
164
+
165
+ def forward(
166
+ self,
167
+ fixed: torch.Tensor,
168
+ moving: torch.Tensor,
169
+ fixed_mask: torch.Tensor,
170
+ moving_mask: torch.Tensor,
171
+ attributes: list[list[Attribute]],
172
+ ) -> torch.Tensor:
173
+ fixed_attrs, moving_attrs, fixed_mask_attrs, moving_mask_attrs = attributes
174
+ device_index = fixed.device.index if fixed.device.type == "cuda" else -1
175
+ fields = []
176
+ # the engines optimise with autograd; the predictor calls forward under inference mode
177
+ with torch.inference_mode(False), torch.enable_grad():
178
+ for b in range(fixed.shape[0]):
179
+ images = [
180
+ data_to_image(t[b].detach().cpu().numpy(), attrs[b])
181
+ for t, attrs in ((fixed, fixed_attrs), (moving, moving_attrs))
182
+ ]
183
+ masks = [
184
+ data_to_image(t[b].detach().cpu().numpy(), attrs[b]) if not bool((t[b] == 1).all()) else None
185
+ for t, attrs in ((fixed_mask, fixed_mask_attrs), (moving_mask, moving_mask_attrs))
186
+ ]
187
+ fields.append(torch.from_numpy(self._engine(images[0], images[1], masks[0], masks[1], device_index)))
188
+ return torch.stack(fields, dim=0).to(fixed.device)
189
+
190
+
191
+ class BaselineNet(network.Network):
192
+ """A baseline as an ``add_module`` graph: fixed = branch 0, moving = branch 1, the masks branches 2 and 3 (a
193
+ mask of ones means none). The one output is ``DisplacementField``, on the fixed grid."""
194
+
195
+ def __init__(
196
+ self,
197
+ engine: Engine,
198
+ dim: int,
199
+ optimizer: network.OptimizerLoader,
200
+ schedulers: dict[str, network.LRSchedulersLoader],
201
+ outputs_criterions: dict[str, network.TargetCriterionsLoader],
202
+ ) -> None:
203
+ super().__init__(
204
+ in_channels=1, optimizer=optimizer, schedulers=schedulers, outputs_criterions=outputs_criterions, dim=dim
205
+ )
206
+ self.add_module("DisplacementField", Registration(engine), in_branch=[0, 1, 2, 3], out_branch=["dvf"])
BrainMorph/model.py ADDED
@@ -0,0 +1,181 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ # Copyright (c) 2025 Valentin Boussot
2
+ #
3
+ # Licensed under the Apache License, Version 2.0 (the "License");
4
+ # you may not use this file except in compliance with the License.
5
+ # You may obtain a copy of the License at
6
+ #
7
+ # http://www.apache.org/licenses/LICENSE-2.0
8
+ #
9
+ # Unless required by applicable law or agreed to in writing, software
10
+ # distributed under the License is distributed on an "AS IS" BASIS,
11
+ # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12
+ # See the License for the specific language governing permissions and
13
+ # limitations under the License.
14
+ #
15
+ # SPDX-License-Identifier: Apache-2.0
16
+
17
+ """BrainMorph (Wang et al.), called as the LUMIR organisers call it in Learn2Reg 2024
18
+ (``LUMIR_L2R/BrainMorph/infer_BrainMorph.py``): 512 keypoints, the "H" model, thin-plate splines with no
19
+ regularisation. The authors' repository at the commit of that date, since later commits dropped the H model, with its
20
+ dependencies at versions of that date (torch 2.3 on Python 3.11) in an environment uv builds in the cache on first use,
21
+ and the weights checked against their hash. Brain MR only. Masks and modalities are accepted and ignored.
22
+
23
+ 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
24
+ image first (the pairs are aligned), so that the saved ``grid_sample`` grid of the fixed box is a field there, then
25
+ resampled onto the fixed grid.
26
+
27
+ NOTE: do NOT add ``from __future__ import annotations``: KonfAI's config engine relies on runtime-evaluated
28
+ annotations (``get_origin``); PEP 563 stringized annotations break binding.
29
+ """
30
+
31
+ import glob
32
+ import hashlib
33
+ import os
34
+ import subprocess # nosec B404
35
+ import tempfile
36
+ from pathlib import Path
37
+ from typing import Annotated
38
+
39
+ import numpy as np
40
+ import SimpleITK as sitk
41
+ from konfai.network import network
42
+
43
+ from baselines import BaselineNet, pinned_environment, pinned_source
44
+
45
+ REPOSITORY = "https://github.com/alanqrwang/brainmorph"
46
+ COMMIT = "106b029d6048d3d9d2f73cf7996a0b0813cbc4ae" # 2024-05-23, "gdown fix and switching to variants"
47
+ # what its setup.py asks for, and what keymorph imports without declaring, at versions of that date
48
+ PACKAGES = [
49
+ "torch==2.3.1",
50
+ "torchvision==0.18.1",
51
+ "numpy==1.26.4",
52
+ "keymorph==1.0.1",
53
+ "torchio==0.19.6",
54
+ "nibabel==5.2.1",
55
+ "scipy==1.13.1",
56
+ "scikit-learn==1.5.0",
57
+ "pandas==2.2.2",
58
+ "pytz==2024.1",
59
+ "ogb==1.3.6",
60
+ "outdated==0.2.2",
61
+ "matplotlib==3.9.0",
62
+ "scikit-image==0.24.0",
63
+ "h5py==3.11.0",
64
+ "pyyaml==6.0.1",
65
+ "SimpleITK==2.5.6",
66
+ "gdown==5.2.0",
67
+ ]
68
+ WEIGHTS = (
69
+ "foundation-numkey512-numlevels7.pth.tar",
70
+ "https://drive.google.com/uc?id=1o_XG1FL4O3rsoCZvH2gzbzsCzd79uKnD",
71
+ "ae8947ea266ed1c2218c2b1449fbc4362f9b116c6afc5dfb24be0e17711da680",
72
+ )
73
+ 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
74
+
75
+
76
+ def home() -> tuple[Path, Path]:
77
+ """The authors' code with its environment and weights, fetched once into the cache: (source, venv)."""
78
+ source = pinned_source("brainmorph", REPOSITORY, COMMIT)
79
+ venv = pinned_environment(source, "3.11", [PACKAGES, ["--no-deps", "-e", str(source)]])
80
+ weights = source / "weights" / WEIGHTS[0]
81
+ if not weights.exists():
82
+ weights.parent.mkdir(exist_ok=True)
83
+ subprocess.run([str(venv / "bin" / "gdown"), "--quiet", WEIGHTS[1], "-O", str(weights)], check=True) # nosec B603
84
+ with weights.open("rb") as stream:
85
+ digest = hashlib.file_digest(stream, "sha256").hexdigest()
86
+ if digest != WEIGHTS[2]:
87
+ weights.unlink()
88
+ raise RuntimeError(f"{WEIGHTS[1]} does not match its recorded hash")
89
+ return source, venv
90
+
91
+
92
+ def box_around(fixed: sitk.Image, extent: int) -> sitk.Image:
93
+ """The RAS, 1 mm, ``extent``^3 box centred on the fixed image, which BrainMorph's own resampling then keeps."""
94
+ box = sitk.Image([extent] * 3, sitk.sitkFloat32)
95
+ box.SetDirection(RAS)
96
+ centre = np.array(fixed.TransformContinuousIndexToPhysicalPoint([(s - 1) / 2 for s in fixed.GetSize()]))
97
+ box.SetOrigin((centre - np.array(RAS).reshape(3, 3) @ np.full(3, (extent - 1) / 2)).tolist())
98
+ return box
99
+
100
+
101
+ class BrainMorph:
102
+ def __init__(self, keypoints: int, variant: str, align: str) -> None:
103
+ self._keypoints, self._variant, self._align = keypoints, variant, align
104
+
105
+ def __call__(
106
+ self,
107
+ fixed: sitk.Image,
108
+ moving: sitk.Image,
109
+ fixed_mask: sitk.Image | None,
110
+ moving_mask: sitk.Image | None,
111
+ device: int,
112
+ ) -> np.ndarray:
113
+ source, venv = home()
114
+ extent = 256
115
+ box = box_around(fixed, extent)
116
+ environment = {**os.environ, "PYTHONPATH": str(source)} # its scripts import scripts.*
117
+ if device < 0:
118
+ environment["CUDA_VISIBLE_DEVICES"] = ""
119
+ with tempfile.TemporaryDirectory(prefix="brainmorph_") as scratch:
120
+ work = Path(scratch)
121
+ for name, image in (("y", fixed), ("x", moving)): # the organisers' names: x moving, y fixed
122
+ image = sitk.Cast(image, sitk.sitkFloat32)
123
+ fill = float(sitk.GetArrayViewFromImage(image).min())
124
+ sitk.WriteImage(
125
+ sitk.Resample(image, box, sitk.Transform(), sitk.sitkLinear, fill), str(work / f"{name}.nii.gz")
126
+ )
127
+ subprocess.run( # nosec B603
128
+ [
129
+ str(venv / "bin" / "python"),
130
+ "scripts/register.py",
131
+ "--num_keypoints",
132
+ str(self._keypoints),
133
+ "--variant",
134
+ self._variant,
135
+ "--weights_dir",
136
+ f"{source / 'weights'}/",
137
+ "--moving",
138
+ str(work / "x.nii.gz"),
139
+ "--fixed",
140
+ str(work / "y.nii.gz"),
141
+ "--list_of_aligns",
142
+ self._align,
143
+ "--list_of_metrics",
144
+ "mse",
145
+ "--save_eval_to_disk",
146
+ "--save_dir",
147
+ str(work / "bm"),
148
+ ],
149
+ cwd=source,
150
+ check=True,
151
+ env=environment,
152
+ )
153
+ pattern = f"{work}/bm/eval_numkey{self._keypoints}_variant{self._variant}/*/grid_0-fixed_0-moving-rot0-{self._align}.npy"
154
+ grid = np.load(glob.glob(pattern)[0])
155
+ # the grid_sample grid of the fixed box, (i, j, k, 3) normalised with align_corners, its axes reversed
156
+ index = (np.squeeze(grid)[..., [2, 1, 0]] + 1) / 2 * (extent - 1)
157
+ d = index - np.stack(np.meshgrid(*[np.arange(extent)] * 3, indexing="ij"), -1) # voxels of the box
158
+ u = d * np.array([-1.0, -1.0, 1.0]) # 1 mm voxels along R, A, S: mm along L, P, S
159
+ field = sitk.GetImageFromArray(np.ascontiguousarray(u.transpose(2, 1, 0, 3)).astype(np.float64), isVector=True)
160
+ field.CopyInformation(box)
161
+ field = sitk.Resample(field, fixed, sitk.Transform(), sitk.sitkLinear, 0.0, sitk.sitkVectorFloat64)
162
+ return np.ascontiguousarray(np.moveaxis(sitk.GetArrayFromImage(field), -1, 0), dtype=np.float32)
163
+
164
+
165
+ class RegistrationNet(BaselineNet):
166
+ """BrainMorph, the LUMIR organisers' call. Brain MR."""
167
+
168
+ def __init__(
169
+ self,
170
+ optimizer: network.OptimizerLoader = network.OptimizerLoader(),
171
+ schedulers: dict[str, network.LRSchedulersLoader] = {
172
+ "default:ReduceLROnPlateau": network.LRSchedulersLoader(0)
173
+ },
174
+ outputs_criterions: dict[str, network.TargetCriterionsLoader] = {"default": network.TargetCriterionsLoader()},
175
+ keypoints: Annotated[int, "register.py's --num_keypoints: 128, 256 or 512."] = 512,
176
+ variant: Annotated[str, "register.py's --variant: S, M, L or H."] = "H",
177
+ align: Annotated[
178
+ str, "register.py's --list_of_aligns: tps_0 for thin-plate splines without regularisation, affine, rigid."
179
+ ] = "tps_0",
180
+ ) -> None:
181
+ super().__init__(BrainMorph(keypoints, variant, align), 3, optimizer, schedulers, outputs_criterions)
BrainMorph/requirements.txt ADDED
@@ -0,0 +1,2 @@
 
 
 
1
+ SimpleITK
2
+ uv==0.12.10
ConvexAdam_MIND/Prediction.yml ADDED
@@ -0,0 +1,85 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ Predictor:
2
+ Model:
3
+ classpath: model:RegistrationNet
4
+ RegistrationNet:
5
+ threads: 0
6
+ outputs_criterions: None
7
+ Dataset:
8
+ groups_src:
9
+ Volume_0:
10
+ groups_dest:
11
+ Fixed:
12
+ transforms:
13
+ TensorCast:
14
+ dtype: float32
15
+ inverse: false
16
+ patch_transforms: None
17
+ is_input: true
18
+ Volume_1:
19
+ groups_dest:
20
+ Moving:
21
+ transforms:
22
+ TensorCast:
23
+ dtype: float32
24
+ inverse: false
25
+ patch_transforms: None
26
+ is_input: true
27
+ Volume_2:
28
+ groups_dest:
29
+ FixedMask:
30
+ transforms:
31
+ TensorCast:
32
+ dtype: float32
33
+ inverse: false
34
+ patch_transforms: None
35
+ is_input: true
36
+ Volume_3:
37
+ groups_dest:
38
+ MovingMask:
39
+ transforms:
40
+ TensorCast:
41
+ dtype: float32
42
+ inverse: false
43
+ patch_transforms: None
44
+ is_input: true
45
+ augmentations: None
46
+ Patch:
47
+ patch_size:
48
+ - 0
49
+ - 0
50
+ - 0
51
+ overlap: 0
52
+ pad_value: None
53
+ extend_slice: 0
54
+ mode: resample
55
+ max_voxels: None
56
+ subset: None
57
+ dataset_filenames:
58
+ - ./Dataset/:mha
59
+ batch_size: 1
60
+ num_workers: None
61
+ pin_memory: false
62
+ prefetch_factor: None
63
+ persistent_workers: None
64
+ outputs_dataset:
65
+ DisplacementField:
66
+ OutputDataset:
67
+ name_class: OutputDataset
68
+ before_reduction_transforms: None
69
+ after_reduction_transforms: None
70
+ final_transforms:
71
+ TensorCast:
72
+ dtype: float32
73
+ inverse: false
74
+ dataset_filename: DisplacementField:mha
75
+ group: DisplacementField
76
+ same_as_group: Volume_0:Fixed
77
+ patch_combine: Cosinus
78
+ reduction: Mean
79
+ Mean: {}
80
+ train_name: Baselines-ConvexAdam_MIND
81
+ manual_seed: 42
82
+ gpu_checkpoints: None
83
+ combine: Mean
84
+ autocast: false
85
+ data_log: None
ConvexAdam_MIND/app.json ADDED
@@ -0,0 +1,18 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ {
2
+ "display_name": "ConvexAdam (MIND)",
3
+ "short_description": "ConvexAdam with MIND-SSC features, the authors' code at a pinned commit with its defaults: the ImagingBenchmarks baseline <code>convexadam_mind</code>.",
4
+ "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 <a href='https://github.com/multimodallearning/convexAdam'>the authors' repository</a> at commit b229e52 with <code>convex_adam_pt(fixed, moving)</code> 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.<br><br><b>How to cite:</b><br><cite>H. Siebert, L. Hansen, M. P. Heinrich, <i>Fast 3D registration with accurate optimisation and little learning for Learn2Reg 2021</i>, MICCAI Workshops 2021.</cite>",
5
+ "task": "registration",
6
+ "tta": 0,
7
+ "mc_dropout": 0,
8
+ "models": [],
9
+ "inputs": {
10
+ "Fixed": {"display_name": "Fixed image", "volume_type": "VOLUME", "required": true},
11
+ "Moving": {"display_name": "Moving image", "volume_type": "VOLUME", "required": true},
12
+ "FixedMask": {"display_name": "Fixed mask (ignored by this baseline)", "volume_type": "SEGMENTATION", "required": false, "default": "ones"},
13
+ "MovingMask": {"display_name": "Moving mask (ignored by this baseline)", "volume_type": "SEGMENTATION", "required": false, "default": "ones"}
14
+ },
15
+ "outputs": {
16
+ "DisplacementField": {"display_name": "Displacement field", "volume_type": "VOLUME", "required": true}
17
+ }
18
+ }
ConvexAdam_MIND/baselines.py ADDED
@@ -0,0 +1,206 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ # Copyright (c) 2025 Valentin Boussot
2
+ #
3
+ # Licensed under the Apache License, Version 2.0 (the "License");
4
+ # you may not use this file except in compliance with the License.
5
+ # You may obtain a copy of the License at
6
+ #
7
+ # http://www.apache.org/licenses/LICENSE-2.0
8
+ #
9
+ # Unless required by applicable law or agreed to in writing, software
10
+ # distributed under the License is distributed on an "AS IS" BASIS,
11
+ # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12
+ # See the License for the specific language governing permissions and
13
+ # limitations under the License.
14
+ #
15
+ # SPDX-License-Identifier: Apache-2.0
16
+
17
+ """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
18
+ engine and gets a displacement field back, and the field's convention.
19
+
20
+ The field is the benchmark's: one component per spatial axis, in mm along the world (ITK, LPS) axes, on the fixed
21
+ image's grid, such that the fixed point ``x`` matches ``x + u(x)`` in the moving image. The predictor attaches the
22
+ fixed image's geometry to the output (``same_as_group: Volume_0:Fixed`` in the app's ``Prediction.yml``).
23
+
24
+ NOTE: do NOT add ``from __future__ import annotations``: KonfAI's config engine relies on runtime-evaluated
25
+ annotations (``get_origin``); PEP 563 stringized annotations break binding.
26
+ """
27
+
28
+ import hashlib
29
+ import os
30
+ import shutil
31
+ import subprocess # nosec B404
32
+ import urllib.request
33
+ import zipfile
34
+ from collections.abc import Callable
35
+ from pathlib import Path
36
+
37
+ import numpy as np
38
+ import SimpleITK as sitk
39
+ import torch
40
+ from konfai.network import network
41
+ from konfai.utils.dataset import Attribute, data_to_image
42
+
43
+ #: An engine: (fixed, moving, fixed mask or None, moving mask or None, CUDA device index or -1) -> the field,
44
+ #: ``[D, *spatial]`` in mm along the world axes on the fixed grid.
45
+ Engine = Callable[[sitk.Image, sitk.Image, sitk.Image | None, sitk.Image | None, int], np.ndarray]
46
+
47
+
48
+ def cache_dir() -> Path:
49
+ """Where the authors' code and binaries live, once fetched: ``$BASELINES_KONFAI_CACHE`` or
50
+ ``~/.cache/baselines-konfai``."""
51
+ return Path(os.environ.get("BASELINES_KONFAI_CACHE", Path.home() / ".cache" / "baselines-konfai"))
52
+
53
+
54
+ def pinned_source(name: str, url: str, commit: str) -> Path:
55
+ """The authors' repository at ``commit``, cloned once into the cache: a baseline runs the code it was
56
+ measured with, never a moving branch."""
57
+ target = cache_dir() / f"{name}-{commit[:12]}"
58
+ if not (target / ".git").exists():
59
+ target.parent.mkdir(parents=True, exist_ok=True)
60
+ subprocess.run(["git", "clone", "--quiet", url, str(target)], check=True) # nosec B603 B607
61
+ subprocess.run(["git", "-C", str(target), "checkout", "--quiet", commit], check=True) # nosec B603 B607
62
+ return target
63
+
64
+
65
+ def fetch(url: str, target: Path, sha256: str | None = None) -> Path:
66
+ """``url`` downloaded once to ``target`` and, when a hash is given, checked against it."""
67
+ if not target.exists():
68
+ target.parent.mkdir(parents=True, exist_ok=True)
69
+ part = target.with_name(target.name + ".part")
70
+ urllib.request.urlretrieve(url, part) # nosec B310 - the authors' release, checked below
71
+ with part.open("rb") as stream:
72
+ digest = hashlib.file_digest(stream, "sha256").hexdigest()
73
+ if sha256 and digest != sha256:
74
+ part.unlink()
75
+ raise RuntimeError(f"{url} does not match its recorded hash")
76
+ part.rename(target)
77
+ return target
78
+
79
+
80
+ def pinned_archive(name: str, url: str, sha256: str) -> Path:
81
+ """A release archive at ``url``, downloaded once into the cache, checked against ``sha256`` and unpacked: the
82
+ binaries a baseline was measured with."""
83
+ target = cache_dir() / f"{name}-{sha256[:12]}"
84
+ if not (target / ".unpacked").exists():
85
+ archive = fetch(url, target / "archive", sha256)
86
+ if zipfile.is_zipfile(archive):
87
+ with zipfile.ZipFile(archive) as packed:
88
+ packed.extractall(target) # nosec B202 - our own pinned archive
89
+ for entry in packed.infolist(): # zipfile drops the modes: the binaries must stay executable
90
+ if mode := (entry.external_attr >> 16) & 0o777:
91
+ (target / entry.filename).chmod(mode)
92
+ else:
93
+ shutil.unpack_archive(str(archive), str(target), "gztar")
94
+ archive.unlink()
95
+ (target / ".unpacked").touch()
96
+ return target
97
+
98
+
99
+ def pinned_environment(root: Path, python: str, installs: list[list[str]]) -> Path:
100
+ """A virtual environment at ``root/venv`` on its own Python, made once by uv (``pip install uv``): for the tools
101
+ whose pins do not run on the host's Python. ``installs`` are ``pip install`` argument lists, run in order."""
102
+ try:
103
+ import uv
104
+
105
+ command = uv.find_uv_bin()
106
+ except ImportError:
107
+ command = shutil.which("uv") or ""
108
+ if not command:
109
+ raise RuntimeError("this baseline builds its own Python environment with uv: pip install uv")
110
+ venv = root / "venv"
111
+ if not (venv / ".ready").exists():
112
+ subprocess.run([command, "venv", "--quiet", "--clear", "--python", python, str(venv)], check=True) # nosec B603
113
+ for arguments in installs:
114
+ subprocess.run( # nosec B603
115
+ [
116
+ command,
117
+ "pip",
118
+ "install",
119
+ "--quiet",
120
+ "--no-cache",
121
+ "--python",
122
+ str(venv / "bin" / "python"),
123
+ *arguments,
124
+ ],
125
+ check=True,
126
+ )
127
+ (venv / ".ready").touch()
128
+ return venv
129
+
130
+
131
+ def built_source(name: str, url: str, commit: str, build: Callable[[Path], None]) -> Path:
132
+ """The authors' repository at ``commit``, built once by ``build`` (a marker says it is done)."""
133
+ source = pinned_source(name, url, commit)
134
+ if not (source / ".built").exists():
135
+ build(source)
136
+ (source / ".built").touch()
137
+ return source
138
+
139
+
140
+ def field_from_voxels(displacement: np.ndarray, fixed: sitk.Image) -> np.ndarray:
141
+ """A displacement in voxels along the index axes, ``[i, j, k, D]``, as the benchmark's field ``[D, k, j, i]``
142
+ in mm along the world axes: ``u = D S d``, with ``D`` the direction and ``S`` the spacing of the fixed image."""
143
+ n = fixed.GetDimension()
144
+ to_world = np.array(fixed.GetDirection()).reshape(n, n) @ np.diag(fixed.GetSpacing())
145
+ world = displacement.astype(np.float64) @ to_world.T # [i, j, k, D]
146
+ return np.ascontiguousarray(np.moveaxis(world, -1, 0).transpose(0, *reversed(range(1, n + 1))), dtype=np.float32)
147
+
148
+
149
+ def to_index_array(image: sitk.Image) -> np.ndarray:
150
+ """The image as a ``[i, j, k]`` array, the index axes in ITK's order, which the tools indexed that way read."""
151
+ return np.ascontiguousarray(sitk.GetArrayFromImage(image).transpose(*reversed(range(image.GetDimension()))))
152
+
153
+
154
+ class Registration(torch.nn.Module):
155
+ """Graph module: the pair's tensors and their geometry in, the field out, through the engine, one sample at
156
+ a time. ``accepts_attributes = True`` opts it into the per-branch ``Attribute`` list (the convention of
157
+ ``CriterionWithAttribute``): registration needs the physical geometry."""
158
+
159
+ accepts_attributes = True
160
+
161
+ def __init__(self, engine: Engine) -> None:
162
+ super().__init__()
163
+ self._engine = engine
164
+
165
+ def forward(
166
+ self,
167
+ fixed: torch.Tensor,
168
+ moving: torch.Tensor,
169
+ fixed_mask: torch.Tensor,
170
+ moving_mask: torch.Tensor,
171
+ attributes: list[list[Attribute]],
172
+ ) -> torch.Tensor:
173
+ fixed_attrs, moving_attrs, fixed_mask_attrs, moving_mask_attrs = attributes
174
+ device_index = fixed.device.index if fixed.device.type == "cuda" else -1
175
+ fields = []
176
+ # the engines optimise with autograd; the predictor calls forward under inference mode
177
+ with torch.inference_mode(False), torch.enable_grad():
178
+ for b in range(fixed.shape[0]):
179
+ images = [
180
+ data_to_image(t[b].detach().cpu().numpy(), attrs[b])
181
+ for t, attrs in ((fixed, fixed_attrs), (moving, moving_attrs))
182
+ ]
183
+ masks = [
184
+ data_to_image(t[b].detach().cpu().numpy(), attrs[b]) if not bool((t[b] == 1).all()) else None
185
+ for t, attrs in ((fixed_mask, fixed_mask_attrs), (moving_mask, moving_mask_attrs))
186
+ ]
187
+ fields.append(torch.from_numpy(self._engine(images[0], images[1], masks[0], masks[1], device_index)))
188
+ return torch.stack(fields, dim=0).to(fixed.device)
189
+
190
+
191
+ class BaselineNet(network.Network):
192
+ """A baseline as an ``add_module`` graph: fixed = branch 0, moving = branch 1, the masks branches 2 and 3 (a
193
+ mask of ones means none). The one output is ``DisplacementField``, on the fixed grid."""
194
+
195
+ def __init__(
196
+ self,
197
+ engine: Engine,
198
+ dim: int,
199
+ optimizer: network.OptimizerLoader,
200
+ schedulers: dict[str, network.LRSchedulersLoader],
201
+ outputs_criterions: dict[str, network.TargetCriterionsLoader],
202
+ ) -> None:
203
+ super().__init__(
204
+ in_channels=1, optimizer=optimizer, schedulers=schedulers, outputs_criterions=outputs_criterions, dim=dim
205
+ )
206
+ self.add_module("DisplacementField", Registration(engine), in_branch=[0, 1, 2, 3], out_branch=["dvf"])
ConvexAdam_MIND/model.py ADDED
@@ -0,0 +1,99 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ # Copyright (c) 2025 Valentin Boussot
2
+ #
3
+ # Licensed under the Apache License, Version 2.0 (the "License");
4
+ # you may not use this file except in compliance with the License.
5
+ # You may obtain a copy of the License at
6
+ #
7
+ # http://www.apache.org/licenses/LICENSE-2.0
8
+ #
9
+ # Unless required by applicable law or agreed to in writing, software
10
+ # distributed under the License is distributed on an "AS IS" BASIS,
11
+ # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12
+ # See the License for the specific language governing permissions and
13
+ # limitations under the License.
14
+ #
15
+ # SPDX-License-Identifier: Apache-2.0
16
+
17
+ """ConvexAdam with MIND-SSC features: the authors' repository (multimodallearning/convexAdam) at a pinned commit,
18
+ ``convex_adam_pt(fixed, moving)`` with its defaults, as the ImagingBenchmarks line ``convexadam_mind`` runs it.
19
+
20
+ NOTE: do NOT add ``from __future__ import annotations``: KonfAI's config engine relies on runtime-evaluated
21
+ annotations (``get_origin``); PEP 563 stringized annotations break binding.
22
+ """
23
+
24
+ import sys
25
+ from typing import Annotated
26
+
27
+ import numpy as np
28
+ import SimpleITK as sitk
29
+ import torch
30
+ from konfai.network import network
31
+
32
+ from baselines import BaselineNet, field_from_voxels, pinned_source, to_index_array
33
+
34
+ REPOSITORY = "https://github.com/multimodallearning/convexAdam"
35
+ COMMIT = "b229e52e44b114e2040a503334c92269750c16b2" # main, 2025-11-17
36
+
37
+
38
+ def _authors_code():
39
+ """The authors' functions, imported from their repository at the pin (it is not a package)."""
40
+ source = pinned_source("convexAdam", REPOSITORY, COMMIT) / "src"
41
+ if str(source) not in sys.path:
42
+ sys.path.insert(0, str(source))
43
+ from convexAdam.convex_adam_MIND import convex_adam_pt
44
+ from convexAdam.convex_adam_utils import resample_moving_to_fixed
45
+
46
+ return convex_adam_pt, resample_moving_to_fixed
47
+
48
+
49
+ class ConvexAdamMind:
50
+ def __init__(self, threads: int) -> None:
51
+ self._threads = threads
52
+
53
+ def __call__(
54
+ self,
55
+ fixed: sitk.Image,
56
+ moving: sitk.Image,
57
+ fixed_mask: sitk.Image | None,
58
+ moving_mask: sitk.Image | None,
59
+ device: int,
60
+ ) -> np.ndarray:
61
+ convex_adam_pt, resample_moving_to_fixed = _authors_code()
62
+ if self._threads:
63
+ torch.set_num_threads(self._threads)
64
+ fixed, moving = sitk.Cast(fixed, sitk.sitkFloat32), sitk.Cast(moving, sitk.sitkFloat32)
65
+ if fixed.GetDimension() != 3 or min(fixed.GetSize()) < 12:
66
+ raise ValueError(
67
+ f"ConvexAdam needs 3D images of at least 12 voxels per axis (grid spacing 6): {fixed.GetSize()}"
68
+ )
69
+
70
+ def geometry(image: sitk.Image) -> tuple:
71
+ return image.GetSize(), image.GetSpacing(), image.GetOrigin(), image.GetDirection()
72
+
73
+ if geometry(moving) != geometry(fixed):
74
+ moving = resample_moving_to_fixed(fixed, moving) # the repository's helper: identity, linear, 0 outside
75
+ # the repository's defaults; the displacement comes back as [i, j, k, 3], fixed -> moving, in voxels
76
+ displacement = convex_adam_pt(torch.from_numpy(to_index_array(fixed)), torch.from_numpy(to_index_array(moving)))
77
+ displacement = np.asarray(displacement)
78
+ if not np.isfinite(displacement).all():
79
+ raise ValueError("ConvexAdam returned a field with non-finite values")
80
+ return field_from_voxels(displacement, fixed)
81
+
82
+
83
+ class RegistrationNet(BaselineNet):
84
+ """ConvexAdam (MIND-SSC) at the authors' defaults: MIND radius 1 and dilation 2, a convex stage on a 6-voxel
85
+ grid with a search half-width of 4 and inverse consistency, then 80 Adam steps on a 2-voxel grid with a
86
+ diffusion weight of 1.25, half precision. A GPU is needed."""
87
+
88
+ def __init__(
89
+ self,
90
+ optimizer: network.OptimizerLoader = network.OptimizerLoader(),
91
+ schedulers: dict[str, network.LRSchedulersLoader] = {
92
+ "default:ReduceLROnPlateau": network.LRSchedulersLoader(0)
93
+ },
94
+ outputs_criterions: dict[str, network.TargetCriterionsLoader] = {"default": network.TargetCriterionsLoader()},
95
+ threads: Annotated[
96
+ int, "CPU threads torch may use for the parts that run on the CPU; 0 leaves the default."
97
+ ] = 0,
98
+ ) -> None:
99
+ super().__init__(ConvexAdamMind(threads), 3, optimizer, schedulers, outputs_criterions)
ConvexAdam_MIND/requirements.txt ADDED
@@ -0,0 +1,3 @@
 
 
 
 
1
+ SimpleITK
2
+ nibabel
3
+ scipy
CorrField/Prediction.yml ADDED
@@ -0,0 +1,86 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ Predictor:
2
+ Model:
3
+ classpath: model:RegistrationNet
4
+ RegistrationNet:
5
+ max_voxels: 50000000.0
6
+ min_spacing: 1.0
7
+ outputs_criterions: None
8
+ Dataset:
9
+ groups_src:
10
+ Volume_0:
11
+ groups_dest:
12
+ Fixed:
13
+ transforms:
14
+ TensorCast:
15
+ dtype: float32
16
+ inverse: false
17
+ patch_transforms: None
18
+ is_input: true
19
+ Volume_1:
20
+ groups_dest:
21
+ Moving:
22
+ transforms:
23
+ TensorCast:
24
+ dtype: float32
25
+ inverse: false
26
+ patch_transforms: None
27
+ is_input: true
28
+ Volume_2:
29
+ groups_dest:
30
+ FixedMask:
31
+ transforms:
32
+ TensorCast:
33
+ dtype: float32
34
+ inverse: false
35
+ patch_transforms: None
36
+ is_input: true
37
+ Volume_3:
38
+ groups_dest:
39
+ MovingMask:
40
+ transforms:
41
+ TensorCast:
42
+ dtype: float32
43
+ inverse: false
44
+ patch_transforms: None
45
+ is_input: true
46
+ augmentations: None
47
+ Patch:
48
+ patch_size:
49
+ - 0
50
+ - 0
51
+ - 0
52
+ overlap: 0
53
+ pad_value: None
54
+ extend_slice: 0
55
+ mode: resample
56
+ max_voxels: None
57
+ subset: None
58
+ dataset_filenames:
59
+ - ./Dataset/:mha
60
+ batch_size: 1
61
+ num_workers: None
62
+ pin_memory: false
63
+ prefetch_factor: None
64
+ persistent_workers: None
65
+ outputs_dataset:
66
+ DisplacementField:
67
+ OutputDataset:
68
+ name_class: OutputDataset
69
+ before_reduction_transforms: None
70
+ after_reduction_transforms: None
71
+ final_transforms:
72
+ TensorCast:
73
+ dtype: float32
74
+ inverse: false
75
+ dataset_filename: DisplacementField:mha
76
+ group: DisplacementField
77
+ same_as_group: Volume_0:Fixed
78
+ patch_combine: Cosinus
79
+ reduction: Mean
80
+ Mean: {}
81
+ train_name: Baselines-CorrField
82
+ manual_seed: 42
83
+ gpu_checkpoints: None
84
+ combine: Mean
85
+ autocast: false
86
+ data_log: None
CorrField/app.json ADDED
@@ -0,0 +1,39 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ {
2
+ "display_name": "corrField",
3
+ "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 <code>corrfield</code>, lungs only: the fixed mask is required.",
4
+ "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 <code>corrfield</code>, 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).",
5
+ "task": "registration",
6
+ "tta": 0,
7
+ "mc_dropout": 0,
8
+ "models": [],
9
+ "inputs": {
10
+ "Fixed": {
11
+ "display_name": "Fixed image",
12
+ "volume_type": "VOLUME",
13
+ "required": true
14
+ },
15
+ "Moving": {
16
+ "display_name": "Moving image",
17
+ "volume_type": "VOLUME",
18
+ "required": true
19
+ },
20
+ "FixedMask": {
21
+ "display_name": "Fixed mask (the lungs)",
22
+ "volume_type": "SEGMENTATION",
23
+ "required": true
24
+ },
25
+ "MovingMask": {
26
+ "display_name": "Moving mask (ignored by this baseline)",
27
+ "volume_type": "SEGMENTATION",
28
+ "required": false,
29
+ "default": "ones"
30
+ }
31
+ },
32
+ "outputs": {
33
+ "DisplacementField": {
34
+ "display_name": "Displacement field",
35
+ "volume_type": "VOLUME",
36
+ "required": true
37
+ }
38
+ }
39
+ }
CorrField/baselines.py ADDED
@@ -0,0 +1,206 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ # Copyright (c) 2025 Valentin Boussot
2
+ #
3
+ # Licensed under the Apache License, Version 2.0 (the "License");
4
+ # you may not use this file except in compliance with the License.
5
+ # You may obtain a copy of the License at
6
+ #
7
+ # http://www.apache.org/licenses/LICENSE-2.0
8
+ #
9
+ # Unless required by applicable law or agreed to in writing, software
10
+ # distributed under the License is distributed on an "AS IS" BASIS,
11
+ # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12
+ # See the License for the specific language governing permissions and
13
+ # limitations under the License.
14
+ #
15
+ # SPDX-License-Identifier: Apache-2.0
16
+
17
+ """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
18
+ engine and gets a displacement field back, and the field's convention.
19
+
20
+ The field is the benchmark's: one component per spatial axis, in mm along the world (ITK, LPS) axes, on the fixed
21
+ image's grid, such that the fixed point ``x`` matches ``x + u(x)`` in the moving image. The predictor attaches the
22
+ fixed image's geometry to the output (``same_as_group: Volume_0:Fixed`` in the app's ``Prediction.yml``).
23
+
24
+ NOTE: do NOT add ``from __future__ import annotations``: KonfAI's config engine relies on runtime-evaluated
25
+ annotations (``get_origin``); PEP 563 stringized annotations break binding.
26
+ """
27
+
28
+ import hashlib
29
+ import os
30
+ import shutil
31
+ import subprocess # nosec B404
32
+ import urllib.request
33
+ import zipfile
34
+ from collections.abc import Callable
35
+ from pathlib import Path
36
+
37
+ import numpy as np
38
+ import SimpleITK as sitk
39
+ import torch
40
+ from konfai.network import network
41
+ from konfai.utils.dataset import Attribute, data_to_image
42
+
43
+ #: An engine: (fixed, moving, fixed mask or None, moving mask or None, CUDA device index or -1) -> the field,
44
+ #: ``[D, *spatial]`` in mm along the world axes on the fixed grid.
45
+ Engine = Callable[[sitk.Image, sitk.Image, sitk.Image | None, sitk.Image | None, int], np.ndarray]
46
+
47
+
48
+ def cache_dir() -> Path:
49
+ """Where the authors' code and binaries live, once fetched: ``$BASELINES_KONFAI_CACHE`` or
50
+ ``~/.cache/baselines-konfai``."""
51
+ return Path(os.environ.get("BASELINES_KONFAI_CACHE", Path.home() / ".cache" / "baselines-konfai"))
52
+
53
+
54
+ def pinned_source(name: str, url: str, commit: str) -> Path:
55
+ """The authors' repository at ``commit``, cloned once into the cache: a baseline runs the code it was
56
+ measured with, never a moving branch."""
57
+ target = cache_dir() / f"{name}-{commit[:12]}"
58
+ if not (target / ".git").exists():
59
+ target.parent.mkdir(parents=True, exist_ok=True)
60
+ subprocess.run(["git", "clone", "--quiet", url, str(target)], check=True) # nosec B603 B607
61
+ subprocess.run(["git", "-C", str(target), "checkout", "--quiet", commit], check=True) # nosec B603 B607
62
+ return target
63
+
64
+
65
+ def fetch(url: str, target: Path, sha256: str | None = None) -> Path:
66
+ """``url`` downloaded once to ``target`` and, when a hash is given, checked against it."""
67
+ if not target.exists():
68
+ target.parent.mkdir(parents=True, exist_ok=True)
69
+ part = target.with_name(target.name + ".part")
70
+ urllib.request.urlretrieve(url, part) # nosec B310 - the authors' release, checked below
71
+ with part.open("rb") as stream:
72
+ digest = hashlib.file_digest(stream, "sha256").hexdigest()
73
+ if sha256 and digest != sha256:
74
+ part.unlink()
75
+ raise RuntimeError(f"{url} does not match its recorded hash")
76
+ part.rename(target)
77
+ return target
78
+
79
+
80
+ def pinned_archive(name: str, url: str, sha256: str) -> Path:
81
+ """A release archive at ``url``, downloaded once into the cache, checked against ``sha256`` and unpacked: the
82
+ binaries a baseline was measured with."""
83
+ target = cache_dir() / f"{name}-{sha256[:12]}"
84
+ if not (target / ".unpacked").exists():
85
+ archive = fetch(url, target / "archive", sha256)
86
+ if zipfile.is_zipfile(archive):
87
+ with zipfile.ZipFile(archive) as packed:
88
+ packed.extractall(target) # nosec B202 - our own pinned archive
89
+ for entry in packed.infolist(): # zipfile drops the modes: the binaries must stay executable
90
+ if mode := (entry.external_attr >> 16) & 0o777:
91
+ (target / entry.filename).chmod(mode)
92
+ else:
93
+ shutil.unpack_archive(str(archive), str(target), "gztar")
94
+ archive.unlink()
95
+ (target / ".unpacked").touch()
96
+ return target
97
+
98
+
99
+ def pinned_environment(root: Path, python: str, installs: list[list[str]]) -> Path:
100
+ """A virtual environment at ``root/venv`` on its own Python, made once by uv (``pip install uv``): for the tools
101
+ whose pins do not run on the host's Python. ``installs`` are ``pip install`` argument lists, run in order."""
102
+ try:
103
+ import uv
104
+
105
+ command = uv.find_uv_bin()
106
+ except ImportError:
107
+ command = shutil.which("uv") or ""
108
+ if not command:
109
+ raise RuntimeError("this baseline builds its own Python environment with uv: pip install uv")
110
+ venv = root / "venv"
111
+ if not (venv / ".ready").exists():
112
+ subprocess.run([command, "venv", "--quiet", "--clear", "--python", python, str(venv)], check=True) # nosec B603
113
+ for arguments in installs:
114
+ subprocess.run( # nosec B603
115
+ [
116
+ command,
117
+ "pip",
118
+ "install",
119
+ "--quiet",
120
+ "--no-cache",
121
+ "--python",
122
+ str(venv / "bin" / "python"),
123
+ *arguments,
124
+ ],
125
+ check=True,
126
+ )
127
+ (venv / ".ready").touch()
128
+ return venv
129
+
130
+
131
+ def built_source(name: str, url: str, commit: str, build: Callable[[Path], None]) -> Path:
132
+ """The authors' repository at ``commit``, built once by ``build`` (a marker says it is done)."""
133
+ source = pinned_source(name, url, commit)
134
+ if not (source / ".built").exists():
135
+ build(source)
136
+ (source / ".built").touch()
137
+ return source
138
+
139
+
140
+ def field_from_voxels(displacement: np.ndarray, fixed: sitk.Image) -> np.ndarray:
141
+ """A displacement in voxels along the index axes, ``[i, j, k, D]``, as the benchmark's field ``[D, k, j, i]``
142
+ in mm along the world axes: ``u = D S d``, with ``D`` the direction and ``S`` the spacing of the fixed image."""
143
+ n = fixed.GetDimension()
144
+ to_world = np.array(fixed.GetDirection()).reshape(n, n) @ np.diag(fixed.GetSpacing())
145
+ world = displacement.astype(np.float64) @ to_world.T # [i, j, k, D]
146
+ return np.ascontiguousarray(np.moveaxis(world, -1, 0).transpose(0, *reversed(range(1, n + 1))), dtype=np.float32)
147
+
148
+
149
+ def to_index_array(image: sitk.Image) -> np.ndarray:
150
+ """The image as a ``[i, j, k]`` array, the index axes in ITK's order, which the tools indexed that way read."""
151
+ return np.ascontiguousarray(sitk.GetArrayFromImage(image).transpose(*reversed(range(image.GetDimension()))))
152
+
153
+
154
+ class Registration(torch.nn.Module):
155
+ """Graph module: the pair's tensors and their geometry in, the field out, through the engine, one sample at
156
+ a time. ``accepts_attributes = True`` opts it into the per-branch ``Attribute`` list (the convention of
157
+ ``CriterionWithAttribute``): registration needs the physical geometry."""
158
+
159
+ accepts_attributes = True
160
+
161
+ def __init__(self, engine: Engine) -> None:
162
+ super().__init__()
163
+ self._engine = engine
164
+
165
+ def forward(
166
+ self,
167
+ fixed: torch.Tensor,
168
+ moving: torch.Tensor,
169
+ fixed_mask: torch.Tensor,
170
+ moving_mask: torch.Tensor,
171
+ attributes: list[list[Attribute]],
172
+ ) -> torch.Tensor:
173
+ fixed_attrs, moving_attrs, fixed_mask_attrs, moving_mask_attrs = attributes
174
+ device_index = fixed.device.index if fixed.device.type == "cuda" else -1
175
+ fields = []
176
+ # the engines optimise with autograd; the predictor calls forward under inference mode
177
+ with torch.inference_mode(False), torch.enable_grad():
178
+ for b in range(fixed.shape[0]):
179
+ images = [
180
+ data_to_image(t[b].detach().cpu().numpy(), attrs[b])
181
+ for t, attrs in ((fixed, fixed_attrs), (moving, moving_attrs))
182
+ ]
183
+ masks = [
184
+ data_to_image(t[b].detach().cpu().numpy(), attrs[b]) if not bool((t[b] == 1).all()) else None
185
+ for t, attrs in ((fixed_mask, fixed_mask_attrs), (moving_mask, moving_mask_attrs))
186
+ ]
187
+ fields.append(torch.from_numpy(self._engine(images[0], images[1], masks[0], masks[1], device_index)))
188
+ return torch.stack(fields, dim=0).to(fixed.device)
189
+
190
+
191
+ class BaselineNet(network.Network):
192
+ """A baseline as an ``add_module`` graph: fixed = branch 0, moving = branch 1, the masks branches 2 and 3 (a
193
+ mask of ones means none). The one output is ``DisplacementField``, on the fixed grid."""
194
+
195
+ def __init__(
196
+ self,
197
+ engine: Engine,
198
+ dim: int,
199
+ optimizer: network.OptimizerLoader,
200
+ schedulers: dict[str, network.LRSchedulersLoader],
201
+ outputs_criterions: dict[str, network.TargetCriterionsLoader],
202
+ ) -> None:
203
+ super().__init__(
204
+ in_channels=1, optimizer=optimizer, schedulers=schedulers, outputs_criterions=outputs_criterions, dim=dim
205
+ )
206
+ self.add_module("DisplacementField", Registration(engine), in_branch=[0, 1, 2, 3], out_branch=["dvf"])
CorrField/model.py ADDED
@@ -0,0 +1,150 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ # Copyright (c) 2025 Valentin Boussot
2
+ #
3
+ # Licensed under the Apache License, Version 2.0 (the "License");
4
+ # you may not use this file except in compliance with the License.
5
+ # You may obtain a copy of the License at
6
+ #
7
+ # http://www.apache.org/licenses/LICENSE-2.0
8
+ #
9
+ # Unless required by applicable law or agreed to in writing, software
10
+ # distributed under the License is distributed on an "AS IS" BASIS,
11
+ # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12
+ # See the License for the specific language governing permissions and
13
+ # limitations under the License.
14
+ #
15
+ # SPDX-License-Identifier: Apache-2.0
16
+
17
+ """corrField as the Lung250M-4B authors ship it (``corrfield.py`` at a pinned commit) with its defaults: Foerstner
18
+ keypoints inside the fixed image's mask (the lungs), MIND-SSC, discrete matching, thin-plate splines. The pair is
19
+ brought to a grid of at least 1 mm and at most 50 million voxels, as the benchmark runs it, and the field back
20
+ onto the fixed grid.
21
+
22
+ NOTE: do NOT add ``from __future__ import annotations``: KonfAI's config engine relies on runtime-evaluated
23
+ annotations (``get_origin``); PEP 563 stringized annotations break binding.
24
+ """
25
+
26
+ import os
27
+ import subprocess # nosec B404
28
+ import sys
29
+ import tempfile
30
+ from pathlib import Path
31
+ from typing import Annotated
32
+
33
+ import nibabel as nib
34
+ import numpy as np
35
+ import SimpleITK as sitk
36
+ from konfai.network import network
37
+
38
+ from baselines import BaselineNet, field_from_voxels, pinned_source
39
+
40
+ REPOSITORY = "https://github.com/multimodallearning/Lung250M-4B"
41
+ COMMIT = "53598ca8f64b13aeb774bc6e6ace486f78d73688" # main, 2024-01-25
42
+
43
+
44
+ def geometry(image: sitk.Image) -> tuple:
45
+ return image.GetSize(), image.GetSpacing(), image.GetOrigin(), image.GetDirection()
46
+
47
+
48
+ class CorrField:
49
+ def __init__(self, max_voxels: float, min_spacing: float) -> None:
50
+ self._max_voxels, self._min_spacing = max_voxels, min_spacing
51
+
52
+ def __call__(
53
+ self,
54
+ fixed: sitk.Image,
55
+ moving: sitk.Image,
56
+ fixed_mask: sitk.Image | None,
57
+ moving_mask: sitk.Image | None,
58
+ device: int,
59
+ ) -> np.ndarray:
60
+ if fixed_mask is None:
61
+ raise ValueError("corrField needs a mask of the fixed image (the lungs): its keypoints are taken inside it")
62
+ script = pinned_source("Lung250M-4B", REPOSITORY, COMMIT) / "corrfield" / "corrfield.py"
63
+ fixed, moving = sitk.Cast(fixed, sitk.sitkFloat32), sitk.Cast(moving, sitk.sitkFloat32)
64
+ mask = sitk.Cast(fixed_mask != 0, sitk.sitkUInt8)
65
+ # the running grid: at least min_spacing, and coarser if the volume exceeds max_voxels
66
+ spacing = np.maximum(fixed.GetSpacing(), self._min_spacing)
67
+ spacing = tuple(
68
+ spacing
69
+ * max(
70
+ 1.0, (np.prod(np.array(fixed.GetSize()) * fixed.GetSpacing() / spacing) / self._max_voxels) ** (1 / 3)
71
+ )
72
+ )
73
+ grid = fixed
74
+ if spacing != fixed.GetSpacing():
75
+ grid = sitk.Image(
76
+ [
77
+ max(1, round(n * s / t))
78
+ for n, s, t in zip(fixed.GetSize(), fixed.GetSpacing(), spacing, strict=True)
79
+ ],
80
+ sitk.sitkUInt8,
81
+ )
82
+ grid.SetSpacing(spacing), grid.SetOrigin(fixed.GetOrigin()), grid.SetDirection(fixed.GetDirection())
83
+
84
+ def on_grid(image: sitk.Image, how: int, outside: float) -> sitk.Image:
85
+ return (
86
+ image
87
+ if geometry(image) == geometry(grid)
88
+ else sitk.Resample(image, grid, sitk.Transform(), how, outside, image.GetPixelID())
89
+ )
90
+
91
+ lowest = lambda image: float(sitk.GetArrayViewFromImage(image).min()) # noqa: E731
92
+ fixed_run, moving_run = (
93
+ on_grid(fixed, sitk.sitkLinear, lowest(fixed)),
94
+ on_grid(moving, sitk.sitkLinear, lowest(moving)),
95
+ )
96
+ mask_run = on_grid(mask, sitk.sitkNearestNeighbor, 0.0)
97
+ with tempfile.TemporaryDirectory(prefix="corrfield_") as scratch:
98
+ work = Path(scratch)
99
+ for name, image in {"fixed": fixed_run, "moving": moving_run, "mask": mask_run}.items():
100
+ sitk.WriteImage(image, str(work / f"{name}.nii.gz"))
101
+ environment = {**os.environ, "CUDA_VISIBLE_DEVICES": str(device) if device >= 0 else ""}
102
+ subprocess.run( # nosec B603
103
+ [
104
+ sys.executable,
105
+ str(script),
106
+ "-F",
107
+ str(work / "fixed.nii.gz"),
108
+ "-M",
109
+ str(work / "moving.nii.gz"),
110
+ "-m",
111
+ str(work / "mask.nii.gz"),
112
+ "-O",
113
+ str(work / "corrfield"),
114
+ ],
115
+ check=True,
116
+ env=environment,
117
+ timeout=1800,
118
+ )
119
+ displacement = np.asarray(nib.load(str(work / "corrfield.nii.gz")).dataobj)[0] # (I, J, K, 3), voxels
120
+ if not np.isfinite(displacement).all():
121
+ raise ValueError("corrField returned a non-finite displacement")
122
+ field = sitk.GetImageFromArray(np.moveaxis(field_from_voxels(displacement, grid), 0, -1), isVector=True)
123
+ field.CopyInformation(grid)
124
+ if grid is not fixed: # back onto the fixed grid, linear, the nearest value past the grid's last sample
125
+ resample = sitk.ResampleImageFilter()
126
+ (
127
+ resample.SetReferenceImage(fixed),
128
+ resample.SetInterpolator(sitk.sitkLinear),
129
+ resample.SetUseNearestNeighborExtrapolator(True),
130
+ )
131
+ field = resample.Execute(field)
132
+ return np.ascontiguousarray(np.moveaxis(sitk.GetArrayFromImage(field), -1, 0), dtype=np.float32)
133
+
134
+
135
+ class RegistrationNet(BaselineNet):
136
+ """corrField with its defaults, on lungs: a mask of the fixed image is required."""
137
+
138
+ def __init__(
139
+ self,
140
+ optimizer: network.OptimizerLoader = network.OptimizerLoader(),
141
+ schedulers: dict[str, network.LRSchedulersLoader] = {
142
+ "default:ReduceLROnPlateau": network.LRSchedulersLoader(0)
143
+ },
144
+ outputs_criterions: dict[str, network.TargetCriterionsLoader] = {"default": network.TargetCriterionsLoader()},
145
+ max_voxels: Annotated[
146
+ float, "The pair is brought to a coarser grid when it holds more voxels than this."
147
+ ] = 50e6,
148
+ min_spacing: Annotated[float, "The finest spacing the pair runs at, in mm."] = 1.0,
149
+ ) -> None:
150
+ super().__init__(CorrField(max_voxels, min_spacing), 3, optimizer, schedulers, outputs_criterions)
CorrField/requirements.txt ADDED
@@ -0,0 +1,3 @@
 
 
 
 
1
+ SimpleITK
2
+ nibabel
3
+ scipy
Deeds/Prediction.yml ADDED
@@ -0,0 +1,85 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ Predictor:
2
+ Model:
3
+ classpath: model:RegistrationNet
4
+ RegistrationNet:
5
+ arguments: []
6
+ outputs_criterions: None
7
+ Dataset:
8
+ groups_src:
9
+ Volume_0:
10
+ groups_dest:
11
+ Fixed:
12
+ transforms:
13
+ TensorCast:
14
+ dtype: float32
15
+ inverse: false
16
+ patch_transforms: None
17
+ is_input: true
18
+ Volume_1:
19
+ groups_dest:
20
+ Moving:
21
+ transforms:
22
+ TensorCast:
23
+ dtype: float32
24
+ inverse: false
25
+ patch_transforms: None
26
+ is_input: true
27
+ Volume_2:
28
+ groups_dest:
29
+ FixedMask:
30
+ transforms:
31
+ TensorCast:
32
+ dtype: float32
33
+ inverse: false
34
+ patch_transforms: None
35
+ is_input: true
36
+ Volume_3:
37
+ groups_dest:
38
+ MovingMask:
39
+ transforms:
40
+ TensorCast:
41
+ dtype: float32
42
+ inverse: false
43
+ patch_transforms: None
44
+ is_input: true
45
+ augmentations: None
46
+ Patch:
47
+ patch_size:
48
+ - 0
49
+ - 0
50
+ - 0
51
+ overlap: 0
52
+ pad_value: None
53
+ extend_slice: 0
54
+ mode: resample
55
+ max_voxels: None
56
+ subset: None
57
+ dataset_filenames:
58
+ - ./Dataset/:mha
59
+ batch_size: 1
60
+ num_workers: None
61
+ pin_memory: false
62
+ prefetch_factor: None
63
+ persistent_workers: None
64
+ outputs_dataset:
65
+ DisplacementField:
66
+ OutputDataset:
67
+ name_class: OutputDataset
68
+ before_reduction_transforms: None
69
+ after_reduction_transforms: None
70
+ final_transforms:
71
+ TensorCast:
72
+ dtype: float32
73
+ inverse: false
74
+ dataset_filename: DisplacementField:mha
75
+ group: DisplacementField
76
+ same_as_group: Volume_0:Fixed
77
+ patch_combine: Cosinus
78
+ reduction: Mean
79
+ Mean: {}
80
+ train_name: Baselines-Deeds
81
+ manual_seed: 42
82
+ gpu_checkpoints: None
83
+ combine: Mean
84
+ autocast: false
85
+ data_log: None
Deeds/app.json ADDED
@@ -0,0 +1,40 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ {
2
+ "display_name": "deeds",
3
+ "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 <code>deeds</code>. CPU.",
4
+ "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 <code>deeds</code>. 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).",
5
+ "task": "registration",
6
+ "tta": 0,
7
+ "mc_dropout": 0,
8
+ "models": [],
9
+ "inputs": {
10
+ "Fixed": {
11
+ "display_name": "Fixed image",
12
+ "volume_type": "VOLUME",
13
+ "required": true
14
+ },
15
+ "Moving": {
16
+ "display_name": "Moving image",
17
+ "volume_type": "VOLUME",
18
+ "required": true
19
+ },
20
+ "FixedMask": {
21
+ "display_name": "Fixed mask (ignored by this baseline)",
22
+ "volume_type": "SEGMENTATION",
23
+ "required": false,
24
+ "default": "ones"
25
+ },
26
+ "MovingMask": {
27
+ "display_name": "Moving mask (ignored by this baseline)",
28
+ "volume_type": "SEGMENTATION",
29
+ "required": false,
30
+ "default": "ones"
31
+ }
32
+ },
33
+ "outputs": {
34
+ "DisplacementField": {
35
+ "display_name": "Displacement field",
36
+ "volume_type": "VOLUME",
37
+ "required": true
38
+ }
39
+ }
40
+ }
Deeds/baselines.py ADDED
@@ -0,0 +1,206 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ # Copyright (c) 2025 Valentin Boussot
2
+ #
3
+ # Licensed under the Apache License, Version 2.0 (the "License");
4
+ # you may not use this file except in compliance with the License.
5
+ # You may obtain a copy of the License at
6
+ #
7
+ # http://www.apache.org/licenses/LICENSE-2.0
8
+ #
9
+ # Unless required by applicable law or agreed to in writing, software
10
+ # distributed under the License is distributed on an "AS IS" BASIS,
11
+ # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12
+ # See the License for the specific language governing permissions and
13
+ # limitations under the License.
14
+ #
15
+ # SPDX-License-Identifier: Apache-2.0
16
+
17
+ """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
18
+ engine and gets a displacement field back, and the field's convention.
19
+
20
+ The field is the benchmark's: one component per spatial axis, in mm along the world (ITK, LPS) axes, on the fixed
21
+ image's grid, such that the fixed point ``x`` matches ``x + u(x)`` in the moving image. The predictor attaches the
22
+ fixed image's geometry to the output (``same_as_group: Volume_0:Fixed`` in the app's ``Prediction.yml``).
23
+
24
+ NOTE: do NOT add ``from __future__ import annotations``: KonfAI's config engine relies on runtime-evaluated
25
+ annotations (``get_origin``); PEP 563 stringized annotations break binding.
26
+ """
27
+
28
+ import hashlib
29
+ import os
30
+ import shutil
31
+ import subprocess # nosec B404
32
+ import urllib.request
33
+ import zipfile
34
+ from collections.abc import Callable
35
+ from pathlib import Path
36
+
37
+ import numpy as np
38
+ import SimpleITK as sitk
39
+ import torch
40
+ from konfai.network import network
41
+ from konfai.utils.dataset import Attribute, data_to_image
42
+
43
+ #: An engine: (fixed, moving, fixed mask or None, moving mask or None, CUDA device index or -1) -> the field,
44
+ #: ``[D, *spatial]`` in mm along the world axes on the fixed grid.
45
+ Engine = Callable[[sitk.Image, sitk.Image, sitk.Image | None, sitk.Image | None, int], np.ndarray]
46
+
47
+
48
+ def cache_dir() -> Path:
49
+ """Where the authors' code and binaries live, once fetched: ``$BASELINES_KONFAI_CACHE`` or
50
+ ``~/.cache/baselines-konfai``."""
51
+ return Path(os.environ.get("BASELINES_KONFAI_CACHE", Path.home() / ".cache" / "baselines-konfai"))
52
+
53
+
54
+ def pinned_source(name: str, url: str, commit: str) -> Path:
55
+ """The authors' repository at ``commit``, cloned once into the cache: a baseline runs the code it was
56
+ measured with, never a moving branch."""
57
+ target = cache_dir() / f"{name}-{commit[:12]}"
58
+ if not (target / ".git").exists():
59
+ target.parent.mkdir(parents=True, exist_ok=True)
60
+ subprocess.run(["git", "clone", "--quiet", url, str(target)], check=True) # nosec B603 B607
61
+ subprocess.run(["git", "-C", str(target), "checkout", "--quiet", commit], check=True) # nosec B603 B607
62
+ return target
63
+
64
+
65
+ def fetch(url: str, target: Path, sha256: str | None = None) -> Path:
66
+ """``url`` downloaded once to ``target`` and, when a hash is given, checked against it."""
67
+ if not target.exists():
68
+ target.parent.mkdir(parents=True, exist_ok=True)
69
+ part = target.with_name(target.name + ".part")
70
+ urllib.request.urlretrieve(url, part) # nosec B310 - the authors' release, checked below
71
+ with part.open("rb") as stream:
72
+ digest = hashlib.file_digest(stream, "sha256").hexdigest()
73
+ if sha256 and digest != sha256:
74
+ part.unlink()
75
+ raise RuntimeError(f"{url} does not match its recorded hash")
76
+ part.rename(target)
77
+ return target
78
+
79
+
80
+ def pinned_archive(name: str, url: str, sha256: str) -> Path:
81
+ """A release archive at ``url``, downloaded once into the cache, checked against ``sha256`` and unpacked: the
82
+ binaries a baseline was measured with."""
83
+ target = cache_dir() / f"{name}-{sha256[:12]}"
84
+ if not (target / ".unpacked").exists():
85
+ archive = fetch(url, target / "archive", sha256)
86
+ if zipfile.is_zipfile(archive):
87
+ with zipfile.ZipFile(archive) as packed:
88
+ packed.extractall(target) # nosec B202 - our own pinned archive
89
+ for entry in packed.infolist(): # zipfile drops the modes: the binaries must stay executable
90
+ if mode := (entry.external_attr >> 16) & 0o777:
91
+ (target / entry.filename).chmod(mode)
92
+ else:
93
+ shutil.unpack_archive(str(archive), str(target), "gztar")
94
+ archive.unlink()
95
+ (target / ".unpacked").touch()
96
+ return target
97
+
98
+
99
+ def pinned_environment(root: Path, python: str, installs: list[list[str]]) -> Path:
100
+ """A virtual environment at ``root/venv`` on its own Python, made once by uv (``pip install uv``): for the tools
101
+ whose pins do not run on the host's Python. ``installs`` are ``pip install`` argument lists, run in order."""
102
+ try:
103
+ import uv
104
+
105
+ command = uv.find_uv_bin()
106
+ except ImportError:
107
+ command = shutil.which("uv") or ""
108
+ if not command:
109
+ raise RuntimeError("this baseline builds its own Python environment with uv: pip install uv")
110
+ venv = root / "venv"
111
+ if not (venv / ".ready").exists():
112
+ subprocess.run([command, "venv", "--quiet", "--clear", "--python", python, str(venv)], check=True) # nosec B603
113
+ for arguments in installs:
114
+ subprocess.run( # nosec B603
115
+ [
116
+ command,
117
+ "pip",
118
+ "install",
119
+ "--quiet",
120
+ "--no-cache",
121
+ "--python",
122
+ str(venv / "bin" / "python"),
123
+ *arguments,
124
+ ],
125
+ check=True,
126
+ )
127
+ (venv / ".ready").touch()
128
+ return venv
129
+
130
+
131
+ def built_source(name: str, url: str, commit: str, build: Callable[[Path], None]) -> Path:
132
+ """The authors' repository at ``commit``, built once by ``build`` (a marker says it is done)."""
133
+ source = pinned_source(name, url, commit)
134
+ if not (source / ".built").exists():
135
+ build(source)
136
+ (source / ".built").touch()
137
+ return source
138
+
139
+
140
+ def field_from_voxels(displacement: np.ndarray, fixed: sitk.Image) -> np.ndarray:
141
+ """A displacement in voxels along the index axes, ``[i, j, k, D]``, as the benchmark's field ``[D, k, j, i]``
142
+ in mm along the world axes: ``u = D S d``, with ``D`` the direction and ``S`` the spacing of the fixed image."""
143
+ n = fixed.GetDimension()
144
+ to_world = np.array(fixed.GetDirection()).reshape(n, n) @ np.diag(fixed.GetSpacing())
145
+ world = displacement.astype(np.float64) @ to_world.T # [i, j, k, D]
146
+ return np.ascontiguousarray(np.moveaxis(world, -1, 0).transpose(0, *reversed(range(1, n + 1))), dtype=np.float32)
147
+
148
+
149
+ def to_index_array(image: sitk.Image) -> np.ndarray:
150
+ """The image as a ``[i, j, k]`` array, the index axes in ITK's order, which the tools indexed that way read."""
151
+ return np.ascontiguousarray(sitk.GetArrayFromImage(image).transpose(*reversed(range(image.GetDimension()))))
152
+
153
+
154
+ class Registration(torch.nn.Module):
155
+ """Graph module: the pair's tensors and their geometry in, the field out, through the engine, one sample at
156
+ a time. ``accepts_attributes = True`` opts it into the per-branch ``Attribute`` list (the convention of
157
+ ``CriterionWithAttribute``): registration needs the physical geometry."""
158
+
159
+ accepts_attributes = True
160
+
161
+ def __init__(self, engine: Engine) -> None:
162
+ super().__init__()
163
+ self._engine = engine
164
+
165
+ def forward(
166
+ self,
167
+ fixed: torch.Tensor,
168
+ moving: torch.Tensor,
169
+ fixed_mask: torch.Tensor,
170
+ moving_mask: torch.Tensor,
171
+ attributes: list[list[Attribute]],
172
+ ) -> torch.Tensor:
173
+ fixed_attrs, moving_attrs, fixed_mask_attrs, moving_mask_attrs = attributes
174
+ device_index = fixed.device.index if fixed.device.type == "cuda" else -1
175
+ fields = []
176
+ # the engines optimise with autograd; the predictor calls forward under inference mode
177
+ with torch.inference_mode(False), torch.enable_grad():
178
+ for b in range(fixed.shape[0]):
179
+ images = [
180
+ data_to_image(t[b].detach().cpu().numpy(), attrs[b])
181
+ for t, attrs in ((fixed, fixed_attrs), (moving, moving_attrs))
182
+ ]
183
+ masks = [
184
+ data_to_image(t[b].detach().cpu().numpy(), attrs[b]) if not bool((t[b] == 1).all()) else None
185
+ for t, attrs in ((fixed_mask, fixed_mask_attrs), (moving_mask, moving_mask_attrs))
186
+ ]
187
+ fields.append(torch.from_numpy(self._engine(images[0], images[1], masks[0], masks[1], device_index)))
188
+ return torch.stack(fields, dim=0).to(fixed.device)
189
+
190
+
191
+ class BaselineNet(network.Network):
192
+ """A baseline as an ``add_module`` graph: fixed = branch 0, moving = branch 1, the masks branches 2 and 3 (a
193
+ mask of ones means none). The one output is ``DisplacementField``, on the fixed grid."""
194
+
195
+ def __init__(
196
+ self,
197
+ engine: Engine,
198
+ dim: int,
199
+ optimizer: network.OptimizerLoader,
200
+ schedulers: dict[str, network.LRSchedulersLoader],
201
+ outputs_criterions: dict[str, network.TargetCriterionsLoader],
202
+ ) -> None:
203
+ super().__init__(
204
+ in_channels=1, optimizer=optimizer, schedulers=schedulers, outputs_criterions=outputs_criterions, dim=dim
205
+ )
206
+ self.add_module("DisplacementField", Registration(engine), in_branch=[0, 1, 2, 3], out_branch=["dvf"])
Deeds/model.py ADDED
@@ -0,0 +1,141 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ # Copyright (c) 2025 Valentin Boussot
2
+ #
3
+ # Licensed under the Apache License, Version 2.0 (the "License");
4
+ # you may not use this file except in compliance with the License.
5
+ # You may obtain a copy of the License at
6
+ #
7
+ # http://www.apache.org/licenses/LICENSE-2.0
8
+ #
9
+ # Unless required by applicable law or agreed to in writing, software
10
+ # distributed under the License is distributed on an "AS IS" BASIS,
11
+ # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12
+ # See the License for the specific language governing permissions and
13
+ # limitations under the License.
14
+ #
15
+ # SPDX-License-Identifier: Apache-2.0
16
+
17
+ """deeds (``deedsBCV``) with its defaults: 5 levels, grid 8x7x6x5x4, search radius 8x7x6x5x4, quantisation
18
+ 5x4x3x2x1, regularisation 1.6, symmetric; built from the authors' repository at a pinned commit on first use. deeds
19
+ reads two arrays of one size without geometry, so an anisotropic fixed image is first brought to an isotropic grid,
20
+ the moving image onto it, and the field back onto the fixed grid.
21
+
22
+ NOTE: do NOT add ``from __future__ import annotations``: KonfAI's config engine relies on runtime-evaluated
23
+ annotations (``get_origin``); PEP 563 stringized annotations break binding.
24
+ """
25
+
26
+ import subprocess # nosec B404
27
+ import tempfile
28
+ from pathlib import Path
29
+ from typing import Annotated
30
+
31
+ import numpy as np
32
+ import SimpleITK as sitk
33
+ from konfai.network import network
34
+
35
+ from baselines import BaselineNet, built_source
36
+
37
+ REPOSITORY = "https://github.com/mattiaspaul/deedsBCV"
38
+ COMMIT = "00b46539aa03d23988a241173d8f1f6c0c68dc6a" # master, 2025-09-09
39
+
40
+
41
+ def _build(source: Path) -> None:
42
+ subprocess.run(["make", "-C", str(source), "linear", "deeds", "applyFloat"], check=True) # nosec B603 B607
43
+
44
+
45
+ def geometry(image: sitk.Image) -> tuple:
46
+ return image.GetSize(), image.GetSpacing(), image.GetOrigin(), image.GetDirection()
47
+
48
+
49
+ def upsample(coarse: np.ndarray, full: tuple[int, int, int]) -> np.ndarray:
50
+ """deeds' ``upsampleDeformationsCL``: voxel p samples the control grid at p * coarse / full, indices clamped."""
51
+ for axis, (extent, size) in enumerate(zip(full, coarse.shape, strict=True)):
52
+ x = np.arange(extent) * size / extent
53
+ low = np.floor(x).astype(int)
54
+ weight = (x - low).astype(np.float32).reshape([-1 if a == axis else 1 for a in range(3)])
55
+ coarse = (
56
+ np.take(coarse, low, axis) * (1 - weight) + np.take(coarse, np.minimum(low + 1, size - 1), axis) * weight
57
+ )
58
+ return coarse
59
+
60
+
61
+ class Deeds:
62
+ def __init__(self, arguments: list[str]) -> None:
63
+ self._arguments = arguments
64
+
65
+ def __call__(
66
+ self,
67
+ fixed: sitk.Image,
68
+ moving: sitk.Image,
69
+ fixed_mask: sitk.Image | None,
70
+ moving_mask: sitk.Image | None,
71
+ device: int,
72
+ ) -> np.ndarray:
73
+ binaries = built_source("deedsBCV", REPOSITORY, COMMIT, _build)
74
+ original, moving = sitk.Cast(fixed, sitk.sitkFloat32), sitk.Cast(moving, sitk.sitkFloat32)
75
+ fixed = original
76
+ spacing = np.array(original.GetSpacing())
77
+ if spacing.max() > 1.01 * spacing.min():
78
+ iso = float(np.prod(spacing) ** (1 / 3))
79
+ size = [int(np.ceil((n - 1) * s / iso)) + 1 for n, s in zip(original.GetSize(), spacing, strict=True)]
80
+ fixed = sitk.Resample(
81
+ original,
82
+ size,
83
+ sitk.Transform(),
84
+ sitk.sitkLinear,
85
+ original.GetOrigin(),
86
+ (iso,) * 3,
87
+ original.GetDirection(),
88
+ float(sitk.GetArrayViewFromImage(original).min()),
89
+ )
90
+ if min(fixed.GetSize()) < 16:
91
+ raise ValueError(f"deeds needs at least 16 voxels per fixed axis (grid 8): {fixed.GetSize()}")
92
+ if geometry(moving) != geometry(fixed):
93
+ moving = sitk.Resample(
94
+ moving, fixed, sitk.Transform(), sitk.sitkLinear, float(sitk.GetArrayViewFromImage(moving).min())
95
+ )
96
+ with tempfile.TemporaryDirectory(prefix="deeds_") as scratch:
97
+ work = Path(scratch)
98
+ sitk.WriteImage(fixed, str(work / "fixed.nii.gz"))
99
+ sitk.WriteImage(moving, str(work / "moving.nii.gz"))
100
+ del moving
101
+ subprocess.run(
102
+ [
103
+ str(binaries / "deedsBCV"),
104
+ "-F",
105
+ str(work / "fixed.nii.gz"),
106
+ "-M",
107
+ str(work / "moving.nii.gz"), # nosec B603
108
+ "-O",
109
+ str(work / "deeds"),
110
+ *self._arguments,
111
+ ],
112
+ check=True,
113
+ )
114
+ flow = np.fromfile(work / "deeds_displacements.dat", np.float32)
115
+ m, n, o = fixed.GetSize()
116
+ step = round((m * n * o / (flow.size // 3)) ** (1 / 3))
117
+ u, v, w = flow.reshape(3, o // step, n // step, m // step) # arrays as (k, j, i)
118
+ displacement = np.stack([upsample(c, (o, n, m)) for c in (v, u, w)], -1) # (k, j, i, 3): voxels along i, j, k
119
+ if not np.isfinite(displacement).all():
120
+ raise ValueError("deeds returned a non-finite displacement")
121
+ to_world = np.array(fixed.GetDirection()).reshape(3, 3) @ np.diag(fixed.GetSpacing())
122
+ field = sitk.GetImageFromArray((displacement @ to_world.T).astype(np.float32), isVector=True)
123
+ field.CopyInformation(fixed)
124
+ if fixed is not original: # world vectors: a plain linear resampling onto the fixed grid
125
+ field = sitk.Resample(field, original, sitk.Transform(), sitk.sitkLinear, 0.0, sitk.sitkVectorFloat32)
126
+ return np.ascontiguousarray(np.moveaxis(sitk.GetArrayFromImage(field), -1, 0), dtype=np.float32)
127
+
128
+
129
+ class RegistrationNet(BaselineNet):
130
+ """deedsBCV, defaults. CPU."""
131
+
132
+ def __init__(
133
+ self,
134
+ optimizer: network.OptimizerLoader = network.OptimizerLoader(),
135
+ schedulers: dict[str, network.LRSchedulersLoader] = {
136
+ "default:ReduceLROnPlateau": network.LRSchedulersLoader(0)
137
+ },
138
+ outputs_criterions: dict[str, network.TargetCriterionsLoader] = {"default": network.TargetCriterionsLoader()},
139
+ arguments: Annotated[list[str], "Extra deedsBCV arguments (-G, -L, -Q, -a); none for the defaults."] = [],
140
+ ) -> None:
141
+ super().__init__(Deeds(list(arguments)), 3, optimizer, schedulers, outputs_criterions)
Deeds/requirements.txt ADDED
@@ -0,0 +1 @@
 
 
1
+ SimpleITK
Demons/Prediction.yml ADDED
@@ -0,0 +1,94 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ Predictor:
2
+ Model:
3
+ classpath: model:RegistrationNet
4
+ RegistrationNet:
5
+ iterations: 20
6
+ standard_deviation: 2.0
7
+ shrinks:
8
+ - 4
9
+ - 2
10
+ sigmas:
11
+ - 8.0
12
+ - 4.0
13
+ modality: auto
14
+ threads: 0
15
+ outputs_criterions: None
16
+ Dataset:
17
+ groups_src:
18
+ Volume_0:
19
+ groups_dest:
20
+ Fixed:
21
+ transforms:
22
+ TensorCast:
23
+ dtype: float32
24
+ inverse: false
25
+ patch_transforms: None
26
+ is_input: true
27
+ Volume_1:
28
+ groups_dest:
29
+ Moving:
30
+ transforms:
31
+ TensorCast:
32
+ dtype: float32
33
+ inverse: false
34
+ patch_transforms: None
35
+ is_input: true
36
+ Volume_2:
37
+ groups_dest:
38
+ FixedMask:
39
+ transforms:
40
+ TensorCast:
41
+ dtype: float32
42
+ inverse: false
43
+ patch_transforms: None
44
+ is_input: true
45
+ Volume_3:
46
+ groups_dest:
47
+ MovingMask:
48
+ transforms:
49
+ TensorCast:
50
+ dtype: float32
51
+ inverse: false
52
+ patch_transforms: None
53
+ is_input: true
54
+ augmentations: None
55
+ Patch:
56
+ patch_size:
57
+ - 0
58
+ - 0
59
+ - 0
60
+ overlap: 0
61
+ pad_value: None
62
+ extend_slice: 0
63
+ mode: resample
64
+ max_voxels: None
65
+ subset: None
66
+ dataset_filenames:
67
+ - ./Dataset/:mha
68
+ batch_size: 1
69
+ num_workers: None
70
+ pin_memory: false
71
+ prefetch_factor: None
72
+ persistent_workers: None
73
+ outputs_dataset:
74
+ DisplacementField:
75
+ OutputDataset:
76
+ name_class: OutputDataset
77
+ before_reduction_transforms: None
78
+ after_reduction_transforms: None
79
+ final_transforms:
80
+ TensorCast:
81
+ dtype: float32
82
+ inverse: false
83
+ dataset_filename: DisplacementField:mha
84
+ group: DisplacementField
85
+ same_as_group: Volume_0:Fixed
86
+ patch_combine: Cosinus
87
+ reduction: Mean
88
+ Mean: {}
89
+ train_name: Baselines-Demons
90
+ manual_seed: 42
91
+ gpu_checkpoints: None
92
+ combine: Mean
93
+ autocast: false
94
+ data_log: None
Demons/app.json ADDED
@@ -0,0 +1,40 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ {
2
+ "display_name": "Demons",
3
+ "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 <code>demons</code>.",
4
+ "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 <code>demons</code>. 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).",
5
+ "task": "registration",
6
+ "tta": 0,
7
+ "mc_dropout": 0,
8
+ "models": [],
9
+ "inputs": {
10
+ "Fixed": {
11
+ "display_name": "Fixed image",
12
+ "volume_type": "VOLUME",
13
+ "required": true
14
+ },
15
+ "Moving": {
16
+ "display_name": "Moving image",
17
+ "volume_type": "VOLUME",
18
+ "required": true
19
+ },
20
+ "FixedMask": {
21
+ "display_name": "Fixed mask (ignored by this baseline)",
22
+ "volume_type": "SEGMENTATION",
23
+ "required": false,
24
+ "default": "ones"
25
+ },
26
+ "MovingMask": {
27
+ "display_name": "Moving mask (ignored by this baseline)",
28
+ "volume_type": "SEGMENTATION",
29
+ "required": false,
30
+ "default": "ones"
31
+ }
32
+ },
33
+ "outputs": {
34
+ "DisplacementField": {
35
+ "display_name": "Displacement field",
36
+ "volume_type": "VOLUME",
37
+ "required": true
38
+ }
39
+ }
40
+ }
Demons/baselines.py ADDED
@@ -0,0 +1,206 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ # Copyright (c) 2025 Valentin Boussot
2
+ #
3
+ # Licensed under the Apache License, Version 2.0 (the "License");
4
+ # you may not use this file except in compliance with the License.
5
+ # You may obtain a copy of the License at
6
+ #
7
+ # http://www.apache.org/licenses/LICENSE-2.0
8
+ #
9
+ # Unless required by applicable law or agreed to in writing, software
10
+ # distributed under the License is distributed on an "AS IS" BASIS,
11
+ # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12
+ # See the License for the specific language governing permissions and
13
+ # limitations under the License.
14
+ #
15
+ # SPDX-License-Identifier: Apache-2.0
16
+
17
+ """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
18
+ engine and gets a displacement field back, and the field's convention.
19
+
20
+ The field is the benchmark's: one component per spatial axis, in mm along the world (ITK, LPS) axes, on the fixed
21
+ image's grid, such that the fixed point ``x`` matches ``x + u(x)`` in the moving image. The predictor attaches the
22
+ fixed image's geometry to the output (``same_as_group: Volume_0:Fixed`` in the app's ``Prediction.yml``).
23
+
24
+ NOTE: do NOT add ``from __future__ import annotations``: KonfAI's config engine relies on runtime-evaluated
25
+ annotations (``get_origin``); PEP 563 stringized annotations break binding.
26
+ """
27
+
28
+ import hashlib
29
+ import os
30
+ import shutil
31
+ import subprocess # nosec B404
32
+ import urllib.request
33
+ import zipfile
34
+ from collections.abc import Callable
35
+ from pathlib import Path
36
+
37
+ import numpy as np
38
+ import SimpleITK as sitk
39
+ import torch
40
+ from konfai.network import network
41
+ from konfai.utils.dataset import Attribute, data_to_image
42
+
43
+ #: An engine: (fixed, moving, fixed mask or None, moving mask or None, CUDA device index or -1) -> the field,
44
+ #: ``[D, *spatial]`` in mm along the world axes on the fixed grid.
45
+ Engine = Callable[[sitk.Image, sitk.Image, sitk.Image | None, sitk.Image | None, int], np.ndarray]
46
+
47
+
48
+ def cache_dir() -> Path:
49
+ """Where the authors' code and binaries live, once fetched: ``$BASELINES_KONFAI_CACHE`` or
50
+ ``~/.cache/baselines-konfai``."""
51
+ return Path(os.environ.get("BASELINES_KONFAI_CACHE", Path.home() / ".cache" / "baselines-konfai"))
52
+
53
+
54
+ def pinned_source(name: str, url: str, commit: str) -> Path:
55
+ """The authors' repository at ``commit``, cloned once into the cache: a baseline runs the code it was
56
+ measured with, never a moving branch."""
57
+ target = cache_dir() / f"{name}-{commit[:12]}"
58
+ if not (target / ".git").exists():
59
+ target.parent.mkdir(parents=True, exist_ok=True)
60
+ subprocess.run(["git", "clone", "--quiet", url, str(target)], check=True) # nosec B603 B607
61
+ subprocess.run(["git", "-C", str(target), "checkout", "--quiet", commit], check=True) # nosec B603 B607
62
+ return target
63
+
64
+
65
+ def fetch(url: str, target: Path, sha256: str | None = None) -> Path:
66
+ """``url`` downloaded once to ``target`` and, when a hash is given, checked against it."""
67
+ if not target.exists():
68
+ target.parent.mkdir(parents=True, exist_ok=True)
69
+ part = target.with_name(target.name + ".part")
70
+ urllib.request.urlretrieve(url, part) # nosec B310 - the authors' release, checked below
71
+ with part.open("rb") as stream:
72
+ digest = hashlib.file_digest(stream, "sha256").hexdigest()
73
+ if sha256 and digest != sha256:
74
+ part.unlink()
75
+ raise RuntimeError(f"{url} does not match its recorded hash")
76
+ part.rename(target)
77
+ return target
78
+
79
+
80
+ def pinned_archive(name: str, url: str, sha256: str) -> Path:
81
+ """A release archive at ``url``, downloaded once into the cache, checked against ``sha256`` and unpacked: the
82
+ binaries a baseline was measured with."""
83
+ target = cache_dir() / f"{name}-{sha256[:12]}"
84
+ if not (target / ".unpacked").exists():
85
+ archive = fetch(url, target / "archive", sha256)
86
+ if zipfile.is_zipfile(archive):
87
+ with zipfile.ZipFile(archive) as packed:
88
+ packed.extractall(target) # nosec B202 - our own pinned archive
89
+ for entry in packed.infolist(): # zipfile drops the modes: the binaries must stay executable
90
+ if mode := (entry.external_attr >> 16) & 0o777:
91
+ (target / entry.filename).chmod(mode)
92
+ else:
93
+ shutil.unpack_archive(str(archive), str(target), "gztar")
94
+ archive.unlink()
95
+ (target / ".unpacked").touch()
96
+ return target
97
+
98
+
99
+ def pinned_environment(root: Path, python: str, installs: list[list[str]]) -> Path:
100
+ """A virtual environment at ``root/venv`` on its own Python, made once by uv (``pip install uv``): for the tools
101
+ whose pins do not run on the host's Python. ``installs`` are ``pip install`` argument lists, run in order."""
102
+ try:
103
+ import uv
104
+
105
+ command = uv.find_uv_bin()
106
+ except ImportError:
107
+ command = shutil.which("uv") or ""
108
+ if not command:
109
+ raise RuntimeError("this baseline builds its own Python environment with uv: pip install uv")
110
+ venv = root / "venv"
111
+ if not (venv / ".ready").exists():
112
+ subprocess.run([command, "venv", "--quiet", "--clear", "--python", python, str(venv)], check=True) # nosec B603
113
+ for arguments in installs:
114
+ subprocess.run( # nosec B603
115
+ [
116
+ command,
117
+ "pip",
118
+ "install",
119
+ "--quiet",
120
+ "--no-cache",
121
+ "--python",
122
+ str(venv / "bin" / "python"),
123
+ *arguments,
124
+ ],
125
+ check=True,
126
+ )
127
+ (venv / ".ready").touch()
128
+ return venv
129
+
130
+
131
+ def built_source(name: str, url: str, commit: str, build: Callable[[Path], None]) -> Path:
132
+ """The authors' repository at ``commit``, built once by ``build`` (a marker says it is done)."""
133
+ source = pinned_source(name, url, commit)
134
+ if not (source / ".built").exists():
135
+ build(source)
136
+ (source / ".built").touch()
137
+ return source
138
+
139
+
140
+ def field_from_voxels(displacement: np.ndarray, fixed: sitk.Image) -> np.ndarray:
141
+ """A displacement in voxels along the index axes, ``[i, j, k, D]``, as the benchmark's field ``[D, k, j, i]``
142
+ in mm along the world axes: ``u = D S d``, with ``D`` the direction and ``S`` the spacing of the fixed image."""
143
+ n = fixed.GetDimension()
144
+ to_world = np.array(fixed.GetDirection()).reshape(n, n) @ np.diag(fixed.GetSpacing())
145
+ world = displacement.astype(np.float64) @ to_world.T # [i, j, k, D]
146
+ return np.ascontiguousarray(np.moveaxis(world, -1, 0).transpose(0, *reversed(range(1, n + 1))), dtype=np.float32)
147
+
148
+
149
+ def to_index_array(image: sitk.Image) -> np.ndarray:
150
+ """The image as a ``[i, j, k]`` array, the index axes in ITK's order, which the tools indexed that way read."""
151
+ return np.ascontiguousarray(sitk.GetArrayFromImage(image).transpose(*reversed(range(image.GetDimension()))))
152
+
153
+
154
+ class Registration(torch.nn.Module):
155
+ """Graph module: the pair's tensors and their geometry in, the field out, through the engine, one sample at
156
+ a time. ``accepts_attributes = True`` opts it into the per-branch ``Attribute`` list (the convention of
157
+ ``CriterionWithAttribute``): registration needs the physical geometry."""
158
+
159
+ accepts_attributes = True
160
+
161
+ def __init__(self, engine: Engine) -> None:
162
+ super().__init__()
163
+ self._engine = engine
164
+
165
+ def forward(
166
+ self,
167
+ fixed: torch.Tensor,
168
+ moving: torch.Tensor,
169
+ fixed_mask: torch.Tensor,
170
+ moving_mask: torch.Tensor,
171
+ attributes: list[list[Attribute]],
172
+ ) -> torch.Tensor:
173
+ fixed_attrs, moving_attrs, fixed_mask_attrs, moving_mask_attrs = attributes
174
+ device_index = fixed.device.index if fixed.device.type == "cuda" else -1
175
+ fields = []
176
+ # the engines optimise with autograd; the predictor calls forward under inference mode
177
+ with torch.inference_mode(False), torch.enable_grad():
178
+ for b in range(fixed.shape[0]):
179
+ images = [
180
+ data_to_image(t[b].detach().cpu().numpy(), attrs[b])
181
+ for t, attrs in ((fixed, fixed_attrs), (moving, moving_attrs))
182
+ ]
183
+ masks = [
184
+ data_to_image(t[b].detach().cpu().numpy(), attrs[b]) if not bool((t[b] == 1).all()) else None
185
+ for t, attrs in ((fixed_mask, fixed_mask_attrs), (moving_mask, moving_mask_attrs))
186
+ ]
187
+ fields.append(torch.from_numpy(self._engine(images[0], images[1], masks[0], masks[1], device_index)))
188
+ return torch.stack(fields, dim=0).to(fixed.device)
189
+
190
+
191
+ class BaselineNet(network.Network):
192
+ """A baseline as an ``add_module`` graph: fixed = branch 0, moving = branch 1, the masks branches 2 and 3 (a
193
+ mask of ones means none). The one output is ``DisplacementField``, on the fixed grid."""
194
+
195
+ def __init__(
196
+ self,
197
+ engine: Engine,
198
+ dim: int,
199
+ optimizer: network.OptimizerLoader,
200
+ schedulers: dict[str, network.LRSchedulersLoader],
201
+ outputs_criterions: dict[str, network.TargetCriterionsLoader],
202
+ ) -> None:
203
+ super().__init__(
204
+ in_channels=1, optimizer=optimizer, schedulers=schedulers, outputs_criterions=outputs_criterions, dim=dim
205
+ )
206
+ self.add_module("DisplacementField", Registration(engine), in_branch=[0, 1, 2, 3], out_branch=["dvf"])
Demons/model.py ADDED
@@ -0,0 +1,152 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ # Copyright (c) 2025 Valentin Boussot
2
+ #
3
+ # Licensed under the Apache License, Version 2.0 (the "License");
4
+ # you may not use this file except in compliance with the License.
5
+ # You may obtain a copy of the License at
6
+ #
7
+ # http://www.apache.org/licenses/LICENSE-2.0
8
+ #
9
+ # Unless required by applicable law or agreed to in writing, software
10
+ # distributed under the License is distributed on an "AS IS" BASIS,
11
+ # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12
+ # See the License for the specific language governing permissions and
13
+ # limitations under the License.
14
+ #
15
+ # SPDX-License-Identifier: Apache-2.0
16
+
17
+ """Demons as SimpleITK's own registration notebook runs it (SimpleITK-Notebooks, 66_Registration_Demons):
18
+ fast symmetric forces, 20 iterations, the field smoothed with a standard deviation of 2, over two coarse levels
19
+ (shrink 4 and 2, smoothing 8 and 4) then full resolution; for MR, the notebook's histogram matching first. Demons
20
+ compares intensities: one modality only.
21
+
22
+ NOTE: do NOT add ``from __future__ import annotations``: KonfAI's config engine relies on runtime-evaluated
23
+ annotations (``get_origin``); PEP 563 stringized annotations break binding.
24
+ """
25
+
26
+ import os
27
+ from typing import Annotated
28
+
29
+ import numpy as np
30
+ import SimpleITK as sitk
31
+ from konfai.network import network
32
+ from konfai.utils.config import Choices
33
+
34
+ from baselines import BaselineNet
35
+
36
+
37
+ def smooth_and_resample(image: sitk.Image, shrink: float, sigma: float) -> sitk.Image:
38
+ """The notebook's function, verbatim in substance."""
39
+ smoothed = sitk.SmoothingRecursiveGaussian(image, [sigma] * image.GetDimension())
40
+ size = [int(sz / float(shrink) + 0.5) for sz in image.GetSize()]
41
+ spacing = [
42
+ ((sz - 1) * sp) / (new - 1) for sz, sp, new in zip(image.GetSize(), image.GetSpacing(), size, strict=True)
43
+ ]
44
+ return sitk.Resample(
45
+ smoothed,
46
+ size,
47
+ sitk.Transform(),
48
+ sitk.sitkLinear,
49
+ image.GetOrigin(),
50
+ spacing,
51
+ image.GetDirection(),
52
+ 0.0,
53
+ image.GetPixelID(),
54
+ )
55
+
56
+
57
+ def multiscale_demons(
58
+ algorithm: sitk.ImageFilter, fixed: sitk.Image, moving: sitk.Image, shrinks: list[int], sigmas: list[float]
59
+ ) -> sitk.Image:
60
+ """The notebook's multiscale loop: the field found at a coarse level starts the next, finer one."""
61
+ size = [int(sz / float(shrinks[0]) + 0.5) for sz in fixed.GetSize()]
62
+ spacing = [
63
+ ((sz - 1) * sp) / (new - 1) for sz, sp, new in zip(fixed.GetSize(), fixed.GetSpacing(), size, strict=True)
64
+ ]
65
+ field = sitk.Image(size, sitk.sitkVectorFloat64, fixed.GetDimension())
66
+ field.SetSpacing(spacing)
67
+ field.SetOrigin(fixed.GetOrigin())
68
+ pairs = [
69
+ (smooth_and_resample(fixed, s, g), smooth_and_resample(moving, s, g))
70
+ for s, g in zip(shrinks, sigmas, strict=True)
71
+ ]
72
+ for f, m in [*pairs, (fixed, moving)]:
73
+ field = sitk.Resample(field, f)
74
+ field = algorithm.Execute(f, m, field)
75
+ return field
76
+
77
+
78
+ class Demons:
79
+ def __init__(
80
+ self,
81
+ iterations: int,
82
+ standard_deviation: float,
83
+ shrinks: list[int],
84
+ sigmas: list[float],
85
+ modality: str,
86
+ threads: int,
87
+ ) -> None:
88
+ self._iterations, self._standard_deviation = iterations, standard_deviation
89
+ self._shrinks, self._sigmas, self._modality, self._threads = shrinks, sigmas, modality, threads
90
+
91
+ def __call__(
92
+ self,
93
+ fixed: sitk.Image,
94
+ moving: sitk.Image,
95
+ fixed_mask: sitk.Image | None,
96
+ moving_mask: sitk.Image | None,
97
+ device: int,
98
+ ) -> np.ndarray:
99
+ sitk.ProcessObject.SetGlobalDefaultNumberOfThreads(
100
+ self._threads or int(os.environ.get("ITK_GLOBAL_DEFAULT_NUMBER_OF_THREADS", "8"))
101
+ )
102
+ fixed, moving = sitk.Cast(fixed, sitk.sitkFloat32), sitk.Cast(moving, sitk.sitkFloat32)
103
+ moving = sitk.Resample(
104
+ moving, fixed, sitk.Transform(), sitk.sitkLinear, float(sitk.GetArrayViewFromImage(moving).min())
105
+ )
106
+ modality = (
107
+ self._modality
108
+ if self._modality != "auto"
109
+ else ("ct" if float(sitk.GetArrayViewFromImage(fixed).min()) < -200 else "mr")
110
+ )
111
+ if modality == "mr": # the notebook's histogram matching: Demons assumes equal intensities, MR breaks that
112
+ matcher = sitk.HistogramMatchingImageFilter()
113
+ matcher.SetNumberOfHistogramLevels(1024)
114
+ matcher.SetNumberOfMatchPoints(7)
115
+ matcher.ThresholdAtMeanIntensityOn()
116
+ moving = matcher.Execute(moving, fixed)
117
+ demons = sitk.FastSymmetricForcesDemonsRegistrationFilter()
118
+ demons.SetNumberOfIterations(self._iterations)
119
+ demons.SetSmoothDisplacementField(True)
120
+ demons.SetStandardDeviations(self._standard_deviation)
121
+ field = multiscale_demons(demons, fixed, moving, self._shrinks, self._sigmas)
122
+ return np.ascontiguousarray(np.moveaxis(sitk.GetArrayFromImage(field), -1, 0), dtype=np.float32)
123
+
124
+
125
+ class RegistrationNet(BaselineNet):
126
+ """Demons, the SimpleITK notebook's settings."""
127
+
128
+ def __init__(
129
+ self,
130
+ optimizer: network.OptimizerLoader = network.OptimizerLoader(),
131
+ schedulers: dict[str, network.LRSchedulersLoader] = {
132
+ "default:ReduceLROnPlateau": network.LRSchedulersLoader(0)
133
+ },
134
+ outputs_criterions: dict[str, network.TargetCriterionsLoader] = {"default": network.TargetCriterionsLoader()},
135
+ iterations: Annotated[int, "Demons iterations at each level."] = 20,
136
+ standard_deviation: Annotated[float, "Standard deviation of the field's smoothing, in voxels."] = 2.0,
137
+ shrinks: Annotated[list[int], "Shrink factor of each coarse level, before full resolution."] = [4, 2],
138
+ sigmas: Annotated[list[float], "Smoothing of each coarse level, in voxels."] = [8.0, 4.0],
139
+ modality: Annotated[
140
+ str,
141
+ Choices(["auto", "ct", "mr"]),
142
+ "mr matches the moving histogram to the fixed first; auto reads it off the intensities.",
143
+ ] = "auto",
144
+ threads: Annotated[int, "ITK threads; 0 takes ITK_GLOBAL_DEFAULT_NUMBER_OF_THREADS or 8."] = 0,
145
+ ) -> None:
146
+ super().__init__(
147
+ Demons(iterations, standard_deviation, shrinks, sigmas, modality, threads),
148
+ 3,
149
+ optimizer,
150
+ schedulers,
151
+ outputs_criterions,
152
+ )
Demons/requirements.txt ADDED
@@ -0,0 +1 @@
 
 
1
+ SimpleITK
Greedy/Prediction.yml ADDED
@@ -0,0 +1,87 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ Predictor:
2
+ Model:
3
+ classpath: model:RegistrationNet
4
+ RegistrationNet:
5
+ metric: NCC 2x2x2
6
+ iterations: 100x50x10
7
+ threads: 0
8
+ outputs_criterions: None
9
+ Dataset:
10
+ groups_src:
11
+ Volume_0:
12
+ groups_dest:
13
+ Fixed:
14
+ transforms:
15
+ TensorCast:
16
+ dtype: float32
17
+ inverse: false
18
+ patch_transforms: None
19
+ is_input: true
20
+ Volume_1:
21
+ groups_dest:
22
+ Moving:
23
+ transforms:
24
+ TensorCast:
25
+ dtype: float32
26
+ inverse: false
27
+ patch_transforms: None
28
+ is_input: true
29
+ Volume_2:
30
+ groups_dest:
31
+ FixedMask:
32
+ transforms:
33
+ TensorCast:
34
+ dtype: float32
35
+ inverse: false
36
+ patch_transforms: None
37
+ is_input: true
38
+ Volume_3:
39
+ groups_dest:
40
+ MovingMask:
41
+ transforms:
42
+ TensorCast:
43
+ dtype: float32
44
+ inverse: false
45
+ patch_transforms: None
46
+ is_input: true
47
+ augmentations: None
48
+ Patch:
49
+ patch_size:
50
+ - 0
51
+ - 0
52
+ - 0
53
+ overlap: 0
54
+ pad_value: None
55
+ extend_slice: 0
56
+ mode: resample
57
+ max_voxels: None
58
+ subset: None
59
+ dataset_filenames:
60
+ - ./Dataset/:mha
61
+ batch_size: 1
62
+ num_workers: None
63
+ pin_memory: false
64
+ prefetch_factor: None
65
+ persistent_workers: None
66
+ outputs_dataset:
67
+ DisplacementField:
68
+ OutputDataset:
69
+ name_class: OutputDataset
70
+ before_reduction_transforms: None
71
+ after_reduction_transforms: None
72
+ final_transforms:
73
+ TensorCast:
74
+ dtype: float32
75
+ inverse: false
76
+ dataset_filename: DisplacementField:mha
77
+ group: DisplacementField
78
+ same_as_group: Volume_0:Fixed
79
+ patch_combine: Cosinus
80
+ reduction: Mean
81
+ Mean: {}
82
+ train_name: Baselines-Greedy
83
+ manual_seed: 42
84
+ gpu_checkpoints: None
85
+ combine: Mean
86
+ autocast: false
87
+ data_log: None
Greedy/app.json ADDED
@@ -0,0 +1,40 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ {
2
+ "display_name": "greedy",
3
+ "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 <code>greedy</code>. CPU.",
4
+ "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 <code>greedy</code>. 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).",
5
+ "task": "registration",
6
+ "tta": 0,
7
+ "mc_dropout": 0,
8
+ "models": [],
9
+ "inputs": {
10
+ "Fixed": {
11
+ "display_name": "Fixed image",
12
+ "volume_type": "VOLUME",
13
+ "required": true
14
+ },
15
+ "Moving": {
16
+ "display_name": "Moving image",
17
+ "volume_type": "VOLUME",
18
+ "required": true
19
+ },
20
+ "FixedMask": {
21
+ "display_name": "Fixed mask (ignored by this baseline)",
22
+ "volume_type": "SEGMENTATION",
23
+ "required": false,
24
+ "default": "ones"
25
+ },
26
+ "MovingMask": {
27
+ "display_name": "Moving mask (ignored by this baseline)",
28
+ "volume_type": "SEGMENTATION",
29
+ "required": false,
30
+ "default": "ones"
31
+ }
32
+ },
33
+ "outputs": {
34
+ "DisplacementField": {
35
+ "display_name": "Displacement field",
36
+ "volume_type": "VOLUME",
37
+ "required": true
38
+ }
39
+ }
40
+ }
Greedy/baselines.py ADDED
@@ -0,0 +1,206 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ # Copyright (c) 2025 Valentin Boussot
2
+ #
3
+ # Licensed under the Apache License, Version 2.0 (the "License");
4
+ # you may not use this file except in compliance with the License.
5
+ # You may obtain a copy of the License at
6
+ #
7
+ # http://www.apache.org/licenses/LICENSE-2.0
8
+ #
9
+ # Unless required by applicable law or agreed to in writing, software
10
+ # distributed under the License is distributed on an "AS IS" BASIS,
11
+ # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12
+ # See the License for the specific language governing permissions and
13
+ # limitations under the License.
14
+ #
15
+ # SPDX-License-Identifier: Apache-2.0
16
+
17
+ """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
18
+ engine and gets a displacement field back, and the field's convention.
19
+
20
+ The field is the benchmark's: one component per spatial axis, in mm along the world (ITK, LPS) axes, on the fixed
21
+ image's grid, such that the fixed point ``x`` matches ``x + u(x)`` in the moving image. The predictor attaches the
22
+ fixed image's geometry to the output (``same_as_group: Volume_0:Fixed`` in the app's ``Prediction.yml``).
23
+
24
+ NOTE: do NOT add ``from __future__ import annotations``: KonfAI's config engine relies on runtime-evaluated
25
+ annotations (``get_origin``); PEP 563 stringized annotations break binding.
26
+ """
27
+
28
+ import hashlib
29
+ import os
30
+ import shutil
31
+ import subprocess # nosec B404
32
+ import urllib.request
33
+ import zipfile
34
+ from collections.abc import Callable
35
+ from pathlib import Path
36
+
37
+ import numpy as np
38
+ import SimpleITK as sitk
39
+ import torch
40
+ from konfai.network import network
41
+ from konfai.utils.dataset import Attribute, data_to_image
42
+
43
+ #: An engine: (fixed, moving, fixed mask or None, moving mask or None, CUDA device index or -1) -> the field,
44
+ #: ``[D, *spatial]`` in mm along the world axes on the fixed grid.
45
+ Engine = Callable[[sitk.Image, sitk.Image, sitk.Image | None, sitk.Image | None, int], np.ndarray]
46
+
47
+
48
+ def cache_dir() -> Path:
49
+ """Where the authors' code and binaries live, once fetched: ``$BASELINES_KONFAI_CACHE`` or
50
+ ``~/.cache/baselines-konfai``."""
51
+ return Path(os.environ.get("BASELINES_KONFAI_CACHE", Path.home() / ".cache" / "baselines-konfai"))
52
+
53
+
54
+ def pinned_source(name: str, url: str, commit: str) -> Path:
55
+ """The authors' repository at ``commit``, cloned once into the cache: a baseline runs the code it was
56
+ measured with, never a moving branch."""
57
+ target = cache_dir() / f"{name}-{commit[:12]}"
58
+ if not (target / ".git").exists():
59
+ target.parent.mkdir(parents=True, exist_ok=True)
60
+ subprocess.run(["git", "clone", "--quiet", url, str(target)], check=True) # nosec B603 B607
61
+ subprocess.run(["git", "-C", str(target), "checkout", "--quiet", commit], check=True) # nosec B603 B607
62
+ return target
63
+
64
+
65
+ def fetch(url: str, target: Path, sha256: str | None = None) -> Path:
66
+ """``url`` downloaded once to ``target`` and, when a hash is given, checked against it."""
67
+ if not target.exists():
68
+ target.parent.mkdir(parents=True, exist_ok=True)
69
+ part = target.with_name(target.name + ".part")
70
+ urllib.request.urlretrieve(url, part) # nosec B310 - the authors' release, checked below
71
+ with part.open("rb") as stream:
72
+ digest = hashlib.file_digest(stream, "sha256").hexdigest()
73
+ if sha256 and digest != sha256:
74
+ part.unlink()
75
+ raise RuntimeError(f"{url} does not match its recorded hash")
76
+ part.rename(target)
77
+ return target
78
+
79
+
80
+ def pinned_archive(name: str, url: str, sha256: str) -> Path:
81
+ """A release archive at ``url``, downloaded once into the cache, checked against ``sha256`` and unpacked: the
82
+ binaries a baseline was measured with."""
83
+ target = cache_dir() / f"{name}-{sha256[:12]}"
84
+ if not (target / ".unpacked").exists():
85
+ archive = fetch(url, target / "archive", sha256)
86
+ if zipfile.is_zipfile(archive):
87
+ with zipfile.ZipFile(archive) as packed:
88
+ packed.extractall(target) # nosec B202 - our own pinned archive
89
+ for entry in packed.infolist(): # zipfile drops the modes: the binaries must stay executable
90
+ if mode := (entry.external_attr >> 16) & 0o777:
91
+ (target / entry.filename).chmod(mode)
92
+ else:
93
+ shutil.unpack_archive(str(archive), str(target), "gztar")
94
+ archive.unlink()
95
+ (target / ".unpacked").touch()
96
+ return target
97
+
98
+
99
+ def pinned_environment(root: Path, python: str, installs: list[list[str]]) -> Path:
100
+ """A virtual environment at ``root/venv`` on its own Python, made once by uv (``pip install uv``): for the tools
101
+ whose pins do not run on the host's Python. ``installs`` are ``pip install`` argument lists, run in order."""
102
+ try:
103
+ import uv
104
+
105
+ command = uv.find_uv_bin()
106
+ except ImportError:
107
+ command = shutil.which("uv") or ""
108
+ if not command:
109
+ raise RuntimeError("this baseline builds its own Python environment with uv: pip install uv")
110
+ venv = root / "venv"
111
+ if not (venv / ".ready").exists():
112
+ subprocess.run([command, "venv", "--quiet", "--clear", "--python", python, str(venv)], check=True) # nosec B603
113
+ for arguments in installs:
114
+ subprocess.run( # nosec B603
115
+ [
116
+ command,
117
+ "pip",
118
+ "install",
119
+ "--quiet",
120
+ "--no-cache",
121
+ "--python",
122
+ str(venv / "bin" / "python"),
123
+ *arguments,
124
+ ],
125
+ check=True,
126
+ )
127
+ (venv / ".ready").touch()
128
+ return venv
129
+
130
+
131
+ def built_source(name: str, url: str, commit: str, build: Callable[[Path], None]) -> Path:
132
+ """The authors' repository at ``commit``, built once by ``build`` (a marker says it is done)."""
133
+ source = pinned_source(name, url, commit)
134
+ if not (source / ".built").exists():
135
+ build(source)
136
+ (source / ".built").touch()
137
+ return source
138
+
139
+
140
+ def field_from_voxels(displacement: np.ndarray, fixed: sitk.Image) -> np.ndarray:
141
+ """A displacement in voxels along the index axes, ``[i, j, k, D]``, as the benchmark's field ``[D, k, j, i]``
142
+ in mm along the world axes: ``u = D S d``, with ``D`` the direction and ``S`` the spacing of the fixed image."""
143
+ n = fixed.GetDimension()
144
+ to_world = np.array(fixed.GetDirection()).reshape(n, n) @ np.diag(fixed.GetSpacing())
145
+ world = displacement.astype(np.float64) @ to_world.T # [i, j, k, D]
146
+ return np.ascontiguousarray(np.moveaxis(world, -1, 0).transpose(0, *reversed(range(1, n + 1))), dtype=np.float32)
147
+
148
+
149
+ def to_index_array(image: sitk.Image) -> np.ndarray:
150
+ """The image as a ``[i, j, k]`` array, the index axes in ITK's order, which the tools indexed that way read."""
151
+ return np.ascontiguousarray(sitk.GetArrayFromImage(image).transpose(*reversed(range(image.GetDimension()))))
152
+
153
+
154
+ class Registration(torch.nn.Module):
155
+ """Graph module: the pair's tensors and their geometry in, the field out, through the engine, one sample at
156
+ a time. ``accepts_attributes = True`` opts it into the per-branch ``Attribute`` list (the convention of
157
+ ``CriterionWithAttribute``): registration needs the physical geometry."""
158
+
159
+ accepts_attributes = True
160
+
161
+ def __init__(self, engine: Engine) -> None:
162
+ super().__init__()
163
+ self._engine = engine
164
+
165
+ def forward(
166
+ self,
167
+ fixed: torch.Tensor,
168
+ moving: torch.Tensor,
169
+ fixed_mask: torch.Tensor,
170
+ moving_mask: torch.Tensor,
171
+ attributes: list[list[Attribute]],
172
+ ) -> torch.Tensor:
173
+ fixed_attrs, moving_attrs, fixed_mask_attrs, moving_mask_attrs = attributes
174
+ device_index = fixed.device.index if fixed.device.type == "cuda" else -1
175
+ fields = []
176
+ # the engines optimise with autograd; the predictor calls forward under inference mode
177
+ with torch.inference_mode(False), torch.enable_grad():
178
+ for b in range(fixed.shape[0]):
179
+ images = [
180
+ data_to_image(t[b].detach().cpu().numpy(), attrs[b])
181
+ for t, attrs in ((fixed, fixed_attrs), (moving, moving_attrs))
182
+ ]
183
+ masks = [
184
+ data_to_image(t[b].detach().cpu().numpy(), attrs[b]) if not bool((t[b] == 1).all()) else None
185
+ for t, attrs in ((fixed_mask, fixed_mask_attrs), (moving_mask, moving_mask_attrs))
186
+ ]
187
+ fields.append(torch.from_numpy(self._engine(images[0], images[1], masks[0], masks[1], device_index)))
188
+ return torch.stack(fields, dim=0).to(fixed.device)
189
+
190
+
191
+ class BaselineNet(network.Network):
192
+ """A baseline as an ``add_module`` graph: fixed = branch 0, moving = branch 1, the masks branches 2 and 3 (a
193
+ mask of ones means none). The one output is ``DisplacementField``, on the fixed grid."""
194
+
195
+ def __init__(
196
+ self,
197
+ engine: Engine,
198
+ dim: int,
199
+ optimizer: network.OptimizerLoader,
200
+ schedulers: dict[str, network.LRSchedulersLoader],
201
+ outputs_criterions: dict[str, network.TargetCriterionsLoader],
202
+ ) -> None:
203
+ super().__init__(
204
+ in_channels=1, optimizer=optimizer, schedulers=schedulers, outputs_criterions=outputs_criterions, dim=dim
205
+ )
206
+ self.add_module("DisplacementField", Registration(engine), in_branch=[0, 1, 2, 3], out_branch=["dvf"])
Greedy/model.py ADDED
@@ -0,0 +1,79 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ # Copyright (c) 2025 Valentin Boussot
2
+ #
3
+ # Licensed under the Apache License, Version 2.0 (the "License");
4
+ # you may not use this file except in compliance with the License.
5
+ # You may obtain a copy of the License at
6
+ #
7
+ # http://www.apache.org/licenses/LICENSE-2.0
8
+ #
9
+ # Unless required by applicable law or agreed to in writing, software
10
+ # distributed under the License is distributed on an "AS IS" BASIS,
11
+ # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12
+ # See the License for the specific language governing permissions and
13
+ # limitations under the License.
14
+ #
15
+ # SPDX-License-Identifier: Apache-2.0
16
+
17
+ """greedy as its Quick Start runs it (the ``picsl_greedy`` package at a pinned version): normalised cross-correlation
18
+ over a 2x2x2 window, 100x50x10 iterations, the deformable stage alone. One modality only.
19
+
20
+ NOTE: do NOT add ``from __future__ import annotations``: KonfAI's config engine relies on runtime-evaluated
21
+ annotations (``get_origin``); PEP 563 stringized annotations break binding.
22
+ """
23
+
24
+ import os
25
+ import tempfile
26
+ from pathlib import Path
27
+ from typing import Annotated
28
+
29
+ import numpy as np
30
+ import SimpleITK as sitk
31
+ from konfai.network import network
32
+
33
+ from baselines import BaselineNet
34
+
35
+ VERSION = "1.4.0.3" # the picsl_greedy package; the bundle's requirements pin it
36
+
37
+
38
+ class Greedy:
39
+ def __init__(self, metric: str, iterations: str, threads: int) -> None:
40
+ self._metric, self._iterations, self._threads = metric, iterations, threads
41
+
42
+ def __call__(
43
+ self,
44
+ fixed: sitk.Image,
45
+ moving: sitk.Image,
46
+ fixed_mask: sitk.Image | None,
47
+ moving_mask: sitk.Image | None,
48
+ device: int,
49
+ ) -> np.ndarray:
50
+ from picsl_greedy import Greedy3D
51
+
52
+ threads = self._threads or int(os.environ.get("ITK_GLOBAL_DEFAULT_NUMBER_OF_THREADS", "8"))
53
+ with tempfile.TemporaryDirectory(prefix="greedy_") as scratch:
54
+ work = Path(scratch)
55
+ sitk.WriteImage(fixed, str(work / "fixed.nii.gz"))
56
+ sitk.WriteImage(moving, str(work / "moving.nii.gz"))
57
+ Greedy3D().execute(
58
+ f"-d 3 -threads {threads} -m {self._metric} -i {work / 'fixed.nii.gz'} {work / 'moving.nii.gz'} "
59
+ f"-n {self._iterations} -o {work / 'warp.nii.gz'}"
60
+ )
61
+ warp = sitk.ReadImage(str(work / "warp.nii.gz"), sitk.sitkVectorFloat32)
62
+ return np.ascontiguousarray(np.moveaxis(sitk.GetArrayFromImage(warp), -1, 0), dtype=np.float32)
63
+
64
+
65
+ class RegistrationNet(BaselineNet):
66
+ """greedy, the Quick Start's deformable call. CPU."""
67
+
68
+ def __init__(
69
+ self,
70
+ optimizer: network.OptimizerLoader = network.OptimizerLoader(),
71
+ schedulers: dict[str, network.LRSchedulersLoader] = {
72
+ "default:ReduceLROnPlateau": network.LRSchedulersLoader(0)
73
+ },
74
+ outputs_criterions: dict[str, network.TargetCriterionsLoader] = {"default": network.TargetCriterionsLoader()},
75
+ metric: Annotated[str, "greedy's -m: the similarity, NCC with its window."] = "NCC 2x2x2",
76
+ iterations: Annotated[str, "greedy's -n: iterations per level."] = "100x50x10",
77
+ threads: Annotated[int, "greedy's -threads; 0 takes ITK_GLOBAL_DEFAULT_NUMBER_OF_THREADS or 8."] = 0,
78
+ ) -> None:
79
+ super().__init__(Greedy(metric, iterations, threads), 3, optimizer, schedulers, outputs_criterions)
Greedy/requirements.txt ADDED
@@ -0,0 +1,2 @@
 
 
 
1
+ SimpleITK
2
+ picsl_greedy==1.4.0.3
MultiGradICON/Prediction.yml ADDED
@@ -0,0 +1,90 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ Predictor:
2
+ Model:
3
+ classpath: model:RegistrationNet
4
+ RegistrationNet:
5
+ model: multigradicon
6
+ masks: false
7
+ fixed_modality: auto
8
+ moving_modality: auto
9
+ iterations: 50
10
+ similarity: lncc
11
+ outputs_criterions: None
12
+ Dataset:
13
+ groups_src:
14
+ Volume_0:
15
+ groups_dest:
16
+ Fixed:
17
+ transforms:
18
+ TensorCast:
19
+ dtype: float32
20
+ inverse: false
21
+ patch_transforms: None
22
+ is_input: true
23
+ Volume_1:
24
+ groups_dest:
25
+ Moving:
26
+ transforms:
27
+ TensorCast:
28
+ dtype: float32
29
+ inverse: false
30
+ patch_transforms: None
31
+ is_input: true
32
+ Volume_2:
33
+ groups_dest:
34
+ FixedMask:
35
+ transforms:
36
+ TensorCast:
37
+ dtype: float32
38
+ inverse: false
39
+ patch_transforms: None
40
+ is_input: true
41
+ Volume_3:
42
+ groups_dest:
43
+ MovingMask:
44
+ transforms:
45
+ TensorCast:
46
+ dtype: float32
47
+ inverse: false
48
+ patch_transforms: None
49
+ is_input: true
50
+ augmentations: None
51
+ Patch:
52
+ patch_size:
53
+ - 0
54
+ - 0
55
+ - 0
56
+ overlap: 0
57
+ pad_value: None
58
+ extend_slice: 0
59
+ mode: resample
60
+ max_voxels: None
61
+ subset: None
62
+ dataset_filenames:
63
+ - ./Dataset/:mha
64
+ batch_size: 1
65
+ num_workers: None
66
+ pin_memory: false
67
+ prefetch_factor: None
68
+ persistent_workers: None
69
+ outputs_dataset:
70
+ DisplacementField:
71
+ OutputDataset:
72
+ name_class: OutputDataset
73
+ before_reduction_transforms: None
74
+ after_reduction_transforms: None
75
+ final_transforms:
76
+ TensorCast:
77
+ dtype: float32
78
+ inverse: false
79
+ dataset_filename: DisplacementField:mha
80
+ group: DisplacementField
81
+ same_as_group: Volume_0:Fixed
82
+ patch_combine: Cosinus
83
+ reduction: Mean
84
+ Mean: {}
85
+ train_name: Baselines-MultiGradICON
86
+ manual_seed: 42
87
+ gpu_checkpoints: None
88
+ combine: Mean
89
+ autocast: false
90
+ data_log: None
MultiGradICON/app.json ADDED
@@ -0,0 +1,40 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ {
2
+ "display_name": "multiGradICON",
3
+ "short_description": "The multiGradICON network's prediction, then 50 steps of instance optimisation on LNCC: <code>unigradicon-register --model multigradicon</code> with its defaults, the ImagingBenchmarks baseline <code>multigradicon</code>.",
4
+ "description": "The multiGradICON network's prediction, then 50 steps of instance optimisation on LNCC: <code>unigradicon-register --model multigradicon</code> with its defaults, the ImagingBenchmarks baseline <code>multigradicon</code>. With <code>--set masks=true</code> each image is multiplied by its lung mask, the authors' Learn2Reg lung protocol (the ImagingBenchmarks line <code>multigradicon_lungmask</code>). 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, <code>ct</code> (clamped to [-1000, 1000] HU) and <code>mri</code> (minimum to the 99th percentile), read off the intensities. The weights come from <a href='https://github.com/uncbiag/uniGradICON'>the authors' release</a>, 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).<br><br><b>How to cite:</b><br><cite>L. Tian et al., <i>uniGradICON: A foundation model for medical image registration</i>, MICCAI 2024; B. Demir et al., <i>multiGradICON</i>, WBIR 2024.</cite>",
5
+ "task": "registration",
6
+ "tta": 0,
7
+ "mc_dropout": 0,
8
+ "models": [],
9
+ "inputs": {
10
+ "Fixed": {
11
+ "display_name": "Fixed image",
12
+ "volume_type": "VOLUME",
13
+ "required": true
14
+ },
15
+ "Moving": {
16
+ "display_name": "Moving image",
17
+ "volume_type": "VOLUME",
18
+ "required": true
19
+ },
20
+ "FixedMask": {
21
+ "display_name": "Fixed lung mask (used with masks=true)",
22
+ "volume_type": "SEGMENTATION",
23
+ "required": false,
24
+ "default": "ones"
25
+ },
26
+ "MovingMask": {
27
+ "display_name": "Moving lung mask (used with masks=true)",
28
+ "volume_type": "SEGMENTATION",
29
+ "required": false,
30
+ "default": "ones"
31
+ }
32
+ },
33
+ "outputs": {
34
+ "DisplacementField": {
35
+ "display_name": "Displacement field",
36
+ "volume_type": "VOLUME",
37
+ "required": true
38
+ }
39
+ }
40
+ }
MultiGradICON/baselines.py ADDED
@@ -0,0 +1,206 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ # Copyright (c) 2025 Valentin Boussot
2
+ #
3
+ # Licensed under the Apache License, Version 2.0 (the "License");
4
+ # you may not use this file except in compliance with the License.
5
+ # You may obtain a copy of the License at
6
+ #
7
+ # http://www.apache.org/licenses/LICENSE-2.0
8
+ #
9
+ # Unless required by applicable law or agreed to in writing, software
10
+ # distributed under the License is distributed on an "AS IS" BASIS,
11
+ # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12
+ # See the License for the specific language governing permissions and
13
+ # limitations under the License.
14
+ #
15
+ # SPDX-License-Identifier: Apache-2.0
16
+
17
+ """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
18
+ engine and gets a displacement field back, and the field's convention.
19
+
20
+ The field is the benchmark's: one component per spatial axis, in mm along the world (ITK, LPS) axes, on the fixed
21
+ image's grid, such that the fixed point ``x`` matches ``x + u(x)`` in the moving image. The predictor attaches the
22
+ fixed image's geometry to the output (``same_as_group: Volume_0:Fixed`` in the app's ``Prediction.yml``).
23
+
24
+ NOTE: do NOT add ``from __future__ import annotations``: KonfAI's config engine relies on runtime-evaluated
25
+ annotations (``get_origin``); PEP 563 stringized annotations break binding.
26
+ """
27
+
28
+ import hashlib
29
+ import os
30
+ import shutil
31
+ import subprocess # nosec B404
32
+ import urllib.request
33
+ import zipfile
34
+ from collections.abc import Callable
35
+ from pathlib import Path
36
+
37
+ import numpy as np
38
+ import SimpleITK as sitk
39
+ import torch
40
+ from konfai.network import network
41
+ from konfai.utils.dataset import Attribute, data_to_image
42
+
43
+ #: An engine: (fixed, moving, fixed mask or None, moving mask or None, CUDA device index or -1) -> the field,
44
+ #: ``[D, *spatial]`` in mm along the world axes on the fixed grid.
45
+ Engine = Callable[[sitk.Image, sitk.Image, sitk.Image | None, sitk.Image | None, int], np.ndarray]
46
+
47
+
48
+ def cache_dir() -> Path:
49
+ """Where the authors' code and binaries live, once fetched: ``$BASELINES_KONFAI_CACHE`` or
50
+ ``~/.cache/baselines-konfai``."""
51
+ return Path(os.environ.get("BASELINES_KONFAI_CACHE", Path.home() / ".cache" / "baselines-konfai"))
52
+
53
+
54
+ def pinned_source(name: str, url: str, commit: str) -> Path:
55
+ """The authors' repository at ``commit``, cloned once into the cache: a baseline runs the code it was
56
+ measured with, never a moving branch."""
57
+ target = cache_dir() / f"{name}-{commit[:12]}"
58
+ if not (target / ".git").exists():
59
+ target.parent.mkdir(parents=True, exist_ok=True)
60
+ subprocess.run(["git", "clone", "--quiet", url, str(target)], check=True) # nosec B603 B607
61
+ subprocess.run(["git", "-C", str(target), "checkout", "--quiet", commit], check=True) # nosec B603 B607
62
+ return target
63
+
64
+
65
+ def fetch(url: str, target: Path, sha256: str | None = None) -> Path:
66
+ """``url`` downloaded once to ``target`` and, when a hash is given, checked against it."""
67
+ if not target.exists():
68
+ target.parent.mkdir(parents=True, exist_ok=True)
69
+ part = target.with_name(target.name + ".part")
70
+ urllib.request.urlretrieve(url, part) # nosec B310 - the authors' release, checked below
71
+ with part.open("rb") as stream:
72
+ digest = hashlib.file_digest(stream, "sha256").hexdigest()
73
+ if sha256 and digest != sha256:
74
+ part.unlink()
75
+ raise RuntimeError(f"{url} does not match its recorded hash")
76
+ part.rename(target)
77
+ return target
78
+
79
+
80
+ def pinned_archive(name: str, url: str, sha256: str) -> Path:
81
+ """A release archive at ``url``, downloaded once into the cache, checked against ``sha256`` and unpacked: the
82
+ binaries a baseline was measured with."""
83
+ target = cache_dir() / f"{name}-{sha256[:12]}"
84
+ if not (target / ".unpacked").exists():
85
+ archive = fetch(url, target / "archive", sha256)
86
+ if zipfile.is_zipfile(archive):
87
+ with zipfile.ZipFile(archive) as packed:
88
+ packed.extractall(target) # nosec B202 - our own pinned archive
89
+ for entry in packed.infolist(): # zipfile drops the modes: the binaries must stay executable
90
+ if mode := (entry.external_attr >> 16) & 0o777:
91
+ (target / entry.filename).chmod(mode)
92
+ else:
93
+ shutil.unpack_archive(str(archive), str(target), "gztar")
94
+ archive.unlink()
95
+ (target / ".unpacked").touch()
96
+ return target
97
+
98
+
99
+ def pinned_environment(root: Path, python: str, installs: list[list[str]]) -> Path:
100
+ """A virtual environment at ``root/venv`` on its own Python, made once by uv (``pip install uv``): for the tools
101
+ whose pins do not run on the host's Python. ``installs`` are ``pip install`` argument lists, run in order."""
102
+ try:
103
+ import uv
104
+
105
+ command = uv.find_uv_bin()
106
+ except ImportError:
107
+ command = shutil.which("uv") or ""
108
+ if not command:
109
+ raise RuntimeError("this baseline builds its own Python environment with uv: pip install uv")
110
+ venv = root / "venv"
111
+ if not (venv / ".ready").exists():
112
+ subprocess.run([command, "venv", "--quiet", "--clear", "--python", python, str(venv)], check=True) # nosec B603
113
+ for arguments in installs:
114
+ subprocess.run( # nosec B603
115
+ [
116
+ command,
117
+ "pip",
118
+ "install",
119
+ "--quiet",
120
+ "--no-cache",
121
+ "--python",
122
+ str(venv / "bin" / "python"),
123
+ *arguments,
124
+ ],
125
+ check=True,
126
+ )
127
+ (venv / ".ready").touch()
128
+ return venv
129
+
130
+
131
+ def built_source(name: str, url: str, commit: str, build: Callable[[Path], None]) -> Path:
132
+ """The authors' repository at ``commit``, built once by ``build`` (a marker says it is done)."""
133
+ source = pinned_source(name, url, commit)
134
+ if not (source / ".built").exists():
135
+ build(source)
136
+ (source / ".built").touch()
137
+ return source
138
+
139
+
140
+ def field_from_voxels(displacement: np.ndarray, fixed: sitk.Image) -> np.ndarray:
141
+ """A displacement in voxels along the index axes, ``[i, j, k, D]``, as the benchmark's field ``[D, k, j, i]``
142
+ in mm along the world axes: ``u = D S d``, with ``D`` the direction and ``S`` the spacing of the fixed image."""
143
+ n = fixed.GetDimension()
144
+ to_world = np.array(fixed.GetDirection()).reshape(n, n) @ np.diag(fixed.GetSpacing())
145
+ world = displacement.astype(np.float64) @ to_world.T # [i, j, k, D]
146
+ return np.ascontiguousarray(np.moveaxis(world, -1, 0).transpose(0, *reversed(range(1, n + 1))), dtype=np.float32)
147
+
148
+
149
+ def to_index_array(image: sitk.Image) -> np.ndarray:
150
+ """The image as a ``[i, j, k]`` array, the index axes in ITK's order, which the tools indexed that way read."""
151
+ return np.ascontiguousarray(sitk.GetArrayFromImage(image).transpose(*reversed(range(image.GetDimension()))))
152
+
153
+
154
+ class Registration(torch.nn.Module):
155
+ """Graph module: the pair's tensors and their geometry in, the field out, through the engine, one sample at
156
+ a time. ``accepts_attributes = True`` opts it into the per-branch ``Attribute`` list (the convention of
157
+ ``CriterionWithAttribute``): registration needs the physical geometry."""
158
+
159
+ accepts_attributes = True
160
+
161
+ def __init__(self, engine: Engine) -> None:
162
+ super().__init__()
163
+ self._engine = engine
164
+
165
+ def forward(
166
+ self,
167
+ fixed: torch.Tensor,
168
+ moving: torch.Tensor,
169
+ fixed_mask: torch.Tensor,
170
+ moving_mask: torch.Tensor,
171
+ attributes: list[list[Attribute]],
172
+ ) -> torch.Tensor:
173
+ fixed_attrs, moving_attrs, fixed_mask_attrs, moving_mask_attrs = attributes
174
+ device_index = fixed.device.index if fixed.device.type == "cuda" else -1
175
+ fields = []
176
+ # the engines optimise with autograd; the predictor calls forward under inference mode
177
+ with torch.inference_mode(False), torch.enable_grad():
178
+ for b in range(fixed.shape[0]):
179
+ images = [
180
+ data_to_image(t[b].detach().cpu().numpy(), attrs[b])
181
+ for t, attrs in ((fixed, fixed_attrs), (moving, moving_attrs))
182
+ ]
183
+ masks = [
184
+ data_to_image(t[b].detach().cpu().numpy(), attrs[b]) if not bool((t[b] == 1).all()) else None
185
+ for t, attrs in ((fixed_mask, fixed_mask_attrs), (moving_mask, moving_mask_attrs))
186
+ ]
187
+ fields.append(torch.from_numpy(self._engine(images[0], images[1], masks[0], masks[1], device_index)))
188
+ return torch.stack(fields, dim=0).to(fixed.device)
189
+
190
+
191
+ class BaselineNet(network.Network):
192
+ """A baseline as an ``add_module`` graph: fixed = branch 0, moving = branch 1, the masks branches 2 and 3 (a
193
+ mask of ones means none). The one output is ``DisplacementField``, on the fixed grid."""
194
+
195
+ def __init__(
196
+ self,
197
+ engine: Engine,
198
+ dim: int,
199
+ optimizer: network.OptimizerLoader,
200
+ schedulers: dict[str, network.LRSchedulersLoader],
201
+ outputs_criterions: dict[str, network.TargetCriterionsLoader],
202
+ ) -> None:
203
+ super().__init__(
204
+ in_channels=1, optimizer=optimizer, schedulers=schedulers, outputs_criterions=outputs_criterions, dim=dim
205
+ )
206
+ self.add_module("DisplacementField", Registration(engine), in_branch=[0, 1, 2, 3], out_branch=["dvf"])
MultiGradICON/model.py ADDED
@@ -0,0 +1,194 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ # Copyright (c) 2025 Valentin Boussot
2
+ #
3
+ # Licensed under the Apache License, Version 2.0 (the "License");
4
+ # you may not use this file except in compliance with the License.
5
+ # You may obtain a copy of the License at
6
+ #
7
+ # http://www.apache.org/licenses/LICENSE-2.0
8
+ #
9
+ # Unless required by applicable law or agreed to in writing, software
10
+ # distributed under the License is distributed on an "AS IS" BASIS,
11
+ # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12
+ # See the License for the specific language governing permissions and
13
+ # limitations under the License.
14
+ #
15
+ # SPDX-License-Identifier: Apache-2.0
16
+
17
+ """uniGradICON and multiGradICON through the authors' command, ``unigradicon-register`` (the ``unigradicon``
18
+ package at a pinned version), with its defaults: the network's prediction, then 50 steps of instance optimisation
19
+ on LNCC; the weights fetched from the authors' release and checked against their hash. The authors' lung protocol
20
+ (``masks``) multiplies each image by its mask, as their Learn2Reg submissions did.
21
+
22
+ NOTE: do NOT add ``from __future__ import annotations``: KonfAI's config engine relies on runtime-evaluated
23
+ annotations (``get_origin``); PEP 563 stringized annotations break binding.
24
+ """
25
+
26
+ import hashlib
27
+ import os
28
+ import shutil
29
+ import subprocess # nosec B404
30
+ import tempfile
31
+ import urllib.request
32
+ from pathlib import Path
33
+ from typing import Annotated
34
+
35
+ import numpy as np
36
+ import SimpleITK as sitk
37
+ from konfai.network import network
38
+ from konfai.utils.config import Choices
39
+
40
+ from baselines import BaselineNet, cache_dir
41
+
42
+ VERSION = "1.0.5" # the unigradicon package; the bundle's requirements pin it
43
+ WEIGHTS = { # the authors' release, sha256 of each file
44
+ "unigradicon": (
45
+ "https://github.com/uncbiag/uniGradICON/releases/download/unigradicon_weights/Step_2_final.trch",
46
+ "1fcfa02214540915cad7b768570add2b4247c22c516d75a21e0e8258f50254a6",
47
+ ),
48
+ "multigradicon": (
49
+ "https://github.com/uncbiag/uniGradICON/releases/download/multigradicon_weights/Step_2_final.trch",
50
+ "c37a7cf5c0576f24b03418f3f659eedde9aaf6b9c1e42469d3fe3eacbb901e01",
51
+ ),
52
+ }
53
+
54
+
55
+ def weights_dir(model: str) -> Path:
56
+ """Where the command finds ``network_weights/<model>1.0/Step_2_final.trch``: it reads them relative to its
57
+ working directory, so the engine runs it from here."""
58
+ root = cache_dir() / "unigradicon"
59
+ target = root / "network_weights" / f"{model}1.0" / "Step_2_final.trch"
60
+ url, digest = WEIGHTS[model]
61
+ if not target.exists() or hashlib.sha256(target.read_bytes()).hexdigest() != digest:
62
+ target.parent.mkdir(parents=True, exist_ok=True)
63
+ urllib.request.urlretrieve(url, target) # nosec B310 - the authors' release, checked below
64
+ if hashlib.sha256(target.read_bytes()).hexdigest() != digest:
65
+ raise RuntimeError(f"the {model} weights do not match their published hash")
66
+ return root
67
+
68
+
69
+ def modality_of(image: sitk.Image, declared: str) -> str:
70
+ """The command's modality: ``ct`` (clamped to [-1000, 1000] HU) or ``mri`` (minimum to the 99th percentile).
71
+ ``auto`` reads it off the intensities: Hounsfield units go below -200."""
72
+ if declared in ("ct", "mri"):
73
+ return declared
74
+ return "ct" if float(sitk.GetArrayViewFromImage(image).min()) < -200 else "mri"
75
+
76
+
77
+ def _on_grid(mask: sitk.Image, image: sitk.Image) -> sitk.Image:
78
+ """The mask on its image's grid: the command multiplies the two and refuses the slightest header difference."""
79
+ if mask.GetSize() == image.GetSize():
80
+ mask.CopyInformation(image)
81
+ return mask
82
+ return sitk.Resample(mask, image, sitk.Transform(), sitk.sitkNearestNeighbor, 0)
83
+
84
+
85
+ class GradICON:
86
+ def __init__(
87
+ self, model: str, masks: bool, fixed_modality: str, moving_modality: str, iterations: int, similarity: str
88
+ ) -> None:
89
+ self._model, self._masks = model, masks
90
+ self._modalities = (fixed_modality, moving_modality)
91
+ self._iterations, self._similarity = iterations, similarity
92
+
93
+ def __call__(
94
+ self,
95
+ fixed: sitk.Image,
96
+ moving: sitk.Image,
97
+ fixed_mask: sitk.Image | None,
98
+ moving_mask: sitk.Image | None,
99
+ device: int,
100
+ ) -> np.ndarray:
101
+ command = os.environ.get("UNIGRADICON_REGISTER") or shutil.which("unigradicon-register")
102
+ if not command:
103
+ raise RuntimeError(f"unigradicon-register was not found: pip install unigradicon=={VERSION}")
104
+ with tempfile.TemporaryDirectory(prefix="gradicon_") as scratch:
105
+ work = Path(scratch)
106
+ sitk.WriteImage(fixed, str(work / "fixed.nii.gz"))
107
+ sitk.WriteImage(moving, str(work / "moving.nii.gz"))
108
+ arguments = [
109
+ command,
110
+ "--fixed",
111
+ str(work / "fixed.nii.gz"),
112
+ "--fixed_modality",
113
+ modality_of(fixed, self._modalities[0]),
114
+ "--moving",
115
+ str(work / "moving.nii.gz"),
116
+ "--moving_modality",
117
+ modality_of(moving, self._modalities[1]),
118
+ "--transform_out",
119
+ str(work / "transform.hdf5"),
120
+ "--model",
121
+ self._model,
122
+ "--io_iterations",
123
+ str(self._iterations),
124
+ "--io_sim",
125
+ self._similarity,
126
+ ]
127
+ if self._masks:
128
+ if fixed_mask is None or moving_mask is None:
129
+ raise ValueError("the lung protocol needs the fixed and the moving mask")
130
+ sitk.WriteImage(_on_grid(fixed_mask, fixed), str(work / "fixed_mask.nii.gz"))
131
+ sitk.WriteImage(_on_grid(moving_mask, moving), str(work / "moving_mask.nii.gz"))
132
+ arguments += [
133
+ "--fixed_segmentation",
134
+ str(work / "fixed_mask.nii.gz"),
135
+ "--moving_segmentation",
136
+ str(work / "moving_mask.nii.gz"),
137
+ ]
138
+ environment = {**os.environ, "CUDA_VISIBLE_DEVICES": str(device) if device >= 0 else ""}
139
+ subprocess.run(arguments, check=True, cwd=weights_dir(self._model), env=environment) # nosec B603
140
+ transform = sitk.ReadTransform(str(work / "transform.hdf5"))
141
+ # the command's transform maps a fixed point to its moving point: sampled on the fixed grid it is the field
142
+ field = sitk.TransformToDisplacementField(
143
+ transform,
144
+ sitk.sitkVectorFloat64,
145
+ fixed.GetSize(),
146
+ fixed.GetOrigin(),
147
+ fixed.GetSpacing(),
148
+ fixed.GetDirection(),
149
+ )
150
+ return np.ascontiguousarray(np.moveaxis(sitk.GetArrayFromImage(field), -1, 0), dtype=np.float32)
151
+
152
+
153
+ class RegistrationNet(BaselineNet):
154
+ """uniGradICON or multiGradICON as the authors' command runs them."""
155
+
156
+ def __init__(
157
+ self,
158
+ optimizer: network.OptimizerLoader = network.OptimizerLoader(),
159
+ schedulers: dict[str, network.LRSchedulersLoader] = {
160
+ "default:ReduceLROnPlateau": network.LRSchedulersLoader(0)
161
+ },
162
+ outputs_criterions: dict[str, network.TargetCriterionsLoader] = {"default": network.TargetCriterionsLoader()},
163
+ model: Annotated[
164
+ str, Choices(["unigradicon", "multigradicon"]), "The network: uniGradICON or multiGradICON."
165
+ ] = "unigradicon",
166
+ masks: Annotated[
167
+ bool, "The authors' lung protocol: each image multiplied by its mask before registration."
168
+ ] = False,
169
+ fixed_modality: Annotated[
170
+ str,
171
+ Choices(["auto", "ct", "mri"]),
172
+ "The command's modality of the fixed image; auto reads it off the intensities.",
173
+ ] = "auto",
174
+ moving_modality: Annotated[
175
+ str,
176
+ Choices(["auto", "ct", "mri"]),
177
+ "The command's modality of the moving image; auto reads it off the intensities.",
178
+ ] = "auto",
179
+ iterations: Annotated[
180
+ int, "Steps of instance optimisation after the network's prediction (the command's default)."
181
+ ] = 50,
182
+ similarity: Annotated[
183
+ str,
184
+ Choices(["lncc", "lncc2", "mind"]),
185
+ "The similarity of the instance optimisation (the command's default).",
186
+ ] = "lncc",
187
+ ) -> None:
188
+ super().__init__(
189
+ GradICON(model, masks, fixed_modality, moving_modality, iterations, similarity),
190
+ 3,
191
+ optimizer,
192
+ schedulers,
193
+ outputs_criterions,
194
+ )
MultiGradICON/requirements.txt ADDED
@@ -0,0 +1,4 @@
 
 
 
 
 
1
+ SimpleITK
2
+ unigradicon==1.0.5
3
+ icon_registration==1.1.8
4
+ itk==6.0b2
NiftyReg/Prediction.yml ADDED
@@ -0,0 +1,86 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ Predictor:
2
+ Model:
3
+ classpath: model:RegistrationNet
4
+ RegistrationNet:
5
+ arguments: []
6
+ threads: 0
7
+ outputs_criterions: None
8
+ Dataset:
9
+ groups_src:
10
+ Volume_0:
11
+ groups_dest:
12
+ Fixed:
13
+ transforms:
14
+ TensorCast:
15
+ dtype: float32
16
+ inverse: false
17
+ patch_transforms: None
18
+ is_input: true
19
+ Volume_1:
20
+ groups_dest:
21
+ Moving:
22
+ transforms:
23
+ TensorCast:
24
+ dtype: float32
25
+ inverse: false
26
+ patch_transforms: None
27
+ is_input: true
28
+ Volume_2:
29
+ groups_dest:
30
+ FixedMask:
31
+ transforms:
32
+ TensorCast:
33
+ dtype: float32
34
+ inverse: false
35
+ patch_transforms: None
36
+ is_input: true
37
+ Volume_3:
38
+ groups_dest:
39
+ MovingMask:
40
+ transforms:
41
+ TensorCast:
42
+ dtype: float32
43
+ inverse: false
44
+ patch_transforms: None
45
+ is_input: true
46
+ augmentations: None
47
+ Patch:
48
+ patch_size:
49
+ - 0
50
+ - 0
51
+ - 0
52
+ overlap: 0
53
+ pad_value: None
54
+ extend_slice: 0
55
+ mode: resample
56
+ max_voxels: None
57
+ subset: None
58
+ dataset_filenames:
59
+ - ./Dataset/:mha
60
+ batch_size: 1
61
+ num_workers: None
62
+ pin_memory: false
63
+ prefetch_factor: None
64
+ persistent_workers: None
65
+ outputs_dataset:
66
+ DisplacementField:
67
+ OutputDataset:
68
+ name_class: OutputDataset
69
+ before_reduction_transforms: None
70
+ after_reduction_transforms: None
71
+ final_transforms:
72
+ TensorCast:
73
+ dtype: float32
74
+ inverse: false
75
+ dataset_filename: DisplacementField:mha
76
+ group: DisplacementField
77
+ same_as_group: Volume_0:Fixed
78
+ patch_combine: Cosinus
79
+ reduction: Mean
80
+ Mean: {}
81
+ train_name: Baselines-NiftyReg
82
+ manual_seed: 42
83
+ gpu_checkpoints: None
84
+ combine: Mean
85
+ autocast: false
86
+ data_log: None
NiftyReg/app.json ADDED
@@ -0,0 +1,40 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ {
2
+ "display_name": "NiftyReg",
3
+ "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 <code>niftyreg</code>. CPU.",
4
+ "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 <code>niftyreg</code>. 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).",
5
+ "task": "registration",
6
+ "tta": 0,
7
+ "mc_dropout": 0,
8
+ "models": [],
9
+ "inputs": {
10
+ "Fixed": {
11
+ "display_name": "Fixed image",
12
+ "volume_type": "VOLUME",
13
+ "required": true
14
+ },
15
+ "Moving": {
16
+ "display_name": "Moving image",
17
+ "volume_type": "VOLUME",
18
+ "required": true
19
+ },
20
+ "FixedMask": {
21
+ "display_name": "Fixed mask (ignored by this baseline)",
22
+ "volume_type": "SEGMENTATION",
23
+ "required": false,
24
+ "default": "ones"
25
+ },
26
+ "MovingMask": {
27
+ "display_name": "Moving mask (ignored by this baseline)",
28
+ "volume_type": "SEGMENTATION",
29
+ "required": false,
30
+ "default": "ones"
31
+ }
32
+ },
33
+ "outputs": {
34
+ "DisplacementField": {
35
+ "display_name": "Displacement field",
36
+ "volume_type": "VOLUME",
37
+ "required": true
38
+ }
39
+ }
40
+ }
NiftyReg/baselines.py ADDED
@@ -0,0 +1,206 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ # Copyright (c) 2025 Valentin Boussot
2
+ #
3
+ # Licensed under the Apache License, Version 2.0 (the "License");
4
+ # you may not use this file except in compliance with the License.
5
+ # You may obtain a copy of the License at
6
+ #
7
+ # http://www.apache.org/licenses/LICENSE-2.0
8
+ #
9
+ # Unless required by applicable law or agreed to in writing, software
10
+ # distributed under the License is distributed on an "AS IS" BASIS,
11
+ # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12
+ # See the License for the specific language governing permissions and
13
+ # limitations under the License.
14
+ #
15
+ # SPDX-License-Identifier: Apache-2.0
16
+
17
+ """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
18
+ engine and gets a displacement field back, and the field's convention.
19
+
20
+ The field is the benchmark's: one component per spatial axis, in mm along the world (ITK, LPS) axes, on the fixed
21
+ image's grid, such that the fixed point ``x`` matches ``x + u(x)`` in the moving image. The predictor attaches the
22
+ fixed image's geometry to the output (``same_as_group: Volume_0:Fixed`` in the app's ``Prediction.yml``).
23
+
24
+ NOTE: do NOT add ``from __future__ import annotations``: KonfAI's config engine relies on runtime-evaluated
25
+ annotations (``get_origin``); PEP 563 stringized annotations break binding.
26
+ """
27
+
28
+ import hashlib
29
+ import os
30
+ import shutil
31
+ import subprocess # nosec B404
32
+ import urllib.request
33
+ import zipfile
34
+ from collections.abc import Callable
35
+ from pathlib import Path
36
+
37
+ import numpy as np
38
+ import SimpleITK as sitk
39
+ import torch
40
+ from konfai.network import network
41
+ from konfai.utils.dataset import Attribute, data_to_image
42
+
43
+ #: An engine: (fixed, moving, fixed mask or None, moving mask or None, CUDA device index or -1) -> the field,
44
+ #: ``[D, *spatial]`` in mm along the world axes on the fixed grid.
45
+ Engine = Callable[[sitk.Image, sitk.Image, sitk.Image | None, sitk.Image | None, int], np.ndarray]
46
+
47
+
48
+ def cache_dir() -> Path:
49
+ """Where the authors' code and binaries live, once fetched: ``$BASELINES_KONFAI_CACHE`` or
50
+ ``~/.cache/baselines-konfai``."""
51
+ return Path(os.environ.get("BASELINES_KONFAI_CACHE", Path.home() / ".cache" / "baselines-konfai"))
52
+
53
+
54
+ def pinned_source(name: str, url: str, commit: str) -> Path:
55
+ """The authors' repository at ``commit``, cloned once into the cache: a baseline runs the code it was
56
+ measured with, never a moving branch."""
57
+ target = cache_dir() / f"{name}-{commit[:12]}"
58
+ if not (target / ".git").exists():
59
+ target.parent.mkdir(parents=True, exist_ok=True)
60
+ subprocess.run(["git", "clone", "--quiet", url, str(target)], check=True) # nosec B603 B607
61
+ subprocess.run(["git", "-C", str(target), "checkout", "--quiet", commit], check=True) # nosec B603 B607
62
+ return target
63
+
64
+
65
+ def fetch(url: str, target: Path, sha256: str | None = None) -> Path:
66
+ """``url`` downloaded once to ``target`` and, when a hash is given, checked against it."""
67
+ if not target.exists():
68
+ target.parent.mkdir(parents=True, exist_ok=True)
69
+ part = target.with_name(target.name + ".part")
70
+ urllib.request.urlretrieve(url, part) # nosec B310 - the authors' release, checked below
71
+ with part.open("rb") as stream:
72
+ digest = hashlib.file_digest(stream, "sha256").hexdigest()
73
+ if sha256 and digest != sha256:
74
+ part.unlink()
75
+ raise RuntimeError(f"{url} does not match its recorded hash")
76
+ part.rename(target)
77
+ return target
78
+
79
+
80
+ def pinned_archive(name: str, url: str, sha256: str) -> Path:
81
+ """A release archive at ``url``, downloaded once into the cache, checked against ``sha256`` and unpacked: the
82
+ binaries a baseline was measured with."""
83
+ target = cache_dir() / f"{name}-{sha256[:12]}"
84
+ if not (target / ".unpacked").exists():
85
+ archive = fetch(url, target / "archive", sha256)
86
+ if zipfile.is_zipfile(archive):
87
+ with zipfile.ZipFile(archive) as packed:
88
+ packed.extractall(target) # nosec B202 - our own pinned archive
89
+ for entry in packed.infolist(): # zipfile drops the modes: the binaries must stay executable
90
+ if mode := (entry.external_attr >> 16) & 0o777:
91
+ (target / entry.filename).chmod(mode)
92
+ else:
93
+ shutil.unpack_archive(str(archive), str(target), "gztar")
94
+ archive.unlink()
95
+ (target / ".unpacked").touch()
96
+ return target
97
+
98
+
99
+ def pinned_environment(root: Path, python: str, installs: list[list[str]]) -> Path:
100
+ """A virtual environment at ``root/venv`` on its own Python, made once by uv (``pip install uv``): for the tools
101
+ whose pins do not run on the host's Python. ``installs`` are ``pip install`` argument lists, run in order."""
102
+ try:
103
+ import uv
104
+
105
+ command = uv.find_uv_bin()
106
+ except ImportError:
107
+ command = shutil.which("uv") or ""
108
+ if not command:
109
+ raise RuntimeError("this baseline builds its own Python environment with uv: pip install uv")
110
+ venv = root / "venv"
111
+ if not (venv / ".ready").exists():
112
+ subprocess.run([command, "venv", "--quiet", "--clear", "--python", python, str(venv)], check=True) # nosec B603
113
+ for arguments in installs:
114
+ subprocess.run( # nosec B603
115
+ [
116
+ command,
117
+ "pip",
118
+ "install",
119
+ "--quiet",
120
+ "--no-cache",
121
+ "--python",
122
+ str(venv / "bin" / "python"),
123
+ *arguments,
124
+ ],
125
+ check=True,
126
+ )
127
+ (venv / ".ready").touch()
128
+ return venv
129
+
130
+
131
+ def built_source(name: str, url: str, commit: str, build: Callable[[Path], None]) -> Path:
132
+ """The authors' repository at ``commit``, built once by ``build`` (a marker says it is done)."""
133
+ source = pinned_source(name, url, commit)
134
+ if not (source / ".built").exists():
135
+ build(source)
136
+ (source / ".built").touch()
137
+ return source
138
+
139
+
140
+ def field_from_voxels(displacement: np.ndarray, fixed: sitk.Image) -> np.ndarray:
141
+ """A displacement in voxels along the index axes, ``[i, j, k, D]``, as the benchmark's field ``[D, k, j, i]``
142
+ in mm along the world axes: ``u = D S d``, with ``D`` the direction and ``S`` the spacing of the fixed image."""
143
+ n = fixed.GetDimension()
144
+ to_world = np.array(fixed.GetDirection()).reshape(n, n) @ np.diag(fixed.GetSpacing())
145
+ world = displacement.astype(np.float64) @ to_world.T # [i, j, k, D]
146
+ return np.ascontiguousarray(np.moveaxis(world, -1, 0).transpose(0, *reversed(range(1, n + 1))), dtype=np.float32)
147
+
148
+
149
+ def to_index_array(image: sitk.Image) -> np.ndarray:
150
+ """The image as a ``[i, j, k]`` array, the index axes in ITK's order, which the tools indexed that way read."""
151
+ return np.ascontiguousarray(sitk.GetArrayFromImage(image).transpose(*reversed(range(image.GetDimension()))))
152
+
153
+
154
+ class Registration(torch.nn.Module):
155
+ """Graph module: the pair's tensors and their geometry in, the field out, through the engine, one sample at
156
+ a time. ``accepts_attributes = True`` opts it into the per-branch ``Attribute`` list (the convention of
157
+ ``CriterionWithAttribute``): registration needs the physical geometry."""
158
+
159
+ accepts_attributes = True
160
+
161
+ def __init__(self, engine: Engine) -> None:
162
+ super().__init__()
163
+ self._engine = engine
164
+
165
+ def forward(
166
+ self,
167
+ fixed: torch.Tensor,
168
+ moving: torch.Tensor,
169
+ fixed_mask: torch.Tensor,
170
+ moving_mask: torch.Tensor,
171
+ attributes: list[list[Attribute]],
172
+ ) -> torch.Tensor:
173
+ fixed_attrs, moving_attrs, fixed_mask_attrs, moving_mask_attrs = attributes
174
+ device_index = fixed.device.index if fixed.device.type == "cuda" else -1
175
+ fields = []
176
+ # the engines optimise with autograd; the predictor calls forward under inference mode
177
+ with torch.inference_mode(False), torch.enable_grad():
178
+ for b in range(fixed.shape[0]):
179
+ images = [
180
+ data_to_image(t[b].detach().cpu().numpy(), attrs[b])
181
+ for t, attrs in ((fixed, fixed_attrs), (moving, moving_attrs))
182
+ ]
183
+ masks = [
184
+ data_to_image(t[b].detach().cpu().numpy(), attrs[b]) if not bool((t[b] == 1).all()) else None
185
+ for t, attrs in ((fixed_mask, fixed_mask_attrs), (moving_mask, moving_mask_attrs))
186
+ ]
187
+ fields.append(torch.from_numpy(self._engine(images[0], images[1], masks[0], masks[1], device_index)))
188
+ return torch.stack(fields, dim=0).to(fixed.device)
189
+
190
+
191
+ class BaselineNet(network.Network):
192
+ """A baseline as an ``add_module`` graph: fixed = branch 0, moving = branch 1, the masks branches 2 and 3 (a
193
+ mask of ones means none). The one output is ``DisplacementField``, on the fixed grid."""
194
+
195
+ def __init__(
196
+ self,
197
+ engine: Engine,
198
+ dim: int,
199
+ optimizer: network.OptimizerLoader,
200
+ schedulers: dict[str, network.LRSchedulersLoader],
201
+ outputs_criterions: dict[str, network.TargetCriterionsLoader],
202
+ ) -> None:
203
+ super().__init__(
204
+ in_channels=1, optimizer=optimizer, schedulers=schedulers, outputs_criterions=outputs_criterions, dim=dim
205
+ )
206
+ self.add_module("DisplacementField", Registration(engine), in_branch=[0, 1, 2, 3], out_branch=["dvf"])
NiftyReg/model.py ADDED
@@ -0,0 +1,129 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ # Copyright (c) 2025 Valentin Boussot
2
+ #
3
+ # Licensed under the Apache License, Version 2.0 (the "License");
4
+ # you may not use this file except in compliance with the License.
5
+ # You may obtain a copy of the License at
6
+ #
7
+ # http://www.apache.org/licenses/LICENSE-2.0
8
+ #
9
+ # Unless required by applicable law or agreed to in writing, software
10
+ # distributed under the License is distributed on an "AS IS" BASIS,
11
+ # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12
+ # See the License for the specific language governing permissions and
13
+ # limitations under the License.
14
+ #
15
+ # SPDX-License-Identifier: Apache-2.0
16
+
17
+ """NiftyReg's ``reg_f3d`` with its defaults (cubic B-spline with control points every 5 voxels, normalised mutual
18
+ information with 64 bins, bending energy 0.001, first-order penalty 0.01, no Jacobian penalty, 3 levels), built from
19
+ the authors' repository at a pinned commit (CPU build) on first use; ``reg_transform`` turns the control points into
20
+ a displacement field, whose RAS axes are brought to ITK's LPS.
21
+
22
+ NOTE: do NOT add ``from __future__ import annotations``: KonfAI's config engine relies on runtime-evaluated
23
+ annotations (``get_origin``); PEP 563 stringized annotations break binding.
24
+ """
25
+
26
+ import subprocess # nosec B404
27
+ import tempfile
28
+ from pathlib import Path
29
+ from typing import Annotated
30
+
31
+ import numpy as np
32
+ import SimpleITK as sitk
33
+ from konfai.network import network
34
+
35
+ from baselines import BaselineNet, built_source
36
+
37
+ REPOSITORY = "https://github.com/KCL-BMEIS/niftyreg"
38
+ COMMIT = "ee6a92d71263a4b1eb29b829fdeb3961d26d8a13" # v2.0.0, 2025-11-21
39
+
40
+
41
+ def _build(source: Path) -> None:
42
+ """cmake, CPU only, into ``install/`` next to the sources: what the benchmark's setup.sh does."""
43
+ build, install = source.parent / f"{source.name}-build", source / "install"
44
+ subprocess.run(
45
+ [
46
+ "cmake",
47
+ "-S",
48
+ str(source),
49
+ "-B",
50
+ str(build),
51
+ "-DCMAKE_BUILD_TYPE=Release", # nosec B603 B607
52
+ f"-DCMAKE_INSTALL_PREFIX={install}",
53
+ "-DUSE_CUDA=OFF",
54
+ "-DUSE_OPENCL=OFF",
55
+ "-DCHECK_GPU=OFF",
56
+ ],
57
+ check=True,
58
+ )
59
+ subprocess.run(["cmake", "--build", str(build), "-j", "8", "--target", "install"], check=True) # nosec B603 B607
60
+
61
+
62
+ class NiftyReg:
63
+ def __init__(self, arguments: list[str], threads: int) -> None:
64
+ self._arguments, self._threads = arguments, threads
65
+
66
+ def __call__(
67
+ self,
68
+ fixed: sitk.Image,
69
+ moving: sitk.Image,
70
+ fixed_mask: sitk.Image | None,
71
+ moving_mask: sitk.Image | None,
72
+ device: int,
73
+ ) -> np.ndarray:
74
+ binaries = built_source("niftyreg", REPOSITORY, COMMIT, _build) / "install" / "bin"
75
+ fixed, moving = sitk.Cast(fixed, sitk.sitkFloat32), sitk.Cast(moving, sitk.sitkFloat32)
76
+ with tempfile.TemporaryDirectory(prefix="niftyreg_") as scratch:
77
+ work = Path(scratch)
78
+ ref, flo = work / "fixed.nii.gz", work / "moving.nii.gz" # NiftyReg reads NIfTI only
79
+ sitk.WriteImage(fixed, str(ref))
80
+ sitk.WriteImage(moving, str(flo))
81
+ threads = ["-omp", str(self._threads)] if self._threads else []
82
+ subprocess.run(
83
+ [
84
+ str(binaries / "reg_f3d"),
85
+ "-ref",
86
+ str(ref),
87
+ "-flo",
88
+ str(flo),
89
+ "-cpp",
90
+ str(work / "cpp.nii.gz"), # nosec B603
91
+ "-res",
92
+ str(work / "moved.nii.gz"),
93
+ *threads,
94
+ *self._arguments,
95
+ ],
96
+ check=True,
97
+ )
98
+ subprocess.run(
99
+ [
100
+ str(binaries / "reg_transform"),
101
+ "-ref",
102
+ str(ref),
103
+ "-disp",
104
+ str(work / "cpp.nii.gz"),
105
+ str(work / "disp.nii.gz"),
106
+ ],
107
+ check=True,
108
+ ) # nosec B603
109
+ displacement = sitk.GetArrayFromImage(sitk.ReadImage(str(work / "disp.nii.gz"), sitk.sitkVectorFloat32))
110
+ if not np.isfinite(displacement).all():
111
+ raise ValueError("NiftyReg returned a non-finite displacement")
112
+ # NiftyReg writes the displacement along the NIfTI (RAS) axes: to ITK's LPS
113
+ return np.ascontiguousarray(np.moveaxis(displacement * np.float32([-1, -1, 1]), -1, 0), dtype=np.float32)
114
+
115
+
116
+ class RegistrationNet(BaselineNet):
117
+ """NiftyReg reg_f3d, defaults. CPU."""
118
+
119
+ def __init__(
120
+ self,
121
+ optimizer: network.OptimizerLoader = network.OptimizerLoader(),
122
+ schedulers: dict[str, network.LRSchedulersLoader] = {
123
+ "default:ReduceLROnPlateau": network.LRSchedulersLoader(0)
124
+ },
125
+ outputs_criterions: dict[str, network.TargetCriterionsLoader] = {"default": network.TargetCriterionsLoader()},
126
+ arguments: Annotated[list[str], "Extra reg_f3d arguments; none for the defaults."] = [],
127
+ threads: Annotated[int, "OpenMP threads (-omp); 0 leaves NiftyReg's default."] = 0,
128
+ ) -> None:
129
+ super().__init__(NiftyReg(list(arguments), threads), 3, optimizer, schedulers, outputs_criterions)
NiftyReg/requirements.txt ADDED
@@ -0,0 +1 @@
 
 
1
+ SimpleITK