simcortexpp 0.1.0__py3-none-any.whl

simcortexpp/utils/tca.py

@@ -0,0 +1,298 @@
+"""
+Topology correction algorithm by Bazin et al.
+Please cite the original papers if you use this code:
+- Bazin et al. Topology correction using fast marching methods and its application to brain segmentation.
+  MICCAI, 2005.
+- Bazin et al. Topology correction of segmented medical images using a fast marching algorithm.
+  Computer methods and programs in biomedicine, 2007.
+
+The algorithm is re-implemented and accelerated using Python+Numba.
+
+For the original Java implementation please see:
+- https://github.com/piloubazin/cbstools-public/blob/master/de/mpg/cbs/core/shape/ShapeTopologyCorrection2.java
+Or refer to the Nighres software:
+- https://nighres.readthedocs.io/en/latest/shape/topology_correction.html
+The look up table file "critical186LUT.raw.gz" is downloaded from Nighres:
+- https://nighres.readthedocs.io/en/latest/
+"""
+
+
+from heapq import *
+import numpy as np
+from numba import njit
+import gzip
+from scipy.ndimage import binary_dilation
+from pathlib import Path
+
+class topology():
+    """
+    apply topology correction algorithm
+    inpt: input volume
+    threshold: used to create initial mask. We set threshold=16 for CortexODE.
+    """
+    def __init__(self):
+        lut_path = Path(__file__).resolve().parent / "critical186LUT.raw.gz"
+        bit, lut = tca_init_fill(str(lut_path), threshold=1.0)
+        self.bit = bit
+        self.lut = lut
+    def apply(self, inpt, threshold=1.0):
+        mask, init_pts = tca_mask_fill(inpt, threshold)
+        output = tca_fill(inpt, mask, init_pts, self.bit, self.lut)
+        return output  # , mask
+
+
+@njit
+def bit_map():
+    """used for compute key"""
+    twobit = np.array([2**k for k in range(26)], dtype=np.float64)
+    bit = np.zeros(27, dtype=np.float64)
+    bit[:13] = twobit[:13]
+    bit[14:] = twobit[13:]
+    bit = bit.copy().reshape(3,3,3)
+    
+    return bit
+
+
+@njit
+def check_topology(img, LUT, bit):
+    """check the critical points"""
+    res = False
+    if img[1,1,1] == 1:  # inside the original object
+        res = True
+    else:  # check topology
+        # load key from pattern: should keep dtypes as the same
+        key = 0.
+        for i in range(3):
+            for j in range(3):
+                for k in range(3):
+                    key += img[i,j,k] * bit[i,j,k]
+        key = int(key)
+        if LUT[key]:        
+            res = True
+        else:
+            res = False
+        return res
+
+
+""" tca_fill
+This algorithm propagates from background to object.
+It fills all holes and is used to fix WM segemntation. 
+"""
+
+def tca_mask_fill(levelset, threshold=1.0):
+    """intialize processing mask"""
+    
+    initmask = np.zeros_like(levelset)
+    initmask[2:-2, 2:-2, 2:-2] = 1
+    initmask *= (levelset <= threshold)
+    mask = binary_dilation(initmask, structure=np.ones([3,3,3]))
+    init_pts = np.stack(np.where((mask-initmask)==1)).astype(int).T
+    
+    return mask, init_pts
+
+
+def tca_init_fill(path, threshold=1.0):
+    """
+    Initialization for topology correction.
+    Step 1. load look up table
+    Step 2. load bit map
+    Step 3. compile the Numba by a toy example
+    """
+    # load look up tables
+    with gzip.open(path, 'rb') as lut_file:
+        LUT = lut_file.read()
+        
+    # load bit map
+    bit = bit_map()
+    
+    # create a toy example to compile the Numba
+    img = (threshold-0.1) * np.ones([10,10,10])
+    img[4:6,4:6,4:6] = threshold + 0.1
+    mask, init_pts = tca_mask_fill(img, threshold)
+    img_fix = tca_fill(img, mask, init_pts, bit, LUT)
+    
+    return bit, LUT
+
+
+@njit
+def tca_fill(levelset, mask, init_pts, bit, LUT):
+
+    dtype = levelset.dtype
+
+    minDistance = np.array(1e-5, dtype=dtype).item()
+    UNKNOWN     = np.array(1e11, dtype=dtype).item()
+
+    nx, ny, nz = levelset.shape
+    C6 = [(-1,0,0), (1,0,0), (0,-1,0), (0,1,0), (0,0,-1), (0,0,1)]
+
+    corrected = np.ones_like(levelset) * UNKNOWN
+    processed = np.zeros(levelset.shape, dtype=np.uint8)
+    inheap    = np.zeros(levelset.shape, dtype=np.uint8)
+
+    mainval = np.array(1e15, dtype=dtype).item()
+    maskval = np.array(-1e15, dtype=dtype).item()
+    maskval = np.max(mask * levelset)
+    
+    """add neighbors to the heap"""
+    heap = []  # max heap
+    for x0,y0,z0 in init_pts:
+        processed[x0,y0,z0] = 1.
+        corrected[x0,y0,z0] = levelset[x0,y0,z0]
+        if corrected[x0,y0,z0] < mainval:
+            mainval = corrected[x0,y0,z0]
+
+        for dx, dy, dz in C6:
+            xn = x0 + dx
+            yn = y0 + dy
+            zn = z0 + dz
+            if mask[xn,yn,zn] and not processed[xn,yn,zn]:
+                heap.append((-levelset[xn,yn,zn],(xn,yn,zn)))
+                inheap[xn,yn,zn] = 1.
+    heapify(heap)
+    
+    """Run Topology Correction"""
+    while len(heap) > 0:
+
+        # pop the heap
+        val_, (x, y, z) = heappop(heap)
+        val = - val_
+        inheap[x, y, z] = 0.
+
+        if processed[x, y, z]:
+            continue
+        cube = processed[x-1:x+2, y-1:y+2, z-1:z+2]
+        non_critical = check_topology(cube, LUT, bit)
+        
+        if non_critical:
+            # all correct: update and find new neighbors
+            corrected[x,y,z] = val
+            processed[x,y,z]= 1.  #  update the current level
+            mainval = val
+
+            # find new neighbors
+            for dx, dy, dz in C6:
+                xn = x + dx
+                yn = y + dy
+                zn = z + dz
+                if mask[xn,yn,zn] and not processed[xn,yn,zn] and not inheap[xn,yn,zn]:
+                    prio = -min(levelset[xn,yn,zn], val - minDistance)
+                    heappush(heap, (prio, (xn, yn, zn)))    
+                    inheap[xn,yn,zn] = True
+                    
+    corrected += (mainval-corrected) * (1-processed)
+    corrected += (maskval-corrected) * (1-mask)
+    
+    return corrected
+
+
+
+""" tca_cut (to be validated)
+This algorithm propagates from object to background.
+It cuts all handles and is used to fix GM segemntation. 
+
+Note: this function is not fully validated because we only use tca_fill for CortexODE.
+"""
+
+def tca_mask_cut(levelset, threshold=1.0):
+    """intialize processing mask"""
+    initmask = np.zeros_like(levelset)
+    initmask[2:-2, 2:-2, 2:-2] = 1
+    initmask *= (levelset <= threshold)
+    mask = binary_dilation(initmask, structure=np.ones([3,3,3]))
+    init_pts = np.stack(np.where(levelset==np.min(levelset))).astype(int).T
+    return mask, init_pts
+
+
+def tca_init_cut(path, threshold=1.0):
+    """
+    Initialization for topology correction.
+    Step 1. load look up table
+    Step 2. load bit map
+    Step 3. compile the Numba by a toy example
+    """
+    # load look up tables
+    with gzip.open(path, 'rb') as lut_file:
+        LUT = lut_file.read()
+        
+    # load bit map
+    bit = bit_map()
+    
+    # create a toy example to compile the Numba
+    img = (threshold+0.1) * np.ones([10,10,10])
+    img[4:6,4:6,4:6] = threshold - 0.1
+    img[5,5,5] = threshold - 0.2
+    mask, init_pts = tca_mask_cut(img, threshold)
+    img_fix = tca_cut(img, mask, init_pts, bit, LUT)
+    
+    return bit, LUT
+
+
+
+@njit
+def tca_cut(levelset, mask, init_pts, bit, LUT):
+    
+    """Configuration"""
+    minDistance = 1e-5
+    UNKNOWN = 10e+10
+    nx,ny,nz = levelset.shape
+    # connectivity
+    C6 = [(-1,0,0), (1,0,0), (0,-1,0), (0,1,0), (0,0,-1), (0,0,1)]
+    
+    """Initialize indicators"""
+    corrected = np.ones_like(levelset) * UNKNOWN  # gdm functions
+    processed = np.zeros_like(levelset).astype(np.float64)
+    inheap = np.zeros_like(levelset).astype(np.float64)
+    mainval = -1e15
+    maskval = -1e15
+    maskval = np.max(mask*levelset)
+    
+    """add neighbors to the heap"""
+    heap = []  # max heap
+    for x0,y0,z0 in init_pts:
+        processed[x0,y0,z0] = 1.
+        corrected[x0,y0,z0] = levelset[x0,y0,z0]
+        if corrected[x0,y0,z0] > mainval:
+            mainval = corrected[x0,y0,z0]
+
+        for dx, dy, dz in C6:
+            xn = x0 + dx
+            yn = y0 + dy
+            zn = z0 + dz
+            if mask[xn,yn,zn] and not processed[xn,yn,zn]:
+                heap.append((levelset[xn,yn,zn],(xn,yn,zn)))
+                inheap[xn,yn,zn] = 1.
+    heapify(heap)
+    
+
+    """Run Topology Correction"""
+    while len(heap) > 0:
+
+        # pop the heap
+        val_, (x, y, z) = heappop(heap)
+        val = val_
+        inheap[x, y, z] = 0.
+
+        if processed[x, y, z]:
+            continue
+        cube = processed[x-1:x+2, y-1:y+2, z-1:z+2]
+        non_critical = check_topology(cube, LUT, bit)
+        
+        if non_critical:
+            # all correct: update and find new neighbors
+            corrected[x,y,z] = val
+            processed[x,y,z]= 1.  #  update the current level
+            mainval = val
+
+            # find new neighbors
+            for dx, dy, dz in C6:
+                xn = x + dx
+                yn = y + dy
+                zn = z + dz
+                if mask[xn,yn,zn] and not processed[xn,yn,zn] and not inheap[xn,yn,zn]:
+                    heappush(heap, (max(levelset[xn,yn,zn], val-minDistance), (xn, yn, zn)))
+                    inheap[xn,yn,zn] = True
+                    
+    corrected += (mainval-corrected) * (1-processed)
+    corrected += (maskval-corrected) * (1-mask)
+    
+    return corrected

simcortexpp-0.1.0.dist-info/METADATA

@@ -0,0 +1,334 @@
+Metadata-Version: 2.4
+Name: simcortexpp
+Version: 0.1.0
+Summary: SimCortexPP (SCPP) — CLI-first pipeline for cortical surface reconstruction (preproc, seg, initsurf, deform)
+Author: Kaveh Moradkhani
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: typer>=0.12
+Requires-Dist: numpy>=1.24
+Requires-Dist: pandas>=2.0
+Requires-Dist: nibabel>=5.2
+Requires-Dist: hydra-core>=1.3
+Requires-Dist: omegaconf>=2.3
+Requires-Dist: tqdm>=4.66
+Requires-Dist: tensorboard>=2.14
+Requires-Dist: trimesh>=4.0
+Requires-Dist: openpyxl>=3.1
+Provides-Extra: seg
+Requires-Dist: monai>=1.3; extra == "seg"
+Provides-Extra: deform-metrics
+Requires-Dist: python-fcl; extra == "deform-metrics"
+Requires-Dist: pymeshlab; extra == "deform-metrics"
+Provides-Extra: torch
+Requires-Dist: torch>=2.0; extra == "torch"
+
+# SimCortexPP (SCPP)
+
+SimCortexPP (SCPP) is a **CLI-first** Python package for cortical surface reconstruction in MNI space. It provides four stages:
+
+1. **Preprocessing (FreeSurfer → MNI152)**  
+   Export key FreeSurfer volumes/surfaces, register them to MNI152, and write outputs in a **BIDS-derivatives-style** layout.
+
+2. **Segmentation (3D U-Net in MNI space)**  
+   Train and apply a 3D U-Net to predict a **9-class segmentation** in **MNI152 space**, with inference and evaluation utilities.
+
+3. **Initial Surfaces (InitSurf)**  
+   Generate initial White Matter and Pial surfaces from segmentation predictions (plus ribbon SDF/probability outputs).
+
+4. **Deformation (Deform)**  
+   Deform the initial surfaces toward MNI-aligned FreeSurfer surfaces using geometric losses and optional collision metrics, and write **deformed surfaces** as BIDS-derivatives.
+
+This README focuses on **how to run the pipeline correctly** (inputs, outputs, folder/file naming, and commands).
+
+---
+
+## Table of Contents
+
+- [Installation](#installation)
+- [Configuration](#configuration)
+- [Data and Folder Conventions](#data-and-folder-conventions)
+- [Split File Format](#split-file-format)
+- [Stage 1 — Preprocessing: FreeSurfer → MNI152](#stage-1--preprocessing-freesurfer--mni152)
+- [Stage 2 — Segmentation: 3D U-Net (MNI space)](#stage-2--segmentation-3d-u-net-mni-space)
+- [Stage 3 — Initial Surfaces (InitSurf)](#stage-3--initial-surfaces-initsurf)
+- [Stage 4 — Deformation (Deform)](#stage-4--deformation-deform)
+- [License](#license)
+
+---
+
+## Installation
+
+From the repository root:
+
+```bash
+pip install -e .
+scpp --help
+scpp seg --help
+scpp initsurf --help
+scpp deform --help
+```
+
+### Recommended environment
+- Python 3.10+
+- PyTorch + MONAI
+- `nibabel`, `numpy`, `pandas`, `openpyxl`
+- `trimesh`, `scipy`, `tqdm`
+- External tools for Stage 1: **NiftyReg** (`reg_aladin`, `reg_resample`)
+- Optional (Deform metrics):
+  - `python-fcl` for collision metrics
+  - `pymeshlab` for SIF (self-intersection fraction) in Deform evaluation
+
+---
+
+## Configuration
+
+All stages use Hydra YAML configs shipped with the package (see `src/simcortexpp/configs/<stage>/*.yaml`).
+
+You have **two** ways to configure a run:
+
+1) **Edit the stage YAML** (recommended for longer runs / stable experiments), then run commands with no extra arguments, e.g.:
+   - `scpp deform eval`
+
+2) **Use Hydra overrides on the CLI** (recommended for quick tests), e.g.:
+   - `scpp deform eval dataset.split_name=test outputs.out_dir=/tmp/deform_eval`
+
+---
+
+## Data and Folder Conventions
+
+You will typically work with **two roots**:
+
+1) **Code repository (this repository)**  
+Contains code, configs, and scripts (no data).
+
+2) **Dataset root (BIDS + derivatives)**  
+Each dataset has its own root directory. Recommended structure:
+
+```text
+datasets/<dataset-name>/
+  bids/                 # raw BIDS dataset
+  derivatives/          # processed outputs (BIDS derivatives)
+    freesurfer-7.4.1/
+    scpp-preproc-0.1/
+    scpp-seg-0.1/
+    scpp-initsurf-0.1/
+    scpp-deform-0.1/
+  splits/
+    <dataset>_split.csv
+```
+
+SCPP reads inputs from `derivatives/` and writes outputs back to `derivatives/` using BIDS-derivatives-style naming.
+
+> Important: keep the dataset root naming consistent (e.g., use `datasets/...` everywhere).
+
+---
+
+## Split File Format
+
+A split CSV is required for Segmentation, InitSurf, and Deform.
+
+### Single-dataset split
+Minimal columns:
+- `subject` (e.g., `sub-0001`)
+- `split` in `{train, val, test}`
+
+### Multi-dataset split
+Include an additional column:
+- `dataset` (string key that matches config keys, e.g., `HCP_YA`, `OASIS1`)
+
+Example:
+```csv
+subject,split,dataset
+sub-100307,test,HCP_YA
+sub-101915,test,HCP_YA
+sub-0001,test,OASIS1
+```
+
+---
+
+## Stage 1 — Preprocessing: FreeSurfer → MNI152
+
+This stage exports key FreeSurfer outputs (volumes + surfaces), registers them to **MNI152**, and writes results to a **BIDS-derivatives-style** folder.
+
+### Inputs
+- FreeSurfer derivatives root (contains `sub-*` folders)
+- MNI template (e.g., `src/MNI152_T1_1mm.nii.gz`)
+
+### Dependencies (system tools)
+- **NiftyReg**: `reg_aladin`, `reg_resample` must be in `PATH`
+- **FreeSurfer** tools are recommended (e.g., `mri_convert`, `mris_convert`) for consistent conversions
+
+### Run (all subjects discovered automatically)
+```bash
+scpp fs-to-mni   --freesurfer-root /path/to/datasets/<dataset>/derivatives/freesurfer-7.4.1   --out-deriv-root  /path/to/datasets/<dataset>/derivatives/scpp-preproc-0.1   --mni-template    /path/to/SimCortexPP/src/MNI152_T1_1mm.nii.gz   --decimate 0.3   -v
+```
+
+### Run (selected subjects)
+```bash
+scpp fs-to-mni   --freesurfer-root /path/to/datasets/<dataset>/derivatives/freesurfer-7.4.1   --out-deriv-root  /path/to/datasets/<dataset>/derivatives/scpp-preproc-0.1   --mni-template    /path/to/SimCortexPP/src/MNI152_T1_1mm.nii.gz   -p sub-0001 -p sub-0019   -v
+```
+
+### Output layout (example)
+```text
+scpp-preproc-0.1/
+  dataset_description.json
+  sub-XXXX/
+    ses-01/
+      anat/
+        sub-XXXX_ses-01_space-MNI152_desc-preproc_T1w.nii.gz
+        sub-XXXX_ses-01_space-MNI152_desc-aparc+aseg_dseg.nii.gz
+        sub-XXXX_ses-01_space-MNI152_desc-filled_T1w.nii.gz
+        sub-XXXX_ses-01_from-T1w_to-MNI152_mode-image_xfm.txt
+      surfaces/
+        sub-XXXX_ses-01_space-MNI152_hemi-L_white.surf.ply
+        sub-XXXX_ses-01_space-MNI152_hemi-L_pial.surf.ply
+        sub-XXXX_ses-01_space-MNI152_hemi-R_white.surf.ply
+        sub-XXXX_ses-01_space-MNI152_hemi-R_pial.surf.ply
+```
+
+---
+
+## Stage 2 — Segmentation: 3D U-Net (MNI space)
+
+This stage trains and applies a 3D U-Net to predict a **9-class segmentation** in **MNI152 space** using Stage 1 outputs.
+
+### Expected inputs (from Stage 1)
+Under `scpp-preproc-*`, for each subject:
+- `..._desc-preproc_T1w.nii.gz`
+- `..._desc-aparc+aseg_dseg.nii.gz`
+- `..._desc-filled_T1w.nii.gz`
+
+### Output naming (predictions)
+Predictions are written under `scpp-seg-*`:
+- `sub-XXXX/ses-01/anat/sub-XXXX_ses-01_space-MNI152_desc-seg9_dseg.nii.gz`
+
+### Train (single GPU)
+```bash
+scpp seg train   dataset.path=/path/to/datasets/<dataset>/derivatives/scpp-preproc-0.1   dataset.split_file=/path/to/datasets/<dataset>/splits/<dataset>_split.csv   outputs.root=/path/to/scpp-runs/seg/exp01   trainer.use_ddp=false
+```
+
+### Train (multi-GPU, torchrun)
+```bash
+scpp seg train --torchrun --nproc-per-node 2   dataset.path=/path/to/datasets/<dataset>/derivatives/scpp-preproc-0.1   dataset.split_file=/path/to/datasets/<dataset>/splits/<dataset>_split.csv   outputs.root=/path/to/scpp-runs/seg/exp01   trainer.use_ddp=true
+```
+
+### Inference
+```bash
+scpp seg infer   dataset.path=/path/to/datasets/<dataset>/derivatives/scpp-preproc-0.1   dataset.split_file=/path/to/datasets/<dataset>/splits/<dataset>_split.csv   dataset.split_name=test   model.ckpt_path=/path/to/seg_best_dice.pt   outputs.out_root=/path/to/datasets/<dataset>/derivatives/scpp-seg-0.1
+```
+
+### Evaluation (multi-dataset example)
+```bash
+scpp seg eval   dataset.split_file=/path/to/datasets/splits/dataset_split.csv   dataset.split_name=test   dataset.roots.HCP_YA=/path/to/datasets/hcpya-u100/derivatives/scpp-preproc-0.1   dataset.roots.OASIS1=/path/to/datasets/oasis-1/derivatives/scpp-preproc-0.1   outputs.pred_roots.HCP_YA=/path/to/datasets/hcpya-u100/derivatives/scpp-seg-0.1   outputs.pred_roots.OASIS1=/path/to/datasets/oasis-1/derivatives/scpp-seg-0.1   outputs.eval_csv=/path/to/scpp-runs/seg/exp01/evals/seg_eval_test.csv   outputs.eval_xlsx=/path/to/scpp-runs/seg/exp01/evals/seg_eval_test.xlsx
+```
+
+---
+
+## Stage 3 — Initial Surfaces (InitSurf)
+
+This stage generates initial cortical surfaces from saved segmentation predictions (not end-to-end).
+
+### Inputs
+- Preproc roots (`scpp-preproc-*`) for MNI T1
+- Seg roots (`scpp-seg-*`) for `..._desc-seg9_dseg.nii.gz`
+- Split CSV (same format as Stage 2)
+
+### Outputs
+BIDS-derivatives-style outputs under `scpp-initsurf-*` (meshes + SDF volumes + ribbon prob):
+```text
+scpp-initsurf-0.1/
+  dataset_description.json
+  sub-XXXX/
+    ses-01/
+      anat/
+        sub-XXXX_ses-01_space-MNI152_desc-lh_white_sdf.nii.gz
+        sub-XXXX_ses-01_space-MNI152_desc-rh_white_sdf.nii.gz
+        sub-XXXX_ses-01_space-MNI152_desc-lh_pial_sdf.nii.gz
+        sub-XXXX_ses-01_space-MNI152_desc-rh_pial_sdf.nii.gz
+        sub-XXXX_ses-01_space-MNI152_desc-ribbon_sdf.nii.gz
+        sub-XXXX_ses-01_space-MNI152_desc-ribbon_prob.nii.gz
+      surfaces/
+        sub-XXXX_ses-01_space-MNI152_hemi-L_white.surf.ply
+        sub-XXXX_ses-01_space-MNI152_hemi-L_pial.surf.ply
+        sub-XXXX_ses-01_space-MNI152_hemi-R_white.surf.ply
+        sub-XXXX_ses-01_space-MNI152_hemi-R_pial.surf.ply
+```
+
+### Run (multi-dataset example)
+```bash
+scpp initsurf generate   dataset.split_file=/path/to/datasets/splits/dataset_split.csv   dataset.split_name=all   dataset.roots.HCP_YA=/path/to/datasets/hcpya-u100/derivatives/scpp-preproc-0.1   dataset.roots.OASIS1=/path/to/datasets/oasis-1/derivatives/scpp-preproc-0.1   dataset.seg_roots.HCP_YA=/path/to/datasets/hcpya-u100/derivatives/scpp-seg-0.1   dataset.seg_roots.OASIS1=/path/to/datasets/oasis-1/derivatives/scpp-seg-0.1   outputs.out_roots.HCP_YA=/path/to/datasets/hcpya-u100/derivatives/scpp-initsurf-0.1   outputs.out_roots.OASIS1=/path/to/datasets/oasis-1/derivatives/scpp-initsurf-0.1   outputs.log_dir=/path/to/scpp-runs/initsurf/exp01/logs_generate
+```
+
+Typical runtime: ~31 s/subject (hardware-dependent).
+
+---
+
+## Stage 4 — Deformation (Deform)
+
+This stage deforms InitSurf meshes using input volumes and geometric losses, and writes **deformed** surfaces to a BIDS-derivatives folder.
+
+### Inputs
+- Preproc root (`scpp-preproc-*`): MNI T1 + GT FreeSurfer surfaces in MNI space
+- InitSurf root (`scpp-initsurf-*`): ribbon probability + initial surfaces
+- Split CSV (same format as Stage 2)
+
+### Outputs
+Deformed surfaces under `scpp-deform-*`:
+```text
+scpp-deform-0.1/
+  dataset_description.json
+  sub-XXXX/
+    ses-01/
+      surfaces/
+        sub-XXXX_ses-01_space-MNI152_desc-deform_hemi-L_white.surf.ply
+        sub-XXXX_ses-01_space-MNI152_desc-deform_hemi-L_pial.surf.ply
+        sub-XXXX_ses-01_space-MNI152_desc-deform_hemi-R_white.surf.ply
+        sub-XXXX_ses-01_space-MNI152_desc-deform_hemi-R_pial.surf.ply
+```
+
+### Train (multi-GPU example)
+```bash
+scpp deform train --torchrun --nproc-per-node 2   outputs.root=/path/to/scpp-runs/deform/exp01
+```
+
+### Inference
+```bash
+scpp deform infer
+```
+
+### Evaluation
+```bash
+scpp deform eval
+```
+
+Evaluation writes four Excel files:
+- `surface_metrics.xlsx`
+- `collision_metrics.xlsx`
+- `collision_metrics_enhanced.xlsx`
+- `collision_summary.xlsx`
+
+---
+
+## Outputs Summary
+
+For each dataset root:
+
+- `derivatives/scpp-preproc-0.1/`  
+  MNI T1, aparc+aseg, filled, transforms, and MNI-aligned FreeSurfer surfaces.
+
+- `derivatives/scpp-seg-0.1/`  
+  9-class segmentation predictions (`*_desc-seg9_dseg.nii.gz`).
+
+- `derivatives/scpp-initsurf-0.1/`  
+  Initial surfaces (`*.surf.ply`) + SDF volumes + ribbon SDF/probability.
+
+- `derivatives/scpp-deform-0.1/`  
+  Deformed surfaces (`*_desc-deform_*.surf.ply`).
+
+---
+
+
+## License
+
+Add your license and citation details here if needed.

simcortexpp-0.1.0.dist-info/RECORD

@@ -0,0 +1,44 @@
+simcortexpp/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+simcortexpp/cli/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+simcortexpp/cli/main.py,sha256=SZyV66Qdzd-q7zkle09-Y9SzLoPsGIMp1zyZpv1tHek,3108
+simcortexpp/configs/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+simcortexpp/configs/deform/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+simcortexpp/configs/deform/eval.yaml,sha256=QQFUciVQrxC9q4PqtpENsPFYYQLwv2LFquc7lhSZZXw,1052
+simcortexpp/configs/deform/inference.yaml,sha256=i9HJ6qscq_7aLN1G5wSfgJRHyZ0bv-15OZbaMMQttmk,1737
+simcortexpp/configs/deform/train.yaml,sha256=n0kly9M-1aaO71ASzGRQGnZiecb1RF80dalf2Ss92W4,2103
+simcortexpp/configs/initsurf/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+simcortexpp/configs/initsurf/generate.yaml,sha256=36WxtHZz7eouurDEuStFq3s0lZQYMigWvi8REWKAM3Q,1434
+simcortexpp/configs/seg/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+simcortexpp/configs/seg/eval.yaml,sha256=nwQ2njQR5sZO6WJPswnniJNmhcC55gZoSGzDPQkAnaE,1115
+simcortexpp/configs/seg/inference.yaml,sha256=3QCT2Zp4wSUvE0QJ6uMMhzrBfcRicY2LVlZ3ILwTfgQ,1031
+simcortexpp/configs/seg/train.yaml,sha256=adm84bcodkQyzEFw1w15u1nt6KNczhgaiqVg29t_FJw,922
+simcortexpp/deform/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+simcortexpp/deform/eval.py,sha256=3WQ4ZCz1LjkFYaN5HNpMYqfpD2qfDYMXCVV-vQc6f54,12186
+simcortexpp/deform/inference.py,sha256=-N_LOT_KEQYCmP_WNUy-5wUp7RG7KPgpaC3rx3fLA8M,8826
+simcortexpp/deform/train.py,sha256=SGblWWk3LhrPO4jKRUe1I7dVkC0-zepar8bwPXzSGus,46719
+simcortexpp/deform/data/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+simcortexpp/deform/data/dataloader.py,sha256=7LQuvz6I7Ie-krJCDWdBBpURy2EkgISyRdGRBcPb1bw,8966
+simcortexpp/deform/models/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+simcortexpp/deform/models/surfdeform.py,sha256=kLG6eSOteu19HluQh4g_st7UgNzmpcEDcruMLtsiSBE,13526
+simcortexpp/deform/utils/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+simcortexpp/deform/utils/coords.py,sha256=efjz2Clr6f3uCEtZxymbAqaEs6tLWX9w_KLoorTCJbg,3010
+simcortexpp/initsurf/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+simcortexpp/initsurf/generate.py,sha256=thM2vN31nt6J3byBtkRAqWpO9he8spvZ07FSr7UCsSM,15095
+simcortexpp/initsurf/paths.py,sha256=Dox0pAGZm8k1wCchsek7OEr2XHyiDb_0b0upqQYblKY,783
+simcortexpp/preproc/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+simcortexpp/preproc/fs_to_mni.py,sha256=LyTla34qkQAfiuc1kgdve20_dTqNWeHkBTMMe_JVcs8,24812
+simcortexpp/seg/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+simcortexpp/seg/eval.py,sha256=UcMUPseL5-NNHlAjZkOic34yAnjvTj_vwOYMqt-ox0A,9288
+simcortexpp/seg/inference.py,sha256=x885BvuQo9yCzmCsjI6CW4aHtKGOZAQ1lnX-gGddbk8,10254
+simcortexpp/seg/train.py,sha256=pT2o06CqbPfVE5nc377bbGilodqVdBm-BgnG42RJWfE,15247
+simcortexpp/seg/data/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+simcortexpp/seg/data/dataloader.py,sha256=TFTMf2SEE3Aqyt0HIeIrN8_dOHvPdRBBmo43_lYnFZM,11292
+simcortexpp/seg/models/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+simcortexpp/seg/models/unet.py,sha256=vG2ZTec2cYRltW4U__3r6oiSZRlsIN5M8kJZ8o21RxE,2379
+simcortexpp/utils/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+simcortexpp/utils/tca.py,sha256=Tj9_HAZo8_PxeK0e1Q46s0f9kBgPYDUbHBTNYhfKWYI,9171
+simcortexpp-0.1.0.dist-info/METADATA,sha256=s9xM_1Ox5cFxGzySme-t1zwdU-N9YQWY-8svLYX7FDc,11984
+simcortexpp-0.1.0.dist-info/WHEEL,sha256=YCfwYGOYMi5Jhw2fU4yNgwErybb2IX5PEwBKV4ZbdBo,91
+simcortexpp-0.1.0.dist-info/entry_points.txt,sha256=6VvMqyqopjoDohH8jLw2jNvo-VzHh8sMfv9JO9Jkwp4,50
+simcortexpp-0.1.0.dist-info/top_level.txt,sha256=SKYCpY9Y_P2F-h9EAtlXjJQRs1XlTEMHMqmdoLRnDik,12
+simcortexpp-0.1.0.dist-info/RECORD,,

simcortexpp-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

simcortexpp-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+scpp = simcortexpp.cli.main:app

simcortexpp-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+simcortexpp