LION

Fully automated tumor segmentation for FDG and PSMA PET scans

Quick Start

python -m venv lion-env
source lion-env/bin/activate        # macOS / Linux
lion-env\Scripts\activate           # Windows

pip install lionz
lionz -d /path/to/data -m fdg

That's it. Models download automatically on first run.

Requirements

• Python 3.10+
• 32GB RAM recommended
• GPU optional (NVIDIA CUDA or Apple Silicon MPS) - CPU works but slower

Installation

We recommend installing LION in a virtual environment to avoid dependency conflicts.

Using uv (recommended)

uv is a fast Python package manager that handles virtual environments automatically.

# Install uv if you don't have it
curl -LsSf https://astral.sh/uv/install.sh | sh   # macOS/Linux
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"  # Windows

Install from PyPI:

uv venv lion-env

# Activate the environment
source lion-env/bin/activate        # macOS / Linux
lion-env\Scripts\activate           # Windows

uv pip install lionz

Install from source:

git clone https://github.com/ENHANCE-PET/LION.git
cd LION
uv sync

Using pip + venv

python -m venv lion-env

# Activate the environment
source lion-env/bin/activate        # macOS / Linux
lion-env\Scripts\activate           # Windows

python -m pip install lionz

Docker with NVIDIA GPUs

The LION Docker image targets CUDA 12.4 and requires NVIDIA driver 550.54.14 or newer on Linux. The host supplies the NVIDIA driver; it is not installed inside the container.

docker run --rm --gpus all --shm-size=2g \
  -v /path/to/data:/shared \
  -v lionz-models:/usr/local/models \
  lalithshiyam/lionz:1.0.6 \
  -d /shared -m psma

LION stores downloaded models under /usr/local/models/nnunet_trained_models, so the model volume persists across container runs.

On a Slurm cluster with Singularity:

singularity exec --nv \
  --bind /path/to/data:/shared \
  --bind /path/to/models:/usr/local/models \
  docker://lalithshiyam/lionz:1.0.6 \
  lionz -d /shared -m psma

Input Data Structure

LION runs on PET input only. CT is not required for the current FDG and PSMA models.

data/
├── patient_001/
│   └── PT_scan.nii.gz      # PET file with PT_ or PT- prefix
├── patient_002/
│   └── PT_scan.nii.gz
└── patient_003/
    └── PT_scan.nii.gz

Rules:

• One folder per subject
• PET files must start with PT_ or PT-
• CT files are not needed and are ignored by the current segmentation models
• Supports .nii and .nii.gz
• PET DICOM folders are also supported; modality is auto-detected from tags

Messy Data?

Use the lion-mcp server with Claude Code or Codex to organize chaotic DICOM/NIfTI dumps. See lion-mcp/README.md.

CLI Usage

# Basic
lionz -d /path/to/data -m fdg

# With SUV threshold
lionz -d /path/to/data -m fdg -t 2.5

# Generate MIP preview
lionz -d /path/to/data -m fdg -g

# Parallel processing (multiple subjects)
lionz -d /path/to/data -m fdg -p 4

# All options
lionz -d /path/to/data -m fdg -t 2.5 -g -p 4

Options:

Library Usage

import lionz

# From file path
result = lionz.lion('/path/to/PT_scan.nii.gz', 'fdg')

# From SimpleITK image
import SimpleITK as sitk
img = sitk.ReadImage('/path/to/PT_scan.nii.gz')
seg = lionz.lion(img, 'fdg')  # Returns SimpleITK.Image

# From numpy array
import numpy as np
array = np.load('pet_data.npy')
spacing = (2.0, 2.0, 2.0)
seg = lionz.lion((array, spacing), 'fdg')  # Returns np.ndarray

# With options
result = lionz.lion(
    '/path/to/PT_scan.nii.gz',
    'fdg',
    output_dir='/path/to/output',
    accelerator='mps',  # 'cpu', 'cuda', or 'mps'
    threshold=2.5
)

Important: Wrap in if __name__ == '__main__': to avoid multiprocessing issues:

import lionz

if __name__ == '__main__':
    lionz.lion('/path/to/PT_scan.nii.gz', 'fdg')

Models

Output Structure

patient_001/
├── PT_scan.nii.gz                    # Original PET input
└── lionz-2024-01-15-10-30-00/
    ├── segmentations/
    │   ├── PT_scan_tumor_seg.nii.gz  # Tumor mask
    │   └── patient_001_rotational_mip.gif  # If -g flag used
    └── stats/
        └── patient_001_metrics.csv   # Volume, SUV metrics

Standards-compliant DICOM SEG export

scripts/export_idc_dicom_seg.py converts an existing LION FDG NIfTI mask back onto its original PET DICOM grid and encodes it as a source-referenced binary DICOM SEG. This dataset workflow is separate from the normal lionz inference command because it requires the original PET instances plus pinned dcmqi and dicom3tools containers.

The LMU Slurm workflow is:

sbatch --wait scripts/lmu/prepare_dicom_seg_tools.sbatch
sbatch --wait --export=ALL,MODE=smoke scripts/lmu/export_idc_dicom_seg.sbatch
sbatch --wait --export=ALL,MODE=full,WORKERS=8 scripts/lmu/export_idc_dicom_seg.sbatch

Every produced object must pass source-UID and coded-metadata checks, zero dciodvfy/dcentvfy errors, and an exact dcmqi SEG-to-mask round trip. Empty masks are recorded explicitly and do not produce meaningless empty SEG objects. The LUNG-PET-CT-Dx export also checks that every SUV>=4 mask is a subset of its corresponding native mask.

Platform Support

For AI Agents

LION provides an MCP server for organizing messy medical imaging data. Install and configure:

cd lion-mcp && pip install -e .

Add to .mcp.json:

{
  "lion-mcp": {
    "type": "stdio",
    "command": ".venv/bin/lion-mcp"
  }
}

Available MCP tools:

• scan_directory - Scan for DICOM/NIfTI files, extract metadata
• read_dicom_header - Read full DICOM tags
• organize_for_lion - Reorganize files into LION structure
• validate_structure - Check if directory is LION-ready
• get_lion_requirements - Get structure documentation

Telemetry

LION collects anonymous usage statistics to help us understand how the tool is used and prioritize development. This is completely optional.

What we collect: version, model used, platform, accelerator type, number of subjects, success/failure

What we DON'T collect: file paths, patient data, IP addresses, any identifiable information

Opt-out:

export LIONZ_TELEMETRY=0

Citation

DOI: 10.5281/zenodo.12626789

License

Apache 2.0.

Contributors

• Lalith Kumar Shiyam Sundar
• Manuel Pires
• Sebastian Gutschmayer

Part of the ENHANCE.PET initiative.