Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
11 changes: 11 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -113,6 +113,17 @@ change the default engine. See [installation, input validation and regression
instructions](docs/VERTEBRAE_HAO.md). Enable with `--vertebrae_engine shapekit_hao`
and `--vertebrae_only`; start with `--cpu_count 1` and a new output directory.

# Level-Counting Vertebrae Engine (ShapeKit-Asfand)

An optional, mask-only `shapekit_asfand` backend fixes label drift, where a
run of vertebral bodies carries labels shifted by one level (e.g. 12 thoracic
labels on 13 bodies). It finds the discs from unlabelled gaps along the
vertebral body centre line, counts bodies upward from L5, and relabels only
the range where the count and the model disagree, growing each body's label
through the bone into its posterior elements. No CT needed. See
[method, results and limitations](docs/VERTEBRAE_ASFAND.md). Enable with
`--vertebrae_engine shapekit_asfand`.

# Evidence-Gated Vertebrae Engine (ShapeKit-Pro)

The default vertebrae module works from the masks alone. ShapeKit can now
Expand Down
4 changes: 4 additions & 0 deletions config.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -98,6 +98,10 @@ if_save_combined_label: True
# See docs/VERTEBRAE_HAO.md for CLI overrides and regression tests.
# shapekit - default mask-based module (no CT needed)
# shapekit_songlin - VerSe-inspired iterative refinement loop (no CT needed)
# shapekit_asfand - mask-only level counting: finds discs from gaps along the
# vertebral body centre line, counts bodies up from L5 and relabels
# only a drifted range (e.g. 12 thoracic labels on 13 bodies).
# No CT needed. See docs/VERTEBRAE_ASFAND.md.
# shapekit_pro - evidence-gated repair against the case CT: recolors
# label errors inside the prediction envelope instead of
# deleting bone; every risky stage self-reverts unless it
Expand Down
65 changes: 65 additions & 0 deletions docs/VERTEBRAE_ASFAND.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,65 @@
# ShapeKit-Asfand vertebrae engine

`vertebrae_engine: shapekit_asfand` (or `--vertebrae_engine shapekit_asfand`)

A mask-only vertebrae engine that fixes **label drift**: runs of vertebral bodies where the model's labels are shifted by one level, so that single bodies carry two labels. No CT, no new dependencies, CPU only.

## The error it targets

In AbdomenAtlas `BDMAP_00000031` (SuPreM vertebrae model) the model put 12 thoracic labels on 13 vertebral bodies. Between T8 and L2, several bodies carried two labels and every level was shifted by one. For example, the L1 body was labelled T12 while its posterior elements were labelled L1. Mask-only cleanup that keeps the largest component per label cannot fix this, because each wrong label is a large, plausible component.

## Method

| Step | What it does | Why |
|---|---|---|
| 1. Fragments | Delete whole-spine components < `min_frag_ml` (2 mL) | Removes stray voxels, e.g. C1 labels in the pelvis |
| 2. Body centre line | Per axial slice, centroid of the deepest part of the mask (distance transform); median filtered and smoothed | The body is the thickest bone. The centroid of the whole slice lies in the spinal canal, because body, pedicles and lamina form a ring |
| 3. Discs | Unlabelled fraction in a 6 mm disk around the centre line; peaks are discs | The model leaves intervertebral discs unlabelled |
| 4. Counting | From the lowest body upward, each body gets the level it must have; a body is trusted if the model's majority label matches with ≥ 90 % share. Stops after 3 trusted bodies following a mismatch, or when a segment is implausibly long | Only the drifted range is changed; the rest of the spine keeps the model's labels |
| 5. Relabel | Seed each body in the drifted range with its counted level and grow through the mask only (geodesic) | Posterior elements reach their own body through the pedicles; straight-line distance would hand sloping spinous processes to the level below |
| 6. Detached pieces | Each label keeps its largest piece; other pieces (≤ 10 mL) join the vertebra they touch most | One connected component per vertebra |

All parameters live in `Config` in `utils/vertebrae_asfand_engine.py`.

## Results

AbdomenAtlas demo, SuPreM `swin_unetr_totalsegmentator_vertebrae.pth` predictions:

| Case | Model pieces | Refined pieces | Bodies relabelled |
|---|---|---|---|
| BDMAP_00000006 | 45 | 24 | 0 |
| BDMAP_00000031 | 122 | 24 | 5 (T8 to L2) |

Average DSC against the reference labels (evaluated by the BodyMaps team): **92.9 %** over the 24 vertebrae of both cases. The weakest band is T7 to L1 (86 to 89 %), which is the range this engine relabels: the level counting is right, but boundaries drawn by the regrowth are less precise than the model's original boundaries.

Runtime on 2 CPU cores: about 15 s for a 2.5 mm case and about 90 s for a 0.7 mm whole-spine case. Memory is dominated by ShapeKit holding the 24 masks (twice, input and output): budget about 10 GB per worker for a 0.7 mm whole-spine case and set `--cpu_count` accordingly.

The ShapeKit integration reproduces the standalone submission exactly: on both demo cases the refined labels are voxel-identical to the evaluated output.

## Usage

```bash
python main.py --input_folder /path/to/predictions --output_folder /path/to/out \
--vertebrae_engine shapekit_asfand --vertebrae_only
```

Vertebrae-only prediction folders have no `liver.nii.gz`; `main.py` then uses any mask in the case as the grid reference.

## Limitations

- **Anchor at the bottom.** Counting starts from the model's label of the lowest body. If that label is itself wrong, or the anatomy is transitional (L6, sacralized L5), the counted levels are shifted too.
- **Discs must be unlabelled.** If a model labels discs as bone, step 3 finds fewer discs; climbing stops at the first implausibly long segment and nothing above it is changed.
- **Boundary placement.** Geodesic growth assigns contested voxels to the higher level when two fronts arrive in the same step (`grey_dilation` takes the maximum). Posterior elements stacked directly over the level below can be pulled up one level.
- **Seed radius.** Seeds are a fixed 12 mm disk around the body centre; in small cervical bodies the disk can reach posterior elements.

## Tests

```bash
python -m pytest -q tests/test_vertebrae_asfand.py
```

Synthetic spines with unlabelled discs and connected posterior elements: clean spine unchanged, drifted bodies relabelled, fragment removal, arbitrary superior-inferior axis, fail-safe fallback.

## Credits

Builds on ShapeKit (Liu et al.) and the mask-based vertebra post-processing of Meng et al. (2022). Engine and adapter by Asfand Yar.
17 changes: 16 additions & 1 deletion main.py
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,7 @@
from utils.vertebrae_pro import postprocessing_vertebrae_pro
from utils.vertebrae_hao import process_case as process_hao_case
from utils.vertebrae_ct_refinement import process_case as process_ct_refinement_case
from utils.vertebrae_asfand import postprocessing_vertebrae_asfand
import logging
import yaml
import traceback
Expand Down Expand Up @@ -206,6 +207,13 @@ def process_organs(segmentation_dict: dict, reference_img, combined_seg: np.arra
ct_path,
logger=logger,
)
elif vertebrae_engine == 'shapekit_asfand':
segmentation_dict = postprocessing_vertebrae_asfand(
patient_id,
segmentation_dict,
reference_img,
logger=logger,
)
elif vertebrae_engine == 'shapekit_songlin':
segmentation_dict = postprocessing_vertebrae_songlin(
patient_id,
Expand Down Expand Up @@ -251,6 +259,13 @@ def main(input_path, input_folder_name, output_path=None):
# --------------------------------------------------------

seg_path = os.path.join(input_path, reference_file_name)
if not os.path.exists(seg_path):
# vertebrae-only predictions have no liver mask: use any mask in the case as the grid reference
seg_dir = os.path.join(input_path, subfolder_name)
candidates = sorted(f for f in os.listdir(seg_dir) if f.endswith('.nii.gz'))
if not candidates:
raise FileNotFoundError(f'No masks found in {seg_dir}')
seg_path = os.path.join(seg_dir, candidates[0])
img = nib.load(seg_path)

segmentation_dict = read_all_segmentations(
Expand Down Expand Up @@ -348,7 +363,7 @@ def run_in_parallel(sub_folders, input_folder, output_folder, max_workers=4, tqd
parser.add_argument('--cpu_count', type=int, default=cpu_count(), help='Number of CPU cores to use for parallel processing (default: system max)')
parser.add_argument('--continue_prediction', action="store_true", help='If continue from last processing record')
parser.add_argument('--tqdm_ncols', type=int, default=100, help='Width of tqdm progress bar in characters')
parser.add_argument('--vertebrae_engine', choices=['shapekit', 'shapekit_songlin', 'shapekit_pro', 'shapekit_hao', 'shapekit_ct_refinement'],
parser.add_argument('--vertebrae_engine', choices=['shapekit', 'shapekit_songlin', 'shapekit_pro', 'shapekit_hao', 'shapekit_ct_refinement', 'shapekit_asfand'],
help='Override config.yaml vertebrae engine for this run')
parser.add_argument('--vertebrae_only', action='store_true', help='Process vertebrae only')
parser.add_argument('--ct_root', help='Override external case CT root for this run')
Expand Down
106 changes: 106 additions & 0 deletions tests/test_vertebrae_asfand.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,106 @@
"""Small deterministic tests for the ShapeKit-Asfand vertebrae engine and adapter."""

import logging

import nibabel as nib
import numpy as np

from utils import vertebrae_asfand as adapter
from utils import vertebrae_asfand_engine as engine

LOGGER = logging.getLogger(__name__)
SPACING = (1.0, 1.0, 2.0)
N_BODIES = 12 # bottom-up: L5, L4, L3, L2, L1, T12, T11, T10, T9, T8, T7, T6
BODY, DISC = 8, 3 # slices per body / per unlabelled disc


def _body_mask(shape):
m = np.zeros(shape, bool)
m[8:42, 30:66, :] = True
return m


def _spine(drift=False):
"""Synthetic spine (superior axis last, superior = higher index).

Bodies are separated by unlabelled discs; posterior elements bridge each
disc, so the whole spine is one connected component, as in real masks.
With drift=True the model 'skips' T11: bodies L1, T12, T11 carry the label
one level too high (body only; their posterior elements keep the true label).
"""
z_total = N_BODIES * (BODY + DISC) + 6
truth = np.zeros((50, 80, z_total), np.uint8)
model = np.zeros_like(truth)
for i in range(N_BODIES):
level = i + 1 # engine id: L5 = 1
z0 = 3 + i * (BODY + DISC)
z1 = z0 + BODY
body = (slice(8, 42), slice(30, 66), slice(z0, z1)) # ~35 mm body, like thoracolumbar
post = (slice(22, 28), slice(8, 30), slice(max(z0 - DISC, 0), z1))
for arr in (truth, model):
arr[post] = level
arr[body] = level
if drift and i in (4, 5, 6): # L1, T12, T11 bodies shifted up by one
model[body] = level + 1
return truth, model


def test_clean_spine_is_unchanged():
truth, model = _spine(drift=False)
out, report = engine.refine(model, SPACING, log=lambda m: None)
assert report["relabelled_bodies"] == 0
assert np.array_equal(out, truth)


def test_drifted_bodies_are_relabelled():
truth, model = _spine(drift=True)
assert (model != truth).sum() > 0
out, report = engine.refine(model, SPACING, log=lambda m: None)
assert report["relabelled_bodies"] == 3
bodies = _body_mask(truth.shape) & (truth > 0)
assert np.array_equal(out[bodies], truth[bodies]) # every body gets its counted level
# posterior elements stacked directly over the level below are the known weak
# spot of the geodesic growth (see docs/VERTEBRAE_ASFAND.md, limitations)
assert np.mean(out[truth > 0] == truth[truth > 0]) > 0.95
for level in range(1, N_BODIES + 1): # every level is one connected piece
assert engine.cc3d.connected_components(out == level).max() == 1


def test_floating_fragment_is_removed():
truth, model = _spine(drift=False)
model[1:3, 1:3, 1:3] = 7 # tiny stray T11 voxels far from the spine
out, report = engine.refine(model, SPACING, log=lambda m: None)
assert report["fragments_removed"] == 1
assert not out[1:3, 1:3, 1:3].any()


def _segmentation_dict(combined):
return {name: (combined == i).astype(np.uint8) for i, name in enumerate(adapter.VERTEBRA_NAMES, 1)}


def test_adapter_handles_any_si_axis():
truth, model = _spine(drift=True)
# move the superior axis to the front and make it point down (I), as in some scanners
moved = np.flip(np.moveaxis(model, 2, 0), axis=0).copy()
affine = np.array([[0, 1.0, 0, 0], [0, 0, 1.0, 0], [-2.0, 0, 0, 0], [0, 0, 0, 1]]) # axcodes I, R, A
ref = nib.Nifti1Image(moved, affine)
assert nib.aff2axcodes(affine)[0] == "I"
out_dict = adapter.postprocessing_vertebrae_asfand("synthetic", _segmentation_dict(moved), ref, LOGGER)
combined = np.zeros_like(moved)
for i, name in enumerate(adapter.VERTEBRA_NAMES, 1):
combined[out_dict[name] > 0] = i
expected = np.flip(np.moveaxis(truth, 2, 0), axis=0)
bodies = np.flip(np.moveaxis(_body_mask(truth.shape), 2, 0), axis=0) & (expected > 0)
assert np.array_equal(combined[bodies], expected[bodies])


def test_adapter_failure_leaves_masks_unchanged():
truth, model = _spine(drift=True)
seg = _segmentation_dict(model)
seg_out = adapter.postprocessing_vertebrae_asfand("broken", seg, None, LOGGER) # no reference -> error path
assert seg_out is seg


def test_adapter_skips_cases_without_vertebrae():
seg = {"liver": np.ones((4, 4, 4), np.uint8)}
assert adapter.postprocessing_vertebrae_asfand("noverts", seg, None, LOGGER) is seg
61 changes: 61 additions & 0 deletions utils/vertebrae_asfand.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,61 @@
"""ShapeKit adapter for the ShapeKit-Asfand vertebrae engine (vertebrae_engine: shapekit_asfand).

Bridges ShapeKit's per-organ binary masks (class_map ids 26 = L5 ... 49 = C1)
and the engine's combined array (ids 1 = L5 ... 24 = C1, superior axis last).
Mask-only: no CT needed. On any internal error the case is logged and the
vertebra masks are returned unchanged, so batch runs never stall.
See docs/VERTEBRAE_ASFAND.md.
"""

import nibabel as nib
import numpy as np

from . import vertebrae_asfand_engine as engine

VERTEBRA_NAMES = [f"vertebrae_{n}" for n in engine.NAMES_BOTTOM_UP] # engine id i -> VERTEBRA_NAMES[i - 1]


def _si_axis(reference_img):
"""Index of the superior-inferior axis and whether a higher index is more superior."""
codes = nib.aff2axcodes(reference_img.affine)
for ax, code in enumerate(codes):
if code in ("S", "I"):
return ax, code == "S"
raise ValueError(f"No superior-inferior axis in orientation {''.join(codes)}")


def postprocessing_vertebrae_asfand(patient_id, segmentation_dict, reference_img, logger, cfg=None):
"""Takes: patient_id, ShapeKit segmentation dict (organ name -> binary array,
already reoriented to the reference axcodes), the reference image, logger.
Returns: a new segmentation dict with refined vertebra masks."""
present = [n for n in VERTEBRA_NAMES if n in segmentation_dict]
if not present:
logger.info(f"[ShapeKit-Asfand] {patient_id}: no vertebra masks, skipping")
return segmentation_dict
try:
shape = segmentation_dict[present[0]].shape
comb = np.zeros(shape, dtype=np.uint8)
for engine_id, name in enumerate(VERTEBRA_NAMES, 1):
mask = segmentation_dict.get(name)
if mask is not None:
comb[(mask > 0) & (comb == 0)] = engine_id

si, superior_up = _si_axis(reference_img)
zooms = [float(z) for z in reference_img.header.get_zooms()[:3]]
order = [a for a in range(3) if a != si] + [si]
spacing = [zooms[a] for a in order]

refined, report = engine.refine(
np.transpose(comb, order), spacing, superior_up=superior_up, cfg=cfg,
log=lambda msg: logger.info(f"[ShapeKit-Asfand] {patient_id}: {msg}"))
refined = np.transpose(refined, np.argsort(order))
except Exception as e: # noqa: BLE001 - batch runs must not stall
logger.warning(f"[ShapeKit-Asfand] {patient_id}: failed ({e}); vertebrae left unchanged")
return segmentation_dict

processed = segmentation_dict.copy()
for engine_id, name in enumerate(VERTEBRA_NAMES, 1):
processed[name] = (refined == engine_id).astype(np.uint8)
logger.info(f"[ShapeKit-Asfand] {patient_id}: done, {report['relabelled_bodies']} bodies relabelled, "
f"{report['fragments_removed']} fragments removed, {report['orphans_moved']} pieces reattached")
return processed
Loading