README.md

metadata

title: PanCancerSeg Specialist Inference
emoji: 🩻
colorFrom: blue
colorTo: indigo
sdk: gradio
sdk_version: 6.12.0
app_file: app.py
pinned: false
license: apache-2.0
short_description: CT tumour segmentation for 4 cancer types

PanCancerSeg Inference

Run one cancer-specific PanCancerSeg nnUNet model on a single CT NIfTI image and save a segmentation mask, slice PNG previews, and an MP4 overlay video.

On Hugging Face Spaces the trained weights are downloaded automatically at first run from KS987/PanCancerSeg-Specialized-weights. Inference is GPU-recommended; the free CPU tier may be slow or run out of memory on large volumes.

Model Weights

Download the trained nnUNet weights from Hugging Face: KS987/PanCancerSeg-Specialized-weights

git lfs install
git clone https://huggingface.co/KS987/PanCancerSeg-Specialized-weights

Setup

Create an environment and install the Python dependencies:

pip install -r requirements.txt

Download the trained nnUNet model weights to a local directory. Inference resampling can require about 64 GB RAM for large 3D volumes.

Expected model layout:

nnUNet_results/
|-- Dataset102_Kidney/
|   `-- nnUNetTrainerWandb2000__nnUNetResEncUNetMPlans__3d_fullres/
|       `-- fold_0/
|           `-- checkpoint_best.pth
|-- Dataset103_Liver/
|-- Dataset104_Pancreas/
`-- Dataset105_Lung/

Usage

Input images can be named either case.nii.gz or case_0000.nii.gz; the script handles both.

--cancer_type values are kidney_cancer, liver_cancer, pancreatic_cancer, and lung_cancer.

Kidney cancer:

python predict.py --input /path/to/case.nii.gz --cancer_type kidney_cancer --model_dir /path/to/nnUNet_results --output_dir ./output

Liver cancer:

python predict.py --input /path/to/case.nii.gz --cancer_type liver_cancer --model_dir /path/to/nnUNet_results --output_dir ./output

Pancreatic cancer:

python predict.py --input /path/to/case.nii.gz --cancer_type pancreatic_cancer --model_dir /path/to/nnUNet_results --output_dir ./output

Lung cancer:

python predict.py --input /path/to/case.nii.gz --cancer_type lung_cancer --model_dir /path/to/nnUNet_results --output_dir ./output

Use CPU only when CUDA is unavailable:

python predict.py --input /path/to/case.nii.gz --cancer_type kidney_cancer --model_dir /path/to/nnUNet_results --output_dir ./output --device cpu

Output Files

The output directory contains:

• {case_id}_seg.nii.gz: predicted segmentation mask
• {case_id}_slice_centroid.png: centroid slice preview
• {case_id}_slice_max_area.png: max predicted area slice preview
• {case_id}_slice_extent25.png: 25% through predicted z-extent preview
• {case_id}_slice_extent75.png: 75% through predicted z-extent preview
• {case_id}_overlay.mp4: scroll-through overlay video

Supported Cancer Types

--cancer_type	Dataset	Window level	Window width
kidney_cancer	Dataset102_Kidney	40	400
liver_cancer	Dataset103_Liver	40	400
pancreatic_cancer	Dataset104_Pancreas	40	400
lung_cancer	Dataset105_Lung	-600	1500

Example Output

The example/ folder contains sample output from running the kidney cancer model on a validation case (FLARE23Ts_0005), including slice PNGs, an overlay video, and the segmentation mask.

Troubleshooting

CUDA unavailable: run with --device cpu or install CUDA-enabled PyTorch.

Missing checkpoint: check that --model_dir points to the directory containing the DatasetXXX_* model folders and that fold_0/checkpoint_best.pth exists.

Missing custom trainer: make sure the cloned repository still has this layout:

PanCancerSeg-Inference/
|-- predict.py
`-- trainers/
    `-- nnUNetTrainerWandb2000.py

Do not move the trainers/ directory out of the repository. predict.py automatically registers the trainer with nnUNet when inference starts.

MP4 video creation failed: the segmentation mask and PNG files may still have been created. Try running the command on another machine or ask technical support to install video support for OpenCV.