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.5 \
  -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.5 \
  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

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.