Metadata-Version: 2.4
Name: pysuv
Version: 0.1.0
Summary: Python library for calculating Standardized Uptake Value (SUV) from PET DICOM images
Author: pysuv contributors
License: MIT
License-File: LICENSE
Keywords: DICOM,PET,SUV,medical imaging,nuclear medicine
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Healthcare Industry
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Medical Science Apps.
Requires-Python: >=3.10
Requires-Dist: numpy>=1.24
Requires-Dist: pydicom>=2.4
Description-Content-Type: text/markdown

<p align="center">
  <img src="assets/logo.png" alt="pySUV" width="300">
</p>

<p align="center">
  <em>A Python library for calculating Standardized Uptake Value (SUV) from PET DICOM images.</em>
</p>

## Table of Contents

- [Why pySUV?](#why-pysuv)
- [Features](#features)
- [Installation](#installation)
- [Quick Start](#quick-start)
- [Documentation](#documentation)
- [API Reference](#api-reference)
- [Validation](#validation)
- [References](#references)
- [Disclaimer](#disclaimer)
- [License](#license)

## Why pySUV?

SUV calculation is essential for PET image analysis, whether for traditional clinical reading (PERCIST criteria, Deauville score) or machine learning pipelines (radiomic features, preprocessing). Yet no simple, validated Python library exists.

| Alternative | Strength | Limitation |
|-------------|----------|------------|
| **3D Slicer** | Complete, multi-vendor | Heavy dependency (~500 MB), GUI-oriented, hard to script |
| **Z-Rad** | Excellent, validated ([arXiv:2410.13348](https://arxiv.org/abs/2410.13348)) | Broad scope (full radiomics + GUI), many dependencies |
| **ACRCode** | Vendor-neutral, lightweight | Incomplete implementation (edge cases) |
| **GitHub snippets** | Simple | Unvalidated, BQML-only |

**pySUV** provides a focused, validated solution: one function call, multi-vendor support, < 1% error vs QIBA reference. Beyond accurate calculations, it validates DICOM metadata against clinical guidelines—catching data entry errors and protocol deviations before they affect your results.

## Features

- **Validated**: Cross-validated against QIBA DRO (< 1% error)
- **Multi-vendor**: Siemens, GE, Philips (BQML and CNTS units)
- **Four normalizations**: SUVbw, SUVlbm, SUVbsa, SUVibw
- **Simple API**: Compute SUV arrays or get conversion factors
- **Clinical validation**: Optional module for protocol compliance checks

## Installation

```bash
pip install pysuv
```

## Quick Start

```python
import pysuv

# Calculate SUV from a PET DICOM file
suv = pysuv.compute_suv("pet.dcm")
print(f"SUVmax: {suv.max():.2f}")

# Use different normalizations
suv_lbm = pysuv.compute_suv("pet.dcm", normalization="lbm")
suv_bsa = pysuv.compute_suv("pet.dcm", normalization="bsa")
```

## Documentation

- **[SUV Conversion Guide](docs/user-guide-suv.md)**: Supported vendors, formats, normalizations, and edge cases
- **[Validation Guide](docs/user-guide-validation.md)**: Clinical protocol validation for FDG PET

## API Reference

### `compute_suv(source, normalization='bw')`

Compute SUV array from a PET DICOM image.

- `source`: Path to DICOM file or pydicom Dataset
- `normalization`: `'bw'` (default), `'lbm'`, `'bsa'`, or `'ibw'`

Returns a numpy array of SUV values (same shape as input image).

### `get_suv_factor(source, normalization='bw')`

Get the SUV conversion factor without computing the full array. Useful for applying to ROIs or storing for reproducibility.

```python
import pydicom
import pysuv

factor = pysuv.get_suv_factor("pet.dcm")

# Apply to pixel data (works for all vendors)
ds = pydicom.dcmread("pet.dcm")
scaled = ds.pixel_array * factor.rescale_slope + factor.rescale_intercept
suv = scaled * factor.suv_factor
```

### `get_suv_parameters(source)`

Inspect the parameters used for SUV calculation.

```python
info = pysuv.get_suv_parameters("pet.dcm")
print(info)
# SUV Parameters:
#   Manufacturer: SIEMENS
#   Injected dose: 370.0 MBq
#   Patient weight: 70.0 kg
#   Half-life: 109.77 min
#   Elapsed time: 60.0 min
```

### Normalizations

| Type | Description | Required fields |
|------|-------------|-----------------|
| `bw` | Body weight (default) | weight |
| `lbm` | Lean body mass | weight, height, sex |
| `bsa` | Body surface area | weight, height |
| `ibw` | Ideal body weight | weight, height, sex |

## Validation

pySUV is validated against:

- **[QIBA DRO](https://qibawiki.rsna.org/index.php/Standardized_Uptake_Value_%28SUV%29)**: Digital Reference Object with known SUV values
- **Reference implementations**: Z-Rad, ACRCode, 3D Slicer

## References

- **Z-Rad**: Pfaehler et al. "Technical Note: Vendor-Specific Approach for Standardized Uptake Value Calculation", [arXiv:2410.13348](https://arxiv.org/abs/2410.13348) (2024)
- **QIBA SUV Profile**: [RSNA QIBA Wiki](https://qibawiki.rsna.org/index.php/Standardized_Uptake_Value_%28SUV%29)
- **QIBA DRO**: [University of Washington PET/CT DRO](https://depts.washington.edu/petctdro/DROsuv_main.html)

## Disclaimer

**For research use only.** This software is not intended for clinical decision-making or diagnostic purposes. It has not been cleared or approved by any regulatory agency.

The authors provide this software "as is" without warranty of any kind. In no event shall the authors be liable for any claim, damages, or other liability arising from the use of this software.

Users are responsible for validating results against their institution's reference standards before use in any research or clinical context.

## License

MIT
