neuroreg 0.1.0__tar.gz

neuroreg-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2020 Deep Medical Imaging Lab (PI Reuter)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

neuroreg-0.1.0/PKG-INFO

@@ -0,0 +1,510 @@
+Metadata-Version: 2.4
+Name: neuroreg
+Version: 0.1.0
+Summary: A package for 3D neuroimaging registration with PyTorch.
+Author: Martin Reuter
+Maintainer: Martin Reuter
+License: MIT License
+        
+        Copyright (c) 2020 Deep Medical Imaging Lab (PI Reuter)
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+        
+Project-URL: homepage, https://Deep-MI.github.io/neuroreg/dev/index.html
+Project-URL: documentation, https://Deep-MI.github.io/neuroreg/dev/index.html
+Project-URL: source, https://github.com/Deep-MI/neuroreg
+Project-URL: tracker, https://github.com/Deep-MI/neuroreg/issues
+Keywords: python,Registration,3D Image,MRI,PyTorch
+Classifier: Operating System :: OS Independent
+Classifier: Environment :: Console
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Natural Language :: English
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Intended Audience :: Science/Research
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: nibabel>=5.1
+Requires-Dist: numpy>=1.25
+Requires-Dist: psutil
+Requires-Dist: scikit-image>=0.21
+Requires-Dist: scipy>=1.11
+Requires-Dist: torch>=2.0.1
+Provides-Extra: build
+Requires-Dist: build; extra == "build"
+Requires-Dist: twine; extra == "build"
+Provides-Extra: doc
+Requires-Dist: furo!=2023.8.17; extra == "doc"
+Requires-Dist: matplotlib>=3.5; extra == "doc"
+Requires-Dist: memory-profiler; extra == "doc"
+Requires-Dist: myst-parser; extra == "doc"
+Requires-Dist: numpydoc; extra == "doc"
+Requires-Dist: sphinx<8,>=7.3; extra == "doc"
+Requires-Dist: sphinxcontrib-bibtex; extra == "doc"
+Requires-Dist: sphinx-copybutton; extra == "doc"
+Requires-Dist: sphinx-design; extra == "doc"
+Requires-Dist: sphinx-gallery; extra == "doc"
+Requires-Dist: sphinx-issues; extra == "doc"
+Requires-Dist: pypandoc; extra == "doc"
+Requires-Dist: nbsphinx; extra == "doc"
+Requires-Dist: IPython; extra == "doc"
+Requires-Dist: ipykernel; extra == "doc"
+Provides-Extra: style
+Requires-Dist: bibclean; extra == "style"
+Requires-Dist: codespell; extra == "style"
+Requires-Dist: pydocstyle[toml]; extra == "style"
+Requires-Dist: ruff; extra == "style"
+Provides-Extra: test
+Requires-Dist: pytest>=8.2.2; extra == "test"
+Requires-Dist: pytest-cov; extra == "test"
+Requires-Dist: pytest-timeout; extra == "test"
+Provides-Extra: all
+Requires-Dist: neuroreg[build]; extra == "all"
+Requires-Dist: neuroreg[doc]; extra == "all"
+Requires-Dist: neuroreg[style]; extra == "all"
+Requires-Dist: neuroreg[test]; extra == "all"
+Provides-Extra: full
+Requires-Dist: neuroreg[all]; extra == "full"
+Dynamic: license-file
+
+[![PyPI version](https://badge.fury.io/py/neuroreg.svg)](https://pypi.org/project/neuroreg/)
+
+# NeuroReg
+
+NeuroReg is a package for the robust registration of 3D neuroimaging data (e.g. MRI).
+It supports both image-to-image (within and cross modal) as well as image to
+landmark (WM-surface) or segmentation. It uses PyTorch's automatic differentiation
+for gradient-based optimisations and can run efficiently on a GPU.
+
+The main user-facing tools are:
+
+- **`robreg`** – Highly accurate and robust same modality image-to-image registration
+  (IRLS based, analogous to FreeSurfer's `mri_robust_register`)
+- **`coreg`** – Image-to-image cross-modal registration
+  (gradient-descent with normalized mutual information NMI, cf. `mri_coreg`)
+- **`bbreg`** – boundary-based registration using cortical WM surfaces or segmentations
+  (analogous to FreeSurfer's `bbregister` / `mri_segreg`)
+- **`lta`** – transform comparison / inversion / concatenation utilities
+
+This project is a work-in-progress in an early development stage. It is developed by
+the creator of FreeSurfer's `mri_robust_register` as an efficient pure Python
+replacement (with GPU support) and cross-modal extensions to support all your medical
+imaging reistration needs, with a focus on high accuracy and speed. If you find it 
+useful for a publication, please cite the relevant papers (see [References](#References)).
+
+## Installation
+
+```bash
+pip install neuroreg
+```
+
+## Command-line interface
+
+### `robreg` — image-to-image registration
+
+Registers a moving image to a reference image using a multi-resolution
+IRLS-based robust registration path with Tukey weighting.
+
+This path is currently intended for **same-contrast or very similar-contrast**
+image pairs.
+On Apple MPS, the current public IRLS path falls back to CPU with a warning due
+to lack of double precision support on MPS.
+
+```
+robreg --mov <moving.nii.gz> --ref <reference.nii.gz> --out <output.lta> [options]
+```
+
+Run `robreg -h` for a full argument summary with defaults.
+
+**Required arguments**
+
+| Argument     | Description                                       |
+|--------------|---------------------------------------------------|
+| `--mov FILE` | Moving (source) image (NIfTI or MGZ).             |
+| `--ref FILE` | Reference (target/fixed) image (NIfTI or MGZ).    |
+| `--out LTA`  | Output LTA file for the recovered transformation. |
+
+**Options**
+
+| Argument          | Default | Description                                                                                                        |
+|-------------------|---------|--------------------------------------------------------------------------------------------------------------------|
+| `--dof {6}`       | `6`     | Degrees of freedom. The public `robreg` path is currently rigid-only.                                              |
+| `--nmax N`        | `5`     | Maximum number of outer IRLS iterations per pyramid level.                                                         |
+| `--sat FLOAT`     | `6.0`   | Tukey biweight saturation threshold.                                                                               |
+| `--nosym`         | off     | Disable symmetric halfway-space registration and run directed registration. Symmetric registration is the default. |
+| `--noinit`        | off     | Skip centroid-based initialization and start from identity (like FreeSurfer `--noinit`).                           |
+| `--mapped FILE`   | —       | Save the warped moving image.                                                                                      |
+| `--outliers FILE` | —       | Save an outlier map (`1 - Tukey weights`).                                                                         |
+| `--verbose`       | off     | Enable INFO-level logging.                                                                                         |
+| `--debug`         | off     | Enable DEBUG-level logging.                                                                                        |
+
+**Example**
+
+```bash
+robreg --mov T1_repeat.nii.gz --ref T1_baseline.mgz --out T1_repeat_to_T1_baseline.lta --verbose
+```
+
+---
+
+### `coreg` — image-based cross-modal registration
+
+This is the image-based gradient-descent registration path used for
+**cross-sequence / cross-modal** registration when no surfaces or segmentation
+are available. In practice it is the package's image-only counterpart to
+FreeSurfer's `mri_coreg`.
+
+```
+coreg --mov <moving.nii.gz> --ref <reference.nii.gz> --out <output.lta> [options]
+```
+
+**Options**
+
+| Argument           | Default | Description                                                           |
+|--------------------|---------|-----------------------------------------------------------------------|
+| `--dof {3,6,9,12}` | `6`     | Degrees of freedom: 3=translation, 6=rigid, 9=rigid+scale, 12=affine. |
+| `--n_iters N`      | auto    | Maximum optimisation iterations per pyramid level.                    |
+| `--noinit`         | off     | Skip centroid-based initialization and start from identity.           |
+| `--device DEVICE`  | `cpu`   | PyTorch device, e.g. `cpu` or `cuda`.                                 |
+| `--verbose`        | off     | Enable INFO-level logging.                                            |
+| `--debug`          | off     | Enable DEBUG-level logging.                                           |
+
+**Example**
+
+```bash
+coreg --mov T2.nii.gz --ref T1.mgz --out T2_to_T1.lta --dof 6 --verbose
+```
+
+---
+
+### `bbreg` — boundary-based registration
+
+Registers a moving image to a T1 anatomy using cortical surface meshes
+(white matter / grey matter boundary). The tissue contrast direction
+(T1-like: WM > GM, or T2-like: GM > WM) is auto-detected from the image
+when not specified.
+
+Surface input can be provided in three ways:
+
+**Mode A — FreeSurfer / FastSurfer subject directory** (recommended)
+
+```
+bbreg --mov <moving.nii.gz> --subject_dir <subject_dir> --out <output.lta> [options]
+```
+
+The subject directory must contain `surf/lh.white`, `surf/rh.white`, and
+`mri/orig.mgz` (standard FreeSurfer / FastSurfer output layout).
+
+**Mode B — explicit surface files**
+
+```
+bbreg --mov <moving.nii.gz> --lh_surf <lh.white> --rh_surf <rh.white> \
+      --ref <T1.mgz> --out <output.lta> [options]
+```
+
+**Mode C — segmentation file (no pre-built surfaces needed)**
+
+```
+bbreg --mov <moving.nii.gz> --seg <aparc+aseg.mgz> --out <output.lta> [options]
+```
+
+The WM/GM boundary surface is extracted on-the-fly from a parcellation or
+aseg file (e.g. `aparc+aseg.mgz`, `aseg.mgz`, or NIfTI) via marching cubes.
+The segmentation header provides the reference geometry; `--ref` must *not* be
+specified in this mode.
+
+**Required arguments**
+
+| Argument                     | Description                                                            |
+|------------------------------|------------------------------------------------------------------------|
+| `--mov FILE`                 | Moving image to register (NIfTI or MGZ).                               |
+| `--out LTA`                  | Output LTA file for the recovered transformation.                      |
+| `--subject_dir DIR`          | *(Mode A)* Subject directory with surfaces and `mri/orig.mgz`.         |
+| `--lh_surf / --rh_surf FILE` | *(Mode B)* Explicit left / right white surface files.                  |
+| `--ref FILE`                 | *(Mode B)* Reference T1 image (required with explicit surfaces).       |
+| `--seg FILE`                 | *(Mode C)* Parcellation / aseg file; surfaces extracted automatically. |
+
+**Options**
+
+| Argument                               | Default    | Description                                                                                            |
+|----------------------------------------|------------|--------------------------------------------------------------------------------------------------------|
+| `--dof {6,9,12}`                       | `6`        | Degrees of freedom: 6=rigid, 9=rigid+scale, 12=affine.                                                 |
+| `--contrast {t1,t2}`                   | auto       | Tissue contrast: `t1` (WM>GM) or `t2` (GM>WM). Auto-detected if omitted.                               |
+| `--cost {contrast,gradient,both}`      | `contrast` | BBR cost term.                                                                                         |
+| `--wm_proj_abs MM`                     | `1.4`      | WM projection depth in mm.                                                                             |
+| `--gm_proj_frac FRAC`                  | `0.5`      | GM projection as fraction of cortical thickness.                                                       |
+| `--slope SLOPE`                        | `0.5`      | Slope of the BBR sigmoid cost function.                                                                |
+| `--gradient_weight W`                  | `0.0`      | Weight for gradient cost term when `--cost=both`.                                                      |
+| `--n_iters N`                          | `500`      | Number of RMSprop optimisation iterations.                                                             |
+| `--lr LR`                              | `0.005`    | Optimiser learning rate.                                                                               |
+| `--subsample N`                        | `2`        | Use every N-th surface vertex (1 = all).                                                               |
+| `--lh_thickness / --rh_thickness FILE` | —          | *(Mode B)* Cortical thickness files for GM projection.                                                 |
+| `--seg_smooth_sigma SIGMA`             | `0.5`      | *(Mode C)* Gaussian pre-blur sigma (voxels) before marching cubes.                                     |
+| `--seg_mc_level LEVEL`                 | `0.45`     | *(Mode C)* Marching-cubes iso-level.                                                                   |
+| `--seg_smooth_iters N`                 | `50`       | *(Mode C)* Taubin smoothing iterations after marching cubes.                                           |
+| `--init_lta FILE`                      | —          | Initialise from an existing LTA transform (e.g. from a prior `robreg` run or a previous `bbreg` pass). |
+| `--device DEVICE`                      | `cpu`      | PyTorch device, e.g. `cpu` or `cuda`.                                                                  |
+| `--verbose`                            | off        | Enable INFO-level logging.                                                                             |
+| `--debug`                              | off        | Enable DEBUG-level logging.                                                                            |
+
+**Examples**
+
+```bash
+# Mode A: register fMRI to T1 using a FastSurfer subject directory
+bbreg --mov fMRI.nii.gz --subject_dir /data/subjects/sub-01 --out fMRI_to_T1.lta
+
+# Mode B: register T2 to T1 with explicit surfaces and thickness files
+bbreg --mov T2.nii.gz \
+      --lh_surf /data/subjects/sub-01/surf/lh.white \
+      --rh_surf /data/subjects/sub-01/surf/rh.white \
+      --lh_thickness /data/subjects/sub-01/surf/lh.thickness \
+      --rh_thickness /data/subjects/sub-01/surf/rh.thickness \
+      --ref /data/subjects/sub-01/mri/orig.mgz \
+      --out T2_to_T1.lta --contrast t2
+
+# Mode C: register fMRI using a segmentation (no surface files required)
+bbreg --mov fMRI.nii.gz --seg /data/subjects/sub-01/mri/aparc+aseg.mgz \
+      --out fMRI_to_T1.lta
+```
+
+Run `bbreg -h` for a full argument summary with defaults.
+
+---
+
+### `lta` — LTA transform utilities
+
+Unified command for manipulating FreeSurfer LTA transform files with three
+subcommands: `diff`, `invert`, and `concat`.
+
+```
+lta diff    LTA1 [LTA2] [options]     # Compare transforms
+lta invert  INPUT OUTPUT              # Invert a transform
+lta concat  LTA1 LTA2 OUTPUT          # Concatenate two transforms
+```
+
+---
+
+#### `lta diff` — Compare transforms
+
+Computes distance metrics between two LTA transforms, or between a single
+transform and identity. Replicates the functionality of FreeSurfer's `lta_diff`.
+
+**Usage**
+
+```
+lta diff LTA1 [LTA2] [--dist {1,2,3,4,5,7}] [--radius MM] [--normdiv FLOAT]
+                     [--invert1] [--invert2]
+```
+
+**Distance types**
+
+| `--dist` | Metric                                                                 |
+|----------|------------------------------------------------------------------------|
+| `1`      | Rigid transform distance: √(‖log R_d‖² + ‖T_d‖²)                       |
+| `2`      | Affine RMS distance (Jenkinson 1999) — **default**                     |
+| `3`      | Mean displacement at the 8 corners of the source volume (mm)           |
+| `4`      | Max displacement on a sphere of radius `r`                             |
+| `5`      | Determinant of M1 (or M1·M2 when two transforms are given)             |
+| `7`      | Polar decomposition: rotation, shear, scales, translation, determinant |
+
+**Options**
+
+| Argument               | Default | Description                                            |
+|------------------------|---------|--------------------------------------------------------|
+| `--dist {1,2,3,4,5,7}` | `2`     | Distance type (see table above).                       |
+| `--radius MM`          | `100`   | Sphere / RMS radius in mm (used by dist 2 and 4).      |
+| `--normdiv FLOAT`      | `1`     | Divide the final distance by this value (must be > 0). |
+| `--invert1`            | off     | Invert LTA1 before comparison.                         |
+| `--invert2`            | off     | Invert LTA2 before comparison (requires a second LTA). |
+
+**Examples**
+
+```bash
+# Affine RMS distance between two registrations (default metric)
+lta diff myreg.lta ref.lta
+
+# Rigid distance
+lta diff myreg.lta ref.lta --dist 1
+
+# Polar decomposition of a single transform
+lta diff myreg.lta --dist 7
+```
+
+---
+
+#### `lta invert` — Invert a transform
+
+Inverts an LTA transform and writes the result to a new file. The output is
+always stored as LINEAR_RAS_TO_RAS with src and dst geometry swapped.
+
+**Usage**
+
+```
+lta invert INPUT OUTPUT
+```
+
+**Examples**
+
+```bash
+# Invert a registration
+lta invert T1_to_MNI.lta MNI_to_T1.lta
+
+# Invert twice to verify round-trip
+lta invert fwd.lta inv.lta
+lta invert inv.lta fwd_again.lta
+```
+
+---
+
+#### `lta concat` — Concatenate transforms
+
+Concatenates two LTA transforms. If `LTA1` maps A→B and `LTA2` maps B→C, the
+output maps A→C. Equivalent to FreeSurfer's `mri_concatenate_lta`.
+
+**Usage**
+
+```
+lta concat LTA1 LTA2 OUTPUT
+```
+
+**Examples**
+
+```bash
+# Concatenate fMRI→T1 and T1→MNI to get fMRI→MNI
+lta concat fMRI_to_T1.lta T1_to_MNI.lta fMRI_to_MNI.lta
+
+# Chain multiple registrations
+lta concat moving_to_intermediate.lta intermediate_to_fixed.lta moving_to_fixed.lta
+```
+
+**Notes**
+
+- All metrics are numerically matched to FreeSurfer's `lta_diff` (except for a
+  known bug in the C++ single-transform corner metric, which is fixed here).
+- When only one LTA is supplied to `diff`, the transform is compared against identity.
+- Run `lta --help` or `lta <subcommand> --help` for detailed usage.
+
+## Python API
+
+```python
+import nibabel as nib
+
+from neuroreg import bbreg, coreg, robreg
+
+# Public robust image-to-image registration (IRLS-backed).
+# Intended for same-/similar-contrast pairs; symmetric mode is the default.
+# On Apple MPS, this path currently warns and falls back to CPU.
+transform_robreg = robreg("T1_repeat.nii.gz", "T1_baseline.mgz")
+
+# The same public robreg path with pre-loaded nibabel images.
+mov_img = nib.load("T1_repeat.nii.gz")
+ref_img = nib.load("T1_baseline.mgz")
+transform_robreg_loaded = robreg(mov_img, ref_img)
+
+# Image-based cross-modal registration path for cases where no
+# white-matter surface or segmentation is available.
+transform_coreg = coreg("T2.nii.gz", "T1.mgz", loss_name="nmi")
+
+# Surface-based (BBR) registration — Mode A: subject directory
+transform_bbreg = bbreg(
+    mov="fMRI.nii.gz",
+    subject_dir="/data/subjects/sub-01",
+    lta_name="fMRI_to_T1.lta",
+    dof=6,
+)
+
+# Surface-based (BBR) registration — Mode B: explicit surface files
+transform_bbreg = bbreg(
+    mov="T2.nii.gz",
+    lh_surf="/data/subjects/sub-01/surf/lh.white",
+    rh_surf="/data/subjects/sub-01/surf/rh.white",
+    lh_thickness="/data/subjects/sub-01/surf/lh.thickness",
+    rh_thickness="/data/subjects/sub-01/surf/rh.thickness",
+    ref="/data/subjects/sub-01/mri/orig.mgz",
+    lta_name="T2_to_T1.lta",
+    contrast="t2",
+)
+
+# Surface-based (BBR) registration — Mode C: segmentation (no surface files needed)
+transform_bbreg = bbreg(
+    mov="fMRI.nii.gz",
+    seg="/data/subjects/sub-01/mri/aparc+aseg.mgz",
+    lta_name="fMRI_to_T1.lta",
+)
+
+# For debugging or inspection, request the fitted model explicitly.
+transform_bbreg, model_bbreg = bbreg(
+    mov="fMRI.nii.gz",
+    subject_dir="/data/subjects/sub-01",
+    return_model=True,
+)
+```
+
+## Degrees of freedom
+
+Current DOF support is:
+
+| Command / API path           | Supported DOF       |
+|------------------------------|---------------------|
+| `robreg` / public `robreg()` | `6` only            |
+| `coreg` / public `coreg()`   | `3`, `6`, `9`, `12` |
+| `bbreg` / public `bbreg()`   | `6`, `9`, `12`      |
+
+The public `robreg` path is intentionally rigid-only for now because it tracks
+the current IRLS implementation.
+
+Also note that the current public `robreg` path is aimed at same-/similar-contrast
+registration. For cross-sequence alignment such as T2→T1, the current options are
+`coreg` (image-based GD) or `bbreg` when a segmentation or surfaces are
+available.
+
+## API Documentation
+
+The API Documentation can be found at https://deep-mi.org/neuroreg .
+
+## References
+
+If you use this software for a publication please cite:
+
+- Reuter, Rosas, Fischl (2010).
+  Highly accurate inverse consistent registration: a robust approach.
+  NeuroImage 53(4):1181-1196.
+  https://doi.org/10.1016/j.neuroimage.2010.07.040
+
+- Reuter, Schmansky, Rosas, Fischl (2012).
+  Within-subject template estimation for unbiased longitudinal image analysis.
+  NeuroImage 61(4):1402-1418.
+  https://doi.org/10.1016/j.neuroimage.2012.02.084
+
+- Reuter, Fischl (2011).
+  Avoiding asymmetry-induced bias in longitudinal image processing.
+  NeuroImage 57(1):19-21.
+  https://doi.org/10.1016/j.neuroimage.2011.02.076
+
+If you use `bbreg` specifically, please also cite:
+
+- Greve, Fischl (2009).
+  Accurate and robust brain image alignment using boundary-based registration.
+  NeuroImage 48(1):63-72.
+  https://doi.org/10.1016/j.neuroimage.2009.06.060
+
+We invite you to check out our lab webpage at https://deep-mi.org