voxelkit 0.1.7

Library-first toolkit for inspecting, previewing, and QA reporting imaging datasets.

VoxelKit

A Python toolkit for inspecting, previewing, and QA-checking 3D/4D volumetric data.

Documentation · Getting Started · CLI Reference · Python API

---

---

VoxelKit gives you a single CLI and Python API to inspect metadata, generate slice previews, and run QA checks across NIfTI, HDF5, NumPy, TIFF, and DICOM files. Instead of wiring up nibabel, h5py, and tifffile separately, you get one consistent interface for all of them.

# quick sanity check on a whole dataset
voxelkit report-batch data/scans/

Features

• Inspect - shape, dtype, and metadata from any supported file
• Preview - PNG slice from any 3D/4D volume
• QA Reports - per-file stats and warnings (NaNs, constant arrays, zero-dominated volumes)
• Batch QA - scan an entire directory, output JSON or a self-contained HTML report with thumbnails
• DICOM Support - single .dcm files and full series directories; PHI stripped by default
• Anonymisation - voxelkit anonymise ./dicoms/ --output ./clean/ scrubs PHI in bulk
• DICOM to NIfTI - voxelkit convert scan.dcm scan.nii.gz
• Embedding Analysis - dead dimensions, outlier samples, collapsed spaces
• REST API - FastAPI server for HTTP-based workflows
• Local GUI - optional Streamlit interface, runs entirely offline

Supported Formats

Format	Extensions / Input
NIfTI	.nii .nii.gz
HDF5	.h5 .hdf5
NumPy	.npy .npz
TIFF	.tif .tiff
DICOM	.dcm file or directory of slices (series)

Install

pip install voxelkit

pip install voxelkit[gui]   # optional Streamlit GUI

Requires Python 3.9+.

Quick Start

# What's in this file?
voxelkit inspect scan.nii.gz

# Run QA checks
voxelkit report scan.nii.gz

# Grab a slice
voxelkit preview scan.nii.gz --plane axial --output preview.png

# Batch QA across a directory (JSON or self-contained HTML)
voxelkit report-batch data/scans/
voxelkit report-batch data/scans/ --html report.html

DICOM workflows:

# Inspect a single .dcm or a whole series directory (PHI stripped by default)
voxelkit inspect scan.dcm
voxelkit inspect ./series/

# Scrub PHI from every .dcm under a directory
voxelkit anonymise ./incoming/ --output ./anonymised/

# Convert DICOM to NIfTI
voxelkit convert ./series/ volume.nii.gz

Or from Python:

from voxelkit import inspect_file, report_file, report_batch

info   = inspect_file("scan.nii.gz")        # also handles .dcm + series dirs
report = report_file("scan.nii.gz")
batch  = report_batch("data/scans/")

# DICOM-specific helpers
from voxelkit.dicom import anonymise_directory, dicom_to_nifti
anonymise_directory("./incoming/", "./anonymised/")
dicom_to_nifti("./series/", "volume.nii.gz")

Full Documentation

Complete CLI reference, Python API docs, REST API, QA warning explanations, and contributing guide:

arsalaanahmad.github.io/VoxelKit

Contributing

Contributions are welcome. See the Contributing Guide for setup instructions, workflow, and how to report issues.

Citation

If you use VoxelKit in research, please cite:

@software{voxelkit,
  author  = {Arsalaan Ahmad},
  title   = {VoxelKit},
  doi     = {10.5281/zenodo.19774569},
  url     = {https://github.com/ArsalaanAhmad/VoxelKit},
}

Disclaimer

VoxelKit is a developer and research utility. It is not a clinical decision system and must not be used for diagnosis or treatment.