neuroreg 0.2.0.dev0__tar.gz → 0.4.0.dev0__tar.gz

{neuroreg-0.2.0.dev0 → neuroreg-0.4.0.dev0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: neuroreg
-Version: 0.2.0.dev0
+Version: 0.4.0.dev0
 Summary: A package for 3D neuroimaging registration with PyTorch.
 Author: Martin Reuter
 Maintainer: Martin Reuter
@@ -105,7 +105,9 @@ The main user-facing tools are:
   (Powell-based by default, analogous to FreeSurfer/SPM `mri_coreg`)
 - **`bbreg`** – boundary-based registration using cortical WM surfaces or segmentations
   (extending FreeSurfer's `bbregister`)
-- **`lta`** – transform comparison / inversion / concatenation utilities
+- **`segreg`** – segmentation-based registration via label centroids
+  (rigid/affine, including atlas-centroid and upright/self-flip modes)
+- **`lta`** – transform comparison, inversion, concatenation, and conversion 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
@@ -312,15 +314,65 @@ Run `bbreg -h` for a full argument summary with defaults.
 
 ---
 
-### `lta` — LTA transform utilities
+### `segreg` — segmentation-based registration
 
-Unified command for manipulating FreeSurfer LTA transform files with three
-subcommands: `diff`, `invert`, and `concat`.
+Registers a moving segmentation by aligning label centroids to another
+segmentation, to bundled atlas centroids such as `fsaverage`, or to a
+left-right flipped self target for upright/midspace workflows. The centroid
+fit now supports translation-only (`3`), rigid (`6`), similarity /
+global-scale (`7`), anisotropic no-shear scaling (`9`), or full affine
+(`12`) transforms.
+
+`segreg` can also write mapped outputs while the package does not yet have a
+separate transform-application CLI. If `--movimg` is provided, `--mapmov` and
+`--mapmovhdr` map that intensity image with the recovered transform; otherwise
+those outputs map the moving segmentation itself.
 
 ```
-lta diff    LTA1 [LTA2] [options]     # Compare transforms
-lta invert  INPUT OUTPUT              # Invert a transform
-lta concat  LTA1 LTA2 OUTPUT          # Concatenate two transforms
+segreg --mov <moving_seg.mgz> (--ref <ref_seg.mgz> | --ref-centroids <centroids.json> | --atlas fsaverage | --flipped) [options]
+```
+
+**Common outputs**
+
+- `--lta FILE` writes the recovered transform as an LTA.
+- `--movimg FILE` provides a separate intensity image for `--mapmov` or `--mapmovhdr`.
+- `--mapmov FILE` writes a resliced mapped output. It maps `--movimg` when provided; otherwise it reslices the moving segmentation itself.
+- `--mapmovhdr FILE` writes a header-only mapped output. It maps `--movimg` when provided; otherwise it remaps the moving segmentation itself.
+
+**Examples**
+
+```bash
+# Register a subject segmentation to another segmentation
+segreg --mov sub-01/aparc+aseg.mgz --ref sub-02/aparc+aseg.mgz \
+       --lta sub01_to_sub02.lta
+
+# Register a segmentation, then map a separate intensity image with the same transform
+segreg --mov subj/mri/aparc+aseg.mgz --movimg subj/mri/orig.mgz --atlas fsaverage \
+       --lta subj_to_fsaverage.lta --mapmov orig_in_fsaverage_space.mgz
+
+# If --movimg is omitted, --mapmov maps the segmentation itself
+segreg --mov subj/mri/aparc+aseg.mgz --atlas fsaverage \
+       --mapmov aparc_aseg_in_fsaverage_space.mgz
+
+# Export centroid JSON only
+segreg --mov subj/mri/aparc+aseg.mgz --atlas fsaverage \
+       --write-mov-centroids subj_centroids.json --write-ref-centroids fsaverage_centroids.json
+```
+
+Run `segreg -h` for a full argument summary with defaults.
+
+---
+
+### `lta` — LTA and linear-transform utilities
+
+Unified command for manipulating FreeSurfer-adjacent linear transforms with four
+subcommands: `diff`, `invert`, `concat`, and `convert`.
+
+```
+lta diff    LTA1 [LTA2] [options]                   # Compare transforms
+lta invert  INPUT OUTPUT                            # Invert a transform
+lta concat  LTA1 LTA2 OUTPUT                        # Concatenate two transforms
+lta convert INPUT OUTPUT [--src-img SRC --dst-img DST]  # Convert formats
 ```
 
 ---
@@ -418,8 +470,104 @@ lta concat fMRI_to_T1.lta T1_to_MNI.lta fMRI_to_MNI.lta
 lta concat moving_to_intermediate.lta intermediate_to_fixed.lta moving_to_fixed.lta
 ```
 
+---
+
+#### `lta convert` — Convert between transform formats
+
+Converts between `.lta`, `.xfm`, volumetric tkregister `.dat`/`.reg`, FSL `.mat`/`.fslmat`, ITK/ANTs 3D affine text transforms, experimental ANTs Matlab-format affine transforms, experimental AFNI affine text transforms, and NiftyReg affine text matrices by normalizing through an internal RAS-to-RAS `LTA`.
+
+**Usage**
+
+```
+lta convert INPUT OUTPUT [--in-format {lta,xfm,fsl,regdat,itk,antsmat,afni,niftyreg}]
+                         [--out-format {lta,xfm,fsl,regdat,itk,antsmat,afni,niftyreg}]
+                         [--src-img SRC] [--dst-img DST]
+                         [--out-type {ras2ras,vox2vox}]
+                         [--subject SUBJECT] [--fscale FSCALE]
+                         [--float2int {tkregister,round,floor}]
+```
+
+**Supported formats**
+
+- `.lta` — FreeSurfer Linear Transform Array
+- `.xfm` — MNI/MINC linear transform
+- `.dat` — old tkregister volumetric `register.dat` format
+- `.mat` / `.fslmat` — FSL FLIRT affine matrix
+- `.tfm` — ITK/ANTs 3D affine text transform
+- `*GenericAffine.mat` — experimental ANTs / ITK Matlab-format affine transform
+- `.aff12.1D` — experimental AFNI affine text matrix
+- `.niftyreg.txt` — NiftyReg 3D affine text matrix
+
 **Notes**
 
+- Reading `register.dat` requires both `--src-img` and `--dst-img`, because the
+  stored matrix is defined in tkregister coordinates rather than scanner RAS.
+- Reading FSL `.mat` / `.fslmat` also requires both `--src-img` and `--dst-img`,
+  because the stored matrix is defined in FSL voxel conventions rather than
+  scanner RAS.
+- Reading `.xfm`, ITK/ANTs text affines, experimental ANTs `.mat`, experimental
+  AFNI affine text, or NiftyReg text matrices without images still preserves the
+  transform matrix, but the resulting LTA geometry blocks stay marked as `valid=0`
+  unless you provide `--src-img` and `--dst-img`.
+- Use `--in-format` / `--out-format` for ambiguous filenames such as `.txt`, `.1D`, or `.mat`.
+- ITK/ANTs text support currently targets 3D affine transforms only, not binary or
+  composite transform files.
+- Experimental ANTs `.mat` support is implemented via SciPy using ITK Matlab IO semantics.
+- Experimental AFNI support targets affine text matrices in AFNI's DICOM/LPS convention.
+- NiftyReg stores the inverse target-to-source RAS matrix in the file, matching
+  FreeSurfer's `lta_convert` handling.
+- `--subject`, `--fscale`, and `--float2int` apply when writing `register.dat`.
+- `--out-type` applies when writing `.lta` output.
+
+**Examples**
+
+```bash
+# XFM -> LTA with explicit image geometry
+lta convert talairach.xfm talairach.lta --src-img mov.mgz --dst-img ref.mgz
+
+# LTA -> XFM
+lta convert sub01_to_mni.lta sub01_to_mni.xfm
+
+# LTA -> tkregister register.dat
+lta convert bold_to_orig.lta bold_to_orig.dat --subject sub-01 --fscale 0.1
+
+# tkregister register.dat -> LTA
+lta convert bold_to_orig.dat bold_to_orig.lta --src-img bold.nii.gz --dst-img orig.mgz
+
+# LTA -> FSL FLIRT matrix
+lta convert bold_to_orig.lta bold_to_orig.mat
+
+# FSL FLIRT matrix -> LTA
+lta convert bold_to_orig.mat bold_to_orig_from_fsl.lta --src-img bold.nii.gz --dst-img orig.mgz
+
+# LTA -> ITK/ANTs text affine
+lta convert bold_to_orig.lta bold_to_orig.tfm
+
+# ITK/ANTs text affine (.txt requires explicit format override)
+lta convert bold_to_orig.txt bold_to_orig_from_itk.lta --in-format itk --src-img bold.nii.gz --dst-img orig.mgz
+
+# LTA -> experimental ANTs GenericAffine .mat
+lta convert bold_to_orig.lta bold_to_orig0GenericAffine.mat
+
+# Experimental ANTs GenericAffine .mat -> LTA (.mat is otherwise assumed FSL)
+lta convert bold_to_orig0GenericAffine.mat bold_to_orig_from_antsmat.lta
+lta convert some_affine.mat bold_to_orig_from_antsmat.lta --in-format antsmat
+
+# LTA -> experimental AFNI affine text
+lta convert bold_to_orig.lta bold_to_orig.aff12.1D
+
+# Experimental AFNI affine text -> LTA (.1D may need explicit format override)
+lta convert bold_to_orig.aff12.1D bold_to_orig_from_afni.lta
+
+# LTA -> NiftyReg affine text matrix (.txt requires explicit format override)
+lta convert bold_to_orig.lta bold_to_orig.txt --out-format niftyreg
+
+# NiftyReg affine text matrix -> LTA
+lta convert bold_to_orig.txt bold_to_orig_from_niftyreg.lta --in-format niftyreg
+```
+
+**General 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.
@@ -486,11 +634,12 @@ transform_bbreg, model_bbreg = bbreg(
 
 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`      |
+| Command / API path           | Supported DOF            |
+|------------------------------|--------------------------|
+| `robreg` / public `robreg()` | `6` only                 |
+| `coreg` / public `coreg()`   | `3`, `6`, `9`, `12`      |
+| `bbreg` / public `bbreg()`   | `6`, `9`, `12`           |
+| `segreg` / public `segreg()` | `3`, `6`, `7`, `9`, `12` |
 
 The public `robreg` path is intentionally rigid-only for now because it tracks
 the current IRLS implementation.

{neuroreg-0.2.0.dev0 → neuroreg-0.4.0.dev0}/README.md

@@ -15,7 +15,9 @@ The main user-facing tools are:
   (Powell-based by default, analogous to FreeSurfer/SPM `mri_coreg`)
 - **`bbreg`** – boundary-based registration using cortical WM surfaces or segmentations
   (extending FreeSurfer's `bbregister`)
-- **`lta`** – transform comparison / inversion / concatenation utilities
+- **`segreg`** – segmentation-based registration via label centroids
+  (rigid/affine, including atlas-centroid and upright/self-flip modes)
+- **`lta`** – transform comparison, inversion, concatenation, and conversion 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
@@ -222,15 +224,65 @@ Run `bbreg -h` for a full argument summary with defaults.
 
 ---
 
-### `lta` — LTA transform utilities
+### `segreg` — segmentation-based registration
 
-Unified command for manipulating FreeSurfer LTA transform files with three
-subcommands: `diff`, `invert`, and `concat`.
+Registers a moving segmentation by aligning label centroids to another
+segmentation, to bundled atlas centroids such as `fsaverage`, or to a
+left-right flipped self target for upright/midspace workflows. The centroid
+fit now supports translation-only (`3`), rigid (`6`), similarity /
+global-scale (`7`), anisotropic no-shear scaling (`9`), or full affine
+(`12`) transforms.
+
+`segreg` can also write mapped outputs while the package does not yet have a
+separate transform-application CLI. If `--movimg` is provided, `--mapmov` and
+`--mapmovhdr` map that intensity image with the recovered transform; otherwise
+those outputs map the moving segmentation itself.
 
 ```
-lta diff    LTA1 [LTA2] [options]     # Compare transforms
-lta invert  INPUT OUTPUT              # Invert a transform
-lta concat  LTA1 LTA2 OUTPUT          # Concatenate two transforms
+segreg --mov <moving_seg.mgz> (--ref <ref_seg.mgz> | --ref-centroids <centroids.json> | --atlas fsaverage | --flipped) [options]
+```
+
+**Common outputs**
+
+- `--lta FILE` writes the recovered transform as an LTA.
+- `--movimg FILE` provides a separate intensity image for `--mapmov` or `--mapmovhdr`.
+- `--mapmov FILE` writes a resliced mapped output. It maps `--movimg` when provided; otherwise it reslices the moving segmentation itself.
+- `--mapmovhdr FILE` writes a header-only mapped output. It maps `--movimg` when provided; otherwise it remaps the moving segmentation itself.
+
+**Examples**
+
+```bash
+# Register a subject segmentation to another segmentation
+segreg --mov sub-01/aparc+aseg.mgz --ref sub-02/aparc+aseg.mgz \
+       --lta sub01_to_sub02.lta
+
+# Register a segmentation, then map a separate intensity image with the same transform
+segreg --mov subj/mri/aparc+aseg.mgz --movimg subj/mri/orig.mgz --atlas fsaverage \
+       --lta subj_to_fsaverage.lta --mapmov orig_in_fsaverage_space.mgz
+
+# If --movimg is omitted, --mapmov maps the segmentation itself
+segreg --mov subj/mri/aparc+aseg.mgz --atlas fsaverage \
+       --mapmov aparc_aseg_in_fsaverage_space.mgz
+
+# Export centroid JSON only
+segreg --mov subj/mri/aparc+aseg.mgz --atlas fsaverage \
+       --write-mov-centroids subj_centroids.json --write-ref-centroids fsaverage_centroids.json
+```
+
+Run `segreg -h` for a full argument summary with defaults.
+
+---
+
+### `lta` — LTA and linear-transform utilities
+
+Unified command for manipulating FreeSurfer-adjacent linear transforms with four
+subcommands: `diff`, `invert`, `concat`, and `convert`.
+
+```
+lta diff    LTA1 [LTA2] [options]                   # Compare transforms
+lta invert  INPUT OUTPUT                            # Invert a transform
+lta concat  LTA1 LTA2 OUTPUT                        # Concatenate two transforms
+lta convert INPUT OUTPUT [--src-img SRC --dst-img DST]  # Convert formats
 ```
 
 ---
@@ -328,8 +380,104 @@ lta concat fMRI_to_T1.lta T1_to_MNI.lta fMRI_to_MNI.lta
 lta concat moving_to_intermediate.lta intermediate_to_fixed.lta moving_to_fixed.lta
 ```
 
+---
+
+#### `lta convert` — Convert between transform formats
+
+Converts between `.lta`, `.xfm`, volumetric tkregister `.dat`/`.reg`, FSL `.mat`/`.fslmat`, ITK/ANTs 3D affine text transforms, experimental ANTs Matlab-format affine transforms, experimental AFNI affine text transforms, and NiftyReg affine text matrices by normalizing through an internal RAS-to-RAS `LTA`.
+
+**Usage**
+
+```
+lta convert INPUT OUTPUT [--in-format {lta,xfm,fsl,regdat,itk,antsmat,afni,niftyreg}]
+                         [--out-format {lta,xfm,fsl,regdat,itk,antsmat,afni,niftyreg}]
+                         [--src-img SRC] [--dst-img DST]
+                         [--out-type {ras2ras,vox2vox}]
+                         [--subject SUBJECT] [--fscale FSCALE]
+                         [--float2int {tkregister,round,floor}]
+```
+
+**Supported formats**
+
+- `.lta` — FreeSurfer Linear Transform Array
+- `.xfm` — MNI/MINC linear transform
+- `.dat` — old tkregister volumetric `register.dat` format
+- `.mat` / `.fslmat` — FSL FLIRT affine matrix
+- `.tfm` — ITK/ANTs 3D affine text transform
+- `*GenericAffine.mat` — experimental ANTs / ITK Matlab-format affine transform
+- `.aff12.1D` — experimental AFNI affine text matrix
+- `.niftyreg.txt` — NiftyReg 3D affine text matrix
+
 **Notes**
 
+- Reading `register.dat` requires both `--src-img` and `--dst-img`, because the
+  stored matrix is defined in tkregister coordinates rather than scanner RAS.
+- Reading FSL `.mat` / `.fslmat` also requires both `--src-img` and `--dst-img`,
+  because the stored matrix is defined in FSL voxel conventions rather than
+  scanner RAS.
+- Reading `.xfm`, ITK/ANTs text affines, experimental ANTs `.mat`, experimental
+  AFNI affine text, or NiftyReg text matrices without images still preserves the
+  transform matrix, but the resulting LTA geometry blocks stay marked as `valid=0`
+  unless you provide `--src-img` and `--dst-img`.
+- Use `--in-format` / `--out-format` for ambiguous filenames such as `.txt`, `.1D`, or `.mat`.
+- ITK/ANTs text support currently targets 3D affine transforms only, not binary or
+  composite transform files.
+- Experimental ANTs `.mat` support is implemented via SciPy using ITK Matlab IO semantics.
+- Experimental AFNI support targets affine text matrices in AFNI's DICOM/LPS convention.
+- NiftyReg stores the inverse target-to-source RAS matrix in the file, matching
+  FreeSurfer's `lta_convert` handling.
+- `--subject`, `--fscale`, and `--float2int` apply when writing `register.dat`.
+- `--out-type` applies when writing `.lta` output.
+
+**Examples**
+
+```bash
+# XFM -> LTA with explicit image geometry
+lta convert talairach.xfm talairach.lta --src-img mov.mgz --dst-img ref.mgz
+
+# LTA -> XFM
+lta convert sub01_to_mni.lta sub01_to_mni.xfm
+
+# LTA -> tkregister register.dat
+lta convert bold_to_orig.lta bold_to_orig.dat --subject sub-01 --fscale 0.1
+
+# tkregister register.dat -> LTA
+lta convert bold_to_orig.dat bold_to_orig.lta --src-img bold.nii.gz --dst-img orig.mgz
+
+# LTA -> FSL FLIRT matrix
+lta convert bold_to_orig.lta bold_to_orig.mat
+
+# FSL FLIRT matrix -> LTA
+lta convert bold_to_orig.mat bold_to_orig_from_fsl.lta --src-img bold.nii.gz --dst-img orig.mgz
+
+# LTA -> ITK/ANTs text affine
+lta convert bold_to_orig.lta bold_to_orig.tfm
+
+# ITK/ANTs text affine (.txt requires explicit format override)
+lta convert bold_to_orig.txt bold_to_orig_from_itk.lta --in-format itk --src-img bold.nii.gz --dst-img orig.mgz
+
+# LTA -> experimental ANTs GenericAffine .mat
+lta convert bold_to_orig.lta bold_to_orig0GenericAffine.mat
+
+# Experimental ANTs GenericAffine .mat -> LTA (.mat is otherwise assumed FSL)
+lta convert bold_to_orig0GenericAffine.mat bold_to_orig_from_antsmat.lta
+lta convert some_affine.mat bold_to_orig_from_antsmat.lta --in-format antsmat
+
+# LTA -> experimental AFNI affine text
+lta convert bold_to_orig.lta bold_to_orig.aff12.1D
+
+# Experimental AFNI affine text -> LTA (.1D may need explicit format override)
+lta convert bold_to_orig.aff12.1D bold_to_orig_from_afni.lta
+
+# LTA -> NiftyReg affine text matrix (.txt requires explicit format override)
+lta convert bold_to_orig.lta bold_to_orig.txt --out-format niftyreg
+
+# NiftyReg affine text matrix -> LTA
+lta convert bold_to_orig.txt bold_to_orig_from_niftyreg.lta --in-format niftyreg
+```
+
+**General 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.
@@ -396,11 +544,12 @@ transform_bbreg, model_bbreg = bbreg(
 
 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`      |
+| Command / API path           | Supported DOF            |
+|------------------------------|--------------------------|
+| `robreg` / public `robreg()` | `6` only                 |
+| `coreg` / public `coreg()`   | `3`, `6`, `9`, `12`      |
+| `bbreg` / public `bbreg()`   | `6`, `9`, `12`           |
+| `segreg` / public `segreg()` | `3`, `6`, `7`, `9`, `12` |
 
 The public `robreg` path is intentionally rigid-only for now because it tracks
 the current IRLS implementation.

{neuroreg-0.2.0.dev0 → neuroreg-0.4.0.dev0}/neuroreg/__init__.py

@@ -3,6 +3,7 @@ from neuroreg._sys_info import sys_info  # noqa: F401
 from neuroreg.bbreg.register import register_surface as bbreg  # noqa: F401
 from neuroreg.imreg.coreg import coreg  # noqa: F401
 from neuroreg.imreg.robreg import robreg  # noqa: F401
+from neuroreg.segreg import segreg  # noqa: F401
 from neuroreg.transforms import (  # noqa: F401
     LINEAR_RAS_TO_RAS,
     LINEAR_VOX_TO_VOX,
@@ -14,6 +15,7 @@ __all__ = [
     "bbreg",
     "coreg",
     "robreg",
+    "segreg",
     "sys_info",
     "LINEAR_RAS_TO_RAS",
     "LINEAR_VOX_TO_VOX",

{neuroreg-0.2.0.dev0 → neuroreg-0.4.0.dev0}/neuroreg/cli/coreg.py

@@ -229,7 +229,7 @@ def main(args=None) -> None:
     v2v = coreg(mov_img, ref_img, **kwargs)
     v2v_cpu = v2v.detach().cpu()
 
-    LTA.from_matrix(v2v_cpu.numpy(), ns.mov, cast(Any, mov_img), ns.ref, cast(Any, ref_img), lta_type=0).write(ns.out)
+    LTA.from_matrix(v2v_cpu.numpy(), ns.mov, mov_img, ns.ref, ref_img, lta_type=0).write(ns.out)
     logger.info("Wrote LTA: %s", ns.out)
     print(f"Output: {ns.out}")