ianpan/ct-cspine-segmentation

Cervical spine C1-C7 segmentation

Training code: GitHub repository · End-to-end reproduction guide · Experiments and results · Decision log

Five-fold X3D-S/DeepLabV3+ ensemble trained with TotalSegmentator pseudo-label pretraining followed by manual-label fine-tuning. The model consumes one axial CT series windowed at center 400 / width 1800 and predicts C1-C7 masks.

This is a research model, not a medical device, and must not be used as the sole basis for diagnosis or treatment.

Training procedure

Local installation and use

bash install_local.sh

from skp.cspine.pipeline import DICOMSeries, CervicalSpineSegmenter

series = DICOMSeries.from_dicom_directory("/path/to/one/series")
segmenter = CervicalSpineSegmenter.from_pretrained(".", device="cuda")
segmentation = segmenter(series)
print(segmentation.anomaly_levels)

See cspine_model.json for the machine-readable preprocessing and ensemble contract. The companion fracture-classification repository consumes this model's SegmentationResult.

Ensemble presets

from skp.cspine.pipeline import CervicalSpineSegmenter
model = CervicalSpineSegmenter.from_pretrained("ianpan/ct-cspine-segmentation", ensemble_size=3)

Choose ensemble_size=1, 3, or 5 (default). These use folds [0], [0,1,2], or [0,1,2,3,4], respectively—not a performance-ranked selection. The classifier retains both MIL families and all four series-head architectures; the preset controls folds for every component, including localization. Smaller presets have not been separately benchmarked. Downloading a package still fetches all its weights; only selected folds are executed.

Input, output, and compatibility

Use both packages from the same final-v1 preparation. DICOM parsing, spatial ordering, windowing, segmentation-guided square vertebra cropping, resizing, and localization geometry mapping are implemented in the bundled runtime. Do not substitute manually resized PNG inputs for the public DICOM interface. The manifest defines the preprocessing contract and output ordering. Classifier outputs are named overall and C1-C7 probabilities; heatmaps are probabilities, not millimetres or precise fracture contours. Quality flags expose missing levels/topology anomalies; downstream users must not silently treat these as reliable negative findings. The default localization threshold is an inference selection rule, not a clinically validated operating point.

Runtime target: Python 3.11, Linux x86-64, PyTorch 2.6.0/CUDA 12.4 and torchvision 0.21.0. requirements.txt specifies direct dependencies, but is not a complete transitive lockfile. GPU timing and peak-memory claims require the separate preparation verification report. Other platforms are unvalidated. These custom-runtime artifacts do not imply hosted Hugging Face Inference API support. Installation requires downloading Python dependencies; weights alone are not a self-contained environment.

For reproducible Hub retrieval after publication, use revision= with the published immutable commit in from_pretrained, snapshot_download, and hf_hub_download. Obtain the commit hash from the repository history. A single SafeTensor download also needs this package's runtime wheel and corresponding manifest/configuration. Fine-tuning is weight initialization, not exact optimizer/scheduler resumption.

Evaluation

Re-evaluated mean C1-C7 Dice: 0.8037 for EMA weights on the small manually segmented subset (raw weights: 0.8031). Full-resolution TotalSegmentator remains the teacher-quality ceiling.

Limitations

Training is based on the RSNA 2022 cervical spine fracture competition data. Performance may degrade under domain shift, incomplete cervical coverage, severe artifacts, altered reconstructions, or thick slices. Topology anomaly flags must be inspected downstream.

Training and evaluation scope

Data: RSNA 2022 Cervical Spine Fracture Detection, 2,019 training studies, including 87 manually segmented studies and 235 studies with bounding-box annotations. Five study-disjoint folds are used; all crops from a study share its fold. No independent patient-identity linkage audit or external clinical validation is claimed. The segmentation student uses 1,931 QC-passed teacher-labeled studies plus manual fine-tuning.

Segmentation, original MIL encoders, and localization decoders use EMA states. The four series-head architectures use raw states (EMA was disabled). Historical training crops used raw segmentation states; deployment uses EMA. Series metrics are OOF results from cached fold-specific features, not a new end-to-end clinical evaluation of the deployed five-fold segmentation ensemble. Log loss uses per-target weights: level negative/positive 1/2, overall 7/14, normalized by the sum of weights. Macro AUC averages C1-C7 AUCs. Confidence intervals, demographic subgroup analyses, calibration guarantees, and prospective clinical utility have not been established.

Training procedure

This package contains the five fold-specific X3D-S + 3D DeepLabV3+ students, not the TotalSegmentator teacher. Training has two stages: teacher-label pretraining, then manual-label fine-tuning. The following recipe reflects the selected reproduction configs; epoch counts are training budgets, not claims that the released checkpoint was selected at the final epoch.

Data, preprocessing, and folds

The RSNA 2022 dataset contains 2,019 training studies, including 87 with manual C1-C7 masks. TotalSegmentator 2.16.0's full-resolution total task (Dataset292, 1.5 mm teacher resolution) generated labels for the remaining studies; 1,931 passed QC. Temporary per-study NIfTI conversion is used for the teacher and removed after use. The student does not require TotalSegmentator at inference.

DICOM HU values are windowed at center 400 / width 1800 ([-500, 1300]), mapped to uint8, and resampled to 128×128×128 rather than a fixed isotropic spacing. The student normalizes intensities to [0,1] and predicts background plus C1-C7. Five study-disjoint folds keep all images from a study together. Pseudo-label training is fold-filtered, and validation uses held-out manual masks; manual fine-tuning initializes from the matching fold's pretrained student.

Optimization and checkpoint selection

Stage	Initialization	Epoch budget	AdamW peak LR
Pseudo-label pretraining	PyTorchVideo pretrained X3D-S backbone	20	3e-4
Manual-mask fine-tuning	Matching fold's pseudo-pretrained student	50	1e-4

Both stages use weight decay 0.01, linear warmup over 5% of the schedule from LR 0, then cosine decay to 1e-6. Configured batch size is 1 volume/GPU with 4-step gradient accumulation (effective global batch 8 on two GPUs). The reference setup uses two RTX A6000 GPUs, DDP, and BF16.

Loss is equally weighted multiclass cross-entropy plus Dice; the Dice term excludes background. Select the checkpoint maximizing mean C1-C7 validation Dice. EMA uses decay 0.999 with warmup and starts after step 100; the released weights are EMA. Historical downstream training crops used the selected checkpoints' raw state; deployment uses EMA. Preserve this distinction when reproducing the already-trained classifier pipeline.

Augmentation applies independent 50% in-plane flips, random 0/90/180/270-degree axial rotations, intensity gain 0.9–1.1 and offset -8 to +8 on the uint8 scale, with clipping to [0,255]. Spatial transforms are shared by image and mask; no depth-axis flip is applied by this selected dataset implementation.

Reproduction entry points

• Pretraining config
• Fine-tuning config
• Shared segmentation settings

Follow reproduction-guide sections 1–3 for environment setup, data access, conversion, folds, teacher generation and both training commands. Training requires a reachable MLflow server. Original runs were not consistently seeded; retraining is evaluated against reported metrics, not promised to reproduce identical weight bytes. Exact exported states and hashes are in provenance.json.

Fine-tuning

Load one checkpoint directly for fine-tuning:

from skp.cspine.artifacts import load_checkpoint_for_finetuning
model, cfg = load_checkpoint_for_finetuning(
    "ianpan/ct-cspine-segmentation", fold=0, device="cuda"
)
optimizer = __import__("torch").optim.AdamW(
    (p for p in model.parameters() if p.requires_grad), lr=1e-5
)

Classifier components are mil, localizer, 7x1, and 7x32, with family d32 or 3x32. Segmentation needs only fold. The loader verifies checksums, strict-loads weights, returns the model in training mode, and preserves intentional freezing (localizer encoder stays frozen). It does not restore optimizer state. Use the returned config and the GitHub training datasets/losses to preserve input normalization, shapes, and targets. Series heads consume MIL features, not CT.

For a weights-only download without the complete ensemble:

from huggingface_hub import hf_hub_download
path = hf_hub_download("ianpan/ct-cspine-segmentation", filename="weights/fold0.safetensors")

Release status and provenance

This is the final-v1 model suite. During initial upload, treat this repository as a candidate until every file in release-inventory.json is available. provenance.json records checkpoint states and exact runtime source hashes; release-inventory.json hashes every payload file except itself. A dirty-source identity is deliberate: these preparation changes have not been committed. The bundled wheel contains the architecture and configuration definitions.

Owner: Ian Pan. Report reproducibility issues through the source repository. See its reproduction guide, experiment history, and decision log. Preparation-only runtime changes may not yet be on remote main.

Licensing, attribution, and safety

The project code and included trained weights are released under Apache-2.0 (see LICENSE). The model owner confirmed authorization to publish the weights under this license. This does not relicense upstream assets or RSNA/Kaggle data. The dataset remains subject to the competition rules, including non-commercial data use and restrictions on dataset redistribution. Dataset citation: RSNA 2022 Cervical Spine Fracture Detection Challenge. Pretrained lineage includes PyTorchVideo X3D and timm MaxViT, and segmentation pseudo-labels from TotalSegmentator's total task. Consult PyTorchVideo, timm, and TotalSegmentator for attribution and upstream terms. No training images, teacher checkpoints, patient identifiers, or optimizer states are included.

Companion repositories: C1-C7 segmentation and fracture classification/localization. The included verification.json records the bounded local smoke checks; these are not additional accuracy or clinical validation results.

Intended users are researchers evaluating CT fracture detection. Not validated for autonomous triage, diagnosis, treatment decisions, or ruling out fractures. Thick slices, motion, hardware, incomplete coverage, unusual anatomy and changes in scanners/reconstruction can cause errors. Heatmaps can appear plausible despite an incorrect prediction. Clinical deployment requires independent safety, regulatory, bias, and workflow evaluation; human review alone does not establish safety. Process CT data in an appropriately secured environment, and do not publish patient-containing inference outputs or logs.