cine2nifti

A unified, configurable cardiac CINE MRI DICOM to NIfTI converter that handles multiple dataset structures through YAML configuration files.

Features

• 🔧 Configurable: Add new datasets via YAML files without code changes
• 🎯 Multiple Strategies: Handles folder-based, recursive, and archive-based (ZIP) DICOM structures
• 🚀 Parallel Processing: Optional multi-core processing for large datasets
• 📊 Progress Tracking: Beautiful progress bars and logging
• ✅ Validation: Config validation with Pydantic
• 🔄 Resume Support: Continue interrupted conversions

Supported Datasets

• Mavacamten
• REMIT
• ROSIE
• TRED-HF
• UK Biobank (UKBB)
• Easy to add more via YAML configs!

Installation

Using Conda (Recommended)

# Clone the repository
git clone https://github.com/yourusername/cine2nifti.git
cd cine2nifti

# Create conda environment
conda env create -f environment.yml

# Activate environment
conda activate cine2nifti

# Install package in editable mode
pip install -e .

Using pip only

# Clone the repository
git clone https://github.com/yourusername/cine2nifti.git
cd cine2nifti

# Create virtual environment
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt

# Install package in editable mode
pip install -e .

Quick Start

# Convert a dataset using predefined config
cine2nifti convert --dataset mavacamten

# Convert specific subjects
cine2nifti convert --dataset ukbb --subjects SUB001,SUB002,SUB003

# Use custom config
cine2nifti convert --config my_custom_config.yaml

# Validate a config file
cine2nifti validate --config configs/datasets/mavacamten.yaml

# List available datasets
cine2nifti list-datasets

Configuration

See configs/datasets/ for examples. Each dataset needs a YAML config specifying:

• Paths to DICOM and output directories
• File organization strategy
• Series identification rules
• View definitions (2ch, 3ch, 4ch, SAX)
• Processing options

Development

# Install development dependencies
pip install -r requirements-dev.txt

# Run tests
pytest

# Run tests with coverage
pytest --cov=cine2nifti

# Format code
black src/

# Lint
ruff check src/

Project Structure

cine2nifti/
├── configs/datasets/      # Dataset-specific YAML configs
├── src/cine2nifti/       # Main package
│   ├── core/             # Core conversion logic
│   ├── strategies/       # File organization strategies
│   ├── parsers/          # Series and view parsing
│   ├── utils/            # Utilities
│   └── cli/              # Command-line interface
├── tests/                # Test suite
└── docs/                 # Documentation

License

MIT License

Contributing

Contributions welcome! Please open an issue or PR.