SPINEPS 2.0: usability, error-proofing, batched inference, segment() API + CLI cleanup

.github/workflows/linter.yml

@@ -10,8 +10,8 @@ jobs:
   ruff:
     runs-on: ubuntu-latest
     steps:
-    - uses: actions/checkout@v3
-    - uses: actions/setup-python@v3
+    - uses: actions/checkout@v4
+    - uses: actions/setup-python@v5
     - run: pip install ruff
     - run: ruff check .
     #- uses: chartboost/ruff-action@v1

.github/workflows/python-publish.yml

@@ -13,10 +13,10 @@ jobs:
     runs-on: ubuntu-latest
 
     steps:
-    - name: Checkout Repository 
-      uses: actions/checkout@v3
+    - name: Checkout Repository
+      uses: actions/checkout@v4
     - name: Set up Python
-      uses: actions/setup-python@v4
+      uses: actions/setup-python@v5
       with:
         python-version: '3.11'
     - name: Install dependencies
@@ -30,5 +30,5 @@ jobs:
       env:
         TWINE_USERNAME: __token__
         TWINE_PASSWORD: ${{ secrets.PYPI_API_TOKEN }}
-      run: | 
-        twine upload dist/*.whl
+      run: |
+        twine upload dist/*

.github/workflows/tests.yml

@@ -30,7 +30,7 @@ jobs:
       run: |
         python -m pip install --upgrade pip
         python -m pip install poetry
-        python -m pip install flake8 pytest
+        python -m pip install pytest
     - name: Install dependancies
       run: |
         python -m poetry install

.gitignore

@@ -4,7 +4,6 @@ nnUNet/*
 .vscode/
 spineps/models/*
 
-*.png
 # Byte-compiled / optimized / DLL files
 __pycache__/
 *.py[cod]
@@ -109,8 +108,6 @@ ENV/
 .mypy_cache/
 
 # project directories
-code/bids
-code/bids/*
 data
 data/*
 output/A/
@@ -121,22 +118,8 @@ unet/out*/
 *.nii
 *.png
 *.csv
-FashionMNIST/
-MNIST/
 .idea/
-anomaly_logs/*
-anomaly_logs
-forward_weighting_tests
-forward_weighting_tests/*
 evaluation_logs/
-corner_detection_test/
-corner_detection_test/*
-paper/
-paper/*
-code/Unet3D/lightning_logs/
-code/Unet3D/lightning_logs/*
-code/Unet3D/L_logs_archive/
-code/Unet3D/L_logs_archive/*
 
 # model checkpoints
 *.pth
@@ -146,10 +129,9 @@ code/Unet3D/L_logs_archive/*
 unet/*_seg/
 *.jpg
 
-*.txt !Notes/
+*.txt
 weights/
 *.gif
-*.png
 *.npy
 
 lightning_logs/
@@ -158,4 +140,5 @@ test.txt
 derivatives_seg
 robert_test.py
 poetry.lock
-*.DS_Store
+*.DS_Store
+*DS_Store*

MIGRATION.md

@@ -0,0 +1,97 @@
+# Migrating to SPINEPS 2.0
+
+SPINEPS 2.0 is a clean-break release: CLI flags, public functions and classes were renamed for clarity and
+consistency, and a new one-call Python API was added. **No backward-compatible aliases are kept** — update your
+scripts using the tables below.
+
+## TL;DR — the new one-call API
+
+The biggest change is that you no longer have to load three models and pass dozens of flags:
+
+```python
+import spineps
+
+# Save a BIDS derivatives folder next to the input:
+result = spineps.segment("sub-01_T2w.nii.gz")
+
+# Or get the masks in memory:
+result = spineps.segment(nii, output_in_memory=True)
+if result.success:
+    semantic, vertebra = result.semantic, result.vertebra
+
+# Segmenting many images? Load the models once:
+from spineps import SpinepsPipeline
+pipe = SpinepsPipeline(model_semantic="t2w", model_instance="instance")
+for path in paths:
+    pipe.segment(path)
+```
+
+## CLI flags
+
+All long flags are now `--kebab-case` (short aliases are unchanged). Negative flags became positive on/off pairs.
+
+| Old | New |
+| --- | --- |
+| `-nocrop` / `-nc` | `--no-crop` (cropping is on by default; pass `--no-crop` to disable) |
+| `-non4` | `--no-n4` (N4 is on by default; pass `--no-n4` to disable) |
+| `-no_tltv_labeling` / `-ntl` | `--enforce-12-thoracic` |
+| `-input` / `-i` | `--input` / `-i` |
+| `-directory` / `-d` | `--directory` / `-d` |
+| `-model_semantic` / `-ms` | `--model-semantic` / `-ms` |
+| `-model_instance` / `-mv` | `--model-instance` / `-mv` / `-mi` |
+| `-model_labeling` / `-ml` | `--model-labeling` / `-ml` |
+| `-der_name` / `-dn` | `--derivative-name` / `-dn` |
+| `-raw_name` / `-rn` | `--rawdata-name` / `-rn` |
+| `-save_debug` / `-sd` | `--save-debug` / `-sd` |
+| `-save_softmax_logits` / `-ssl` | `--save-softmax-logits` / `-ssl` |
+| `-save_modelres_mask` / `-smrm` | `--save-modelres-mask` / `-smrm` |
+| `-save_log` / `-sl` | `--save-log` / `-sl` |
+| `-save_snaps_folder` / `-ssf` | `--save-snaps-folder` / `-ssf` |
+| `-override_semantic` / `-os` | `--override-semantic` / `-os` |
+| `-override_instance` / `-oi` | `--override-instance` / `-oi` |
+| `-override_postpair` / `-opp` | `--override-postpair` / `-opp` |
+| `-override_ctd` / `-oc` | `--override-ctd` / `-oc` |
+| `-ignore_inference_compatibility` / `-iic` | `--ignore-inference-compatibility` / `-iic` |
+| `-ignore_bids_filter` / `-ibf` | `--ignore-bids-filter` / `-ibf` |
+| `-ignore_model_compatibility` / `-imc` | `--ignore-model-compatibility` / `-imc` |
+| `-run_cprofiler` / `-rcp` | `--run-cprofiler` / `-rcp` |
+| `-cpu` | `--cpu` |
+| `-verbose` / `-v` | `--verbose` / `-v` |
+| *(new)* | `--batch-size` / `-bs` — vertebra cutouts per batched forward pass (faster; default 4) |
+| *(new)* | `--amp` — run the instance forward pass under CUDA autocast (faster, may slightly change the output) |
+| *(new)* | `--step-size` — semantic model sliding-window tile step size (larger = faster, less accurate) |
+| *(new)* | `--tta` / `--no-tta` — force test-time augmentation (mirroring) on/off for the semantic model |
+
+Example:
+
+```bash
+# 1.x
+spineps sample -i scan.nii.gz -model_semantic t2w -model_instance instance -nocrop -non4
+
+# 2.0
+spineps sample -i scan.nii.gz --model-semantic t2w --model-instance instance --no-crop --no-n4
+```
+
+## Python API
+
+| Old | New |
+| --- | --- |
+| `process_img_nii(...)` | `segment_image(...)` |
+| `Segmentation_Model` | `SegmentationModel` |
+| `Segmentation_Model_NNunet` | `SegmentationModelNNunet` |
+| `Segmentation_Model_Unet3D` | `SegmentationModelUnet3D` |
+
+`process_dataset`, `get_semantic_model`, `get_instance_model`, `get_labeling_model`, `predict_semantic_mask`,
+`predict_instance_mask` and the other phase functions keep their names.
+
+## New in 2.0
+
+- **`spineps.segment(...)`**, **`SpinepsPipeline`**, **`SpinepsResult`** — the high-level API shown above.
+- **Config objects** `SemanticConfig`, `InstanceConfig`, `LabelingConfig`, `PostConfig` group the many `proc_*`
+  flags. Pass them to `segment(...)`, e.g. `spineps.segment(path, instance=InstanceConfig(batch_size=8))`.
+- **`--batch-size`** / `InstanceConfig.batch_size` — the instance model now runs cutouts in batched forward passes
+  (much faster on GPU); falls back to one-by-one on out-of-memory.
+- **More speed knobs**: `--amp` / `InstanceConfig.amp` (instance autocast), `--step-size` / `SemanticConfig.step_size`
+  (semantic sliding-window step), and `--tta` / `--no-tta` (toggle test-time mirroring; `SegmentationModel.set_test_time_augmentation(...)` in Python).
+- Clearer errors: invalid paths / missing models now raise `FileNotFoundError` / `ValueError` instead of bare
+  `AssertionError`, and `spineps sample -h` / `dataset -h` no longer crash.