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 @@ -154,6 +154,17 @@ size, emptiness; exactly 24 components), the collapsed L1 is restored from
23.3 to 62.9 cm3 at detected disc planes, and every spinous process is
re-attached to its own vertebra on the fused case.

# Anchor-Graph Vertebrae Engine (ShapeKit-AnchorGraph)

An optional `shapekit_anchor_graph` engine checks the anatomical order of each
vertebra's main body, relabels fragments by the surface they share with the
spine, merges bones split across two labels and fills holes. When the case CT
is on the same grid it also counts bones from the discs to renumber shifted
labels and refines the bone surface; otherwise it runs from the masks alone.
Every change and flag is written to a per-case JSON report. Enable with
`--vertebrae_engine shapekit_anchor_graph`; see
[docs/VERTEBRAE_ANCHOR_GRAPH.md](docs/VERTEBRAE_ANCHOR_GRAPH.md).

# Iterative Vertebrae Engine (ShapeKit-Iterative)

In addition to the default and Pro vertebrae engines, ShapeKit now offers a
Expand Down
5 changes: 5 additions & 0 deletions config.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -96,6 +96,11 @@ if_save_combined_label: True
# requires matching calibrated CT and target_organs [vertebrae].
# Fails on grid mismatch/missing CT; no legacy fallback.
# See docs/VERTEBRAE_HAO.md for CLI overrides and regression tests.
# shapekit_anchor_graph - order-checked anchors + contact-graph relabelling, split-bone
# merge, hole fill; uses the case CT (same grid) for disc-based
# renumbering and surface refinement when found, else mask-only.
# Writes vertebrae_anchor_graph_report.json per case.
# See docs/VERTEBRAE_ANCHOR_GRAPH.md.
# shapekit - default mask-based module (no CT needed)
# shapekit_songlin - VerSe-inspired iterative refinement loop (no CT needed)
# shapekit_pro - evidence-gated repair against the case CT: recolors
Expand Down
74 changes: 74 additions & 0 deletions docs/VERTEBRAE_ANCHOR_GRAPH.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,74 @@
# Anchor-graph vertebrae engine (`shapekit_anchor_graph`)

It is an optional vertebrae engine. It does not change the default (`shapekit_songlin`) and runs inside the normal
ShapeKit pipeline, so the other organs are still post-processed as usual.

`utils/vertebrae_anchor_graph_engine.py` is the standalone warm-up script, kept unchanged; its SHA256 is
written into every case report. `utils/vertebrae_anchor_graph.py` is the ShapeKit adapter.

## Method

All steps work in a superior-up view of a crop around the spine; nothing is resampled.

1. **Order check** – each label's main body must follow anatomical order (L5 lowest … C1 highest); a body out
of order is demoted to a fragment (a correctly placed piece of the same label replaces it when one exists).
2. **Contact-graph relabelling** – fragments touching the spine take the label they share the most surface with.
3. **Isolated fragments** – kept (as the nearest vertebra) only within `near_mm`, otherwise removed.
4. **Split-bone merge** – one bone split across two labels is merged into one label; nothing is renumbered,
the resulting gap is reported as a flag instead (at most `max_merges` per case).
5. **CT step (only with a CT)** – discs are detected from the label area and endplate density; a run of
shifted labels enclosed by two agreeing blocks is renumbered, and each repair is rejected unless every
affected vertebra is one piece with a plausible volume. Then labelled fat/air reached from outside is
trimmed, the missed cortical rim is added and bone-dense notches are filled.
6. **Hole fill** – enclosed holes inside each vertebra.

Every voxel change is logged in the report; the engine asserts that no change goes unlogged and that voxels
are only added by fill, notch and rim steps.

## Enable

```yaml
vertebrae_engine: shapekit_anchor_graph
ct_file_name: ct.nii.gz
```

or per run: `python main.py --vertebrae_engine shapekit_anchor_graph --input_folder ... --output_folder ...`.
Add `--vertebrae_only` to skip the other organs.

## Input

The usual ShapeKit layout, `CASE/segmentations/vertebrae_L5.nii.gz … vertebrae_C1.nii.gz`. The CT is **optional**: it is used only when it has the same shape and affine as the masks;
a missing or misaligned CT is logged and the case runs mask-only. Overlapping vertebra masks are resolved
in favour of the higher label.

## Output

- All 24 vertebra masks are written for every case, **including empty ones**, so a vertebra removed or merged
by the engine does not reappear from the input copy that `main.py` places in the output folder first.
- `CASE/vertebrae_anchor_graph_report.json`: `status` (`ok` / `engine_failed`), `ct_used`, per-label metrics
before/after, every change with location and reason, `flags` (missing labels, pitch/volume outliers,
truncation by the field of view, large reassignments, rejected CT repairs, …), runtime, engine SHA256.
- If the engine raises for a case, the error is logged, the input vertebrae are kept unchanged and the report
says `engine_failed`; the batch continues. Such a case is still listed as "Successfully processed" in
`postprocessing.log` (that line is written for every engine once `main()` returns), so check `status` in the
report or search the log for `engine failed`.
- A missing, unreadable or misaligned CT runs the case mask-only; a CT with a trailing singleton axis
`(x, y, z, 1)` is accepted.

## Validation

```sh
python -m unittest tests.test_vertebrae_anchor_graph -v
```

The tests use synthetic volumes. Integration: fragment removal, empty-label overwrite, saver regression,
no-vertebrae, misaligned, unreadable and 4D CT paths, engine failure, and voxel-for-voxel equality with the
standalone script. Engine steps: a touching wrong-label fragment is reassigned, a vertebra split across two labels
is merged and the gap flagged, a missed bone rim is grown from the CT, and a second pass changes nothing. They
check behaviour, not accuracy: no DSC against ground truth is claimed here.

## Scale

CPU only; one case per worker through `--cpu_count`. The engine works on the spine crop and reads only the
matching CT block, so memory is dominated by ShapeKit loading all organ masks of a case. Measure peak memory
on a few real cases before raising `--cpu_count`.
22 changes: 18 additions & 4 deletions 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_anchor_graph import postprocessing_vertebrae_anchor_graph, VERTEBRA_NAMES as ANCHOR_GRAPH_NAMES
import logging
import yaml
import traceback
Expand Down Expand Up @@ -113,6 +114,7 @@ def combine_segmentation_dict(segmentation_dict: dict, class_map: dict) -> np.nd

def process_organs(segmentation_dict: dict, reference_img, combined_seg: np.array, target_organs: set, patient_id: str, logger: logging.Logger,
ct_path: str = None,
report_dir: str | None = None,
):
"""
Apply organ-specific post-processing functions to the segmentation dict
Expand Down Expand Up @@ -206,6 +208,15 @@ def process_organs(segmentation_dict: dict, reference_img, combined_seg: np.arra
ct_path,
logger=logger,
)
elif vertebrae_engine == 'shapekit_anchor_graph':
segmentation_dict = postprocessing_vertebrae_anchor_graph(
patient_id,
segmentation_dict,
reference_img,
ct_path,
logger=logger,
report_dir=report_dir,
)
elif vertebrae_engine == 'shapekit_songlin':
segmentation_dict = postprocessing_vertebrae_songlin(
patient_id,
Expand Down Expand Up @@ -268,6 +279,7 @@ def main(input_path, input_folder_name, output_path=None):
if not os.path.exists(ct_path) and ct_root is not None:
ct_path = os.path.join(ct_root, input_folder_name, ct_file_name)

save_folder_path = os.path.join(output_path, input_folder_name)
postprocessed_segmentation_dict = process_organs(
segmentation_dict,
img,
Expand All @@ -276,17 +288,19 @@ def main(input_path, input_folder_name, output_path=None):
patient_id = patient_id,
logger = logging,
ct_path = ct_path,
report_dir = save_folder_path,
)

save_folder_path = os.path.join(output_path, input_folder_name)

os.makedirs(save_folder_path, exist_ok=True)

anchor_graph = vertebrae_engine == 'shapekit_anchor_graph' and 'vertebrae' in target_organs
save_and_combine_segmentations(
processed_segmentation_dict=postprocessed_segmentation_dict,
class_map=class_map,
reference_img=img,
output_folder=save_folder_path,
if_save_combined=save_combined_label_bool
if_save_combined=save_combined_label_bool,
write_empty=set(ANCHOR_GRAPH_NAMES.values()) if anchor_graph else (),
)

del img
Expand Down Expand Up @@ -348,7 +362,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_anchor_graph'],
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
1 change: 1 addition & 0 deletions requirements-vertebrae-ct_refinement.txt
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,7 @@ numpy==2.5.3
scipy==1.18.1
nibabel==5.4.2
connected-components-3d==4.1.0
fastremap==1.21.0
scikit-image==0.26.0
matplotlib==3.11.1
PyYAML==6.0.3
Expand Down
1 change: 1 addition & 0 deletions requirements-vertebrae-hao.txt
Original file line number Diff line number Diff line change
Expand Up @@ -5,6 +5,7 @@ scipy==1.15.3
nibabel==5.4.2
scikit-image==0.25.2
connected-components-3d
fastremap
tqdm
matplotlib
PyYAML
Loading