Skip to content

Add opt-in shapekit_driftfix vertebrae engine (five-stage cleanup with review flags) - #30

Open
Rusheel86 wants to merge 8 commits into
BodyMaps:mainfrom
Rusheel86:add-driftfix-vertebrae-engine
Open

Rusheel86 wants to merge 8 commits into
BodyMaps:mainfrom
Rusheel86:add-driftfix-vertebrae-engine

Conversation

@Rusheel86

@Rusheel86 Rusheel86 commented Nov 16, 2026 •

Copy link
Copy Markdown

What

Adds an optional case engine, shapekit_driftfix, for the 24 vertebra masks (L5 ... C1).
It removes specks and far debris, decides what to do with detached fragments, repairs label drift at the
discs, restores a lost level when the CT supports it, and flags inverted or oversized level steps. Every
change and flag is in a JSON report.

Files: the algorithm as a vendored script (utils/vertebrae_driftfix_engine.py, unchanged from the
standalone version), a thin adapter (utils/vertebrae_driftfix.py), tests, docs/VERTEBRAE_DRIFTFIX.md,
a README section, a comment and one key in config.yaml, and three small edits in main.py (import,
choices, dispatch).

Why opt-in

It is selected only with --vertebrae_engine shapekit_driftfix --vertebrae_only. The default engine, other
engines and shared code are untouched. All five stages run by default, which is the configuration scored on held-out scans. Setting
vertebrae_driftfix_relabel: false skips the two stages that can change a vertebra's level; use it where
spines with an L6 or T13 are likely and nobody reviews the flags (see the L6 result below). The CT is optional; without it the
engine runs mask-only and the report says ct_used: false (this differs from hao and ct_refinement, which
raise an error).

Validation actually done

  • New tests: label round trip 26..49 <-> 1..24; adapter output equals the engine run directly, voxel for
    voxel, on a synthetic phantom and on the cropped demo case BDMAP_00000006 (relabel off and on); missing
    CT; existing output refused; grid mismatch, overlap and non-binary masks rejected. 15 tests pass.
  • Whole suite: 68 passed, 5 failed. The 5 failures are the known hao hash checks that fail on a Windows
    CRLF checkout, not related to this change.
  • Cropped BDMAP_00000006 through main.py: exit 0, 794 voxels changed, 1 review flag, about 28 s.
  • Benchmark on 70 held-out TotalSegmentator v3.0.0 scans with public masks, every engine through main.py on Kaggle
    CPU (table in docs/VERTEBRAE_DRIFTFIX.md): raw 0.8805 mean Dice; ct_refinement 0.8905 (+0.0100); this engine 0.8892
    (+0.0087, 95% interval +0.0017 to +0.0176), order violations 964 to 287, 59 scans better and 9 worse; hao 0.8809;
    default shapekit 0.8769; songlin 0.8460. ct_refinement is ahead on Dice and makes only 1 scan worse.
  • shapekit_pro crashed on 6 of the first 10 scans: IndexError at utils/vertebrae_pro_engine.py:815 (index equal to
    the array length when a band reaches the top of the cropped spine). Happy to send a separate small fix.
  • The engine output equals the standalone script voxel for voxel on all 70 scans.
  • Not done: BDMAP_00000031 (too large for the 8 GB laptop), peak-memory measurement.

Known limits

From the author's held-out test of 100 CTs with ground truth (frozen script, scored once):

  • 90 typical spines: Dice 0.880 -> 0.888, order violations 12.4 -> 3.9 per case.
  • 10 spines with L6 or T13: Dice 0.577 -> 0.506. The lost-level repair can wreck an L6 spine (one scan
    moved 14 vertebrae one level the wrong way).
  • Only 24 classes, so L6 and T13 cannot be written.
  • On the two demo cases there is no ground truth.

AI assistance

The design, the evaluation protocol and the benchmark are mine; much of the code, tests and docs were written with Claude Code under my direction and reviewed by me.

Copied byte-for-byte from the standalone script. A .gitattributes rule keeps
LF line endings so file hashes stay the same on Windows checkouts.
Reads the 24 per-level masks, validates them, runs the engine in memory,
writes 24 masks, a combined map with ids 26-49 and a JSON report.
Import, choices entry and dispatch only. Default engine is unchanged. Adds the
vertebrae_driftfix_relabel config key (default false).
Includes known limits and a placeholder for the benchmark table.
The held-out numbers in the docs describe the full pipeline, so the
default now matches them. vertebrae_driftfix_relabel: false keeps the
safer mask-preserving mode for data with L6/T13 spines.
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