sc-crop 0.6.0__tar.gz

sc_crop-0.6.0/PKG-INFO

@@ -0,0 +1,14 @@
+Metadata-Version: 2.4
+Name: sc-crop
+Version: 0.6.0
+Summary: Spinal cord detection and volume cropping
+Requires-Python: >=3.8
+Requires-Dist: nibabel>=5.0.0
+Requires-Dist: numpy>=1.24.0
+Requires-Dist: onnxruntime>=1.18.0
+Requires-Dist: pillow>=10.0.0
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: scipy>=1.10.0
+Requires-Dist: ultralytics>=8.0.0
+Provides-Extra: segment
+Requires-Dist: nnunet-onnx; extra == "segment"

sc_crop-0.6.0/README.md

@@ -0,0 +1,358 @@
+# sc-crop — Spinal cord detection and cropping
+
+<img width="1635" height="977" alt="image" src="https://github.com/user-attachments/assets/882bb621-685d-4efa-bc45-f484cfe78ab0" />
+
+
+
+
+Segmentation models for spinal cord pathologies (tumors, lesions, SC itself) are typically trained and run on full volumes where the spinal cord occupies only a small fraction of the volume. **sc-crop** solves this by automatically detecting the spinal cord and cropping the volume tightly around it, so your segmentation model only ever sees the relevant region.
+
+This reduces memory usage, speeds up inference, and often improves model accuracy by removing irrelevant background. The recommended workflow is:
+
+1. **Preprocessing** — crop all training images and labels around the detected spinal cord, adding a fixed security margin
+2. **Training** — train your segmentation model on the cropped volumes
+3. **Inference** — apply the same sc-crop preprocessing to new images, run your model, then optionally restore the segmentation to the original space
+
+Works on both **MRI and CT**, across contrasts (T1, T2, MP2RAGE, DWI…), field strengths, and pathologies. Based on a YOLO26n model trained on multiple datasets covering cervical and lumbar spine. Available as a **CLI tool** and as an **importable Python package**.
+
+<img width="1713" height="727" alt="image" src="https://github.com/user-attachments/assets/d8958227-06b6-4430-9378-4a6f91e9741d" />
+
+---
+
+## Install
+
+Fresh dedicated environment (for testing):
+
+```bash
+conda create -n sc_crop python=3.13 && conda activate sc_crop
+pip install sc-crop
+```
+
+Or into an existing environment:
+
+```bash
+pip install sc-crop
+```
+
+*To pin in a `requirements.txt`: add `sc-crop>=0.6.0`*
+
+To install from source (latest development version):
+
+```bash
+pip install git+https://github.com/ivadomed/sc-crop.git
+```
+
+---
+
+## Command-line interface: detect and crop spinal cord volumes
+
+> The environment where sc-crop was installed must be active for the `sc_crop` command to be available.
+
+### Quick start — download the test data
+
+Image and label are available from the same release:
+
+```bash
+mkdir ~/sc-crop-test && cd ~/sc-crop-test
+curl -L https://github.com/ivadomed/sc-crop/releases/download/test-data/t2.nii.gz -o t2.nii.gz
+curl -L https://github.com/ivadomed/sc-crop/releases/download/test-data/t2_seg.nii.gz -o t2_seg.nii.gz
+```
+
+### Crop the image
+
+```bash
+sc_crop -i t2.nii.gz
+```
+
+Three files are written:
+
+| File | Content |
+|---|---|
+| `t2_crop.nii.gz` | Cropped image (affine origin updated) |
+| `t2_cropbox.nii.gz` | Binary mask of the bounding box used (FSLeyes overlay) |
+| `t2_bbox.txt` | Bounding box coordinates in voxel space (human-readable) |
+
+The command also prints a ready-to-use FSLeyes command to visualise the crop and its bounding box:
+
+```bash
+fsleyes t2.nii.gz t2_crop.nii.gz t2_cropbox.nii.gz -ot mask -mc 1 0 0 --outline -w 3 &
+```
+
+<table><tr>
+<td><img width="560" alt="FSLeyes bounding box overlay" src="https://github.com/user-attachments/assets/510fff6e-5436-47d1-89b3-ebe549e38449" /></td>
+<td><img width="200" alt="FSLeyes overlay panel" src="https://github.com/user-attachments/assets/4d83d93d-efc5-4695-97f3-0535aec30fce" /></td>
+</tr></table>
+
+
+
+### Crop a label with the same bounding box
+
+Use the `t2_cropbox.nii.gz` (or `t2_bbox.txt`) produced above to crop any other volume — label, atlas, or additional contrast — with the exact same boundaries:
+
+```bash
+sc_crop -i t2_seg.nii.gz --bbox t2_cropbox.nii.gz -o t2_seg_crop.nii.gz
+```
+
+### Adjust the bounding box margin
+
+```bash
+sc_crop -i t2.nii.gz --pad-sup 50 --pad-inf 80 --pad-left 10 --pad-right 10 --pad-ant 15 --pad-post 15
+```
+
+```bash
+sc_crop -i t2.nii.gz --pad-si 30 --pad-rl 10 --pad-ap 15
+```
+
+Priority: individual (e.g. `--pad-sup`) > symmetric (e.g. `--pad-si`) > default.
+
+Use `--detect` to run detection only (outputs cropbox + bbox.txt, skips the crop step).
+
+Run `sc_crop --help` for all options.
+
+---
+
+## Python API
+
+Three functions cover all use cases:
+
+| Function | Description |
+|---|---|
+| `detect(img_path)` | Runs the SC detector and returns the bounding box coordinates |
+| `crop(img, bbox)` | Crops any NIfTI volume (image or label) to the bounding box |
+| `uncrop(seg, bbox)` | Restores a segmentation from the cropped space back to the original full image space |
+| `check_label_crop(label, bbox)` | Checks the crop preserves every label voxel; reports the extra padding (mm) needed per face if not |
+| `CropReport` | Accumulates per-volume `check_label_crop` results and writes a CSV report + JSON summary |
+
+```python
+from sc_crop import detect, crop, uncrop
+import nibabel as nib
+
+img  = nib.load("t2.nii.gz")
+bbox = detect(img)                              # detect the spinal cord, return bounding box
+```
+
+```python
+from sc_crop import crop
+import nibabel as nib
+
+crop_img = crop(nib.load("t2.nii.gz"), bbox)   # also works on t2_seg.nii.gz
+```
+
+```python
+from sc_crop import uncrop
+
+full_img = uncrop(crop_img, bbox)               # restore to the original space
+```
+
+### Bounding box padding
+
+The margin around the detected spinal cord is adjustable per face (in mm).
+
+```python
+# Adjust SI only (most common)
+bbox = detect(img, pad_superior=50, pad_inferior=80)
+
+# All 3 symmetric
+bbox = detect(img, pad_si=30, pad_rl=10, pad_ap=15)
+
+# Symmetric + override one face
+bbox = detect(img, pad_si=30, pad_inferior=60)
+
+# Full per-face control
+bbox = detect(img, pad_superior=40, pad_inferior=100,
+                   pad_left=15,     pad_right=15,
+                   pad_anterior=15, pad_posterior=22)
+```
+
+Padding is always clamped to the image boundaries. Priority per face: **individual > symmetric > default** (sup=40, inf=100, left=right=15, ant=15, post=22).
+
+---
+
+## Use in a training + inference pipeline
+
+### ⚠️ Critical: use the same padding at training and inference
+
+sc-crop must be applied with **identical padding around the detected spinal cord** at both training and inference time. Different padding changes the crop boundaries and the distribution of what the model sees, which degrades performance. Pick your padding values once and keep them fixed throughout.
+
+### Step 1 — Preprocess training data
+
+Crop all images and their labels with the same padding. Use `check_label_crop`
+and `CropReport` to verify no label voxel is cut by the crop — any loss means the
+detected box (plus padding) does not fully contain the cord, which would silently
+remove ground-truth voxels from training:
+
+```python
+from sc_crop import detect, crop, check_label_crop, CropReport
+import nibabel as nib
+
+# Use the same padding for every subject
+PAD = dict(pad_superior=40, pad_inferior=100, pad_left=15, pad_right=15,
+           pad_anterior=15, pad_posterior=22)
+
+report = CropReport()                       # accumulates per-volume QC
+
+for subject in subjects:
+    bbox       = detect(subject.image, **PAD)
+    label_nii  = nib.load(subject.label)
+
+    qc = check_label_crop(label_nii, bbox)  # check BEFORE cropping
+    report.add(subject.label, qc)           # qc["ok"], voxels_before/after,
+                                            # extra_pad_<face>_mm if a face is short
+
+    crop_img   = crop(nib.load(subject.image), bbox)
+    crop_label = crop(label_nii, bbox)
+    nib.save(crop_img,   subject.image_crop)
+    nib.save(crop_label, subject.label_crop)
+
+report.save("crop_qc_report.csv")           # one row per volume
+report.save_summary("crop_qc_summary.json") # totals + max extra padding needed per face
+print(f"{report.n_failed()} / {len(report)} crops lost label voxels")
+```
+
+If `report.n_failed() > 0`, inspect `crop_qc_summary.json`: its `max_extra_padding_mm`
+field tells you how many mm to add on each face (e.g. raise `pad_posterior`) so every
+cord is fully contained. The defaults above were tuned this way.
+
+### Step 2 — Train your model on the cropped volumes
+
+Train normally on `*_crop.nii.gz` images and labels.
+
+### Step 3 — Inference on a new image
+
+Apply the **same padding**, run your model on the crop, then restore the segmentation to the original space:
+
+```python
+from sc_crop import detect, crop, uncrop
+import nibabel as nib
+
+PAD = dict(pad_superior=40, pad_inferior=100, pad_left=15, pad_right=15,
+           pad_anterior=15, pad_posterior=22)  # identical to training
+
+bbox      = detect("new_subject.nii.gz", **PAD)
+crop_img = crop(nib.load("new_subject.nii.gz"), bbox)
+
+seg_crop = my_model(crop_img)                  # run your segmentation model
+seg_full = uncrop(seg_crop, bbox) # back to original space + affine
+nib.save(seg_full, "new_subject_seg.nii.gz")
+```
+
+### nnUNet integration
+
+sc-crop is applied **before** nnUNet's own preprocessing. The cropped images go directly into the nnUNet raw dataset folder; nnUNet never sees the original full volumes.
+
+**Step 1 — Populate `nnUNet_raw/Dataset{ID}_{Name}/`**
+
+nnUNet expects images in `imagesTr/` named `{case}_{0000}.nii.gz` and labels in `labelsTr/` named `{case}.nii.gz`. Crop image and label with the same bbox before saving there:
+
+```python
+from sc_crop import detect, crop
+import nibabel as nib
+from pathlib import Path
+
+RAW = Path("nnUNet_raw/Dataset001_MyTask")
+PAD = dict(pad_superior=40, pad_inferior=100, pad_left=15, pad_right=15,
+           pad_anterior=15, pad_posterior=22)
+
+for case_id, img_path, lbl_path in subjects:
+    bbox = detect(img_path, **PAD)                                          # detect once
+    nib.save(crop(nib.load(img_path), bbox),
+             RAW / "imagesTr" / f"{case_id}_0000.nii.gz")                  # cropped image
+    nib.save(crop(nib.load(lbl_path), bbox),
+             RAW / "labelsTr" / f"{case_id}.nii.gz")                       # same bbox
+```
+
+**Step 2 — Run the standard nnUNet pipeline**
+
+```bash
+nnUNetv2_plan_and_preprocess -d 001 --verify_dataset_integrity
+nnUNetv2_train 001 3d_fullres 0
+```
+
+**Step 3 — Inference on a new image**
+
+The simplest approach uses the built-in `segment_onnx` / `segment_pt` functions (or their CLI equivalents) which handle detect → crop → infer → uncrop in one call. Install [nnunet-onnx](https://github.com/quentinRevillon/nnunet-onnx) for the inference backend:
+
+```bash
+pip install "nnunet-onnx @ git+https://github.com/quentinRevillon/nnunet-onnx.git" torch nnunetv2 onnxscript onnx
+```
+
+**Via CLI:**
+```bash
+# PyTorch checkpoint
+sc-segment-pt -i new_subject.nii.gz -o seg.nii.gz \
+    --checkpoint /path/to/fold_0/checkpoint_best.pth
+
+# ONNX model (no nnunetv2 needed at runtime)
+sc-segment-onnx -i new_subject.nii.gz -o seg.nii.gz \
+    --model /path/to/model.onnx
+```
+
+**Via Python API:**
+```python
+from sc_crop import segment_pt, segment_onnx
+import nibabel as nib
+
+seg = segment_pt("new_subject.nii.gz", "/path/to/fold_0/checkpoint_best.pth")
+seg = segment_onnx("new_subject.nii.gz", "/path/to/model.onnx")
+nib.save(seg, "seg.nii.gz")
+```
+
+To convert a checkpoint to ONNX (plans are embedded in the file — no external json needed):
+```bash
+python -m nnunet_onnx.export \
+    --checkpoint /path/to/fold_0/checkpoint_best.pth \
+    --output model.onnx
+```
+
+---
+
+## Examples
+
+The example scripts are part of the repository — clone it to run them:
+
+```bash
+git clone https://github.com/ivadomed/sc-crop.git
+cd sc-crop
+```
+
+**`examples/api_examples.py`** — Python API cookbook covering all usage patterns. If no image is provided, the SCT tutorial T2 is downloaded automatically:
+
+```bash
+python examples/api_examples.py                  # auto-download tutorial data
+python examples/api_examples.py t2.nii.gz        # use your own image
+python examples/api_examples.py t2.nii.gz --ex 3 # run example 3 only (padding)
+```
+
+| # | Pattern |
+|---|---------|
+| 1 | Basic `detect()` + `crop()` |
+| 2 | Multi-volume: detect once, crop image + label with the same bbox |
+| 3 | Padding variants: default / symmetric / mixed / full individual |
+| 4 | `detect_and_crop()` one-liner |
+| 5 | Fake segmentation model + `uncrop()` round-trip |
+| 6 | GPU inference (`device="cuda"`) |
+
+**`examples/infer_with_sc_crop.py`** — Full inference pipeline template with a built-in fake model (center-cylinder segmentation). If no input is provided, the SCT tutorial T2 is downloaded automatically:
+
+```bash
+python examples/infer_with_sc_crop.py                        # auto-download tutorial data
+python examples/infer_with_sc_crop.py -i t2.nii.gz -o seg.nii.gz
+```
+
+Replace `fake_sc_segmentation()` with your own model to use in production.
+
+---
+
+## Requirements
+
+Python ≥ 3.8. Dependencies installed automatically: `nibabel`, `numpy`, `onnxruntime`, `pillow`, `pyyaml`, `scipy`, `ultralytics` (includes `opencv`).
+
+Optional: `nnunet-onnx` for the `segment_onnx` / `segment_pt` functions — install with `pip install "sc-crop[segment]"`.
+
+---
+
+## Training the detector
+
+The detection model was trained using [ivadomed/model_cropping_sc_contrast-agnostic_yolo](https://github.com/ivadomed/model_cropping_sc_contrast-agnostic_yolo).
+The link between package versions, model versions, and training runs is documented in [VERSIONS.md](VERSIONS.md).
+To publish a new model version, see the release procedure in [VERSIONS.md](VERSIONS.md#procédure-de-release).

sc_crop-0.6.0/examples/api_examples.py

@@ -0,0 +1,229 @@
+"""
+sc-crop API examples — runnable cookbook.
+
+Shows all major usage patterns for the Python API, from the simplest
+to the most advanced. Each example is self-contained and can be run
+independently by calling it directly.
+
+If no image is provided, a T2 image and its SC segmentation are downloaded
+automatically (~5 MB) and cached in ~/.cache/sc_crop/tutorial/.
+
+Requirements:
+    pip install "sc-crop @ git+https://github.com/ivadomed/sc-crop.git"
+
+Usage:
+    python examples/api_examples.py                        # auto-download tutorial data
+    python examples/api_examples.py image.nii.gz           # use your own image
+    python examples/api_examples.py image.nii.gz --ex 3   # run example 3 only
+"""
+
+import argparse
+import urllib.request
+from pathlib import Path
+
+import nibabel as nib
+import numpy as np
+
+from sc_crop import detect, crop, detect_and_crop, uncrop
+
+_BASE_URL      = "https://github.com/ivadomed/sc-crop/releases/download/test-data"
+_TUTORIAL_CACHE = Path.home() / ".cache" / "sc_crop" / "tutorial"
+_TUTORIAL_IMG  = _TUTORIAL_CACHE / "t2.nii.gz"
+_TUTORIAL_SEG  = _TUTORIAL_CACHE / "t2_seg.nii.gz"
+
+
+def _get_tutorial_data() -> tuple[str, str]:
+    """Download and cache the tutorial T2 image and SC segmentation. Returns (img_path, seg_path)."""
+    _TUTORIAL_CACHE.mkdir(parents=True, exist_ok=True)
+    for fname in ("t2.nii.gz", "t2_seg.nii.gz"):
+        out = _TUTORIAL_CACHE / fname
+        if not out.exists():
+            url = f"{_BASE_URL}/{fname}"
+            print(f"Downloading {fname} → {out}")
+            urllib.request.urlretrieve(url, out)
+    return str(_TUTORIAL_IMG), str(_TUTORIAL_SEG)
+
+
+# ─── Example 1 — Basic: detect + crop ────────────────────────────────────────
+
+def example_basic(img_path: str, _seg_path: str) -> None:
+    """Detect the SC bbox, then crop the image."""
+    print("\n── Example 1: Basic detect + crop ──────────────────────────────")
+
+    bbox = detect(img_path)
+    print(f"  bbox: x[{bbox['xmin']}:{bbox['xmax']}]  "
+          f"y[{bbox['ymin']}:{bbox['ymax']}]  "
+          f"z[{bbox['zmin']}:{bbox['zmax']}]")
+    print(f"  orientation: {bbox['original_axcodes']}")
+
+    crop_img = crop(nib.load(img_path), bbox)
+    print(f"  original shape : {nib.load(img_path).shape}")
+    print(f"  cropped shape  : {crop_img.shape}")
+
+    out = Path(img_path).with_name(Path(img_path).stem.replace(".nii", "") + "_ex1_crop.nii.gz")
+    nib.save(crop_img, out)
+    print(f"  → {out}")
+
+
+# ─── Example 2 — Multi-volume: image + label with the same bbox ──────────────
+
+def example_multi_volume(img_path: str, seg_path: str) -> None:
+    """Detect once, crop both image and label — they share the same bbox."""
+    print("\n── Example 2: Multi-volume (image + label) ──────────────────────")
+
+    img   = nib.load(img_path)
+    label = nib.load(seg_path)
+
+    bbox        = detect(img_path)
+    crop_img   = crop(img,   bbox)
+    crop_label = crop(label, bbox)
+
+    assert crop_img.shape == crop_label.shape, "image and label must have the same cropped shape"
+    print(f"  cropped image shape : {crop_img.shape}")
+    print(f"  cropped label shape : {crop_label.shape}  (identical bbox ✓)")
+
+    stem   = Path(img_path).name.replace(".nii.gz", "").replace(".nii", "")
+    parent = Path(img_path).parent
+    nib.save(crop_img,   parent / f"{stem}_ex2_crop.nii.gz")
+    nib.save(crop_label, parent / f"{stem}_ex2_label_crop.nii.gz")
+    print(f"  → {parent / f'{stem}_ex2_crop.nii.gz'}")
+    print(f"  → {parent / f'{stem}_ex2_label_crop.nii.gz'}")
+
+
+# ─── Example 3 — Padding variants ────────────────────────────────────────────
+
+def example_padding(img_path: str, _seg_path: str) -> None:
+    """Show the 3 padding styles and how priority works."""
+    print("\n── Example 3: Padding variants ──────────────────────────────────")
+
+    # Defaults: superior=40, inferior=60, left=right=10, anterior=posterior=15
+    bbox_default = detect(img_path)
+
+    # Symmetric SI (common for focused cervical datasets)
+    bbox_si = detect(img_path, pad_si=30)
+
+    # Symmetric + override one face (highest priority)
+    bbox_mix = detect(img_path, pad_si=30, pad_inferior=60)
+
+    # Full individual control (all 6 faces)
+    bbox_full = detect(img_path,
+                      pad_superior=40, pad_inferior=60,
+                      pad_left=10,     pad_right=10,
+                      pad_anterior=15, pad_posterior=15)
+
+    def _z(bbox): return bbox["zmax"] - bbox["zmin"]
+    def _x(bbox): return bbox["xmax"] - bbox["xmin"]
+
+    print(f"  {'style':<30} {'z_range':>8}  {'x_range':>8}")
+    print(f"  {'─'*50}")
+    print(f"  {'default (sup=40, inf=60)':<30} {_z(bbox_default):>8}  {_x(bbox_default):>8}")
+    print(f"  {'pad_si=30 (symmetric)':<30} {_z(bbox_si):>8}  {_x(bbox_si):>8}")
+    print(f"  {'pad_si=30 + pad_inf=60':<30} {_z(bbox_mix):>8}  {_x(bbox_mix):>8}")
+    print(f"  {'full individual':<30} {_z(bbox_full):>8}  {_x(bbox_full):>8}")
+
+    assert _z(bbox_mix) >= _z(bbox_si), "pad_inferior=60 should give >= padding than pad_si=30"
+    print("  priority rule verified: individual > symmetric ✓")
+
+
+# ─── Example 4 — detect_and_crop convenience wrapper ─────────────────────────
+
+def example_detect_and_crop(img_path: str, _seg_path: str) -> None:
+    """Single-call convenience when only cropping one volume."""
+    print("\n── Example 4: detect_and_crop() one-liner ───────────────────────")
+
+    crop_nii, bbox = detect_and_crop(img_path)
+    print(f"  cropped shape : {crop_nii.shape}")
+    print(f"  bbox keys      : {[k for k in bbox if not k.startswith('_')]}")
+
+    out = Path(img_path).with_name(Path(img_path).stem.replace(".nii", "") + "_ex4_crop.nii.gz")
+    nib.save(crop_nii, out)
+    print(f"  → {out}")
+
+
+# ─── Example 5 — uncrop ────────────────────────────────────────
+
+def example_restore(img_path: str, seg_path: str) -> None:
+    """Crop the SC segmentation with the same bbox, restore it to the original space.
+
+    Uses the real SC segmentation (t2_seg.nii.gz) to demonstrate that
+    uncrop() correctly places it back at the right anatomical
+    location. Open the output in FSLeyes alongside the original to verify.
+    """
+    print("\n── Example 5: crop label + uncrop() ──────────────")
+
+    crop_nii, bbox = detect_and_crop(img_path)
+    crop_seg       = crop(nib.load(seg_path), bbox)
+
+    # Simulate a model output: use the cropped real segmentation as-is
+    seg_full   = uncrop(crop_seg, bbox)
+    orig_shape = nib.load(img_path).shape[:3]
+    assert seg_full.shape == orig_shape, f"expected {orig_shape}, got {seg_full.shape}"
+
+    n = int(np.asarray(seg_full.dataobj).sum())
+    print(f"  crop shape          : {crop_nii.shape}")
+    print(f"  restored seg shape  : {seg_full.shape}  ({n} non-zero voxels)")
+
+    out = Path(img_path).with_name(Path(img_path).stem.replace(".nii", "") + "_ex5_seg.nii.gz")
+    nib.save(seg_full, out)
+    print(f"  → {out}")
+    print(f"  verify: fsleyes {img_path} {out} -cm red")
+
+
+# ─── Example 6 — GPU inference ───────────────────────────────────────────────
+
+def example_gpu(img_path: str, _seg_path: str, device: str = "cuda") -> None:
+    """Run inference on GPU by passing device='cuda' (or 'mps' on Apple Silicon)."""
+    print("\n── Example 6: GPU inference ─────────────────────────────────────")
+    try:
+        bbox = detect(img_path, device=device)
+        print(f"  GPU ({device}) inference bbox: x[{bbox['xmin']}:{bbox['xmax']}]")
+    except Exception as exc:
+        print(f"  skipped — {exc}")
+
+
+# ─── Runner ───────────────────────────────────────────────────────────────────
+
+EXAMPLES = {
+    1: ("Basic detect + crop",                    example_basic),
+    2: ("Multi-volume: image + label",             example_multi_volume),
+    3: ("Padding variants",                        example_padding),
+    4: ("detect_and_crop() one-liner",             example_detect_and_crop),
+    5: ("crop label + uncrop()",     example_restore),
+    6: ("GPU inference (skip if no GPU)",           example_gpu),
+}
+
+
+def main():
+    p = argparse.ArgumentParser(
+        description="sc-crop API cookbook — runnable examples",
+        formatter_class=argparse.ArgumentDefaultsHelpFormatter,
+    )
+    p.add_argument("input", nargs="?", default=None,
+                   help="Input NIfTI volume (.nii or .nii.gz) — downloads tutorial T2 if omitted")
+    p.add_argument("--seg", default=None,
+                   help="SC segmentation label — downloads tutorial t2_seg.nii.gz if omitted")
+    g = p.add_mutually_exclusive_group()
+    g.add_argument("--all", action="store_true", help="Run all examples (default)")
+    g.add_argument("--ex",  type=int, choices=list(EXAMPLES), metavar="N",
+                   help=f"Run only example N ({', '.join(str(k) for k in EXAMPLES)})")
+    args = p.parse_args()
+
+    if args.input is None:
+        img_path, seg_path = _get_tutorial_data()
+    else:
+        img_path = args.input
+        seg_path = args.seg or str(Path(img_path).with_name(
+            Path(img_path).name.replace(".nii.gz", "").replace(".nii", "") + "_seg.nii.gz"
+        ))
+
+    print(f"\nsc-crop API examples — {img_path}")
+    for idx, (label, fn) in EXAMPLES.items():
+        if args.ex and args.ex != idx:
+            continue
+        fn(img_path, seg_path)
+
+    print("\n✅  Done.")
+
+
+if __name__ == "__main__":
+    main()

sc_crop-0.6.0/examples/demo.py

@@ -0,0 +1,89 @@
+"""
+sc-crop demo — spinal cord detection and cropping.
+
+Detects the spinal cord bounding box, prints coordinates, and optionally saves
+the cropped volume. No segmentation model required — only the SC detector.
+detect() is pure and writes no files; cropping and saving are done here explicitly.
+
+Usage:
+    python examples/demo.py t2.nii.gz
+    python examples/demo.py t2.nii.gz --crop
+    python examples/demo.py t2.nii.gz --crop --pad-sup 50 --pad-inf 80
+    python examples/demo.py t2.nii.gz --crop --pad-si 30
+    python examples/demo.py t2.nii.gz --crop --time
+
+Requirements:
+    pip install git+https://github.com/ivadomed/sc-crop.git
+"""
+
+import argparse
+from pathlib import Path
+
+import nibabel as nib
+
+from sc_crop import detect, crop
+
+
+def main():
+    p = argparse.ArgumentParser(
+        description="sc-crop demo: detect SC bbox and optionally crop the volume.",
+        formatter_class=argparse.ArgumentDefaultsHelpFormatter,
+    )
+    p.add_argument("input",        help="Input NIfTI volume (.nii or .nii.gz)")
+    p.add_argument("--crop",       action="store_true", help="Save the cropped volume")
+    p.add_argument("--pad-sup",    type=float, default=None, dest="pad_superior",
+                   metavar="MM",   help="Superior padding mm (default 40)")
+    p.add_argument("--pad-inf",    type=float, default=None, dest="pad_inferior",
+                   metavar="MM",   help="Inferior padding mm (default 60)")
+    p.add_argument("--pad-si",     type=float, default=None, dest="pad_si",
+                   metavar="MM",   help="Symmetric SI")
+    p.add_argument("--pad-rl",     type=float, default=None, dest="pad_rl",
+                   metavar="MM",   help="Symmetric RL padding mm (default 10)")
+    p.add_argument("--pad-ap",     type=float, default=None, dest="pad_ap",
+                   metavar="MM",   help="Symmetric AP padding mm (default 15)")
+    p.add_argument("--time",       action="store_true", help="Print elapsed time per step")
+    args = p.parse_args()
+
+    print(f"\n{'─'*60}")
+    print(f"  sc-crop demo")
+    print(f"{'─'*60}")
+
+    bbox = detect(
+        args.input,
+        pad_superior=args.pad_superior,
+        pad_inferior=args.pad_inferior,
+        pad_si=args.pad_si,
+        pad_rl=args.pad_rl,
+        pad_ap=args.pad_ap,
+        time_steps=args.time,
+    )
+
+    print(f"\n{'─'*60}")
+    print(f"  Bounding box (inclusive voxel indices, native space)")
+    print(f"{'─'*60}")
+    print(f"  x  [{bbox['xmin']:4d} : {bbox['xmax']:4d}]  ({bbox['xmax'] - bbox['xmin'] + 1} voxels)")
+    print(f"  y  [{bbox['ymin']:4d} : {bbox['ymax']:4d}]  ({bbox['ymax'] - bbox['ymin'] + 1} voxels)")
+    print(f"  z  [{bbox['zmin']:4d} : {bbox['zmax']:4d}]  ({bbox['zmax'] - bbox['zmin'] + 1} voxels)")
+
+    if args.crop:
+        orig     = nib.load(args.input)
+        crop_nii = crop(orig, bbox)
+
+        inp      = Path(args.input)
+        stem     = inp.name.replace(".nii.gz", "").replace(".nii", "")
+        out_path = inp.parent / f"{stem}_crop.nii.gz"
+        nib.save(crop_nii, out_path)
+
+        orig_mm = [round(float(v), 2) for v in orig.header.get_zooms()[:3]]
+        print(f"\n{'─'*60}")
+        print(f"  Crop")
+        print(f"{'─'*60}")
+        print(f"  Original : {orig.shape}  {orig_mm} mm")
+        print(f"  Cropped  : {crop_nii.shape}")
+        print(f"  → {out_path}")
+
+    print()
+
+
+if __name__ == "__main__":
+    main()