Metadata-Version: 2.4
Name: pictologics
Version: 1.0.0
Summary: IBSI-compliant radiomic feature extraction package
License: Apache-2.0
License-File: LICENSE
License-File: NOTICE
Keywords: radiomics,medical-imaging,ibsi,dicom,nifti
Author: Márton Kolossváry
Author-email: marton.kolossvary@gmail.com
Requires-Python: >=3.12,<3.15
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Scientific/Engineering :: Medical Science Apps.
Classifier: Typing :: Typed
Provides-Extra: viz
Requires-Dist: Pillow (>=11.1.0)
Requires-Dist: PyWavelets (>=1.6.0)
Requires-Dist: matplotlib (>=3.10.0) ; extra == "viz"
Requires-Dist: nibabel (>=5.2.0)
Requires-Dist: numba (>=0.62.1) ; (sys_platform != "darwin" or platform_machine != "x86_64") and python_version < "3.14"
Requires-Dist: numba (>=0.62.1,<0.63) ; sys_platform == "darwin" and platform_machine == "x86_64"
Requires-Dist: numba (>=0.63.0) ; (sys_platform != "darwin" or platform_machine != "x86_64") and python_version >= "3.14"
Requires-Dist: numpy (>=2.0) ; python_version < "3.14"
Requires-Dist: numpy (>=2.3.2) ; python_version >= "3.14"
Requires-Dist: pandas (>=2.2.2)
Requires-Dist: pydicom (>=3.0.1)
Requires-Dist: python-gdcm (>=3.0.10)
Requires-Dist: pyyaml (>=6.0)
Requires-Dist: scipy (>=1.16.3)
Requires-Dist: tqdm (>=4.66.0)
Project-URL: Documentation, https://martonkolossvary.github.io/pictologics/
Project-URL: Homepage, https://martonkolossvary.github.io/pictologics/
Project-URL: Repository, https://github.com/martonkolossvary/pictologics
Description-Content-Type: text/markdown

# Pictologics

<p align="center">
    <img src="https://raw.githubusercontent.com/martonkolossvary/pictologics/main/docs/assets/logo.png" width="220" alt="Pictologics logo" />
</p>

[![CI](https://github.com/martonkolossvary/pictologics/actions/workflows/ci.yml/badge.svg)](https://github.com/martonkolossvary/pictologics/actions/workflows/ci.yml)
[![Docs](https://img.shields.io/badge/docs-GitHub%20Pages-blue)](https://martonkolossvary.github.io/pictologics/)
[![PyPI](https://img.shields.io/pypi/v/pictologics)](https://pypi.org/project/pictologics/)
[![Python](https://img.shields.io/pypi/pyversions/pictologics)](https://pypi.org/project/pictologics/)
[![Downloads](https://img.shields.io/pypi/dm/pictologics)](https://pypi.org/project/pictologics/)
[![License](https://img.shields.io/github/license/martonkolossvary/pictologics)](https://github.com/martonkolossvary/pictologics/blob/main/LICENSE)
[![codecov](https://codecov.io/gh/martonkolossvary/pictologics/graph/badge.svg)](https://codecov.io/gh/martonkolossvary/pictologics)
[![Ruff](https://img.shields.io/badge/ruff-0%20issues-261230.svg)](https://github.com/astral-sh/ruff)
[![Mypy](https://img.shields.io/badge/mypy-0%20errors-blue.svg)](https://mypy-lang.org/)

**Pictologics** is a Python library for radiomic feature extraction from medical images. It follows IBSI 1 (the features) and IBSI 2 (the filters), and it checks its results against the IBSI reference values.

Documentation (user guide, tutorials, API, benchmarks): https://martonkolossvary.github.io/pictologics/

## Why Pictologics?

*   **🚀 Fast**: Numba compiles the computations for your computer, and they run on its fast cores. The [Benchmarks](https://martonkolossvary.github.io/pictologics/benchmarks/) page gives the time of each part.
*   **✅ IBSI compliant**: checked against the IBSI phantoms and data sets:
    *   **IBSI 1** (features): 675 feature values pass; 21 more have a reference value without a tolerance ([report](https://martonkolossvary.github.io/pictologics/ibsi1_compliance/)).
    *   **IBSI 2 Phase 1** (filters): 28 of 28 compared tests pass ([report](https://martonkolossvary.github.io/pictologics/ibsi2_compliance/)).
    *   **IBSI 2 Phase 2** (filtered features): 9 of 9 tests pass ([report](https://martonkolossvary.github.io/pictologics/ibsi2_phase2_compliance/)).
    *   **IBSI 2 Phase 3** (reproducibility): 153 scans, compared with 9 teams ([report](https://martonkolossvary.github.io/pictologics/ibsi2_phase3_compliance/)).
*   **🔧 Versatile**: reads NIfTI, NRRD, MetaImage and DICOM images, DICOM SEG, DICOM RTSTRUCT and 3D Slicer segmentations, and DICOM SR reports.
*   **✨ Easy to use**: pip installs it. One pipeline runs the preprocessing and the features, for one image or for a whole study.
*   **🛡️ Predictable results**: each configuration gives all its feature columns, also when a step fails (the values are then `NaN`). A study table never has missing columns.
*   **🛠️ Maintained**: Pictologics is developed to give robust radiomic features that describe the morphology of diseases on radiological images.

## What Is New in 1.0.0

Pictologics 1.0.0 is the first stable release. The code, the tests and the developer scripts are cleaned of old comments and dead code; the API does not change.

- **Pipeline**: a large float64 image is cut to the ROI region at the start of each configuration that reads only that region: on a 512×512×200 CT, a lesion run with outlier filtering, resegmentation and FBN takes 0.14 of the time, and `run_rois` with 20 ROIs 0.04. A `grow_mask` step with `nearest_roi` in `run_rois` reads only the box of the grown mask (0.12 s instead of 2.3 s for 20 ROIs). `run_batch` writes each case record in one JSON pass.
- **Morphology**: the surface area and the volume come from the corner cases of the marching cubes, without the mesh (0.53 to 0.71 of the time on cubes, the volume exact to rounding); the hull candidates take fewer sorts; the MVEE keeps the Mahalanobis value of each hull point (0.60 of the morphology time for a CT lesion).
- **Textures**: the NGTDM features come from one compiled kernel (1.7 µs instead of 19 µs a call); the GLCM sums the upper triangle; the zone fill checks only the later neighbours of a seed; the NGLDM counts in one vectorized loop; the threaded distance map and grey-level volume write every voxel in the threads.
- **Intensity**: the first-order family takes the mean, the minimum, the maximum and the energy from one pass (0.53 of the time for 20 million values); the IVH counts whole values with no copy (0.42 to 0.63 of the time); Moran's I and Geary's C keep only the folded quarter of the kernel spectrum.
- **Filters**: the Laws and wavelet rotation-invariant averages add in compiled kernels in threads (0.63 to 0.84 of the time); the FFT filters with a non-periodic boundary cut the padded border after each axis (0.83 to 0.89 of the memory or time).
- **Files**: `save_image` writes int16 and uint16 images in 0.1 of the time; a `.seg.nrrd` layer loads in 0.69 of the time; `load_and_merge_images` merges stored-type masks with no relabelled copy (0.30 of the time); a single-file PET in SUV scales in place; `load_seg` copies only the slices of each segment.
- **Preprocessing**: `discretise_image` with a bool mask finds the ROI range in one pass (0.29 of the time); `keep_largest_component` counts its components in threads (0.72 of the time, 0.46 of the memory).
- **Fixes**: a one-voxel image gives the texture features of a one-voxel ROI; a SEG with dimension index values from 0 loads its first frame into the first slice; information correlation 2 of a GLCM with independent grey levels is 0, not NaN; the IVH volume fractions keep a given range end (IBSI 4.3); the threaded level count handles infinite and huge values as the one-thread count does; the warm-up runs on two threads when one thread is set after numba started.
- **Changes**: the `resegment` and `filter_outliers` steps change the intensity mask only by default, as IBSI re-segmentation does (give `apply_to: both` for the old behaviour; the `lv` and `coronary` templates do). The IBSI compliance is the same. See the [Changelog](https://martonkolossvary.github.io/pictologics/CHANGELOG/).

## Installation

Pictologics needs Python 3.12, 3.13 or 3.14.

```bash
pip install pictologics
```

From the source code:

```bash
git clone https://github.com/martonkolossvary/pictologics.git
cd pictologics
pip install .
```

## Quick Start

```python
from pictologics import RadiomicsPipeline, format_results, save_results

# 1. A pipeline with the six standard configurations
pipeline = RadiomicsPipeline()

# 2. Run the configurations on an image and its mask
results = pipeline.run(
    image="path/to/ct.nii.gz",
    mask="path/to/mask.nii.gz",
    subject_id="Subject_001",
    config_names=["all_standard"],  # the FBS configurations start at -1000 HU, for CT
)

# 3. One table row, with your own columns first
row = format_results(results, fmt="wide", meta={"subject_id": "Subject_001", "group": "control"})

# 4. Save the row to a CSV file
save_results([row], "results.csv")
```

For MR or PET images, use the FBN configurations (`config_names=["standard_fbn_32"]`) or your own. See the [Quick Start](https://martonkolossvary.github.io/pictologics/user_guide/quick_start/) and the [Cookbook](https://martonkolossvary.github.io/pictologics/user_guide/cookbook/).

## Performance Benchmarks

| Task | Size | Time (median) |
|:--|:--|--:|
| run(): one standard configuration (standard_fbn_32) | CT of 512 × 512 × 200 | 8.6 ms |
| run(): the 6 standard configurations | CT of 512 × 512 × 200 | 29.0 ms |
| Texture (all 6 families) | 2,311,384 ROI voxels | 17.2 ms |
| Morphology | 2,311,384 ROI voxels | 2.3 ms |
| LoG (sigma 2 mm) | 256³ voxels | 38.8 ms |
| Gabor (axial, rotation invariant) | 256³ voxels | 53.5 ms |

The median of 5 runs on one computer, after a warm-up run. See the [benchmark page](https://martonkolossvary.github.io/pictologics/benchmarks/) for all results, plots and the computer.


## Quality & Compliance

**IBSI Compliance**: [IBSI 1 Features](https://martonkolossvary.github.io/pictologics/ibsi1_compliance/) | [IBSI 2 Phase 1 Filters](https://martonkolossvary.github.io/pictologics/ibsi2_compliance/) | [Phase 2 Features](https://martonkolossvary.github.io/pictologics/ibsi2_phase2_compliance/) | [Phase 3 Reproducibility](https://martonkolossvary.github.io/pictologics/ibsi2_phase3_compliance/)

### Code Health

- **Test Coverage**: 100.00%
- **Mypy Errors**: 0
- **Ruff Issues**: 0

See [Quality Report](https://martonkolossvary.github.io/pictologics/quality/) for full details.

## Citation

If you use Pictologics in your research, please cite it (GitHub shows the same citation from `CITATION.cff`):

```text
Kolossváry M. Pictologics: IBSI-compliant radiomic feature extraction (version 1.0.0). 2026. https://github.com/martonkolossvary/pictologics
```

## License

Apache-2.0

