Metadata-Version: 2.4
Name: z-rad
Version: 26.9.0
Summary: Z-Rad is a radiomic feature extraction software with GUI and API.
Author-email: Radiomics Team of Radiation Oncology Department at University Hospital Zurich <zrad@usz.ch>
License: MIT
Keywords: radiomics,feature-extraction,python,GUI,API
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pyqtgraph>=0.14.0
Requires-Dist: pydicom>=3.0.0
Requires-Dist: pyqt5>=5.15.11
Requires-Dist: numpy>=2.1.1
Requires-Dist: simpleitk>=2.4.0
Requires-Dist: scipy>=1.14.1
Requires-Dist: pywavelets>=1.7.0
Requires-Dist: scikit-image>=0.24.0
Requires-Dist: opencv-python-headless>=4.10.0.84
Requires-Dist: joblib>=1.4.2
Provides-Extra: docs
Requires-Dist: sphinx>=8; extra == "docs"
Requires-Dist: pydata-sphinx-theme>=0.16.1; extra == "docs"
Requires-Dist: sphinx-design>=0.6; extra == "docs"
Provides-Extra: test
Requires-Dist: pytest; extra == "test"
Requires-Dist: pytest-cov; extra == "test"
Requires-Dist: pytest-xdist; extra == "test"
Requires-Dist: pytest-benchmark>=5.3.0; extra == "test"
Requires-Dist: threadpoolctl>=3.5; extra == "test"
Provides-Extra: profiling
Requires-Dist: memray>=1.19; (sys_platform == "linux" or sys_platform == "darwin") and extra == "profiling"
Provides-Extra: lint
Requires-Dist: ruff==0.16.8; extra == "lint"
Provides-Extra: dev
Requires-Dist: sphinx>=8; extra == "dev"
Requires-Dist: pydata-sphinx-theme>=0.16.1; extra == "dev"
Requires-Dist: sphinx-design>=0.6; extra == "dev"
Requires-Dist: pytest; extra == "dev"
Requires-Dist: pytest-cov; extra == "dev"
Requires-Dist: pytest-xdist; extra == "dev"
Requires-Dist: pytest-benchmark>=5.3.0; extra == "dev"
Requires-Dist: threadpoolctl>=3.5; extra == "dev"
Requires-Dist: ruff==0.16.8; extra == "dev"
Dynamic: license-file

# Z-Rad

[![Tests](https://github.com/medical-physics-usz/z-rad/actions/workflows/test.yml/badge.svg?branch=master)](https://github.com/medical-physics-usz/z-rad/actions/workflows/test.yml)
[![Ruff](https://github.com/medical-physics-usz/z-rad/actions/workflows/python-lint.yml/badge.svg?branch=master)](https://github.com/medical-physics-usz/z-rad/actions/workflows/python-lint.yml)
[![Docs](https://github.com/medical-physics-usz/z-rad/actions/workflows/docs.yml/badge.svg?branch=master)](https://github.com/medical-physics-usz/z-rad/actions/workflows/docs.yml)
[![PyPI](https://img.shields.io/pypi/v/z-rad.svg)](https://pypi.org/project/z-rad/)
[![Python](https://img.shields.io/pypi/pyversions/z-rad.svg)](https://pypi.org/project/z-rad/)
[![License](https://img.shields.io/pypi/l/z-rad.svg)](https://github.com/medical-physics-usz/z-rad/blob/master/LICENSE)

<p align="center">
  <img src="https://raw.githubusercontent.com/medical-physics-usz/z-rad/master/docs/logos/ZRadLogo.jpg" width="320" alt="Z-Rad — Zurich Radiomics" />
</p>

<p align="center">
  <strong>Extract quantitative features from medical images with a desktop interface or Python API.</strong><br />
  CT, PET, MR, MG, US, and RTDOSE · DICOM and NIfTI · Windows, macOS, and Linux<br />
  Developed by the Department of Radiation Oncology at University Hospital Zurich
</p>

<p align="center">
  <a href="#from-images-to-a-feature-table"><strong>Full IBSI I preprocessing and feature coverage · All IBSI II filters</strong></a>
</p>

<p align="center">
  <a href="https://github.com/medical-physics-usz/z-rad/releases">Download</a> ·
  <a href="https://medical-physics-usz.github.io/z-rad/">Documentation</a> ·
  <a href="#python-quickstart">Python quickstart</a> ·
  <a href="https://medical-physics-usz.github.io/z-rad/examples/">Examples</a> ·
  <a href="#ibsi-validation">Validation</a>
</p>

## From images to a feature table

<p align="center">
  <img src="https://raw.githubusercontent.com/medical-physics-usz/z-rad/master/docs/images/readme_workflow.png" width="700" alt="Workflow from images and ROI masks through preprocessing, optional filtering, feature extraction, and export to a feature dictionary or CSV." />
</p>
<p align="center">
  <em></em>
</p>
<br>

| Capability | What you can do |
| --- | --- |
| Inspect images | View images and ROI masks together in the desktop viewer. |
| Prepare images | Convert DICOM to NIfTI and apply **all IBSI I preprocessing operations**, including image and mask interpolation, resegmentation, and intensity discretization. |
| Filter images | Apply **all IBSI II filters**, including mean, LoG, Laws, Gabor, separable wavelets, Simoncelli, and Riesz transforms. |
| Extract features | Calculate **all IBSI I radiomic features** across morphology, local intensity, intensity statistics, histograms, intensity-volume histograms, and texture, with applicable 2D, 2.5D, and 3D aggregation options. |
| Process cohorts | Run preprocessing, filtering, and feature extraction across case folders through the GUI or Python batch APIs. |
| Export results | Collect feature dictionaries in Python or export batch radiomics results to CSV. |

<br>
<p align="center">
  <img src="https://raw.githubusercontent.com/medical-physics-usz/z-rad/master/docs/images/zrad_extraction_pathways.svg" width="700" alt="Z-Rad screenshot"/>
</p>

<p align="center">
  <em>Use preprocessing, filtering, and feature extraction independently or combine them into a complete workflow.</em>
</p>


## Supported images and masks

| Data format | Data type | Supported types and notes |
| --- | --- | --- |
| DICOM | Image | CT, MR, PET (PT), mammography (MG), ultrasound (US), and RTDOSE. |
| DICOM | Mask | RTSTRUCT contours and BINARY DICOM SEG objects; select ROIs by structure name or segment label. |
| NIfTI | Image | Scalar image volumes with spatial geometry. |
| NIfTI | Mask | One binary ROI mask per file, paired with its reference image. |

Use scalar image volumes with masks on the same physical voxel grid. See the [data-format and folder-layout guide](https://medical-physics-usz.github.io/z-rad/user/data_structure.html) for input restrictions, case organization, and structure selection.

## Get started

### Desktop application

1. Open [Z-Rad releases](https://github.com/medical-physics-usz/z-rad/releases) and choose a release.
2. Download the asset for your platform:

   | Platform | Release asset | Launch |
   | --- | --- | --- |
   | Windows | `z-rad-<release-tag>-windows.exe` | Run the executable. |
   | Apple Silicon macOS | `z-rad-<release-tag>-macos-arm64.zip` | Extract the archive and open `Z-Rad.app`. |

3. Follow the [GUI quickstart](https://medical-physics-usz.github.io/z-rad/user/gui_quickstart.html) to select your input data, configure processing, and run your first analysis.

The macOS app is currently unsigned and unnotarized, so Gatekeeper may show a warning. For Linux, Intel Macs, or the current source version, follow [Run from source](https://medical-physics-usz.github.io/z-rad/user/installation.html#run-from-source) to install and launch the GUI.

<p align="center">
  <img src="https://raw.githubusercontent.com/medical-physics-usz/z-rad/master/docs/images/zrad_screenshot.png" width="700" alt="Z-Rad screenshot"/>
</p>

<p align="center">
  <em>Run the workflow interactively through the
    <a href="https://medical-physics-usz.github.io/z-rad/user/gui_workflows.html">graphical user interface</a>
    or automate it with the
    <a href="https://medical-physics-usz.github.io/z-rad/user/api_quickstart.html">Python API</a>.</em>
</p>

### Python quickstart

**Requires Python 3.11 or newer.** Install the published package:

```sh
python -m pip install z-rad
```

The example below requires your own NIfTI image and binary ROI mask on the same physical voxel grid. Replace the two paths with your files. It extracts intensity statistics without resampling or filtering:

```python
from zrad.image import Image
from zrad.preprocessing import IntensityMaskBuilder, RoiData
from zrad.radiomics import Radiomics

image = Image.from_nifti("path/to/image.nii.gz")
mask = Image.from_nifti_mask("path/to/mask.nii.gz", reference=image)
roi = IntensityMaskBuilder().apply(RoiData(image=image, morphological_mask=mask))
features = Radiomics().extract_features(roi_data=roi, families=["intensity_statistics"])
print(features["stat_mean"])
```

The result is a dictionary of feature names and values. To try a complete example with supplied data and an expected result, follow the [bundled phantom example](https://medical-physics-usz.github.io/z-rad/user/api_quickstart.html#run-the-bundled-phantom-example).

In the Python single-ROI API, texture and intensity-volume histogram (IVH) features require additional preparation; see the [full Python workflow](https://medical-physics-usz.github.io/z-rad/user/api_workflows.html#recommended-workflow).

## IBSI validation

Automated benchmarks compare Z-Rad results against published reference data from the Image Biomarker Standardisation Initiative (IBSI):

- **IBSI I:** digital-phantom features and CT configurations A–E, including preprocessing diagnostics.
- **IBSI II:** digital-phantom filter response maps and features from filtered CT images.
- **IBSI-SUV:** SUV conversion checks using valid and intentionally invalid digital reference objects.

Implementation coverage describes available operations; benchmark agreement applies to the tested configurations and features. See [IBSI coverage and limitations](https://medical-physics-usz.github.io/z-rad/ibsi/) for the scope, comparison rules, and unavailable references, and [execution reports and reproduction](https://medical-physics-usz.github.io/z-rad/developer/testing.html#ibsi-benchmark-reports) to inspect results for a particular revision.

## Contribute and get in touch

Found a bug or have a feature request? [Open an issue](https://github.com/medical-physics-usz/z-rad/issues). To contribute code or documentation, start with [CONTRIBUTING.md](CONTRIBUTING.md).

For questions or research collaborations, contact [zrad@usz.ch](mailto:zrad@usz.ch).
