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
27 changes: 27 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -103,6 +103,33 @@ target_organs: (example)

Before running any commands, please ensure that `config.yaml` is properly configured. But don't worry! **Most of the configurations do not need to be changed at all.**
</details>
# Vertebrae Warm-up Post-processing

ShapeKit exposes the vertebrae warm-up workflow through the optional `shapekit_warmup` engine. Run these examples from the repository root. Replace the example paths with your own paths and use a fresh output directory.

**Components mode** removes disconnected fragments from the predicted C1 mask. Set --input_folder to the directory containing the case folders. Each case folder contains the predicted vertebra masks.

```bash
python main.py --input_folder /path/to/predictions \
--output_folder /path/to/components-results \
--vertebrae_engine shapekit_warmup --vertebrae_only \
--warmup-mode components --case BDMAP_00000006 --cpu_count 1
```

**Rooted mode** uses the original CT and a matching SuPreM probability cache to refine vertebra labels. The CT root contains `<case>/ct.nii.gz`, and the cache root contains `<case>.pt`. This mode reuses cached predictions.

```bash
python main.py --input_folder /path/to/predictions \
--output_folder /path/to/rooted-results \
--vertebrae_engine shapekit_warmup --vertebrae_only \
--warmup-mode rooted --case BDMAP_00000031 --cpu_count 1 \
--ct_root /path/to/ct-cases \
--warmup-cache-root /path/to/probability-caches \
--warmup-suprem-repo /path/to/SuPreM/direct_inference \
--warmup-python /path/to/suprem/python
```

Each run writes a combined label map, individual vertebra masks, and a JSON report. On the two example cases above, all 24 vertebra masks per case matched the original standalone workflow voxel for voxel. This comparison verified output consistency on those two cases.

# Native-Grid Two-Stage Vertebrae Engine (ShapeKit-Hao)

Expand Down
25 changes: 22 additions & 3 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_warmup import process_case as process_warmup_case
import logging
import yaml
import traceback
Expand Down Expand Up @@ -228,14 +229,24 @@ def main(input_path, input_folder_name, output_path=None):
input_path: the folder path
"""

if vertebrae_engine in ('shapekit_hao', 'shapekit_ct_refinement'):
if vertebrae_engine in ('shapekit_hao', 'shapekit_ct_refinement', 'shapekit_warmup'):
# Isolate the evaluated algorithm from legacy organ cleanup and IO.
# The strict adapter validates each mask/CT grid and writes zero masks.
if target_organs != {'vertebrae'}:
raise ValueError(f'{vertebrae_engine} requires --vertebrae_only')
ct_path = os.path.join(input_path, ct_file_name)
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)
if vertebrae_engine == 'shapekit_warmup':
rooted = None
if args.warmup_mode == 'rooted':
rooted = (
os.path.join(args.warmup_cache_root, input_folder_name + '.pt'),
ct_path, args.warmup_suprem_repo, args.warmup_python,
)
return process_warmup_case(
input_path, os.path.join(output_path, input_folder_name),
class_map, subfolder_name=subfolder_name, rooted=rooted)
processor = process_ct_refinement_case if vertebrae_engine == 'shapekit_ct_refinement' else process_hao_case
return processor(
input_path, os.path.join(output_path, input_folder_name),
Expand Down Expand Up @@ -348,14 +359,22 @@ 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_warmup'],
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')
parser.add_argument('--case', action='append', help='Process only this case folder (repeatable)')
parser.add_argument('--warmup-mode', choices=['components', 'rooted'], default='components',
help='Warm-up method to run with shapekit_warmup')
parser.add_argument('--warmup-cache-root', help='Directory of trusted per-case SuPreM probability caches')
parser.add_argument('--warmup-suprem-repo', help='Path to the SuPreM direct_inference directory')
parser.add_argument('--warmup-python', help='Python executable for the SuPreM environment')
args = parser.parse_args()
if args.vertebrae_engine is not None:
vertebrae_engine = args.vertebrae_engine
if (vertebrae_engine == 'shapekit_warmup' and args.warmup_mode == 'rooted'
and not (args.warmup_cache_root and args.warmup_suprem_repo)):
parser.error('Warm-up rooted mode requires --warmup-cache-root and --warmup-suprem-repo')
if args.vertebrae_only:
target_organs = {'vertebrae'}
if args.ct_root is not None:
Expand Down Expand Up @@ -397,7 +416,7 @@ def run_in_parallel(sub_folders, input_folder, output_folder, max_workers=4, tqd
parser.error('--input_folder and --output_folder are required')
if args.cpu_count < 1:
parser.error('--cpu_count must be at least 1')
if vertebrae_engine in ('shapekit_hao', 'shapekit_ct_refinement'):
if vertebrae_engine in ('shapekit_hao', 'shapekit_ct_refinement', 'shapekit_warmup'):
if target_organs != {'vertebrae'}:
parser.error(f'{vertebrae_engine} requires --vertebrae_only')
if args.continue_prediction:
Expand Down
106 changes: 106 additions & 0 deletions utils/vertebrae_warmup.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,106 @@
"""Expose the warm-up vertebrae methods through ShapeKit."""

import json
from pathlib import Path
import shutil
import subprocess
import sys
import tempfile

import nibabel as nib
import numpy as np

from . import vertebrae_warmup_engine as engine
from .vertebrae_hao import _binary, _check_grid, _disjoint, load_vertebrae
from .vertebrae_hao_engine import save_volume


def run_rooted(source, output, workspace, rooted):
cache_path, ct_path, suprem_repo, python = rooted
cache, ct, repo = (Path(path).resolve() for path in (cache_path, ct_path, suprem_repo))
for path in (cache, ct, repo / "dataset" / "dataloader_test.py", repo / "utils" / "utils.py"):
if not path.is_file():
raise FileNotFoundError(f"Required rooted input missing: {path}")
if any(not _disjoint(output, path) for path in (cache, ct)):
raise ValueError("Output case must be disjoint from the cache and CT")

interpreter = str(Path(python).resolve()) if python else sys.executable
stage_root = workspace / "rooted"
# The submitted inverse transform imports SuPreM's own utils package.
# A subprocess gives it a separate import namespace from ShapeKit.
subprocess.run([
interpreter, "-I", "-c",
"import runpy, sys; runpy.run_path(sys.argv.pop(1), run_name='__main__')",
str(Path(engine.__file__).resolve()), "rooted",
"--cache", str(cache), "--ct", str(ct), "--suprem-repo", str(repo),
"--output-root", str(stage_root),
], cwd=repo, check=True)
native = stage_root / source.name
reference = nib.load(ct)
_check_grid(nib.load(native / "combined_labels.nii.gz"), reference, "rooted output")
stage = workspace / "publish"
stage.mkdir()
for name in ("combined_labels.nii.gz", "segmentations"):
(native / name).rename(stage / name)
summary = json.loads((stage_root / "workflow_report.json").read_text(encoding="utf-8"))
summary["native_segmentation"] = str(output / "combined_labels.nii.gz")
(stage / "workflow_report.json").write_text(json.dumps(summary, indent=2), encoding="utf-8")
return reference, stage


def process_case(input_path, output_path, class_map, subfolder_name="segmentations", *, rooted=None):
"""Run a submitted warm-up method and write a ShapeKit case."""
source, output = Path(input_path).resolve(), Path(output_path).resolve()
if not _disjoint(source, output):
raise ValueError("Input and output case directories must be disjoint")
if output.exists():
raise FileExistsError(f"Output case already exists: {output}")
if Path(subfolder_name).name != subfolder_name or subfolder_name in ("", ".", ".."):
raise ValueError("Invalid segmentation subfolder")
if any(type(label) is not int or not 1 <= label <= 65535 for label in class_map):
raise ValueError("class_map must use positive uint16 label IDs")
internal_ids = {name: label for label, name in enumerate(engine.NAMES[1:], 1)}
names = set(class_map.values())
if len(names) != len(class_map) or not internal_ids.keys() <= names:
raise ValueError("class_map must contain unique names and all vertebrae")

output.parent.mkdir(parents=True, exist_ok=True)
with tempfile.TemporaryDirectory(prefix="warmup-", dir=output.parent) as temp:
workspace = Path(temp)
if rooted is None:
reference, raw, _ = load_vertebrae(source, subfolder_name)
raw_path = workspace / "input" / source.name / "combined_labels.nii.gz"
raw_path.parent.mkdir(parents=True)
save_volume(raw, reference, raw_path)
del raw

stage_root = workspace / "result"
engine.component_filter(raw_path, stage_root, [internal_ids["vertebrae_C1"]])
stage = stage_root / source.name
else:
reference, stage = run_rooted(source, output, workspace, rooted)
combined_path = stage / "combined_labels.nii.gz"
labels = np.asarray(nib.load(combined_path).dataobj)
segdir = stage / subfolder_name
if subfolder_name != "segmentations":
(stage / "segmentations").rename(segdir)

for path in (source / subfolder_name).glob("*.nii.gz"):
if path.name[:-7] not in internal_ids:
image = nib.load(path)
_check_grid(image, reference, path.name)
shutil.copy2(path, segdir / path.name)

dtype = np.uint8 if max(class_map) <= 255 else np.uint16
combined = np.zeros(labels.shape, dtype=dtype)
for label, name in sorted(class_map.items()):
if name in internal_ids:
mask = labels == internal_ids[name]
else:
path = segdir / f"{name}.nii.gz"
if not path.is_file():
continue
mask = _binary(nib.load(path), name)
combined[mask] = label
save_volume(combined, reference, combined_path)
stage.rename(output)
Loading