Cardiac Shared

Production-ready toolkit for cardiac CT imaging research.

cardiac-shared provides the foundational infrastructure that cardiac imaging researchers need most: robust hardware detection, medical image I/O, DICOM preprocessing, CT slice thickness analysis, and a curated catalog of public cardiac datasets — all in one lightweight, well-tested package.

Version: 1.1.0 | PyPI: https://pypi.org/project/cardiac-shared/

What's New in v1.0

• External Dataset Catalog — Instant access to metadata, directory structures, access URLs, and usage notes for NLST (26K cases), Stanford COCA (1K cases), and TotalSegmentator (1.2K cases)
• Production-Ready API — Stable, focused API surface after extensive real-world validation across 5+ research projects and 4,000+ patient cases
• Python 3.10-3.14 — Tested on Python 3.10 through 3.14.3, including full PEP 649 (deferred annotations) and annotationlib compatibility
• Streamlined Architecture — Focused on the core utilities every cardiac imaging project needs, with clear extension points for project-specific features

Installation

pip install cardiac-shared

# With optional dependencies
pip install cardiac-shared[dicom]    # DICOM support (pydicom)
pip install cardiac-shared[nifti]    # NIfTI support (nibabel)
pip install cardiac-shared[gpu]      # GPU detection (torch)

Quick Start

Explore Available Datasets

from cardiac_shared.data import print_dataset_catalog, get_dataset_info

# See what's available
print_dataset_catalog()

# Get detailed info on a specific dataset
nlst = get_dataset_info('nlst')
print(nlst.access_url)           # https://cdas.cancer.gov/nlst/
print(nlst.typical_structure)     # Directory layout
print(nlst.paired_selection_criteria)  # How to find dual-thickness pairs

Detect Your Hardware

from cardiac_shared import detect_hardware, detect_runtime

hw = detect_hardware()
print(f"GPU: {hw.gpu.device_name if hw.gpu.available else 'CPU only'}")
print(f"Optimal batch size: {hw.ram.recommended_batch_size}")

config = get_optimal_config()  # Auto-detect and recommend settings

Process DICOM Data

from cardiac_shared.preprocessing import DicomConverter, detect_thickness

# Convert DICOM to NIfTI
converter = DicomConverter(output_dir="/data/nifti")
result = converter.convert_patient("P001234", "/data/dicom/P001234")
print(f"Output: {result.output_path}")

# Detect slice thickness
info = detect_thickness(nifti_path="/data/nifti/P001234.nii.gz")
print(f"Thickness: {info.thickness}mm ({info.category})")
# -> Thickness: 2.0mm (MEDIUM)

Work with NIfTI Files

from cardiac_shared.io import load_nifti, save_nifti, AsyncNiftiPreloader

# Simple load/save
volume, header = load_nifti("/data/patient.nii.gz")

# Background preloading for batch processing
preloader = AsyncNiftiPreloader(cache_size=10)
preloader.submit([path1, path2, path3])
vol1 = preloader.get(path1)  # Already loaded in background

Core Modules

Hardware Detection

Auto-detect GPU, CPU, and RAM; get optimized inference configurations; 5-tier GPU profiling from budget laptops to multi-GPU servers.

IO

DICOM series reading, NIfTI load/save, ZIP extraction, async preloading, multi-series DICOM inventory with thickness classification.

Preprocessing

DICOM-to-NIfTI conversion with series selection and deduplication. CT slice thickness detection from DICOM metadata, NIfTI headers, or Z-spacing.

Environment

Runtime detection — WSL, Google Colab, Jupyter, Windows, Linux, macOS. Automatic data path recommendations per environment.

Data

Curated catalog of public cardiac imaging datasets (NLST, COCA, TotalSegmentator) with standardized metadata, access URLs, and practical usage notes. Extensible via register_dataset().

Progress

Multi-level progress tracking with ETA estimation for long-running pipelines.

Upgrading from v0.9.x

v1.0 focuses the package on its core strengths. Specialized modules (tissue classification, vertebra detection, batch management, parallel processing) are now available as separate packages to keep cardiac-shared lightweight.

If you use any of these, you'll get a clear message telling you exactly where to find them:

>>> from cardiac_shared.tissue import TissueClassifier
ImportError: TissueClassifier has moved to cardiac_private.tissue in v1.0.0.
  Old: from cardiac_shared.tissue import TissueClassifier
  New: from cardiac_private.tissue import TissueClassifier

API Reference

See CHANGELOG.md for full version history.

License

MIT License - see LICENSE for details.