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

Many dataasets are supported, and it is easy to add more via YAML configs!

Installation

Using Conda (Recommended)

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

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

# Activate environment
conda activate cine2nifti

# Aternatively , use pip only 
# python -m venv venv; source venv/bin/activate  # On Windows: venv\Scripts\activate

# 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.