Pictologics

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 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).
  • IBSI 2 Phase 1 (filters): 28 of 28 compared tests pass (report).
  • IBSI 2 Phase 2 (filtered features): 9 of 9 tests pass (report).
  • IBSI 2 Phase 3 (reproducibility): 153 scans, compared with 9 teams (report).
• 🔧 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.

Installation

Pictologics needs Python 3.12, 3.13 or 3.14.

pip install pictologics

From the source code:

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

Quick Start

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 and the Cookbook.

Performance Benchmarks

The median of 5 runs on one computer, after a warm-up run. See the benchmark page for all results, plots and the computer.

Quality & Compliance

IBSI Compliance: IBSI 1 Features | IBSI 2 Phase 1 Filters | Phase 2 Features | Phase 3 Reproducibility

Code Health

• Test Coverage: 100.00%
• Mypy Errors: 0
• Ruff Issues: 0

See Quality Report for full details.

Citation

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

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

License

Apache-2.0