# Cardiac Shared

[![PyPI version](https://badge.fury.io/py/cardiac-shared.svg)](https://pypi.org/project/cardiac-shared/)
[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)

**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.0.1 | **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
- **Modern Python** — Requires Python 3.10+ for cleaner code and better type support
- **Streamlined Architecture** — Focused on the core utilities every cardiac imaging
  project needs, with clear extension points for project-specific features

## Installation

```bash
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

```python
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

```python
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

```python
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

```python
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:

```python
>>> 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](CHANGELOG.md) for full version history.

## License

MIT License - see [LICENSE](LICENSE) for details.
