Skip to content

Add vertebrae anchor graph engine - #28

Open
NavinAnik wants to merge 5 commits into
BodyMaps:mainfrom
NavinAnik:add-vertebrae-anchor-graph-engine
Open

NavinAnik wants to merge 5 commits into
BodyMaps:mainfrom
NavinAnik:add-vertebrae-anchor-graph-engine

Conversation

@NavinAnik

Copy link
Copy Markdown

Summary

Adds shapekit_anchor_graph, an opt-in vertebrae engine based on my warm-up solution. It cleans the 24 vertebra masks using the anatomical order of the vertebrae and the contact between them. When the case CT is on the same grid, it also refines the bone surface. The default engine (shapekit_songlin) and all other engines are unchanged.
On 8 held-out VerSe'19 scans it was not clearly better than the raw SuPreM prediction. It gave the best whole-spine Dice of the 7 engines in the repo, but
it fixed no numbering errors. See Evaluation.
Not to be confused with #14 (shapekit_anchor), which is a separate engine.

How it works

The engine works on a crop around the spine and never resamples:

  1. Order check. Each label's main body must follow anatomical order, from L5 lowest to C1 highest. A body out of order is demoted to a fragment. 2. Contact-graph relabelling. A fragment touching the spine takes the label it shares the most surface with. An isolated fragment is kept only near the
    spine. 3. Split-bone merge. One bone split across two labels is merged into one label. The resulting gap is flagged, not renumbered.
  2. CT step (only with a matching CT). - Discs are detected from label area and endplate density.
    • A shifted run of labels enclosed by two agreeing blocks can be renumbered. Each repair is rejected unless every affected vertebra is one piece with a plausible volume.
    • Labelled fat or air reached from outside is trimmed, the missed cortical rim is added and bone-dense notches are filled. 5. Hole fill inside each vertebra.
      Every voxel change is logged in the report, and the engine asserts that no change goes unlogged.

Changes

new:      utils/vertebrae_anchor_graph_engine.py   the engine, unchanged from the warm-up script new:      utils/vertebrae_anchor_graph.py          ShapeKit adapter: mask dict <-> 1..24 label map, CT check, report
new:      tests/test_vertebrae_anchor_graph.py     15 tests new:      docs/VERTEBRAE_ANCHOR_GRAPH.md
modified: main.py          registers the engine, passes report_dir, saves all 24 vertebra masks modified: utils/utils.py   save_and_combine_segmentations gets write_empty=() (default keeps current behaviour)
modified: config.yaml      comments only; the default engine stays shapekit_songlin modified: README.md        short section linking to the docs
modified: requirements-vertebrae-hao.txt, requirements-vertebrae-ct_refinement.txt   add fastremap ```
Changes to shared code:
- **`process_organs`** gets an optional `report_dir=None`. In `main()`, `save_folder_path` is now computed before the `process_organs` call (same value), so the report can be written there.
- **`save_and_combine_segmentations`** gets `write_empty`, and masks named in it are saved even when empty.   - `main.py` copies the input case into the output folder before post-processing. Without this option, a vertebra the engine removed or merged would come back
from that copy.   - It is set only for this engine. A test checks that the default behaviour is unchanged.
- **Requirements:** `fastremap` and `cc3d` are already in `requirements.txt`. `fastremap` is added to the hao and ct_refinement requirement files because `main.py` imports every engine at start-up.
## Usage
```console
python main.py --vertebrae_engine shapekit_anchor_graph --vertebrae_only \
 --input_folder /data/predictions --ct_root /data/ct_root \
 --output_folder /data/anchor_graph_results --cpu_count 1

You can also set vertebrae_engine: shapekit_anchor_graph in config.yaml.

  • CT: optional. It is used only when it has the same shape and affine as the masks. A missing, unreadable or misaligned CT is logged and the case runs mask-only.
  • Output:
    • all 24 vertebra masks, empty ones included;
    • vertebrae_anchor_graph_report.json per case, with status, ct_used, per-label metrics before and after, every change with its location and reason,
      flags, runtime and the engine SHA256.
  • Failure: if the engine raises, the input vertebrae are kept, the report says engine_failed and the batch continues. main.py still logs "Successfully
    processed" for that case, so check status in the report.

Testing

  • python -m pytest tests -q: 73 passed, 15 of them new. No existing test was changed.
  • The new tests use synthetic volumes. They check behaviour, not accuracy:
    • CT handling: aligned, misaligned, unreadable, and 4D with a singleton axis;
    • the failure path;
    • a voxel-for-voxel match with the standalone engine;
    • fragment reassignment, split-vertebra merge and CT rim growth;
    • an idempotent second pass;
    • write_empty and the default saver behaviour;
    • an end-to-end main.py run.

Evaluation

All 7 vertebra engines in the repo were run on identical inputs with default settings: the 6 --vertebrae_engine options and
utils/postprocessing_vertebrae.py from #23. The raw SuPreM prediction is the control. The rules were fixed before any engine output existed.

Held-out ground truth: 8 VerSe'19 validation scans.

  • Selection: the first 8 by ID with at least 10 labelled vertebrae, including T12 and L1. This engine was not developed on them.
  • Raw predictions: SuPreM swin_unetr_totalsegmentator_vertebrae.pth.
  • Identification uses the VerSe definition: the centroid is within 20 mm of the true one and no other true centroid is closer.
  • "Clear" means the 95% bootstrap CI over scans excludes 0.
source identification rate mean Dice whole-spine Dice HD95 mm
raw (no engine) 0.900 0.8270 0.9205 6.51
shapekit_anchor_graph 0.900 0.8313 0.9260 5.91
shapekit 0.912 0.8325 0.9188 5.67
shapekit_songlin (default) 0.141 0.1297 0.9112 111.64
shapekit_pro 0.900 0.8153 0.9096 6.63
shapekit_hao 0.900 0.8266 0.9202 6.65
shapekit_ct_refinement refused all 8 (supports RAS/LAS only, as documented)
postprocessing_vertebrae.py (#23) 0.925 0.8465 0.9207 5.07
  • Against raw: mean Dice +0.0043 (CI −0.0100 to +0.0171; 5 better, 1 tie, 2 worse). Identification is unchanged on every scan. Not a clear difference.
  • Against the other engines:
  • Where it helps: on the 6 scans that raw numbered correctly, it raised Dice on 5 (mean +0.014). This subgroup was chosen after seeing the results.
  • Where it does not:
    • The CT was used on all 8 scans, but the renumbering step never applied a change. On sub-verse067 it flagged the wrong L2 but did not renumber it, because the run was not enclosed by two agreeing blocks.
    • Both mis-numbered scans stayed wrong and lost Dice (−0.033 and −0.018). The Add vertebrae postprocessing script to utils #23 script fixed one of them.
    • Of the 130 mL the engine adds, 56% lands on the correct vertebra, 8% on a neighbour and 31–35% outside the true vertebrae.
  • Stability: deterministic. A second pass on its own output changes at most 0.35 mL (0.06%).

Demo cases (in-sample: I developed the engine on them).

  • Synthetic errors: these are 5 error scenarios built from BDMAP_00000006.
    • It removed 100% of the injected specks, fragments and holes, the best of the 7.
    • It repaired none of the injected numbering errors (shift, split and merge).
  • Leakage: it leaks least into fat and air. On BDMAP_00000031, 0.01% of its labelled voxels are below 0 HU, against 0.27–0.38% for the others.
  • Numbering on BDMAP_00000031: it moves T8–T12 by one level, and 5 other engines do the same. Raw, shapekit and TotalSegmentator keep the original numbering. Which one is right needs a radiologist's count.

Limits of this evaluation:

  • With 8 scans, a real Dice difference of about ±0.01 can go undetected.
  • All 8 VerSe scans are sagittal (PIR) thoracolumbar CT, not the axial abdominal CT that ShapeKit targets.
    • This made ct_refinement untestable.
    • It probably explains songlin's result: it looks like an orientation assumption, but I have not verified that, and it may deserve a separate issue.
  • VerSe is assumed to be absent from the SuPreM checkpoint's training data. This has not been verified.

The full report (frozen protocol, per-scan results and scripts) is available on request.

Scale

CPU only, one case per worker.

  • Median 9 s per VerSe scan.
  • On BDMAP_00000031 through main.py --vertebrae_only --cpu_count 1: 358 s and a peak of 11.7 GB. The other engines peaked at 4.1–12.2 GB.

Measure memory on a few cases before raising --cpu_count.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant