diff --git a/README.md b/README.md index 1bdc0e6..407af11 100644 --- a/README.md +++ b/README.md @@ -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 diff --git a/config.yaml b/config.yaml index 2c7453f..c2ed06d 100644 --- a/config.yaml +++ b/config.yaml @@ -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 diff --git a/docs/VERTEBRAE_ASFAND.md b/docs/VERTEBRAE_ASFAND.md new file mode 100644 index 0000000..334f0e1 --- /dev/null +++ b/docs/VERTEBRAE_ASFAND.md @@ -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. diff --git a/main.py b/main.py index 52d92bb..f4df3e6 100644 --- a/main.py +++ b/main.py @@ -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 @@ -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, @@ -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( @@ -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') diff --git a/tests/test_vertebrae_asfand.py b/tests/test_vertebrae_asfand.py new file mode 100644 index 0000000..44f8de1 --- /dev/null +++ b/tests/test_vertebrae_asfand.py @@ -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 diff --git a/utils/vertebrae_asfand.py b/utils/vertebrae_asfand.py new file mode 100644 index 0000000..fd99d6f --- /dev/null +++ b/utils/vertebrae_asfand.py @@ -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 diff --git a/utils/vertebrae_asfand_engine.py b/utils/vertebrae_asfand_engine.py new file mode 100644 index 0000000..c55ae85 --- /dev/null +++ b/utils/vertebrae_asfand_engine.py @@ -0,0 +1,319 @@ +"""ShapeKit-Asfand vertebrae engine: level counting from L5 with drift repair. + +Mask-only (no CT), CPU-only. Operates on a combined label array with engine +ids 1 = L5 ... 24 = C1 (SuPreM convention) and the superior-inferior axis LAST. + +Error this engine targets +------------------------- +Label drift: the model spreads N labels over N + 1 vertebral bodies (or the +reverse), so a run of bodies carries two labels each and every level in the +run is shifted by one. Example from AbdomenAtlas BDMAP_00000031: 12 thoracic +labels on 13 bodies; the L1 body was labelled T12 while its posterior +elements were labelled L1. + +Method +------ +1. Fragment removal: whole-spine components smaller than min_frag_ml. +2. Body centre line: per axial slice, the centroid of the deepest part of the + mask (distance transform). The vertebral body is the thickest bone; the + centroid of the whole slice is avoided because body + pedicles + lamina + form a ring whose centre lies in the spinal canal. Median-filtered and + smoothed along the axis. +3. Discs: the model leaves intervertebral discs unlabelled, so along the + centre line the unlabelled fraction in a small disk peaks at each disc. + Peaks split the column into one segment per vertebral body. +4. Counting: from the lowest body upward, each body gets the level it must + have (anchor = the model's label of the lowest body). A body is trusted + when the model's majority label equals the counted level with share >= + trust_frac. Climbing stops after sync_run trusted bodies following a + mismatch, or when a segment is implausibly long (disc detection no longer + reliable). Nothing above that point is touched. +5. Relabel: bodies in the drifted range are seeded with their counted level + and grown through the bone only (geodesic), so posterior elements follow + their own body via the pedicles. Only voxels whose model label lies in the + drifted range are rewritten. +6. Detached pieces: every label keeps its largest piece; other pieces of that + label (<= orphan_max_ml) join the vertebra they touch most. + +Related work: ShapeKit (Liu et al.) and Meng et al. (2022) for mask-based +vertebra post-processing; this engine adds disc-based level counting. +""" + +from dataclasses import dataclass + +import cc3d +import numpy as np +from scipy import ndimage +from scipy.signal import find_peaks + +LEVELS = [f"C{i}" for i in range(1, 8)] + [f"T{i}" for i in range(1, 13)] + [f"L{i}" for i in range(1, 6)] +VAL = {name: 24 - i for i, name in enumerate(LEVELS)} # engine ids: C1=24 ... L5=1 +NAMES_BOTTOM_UP = [LEVELS[24 - v] for v in range(1, 25)] # L5, L4, ..., C1 + + +@dataclass +class Config: + min_frag_ml: float = 2.0 # delete floating pieces smaller than this + smooth_mm: float = 8.0 # smoothing of the body centre line + radius_mm: float = 6.0 # disk radius around the centre line for the gap profile + gap_height: float = 0.5 # min unlabelled fraction that marks a disc + min_level_mm: float = 8.0 # minimum distance between discs + trust_frac: float = 0.9 # body trusted if model majority share >= this + sync_run: int = 3 # trusted bodies in a row that end the drifted range + max_len_ratio: float = 1.7 # stop climbing if a segment is this x longer than the previous + seed_mm: float = 12.0 # radius of the body column used as seeds + disc_gap_mm: float = 1.5 # slab at each disc excluded from seeds + max_iter: int = 400 # max geodesic growth steps + orphan_max_ml: float = 10.0 # max size of a detached piece that is moved + margin: int = 5 # crop margin in voxels + + +def lvl_name(v): + return LEVELS[24 - int(v)] if 1 <= v <= 24 else "-" + + +def remove_fragments(comb, vox_ml, min_ml): + union = comb > 0 + cc = cc3d.connected_components(union, connectivity=26) + counts = np.bincount(cc.ravel()) + keep = counts * vox_ml >= min_ml + keep[0] = False + n_rm = int((~keep[1:]).sum()) + ml_rm = float(counts[1:][~keep[1:]].sum() * vox_ml) + union = keep[cc] + del cc + return np.where(union, comb, 0).astype(np.uint8), union, n_rm, ml_rm + + +def body_centerline(u, spacing, smooth_mm): + Z = u.shape[2] + cx = np.full(Z, np.nan) + cy = np.full(Z, np.nan) + for z in range(Z): + sl = u[:, :, z] + if not sl.any(): + continue + d = ndimage.distance_transform_edt(sl, sampling=spacing[:2]) + deep = d >= 0.8 * d.max() + lab, n = ndimage.label(deep) + if n > 1: + best = int(np.argmax(ndimage.maximum(d, lab, index=np.arange(1, n + 1)))) + 1 + deep = lab == best + cx[z], cy[z] = np.argwhere(deep).mean(0) + ok = ~np.isnan(cx) + zz = np.arange(Z) + w = max(1, int(round(10.0 / spacing[2]))) + + def robust(x): + x = x.copy() + x[~ok] = np.interp(zz[~ok], zz[ok], x[ok]) + x = ndimage.median_filter(x, size=2 * w + 1, mode="nearest") + return ndimage.gaussian_filter1d(x, smooth_mm / spacing[2]) + + return robust(cx), robust(cy), ok + + +def geodesic_grow(seeds, region, max_iter): + lab = seeds.copy() + free = region & (lab == 0) + fp = np.ones((3, 3, 3), bool) + for _ in range(max_iter): + if not free.any(): + break + grown = ndimage.grey_dilation(lab, footprint=fp) + new = free & (grown > 0) + if not new.any(): + break + lab[new] = grown[new] + free &= ~new + return lab, free + + +def contact_counts(cc): + """Face-contact counts between different components: dict (a, b) -> count, both directions.""" + out = {} + for ax in range(3): + a = np.moveaxis(cc, ax, 0) + x, y = a[:-1], a[1:] + m = (x != y) & (x > 0) & (y > 0) + if not m.any(): + continue + keys = x[m].astype(np.int64) * (1 << 32) + y[m].astype(np.int64) + u, n = np.unique(keys, return_counts=True) + for k, cnt in zip(u, n): + p, q = int(k >> 32), int(k & 0xFFFFFFFF) + out[(p, q)] = out.get((p, q), 0) + int(cnt) + out[(q, p)] = out.get((q, p), 0) + int(cnt) + return out + + +def reassign_orphans(lab, vox_ml, max_ml): + """Every label keeps its largest piece; any other piece (<= max_ml) goes to the label it touches most.""" + cc = cc3d.connected_components(lab, connectivity=26) + n = int(cc.max()) + 1 + size = np.bincount(cc.ravel(), minlength=n) + owner = np.zeros(n, np.int64) + owner[cc.ravel()] = lab.ravel() + largest = {} + for i in range(1, n): + v = owner[i] + if v not in largest or size[i] > size[largest[v]]: + largest[v] = i + orphans = [i for i in range(1, n) if largest[owner[i]] != i and size[i] * vox_ml <= max_ml] + if not orphans: + return lab, 0, 0.0 + cont = contact_counts(cc) + lut = owner.copy() + moved_ml = 0.0 + for i in orphans: + score = {} + for (p, q), k in cont.items(): + if p == i and owner[q] != owner[i]: + score[owner[q]] = score.get(owner[q], 0) + k + if score: + lut[i] = max(score, key=score.get) + moved_ml += size[i] * vox_ml + return lut[cc].astype(np.uint8), len(orphans), moved_ml + + +def refine(comb, spacing, superior_up=True, cfg=None, log=print): + """Refine a combined vertebra label array. + + comb: uint8 array, engine ids 1 (L5) ... 24 (C1), 0 background; the + superior-inferior axis must be the LAST axis. + spacing: voxel size in mm, same axis order as comb. + superior_up: True if a higher index on the last axis is more superior. + Returns (refined uint8 array of the same shape, report dict). + """ + cfg = cfg or Config() + spacing = tuple(float(s) for s in spacing) + vox_ml = float(np.prod(spacing)) / 1000.0 + comb = np.asarray(comb).astype(np.uint8) + report = dict(fragments_removed=0, fragments_ml=0.0, discs=0, bodies=[], + relabelled_bodies=0, rewritten_voxels=0, orphans_moved=0, orphans_ml=0.0) + + # 1. fragments + comb, union, n_rm, ml_rm = remove_fragments(comb, vox_ml, cfg.min_frag_ml) + report.update(fragments_removed=n_rm, fragments_ml=round(ml_rm, 3)) + log(f"[1] removed {n_rm} floating fragments ({ml_rm:.2f} mL)") + out = comb.copy() + if not union.any(): + return out, report + + idx = [np.where(union.any(axis=tuple(a for a in range(3) if a != ax)))[0] for ax in range(3)] + m = cfg.margin + crop = tuple(slice(max(int(a[0]) - m, 0), min(int(a[-1]) + 1 + m, dim)) for a, dim in zip(idx, comb.shape)) + c = comb[crop].copy() + u = union[crop] + Z = c.shape[2] + zz = np.arange(Z) + + # 2. centre line + cx, cy, ok = body_centerline(u, spacing, cfg.smooth_mm) + xx, yy = np.meshgrid(np.arange(c.shape[0]) * spacing[0], np.arange(c.shape[1]) * spacing[1], indexing="ij") + + def disk(z, r): + return (xx - cx[z] * spacing[0]) ** 2 + (yy - cy[z] * spacing[1]) ** 2 <= r * r + + # 3. discs from unlabelled gaps along the centre line + gap = np.zeros(Z) + lab_c = np.zeros(Z, int) + for z in zz[ok]: + dk = disk(z, cfg.radius_mm) + gap[z] = 1.0 - (c[:, :, z][dk] > 0).mean() + lab_c[z] = c[int(round(cx[z])), int(round(cy[z])), z] + lz = np.where(lab_c > 0)[0] + info = [] + discs = np.array([], int) + if len(lz): + lo, hi = int(lz.min()), int(lz.max()) + pk, _ = find_peaks(gap[lo:hi + 1], height=cfg.gap_height, + distance=max(1, int(round(cfg.min_level_mm / spacing[2])))) + discs = np.sort(pk + lo) + bounds = np.r_[lo, discs, hi + 1] + segs = [(int(bounds[i]), int(bounds[i + 1])) for i in range(len(bounds) - 1)] + seg_bt = segs if superior_up else segs[::-1] # bottom -> top anatomically + for a, b in seg_bt: + v = lab_c[a:b] + v = v[v > 0] + if len(v) < 2: + continue + h = np.bincount(v, minlength=25) + maj = int(h.argmax()) + info.append(dict(z0=a, z1=b, maj=maj, share=h[maj] / len(v), h=h, len_mm=(b - a) * spacing[2])) + report["discs"] = int(len(discs)) + log(f"[2-3] {len(discs)} discs from mask gaps along the body centre line") + + # 4. count from the bottom (anchor = model label of the lowest body) + if info: + anchor = info[0]["maj"] + mism_seen = False + run = 0 + plan = [] + prev_len = None + for i, s in enumerate(info): + exp = anchor + i # label value increases upwards (L5=1 ... C1=24) + if exp > 24: + break + if prev_len is not None and s["len_mm"] > cfg.max_len_ratio * prev_len: + log(f" stop: segment {s['len_mm']:.0f} mm is too long (disc detection unreliable above)") + break + trusted = s["maj"] == exp and s["share"] >= cfg.trust_frac + plan.append((s, exp, trusted)) + prev_len = s["len_mm"] + if not trusted: + mism_seen = True + run = 0 + else: + run += 1 + if mism_seen and run >= cfg.sync_run: + break + for s, exp, tr in plan: + top = [int(k) for k in np.argsort(-s["h"])[:2] if s["h"][k] > 0] + labels = {lvl_name(k): round(float(s["h"][k] / s["h"].sum()), 3) for k in top} + report["bodies"].append(dict(length_mm=round(float(s["len_mm"]), 1), model=labels, + counted=lvl_name(exp), status="ok" if tr else "relabel")) + log(f" body {s['len_mm']:5.0f} mm model {labels} counted {lvl_name(exp)} " + f"{'ok' if tr else 'RELABEL'}") + + bad_idx = [i for i, (s, exp, tr) in enumerate(plan) if not tr] + if bad_idx: + # 5. relabel the drifted range through the bone; labels that may be + # rewritten: everything seen in the drifted range, widened by one + # trusted body on each side + i0, i1 = max(bad_idx[0] - 1, 0), min(bad_idx[-1] + 1, len(plan) - 1) + drift_labels = set() + for s, exp, tr in plan[i0:i1 + 1]: + drift_labels.add(exp) + drift_labels.update(int(k) for k in np.nonzero(s["h"])[0] if k > 0) + region = np.isin(c, sorted(drift_labels)) & u + seeds = np.zeros(c.shape, np.int32) + gapz = max(1, int(round(cfg.disc_gap_mm / spacing[2]))) + for s, exp, tr in plan: + for z in range(s["z0"] + gapz, s["z1"] - gapz): + if not ok[z]: + continue + col = disk(z, cfg.seed_mm) & u[:, :, z] + seeds[:, :, z][col] = exp + grown, left = geodesic_grow(seeds, region | (seeds > 0), cfg.max_iter) + new_c = c.copy() + assign = region & (grown > 0) + new_c[assign] = grown[assign] + changed = int((new_c != c).sum()) + report.update(relabelled_bodies=len(bad_idx), rewritten_voxels=changed) + log(f"[4-5] relabelled {len(bad_idx)} drifted bodies; rewritten {changed * vox_ml:.1f} mL") + out[crop] = new_c + else: + log("[4-5] counted levels agree with the model: no relabelling needed") + + # 6. detached pieces: each label keeps one piece; detached bits join the vertebra they touch most + cleaned, n_orph, ml_orph = reassign_orphans(out[crop], vox_ml, cfg.orphan_max_ml) + for _ in range(2): # a moved piece can itself become detached; repeat until stable + cleaned, n2, ml2 = reassign_orphans(cleaned, vox_ml, cfg.orphan_max_ml) + n_orph, ml_orph = n_orph + n2, ml_orph + ml2 + if n2 == 0: + break + out[crop] = cleaned + report.update(orphans_moved=int(n_orph), orphans_ml=round(float(ml_orph), 3)) + log(f"[6] {n_orph} detached pieces moved to the vertebra they touch most ({ml_orph:.1f} mL)") + return out, report