dcm2niix

dcm2niix is a command-line application with Python bindings that converts medical imaging data from the DICOM format to the NIfTI format. The tool is specifically designed for neuroimaging data and handles vendor-specific DICOM interpretations. It generates BIDS-compliant JSON sidecars containing metadata in a vendor-agnostic, human-readable format.

Package Information

• Package Name: dcm2niix
• Package Type: pypi
• Language: C++ (core application), Python (bindings)
• Installation: pip install dcm2niix

Quick Start

Installation

pip install dcm2niix

Basic Python Usage

from dcm2niix import main

# Convert DICOM folder to NIfTI
exit_code = main(["/path/to/dicom/folder"])

Basic Command-Line Usage

# Basic conversion
dcm2niix /path/to/dicom/folder

# Compressed output with BIDS JSON
dcm2niix -z y -b y -o /output/folder /input/folder

See Quick Start Guide for detailed instructions.

Core Concepts

Architecture

dcm2niix wraps a high-performance C++ binary via Python subprocess:

• DICOM Parser: Handles multiple transfer syntaxes (RLE, JPEG, JPEG-LS, JPEG2000)
• NIfTI Converter: Generates NIfTI-1.1 format files with proper orientation
• BIDS JSON Generator: Extracts comprehensive metadata to JSON sidecars
• Vendor-Specific Handlers: Specialized parsing for Siemens, Philips, and GE

Python API

from dcm2niix import main, bin, bin_path, __version__

• main(args, **run_kwargs): Execute dcm2niix binary with arguments
• bin: Path to dcm2niix binary (string)
• bin_path: Path object pointing to binary
• __version__: Package version string

→ Python API Reference

Command-Line Interface

dcm2niix [options] <in_folder>

Common options:

• -o <dir>: Output directory
• -f <pattern>: Filename pattern
• -z <y/i/n>: Compression mode
• -b <y/n/o>: BIDS sidecar generation
• -i <y/n>: Ignore derived/localizer images
• -v <0/1/2>: Verbosity level

→ CLI Options Reference

Quick Reference

Exit Codes

→ Complete Exit Code Reference

Common CLI Options

→ Complete CLI Reference

Filename Placeholders

Common placeholders for -f option:

• %p: Protocol name
• %s: Series number
• %i: Patient ID
• %t: Study time
• %d: Series description
• %e: Echo number

→ Complete Placeholder Reference

Capabilities

Output Formats

• NIfTI (.nii/.nii.gz): Standard neuroimaging format
• NRRD (.nrrd): Scientific visualization
• MGH/MGZ (.mgh/.mgz): FreeSurfer format
• JNIfTI/BJNIfTI: JSON-based formats (requires compile support)

→ Output Formats Reference

BIDS JSON Metadata

Generates BIDS-compliant JSON sidecars with:

• Acquisition parameters (TR, TE, flip angle)
• Equipment information
• Image geometry and orientation
• Timing information
• Vendor-specific metadata

→ BIDS JSON Reference

Image Processing

• 16-bit range scaling
• 3D acquisition cropping
• CT gantry tilt correction
• Philips precise float scaling
• Complex image separation
• Multi-echo/multi-coil handling

→ Image Processing Reference

Filtering and Selection

• Ignore derived/localizer images
• Select specific series by CRC
• Control 2D slice merging
• Directory search depth control

→ Filtering Reference

Batch Processing

Process multiple DICOM directories using YAML configuration files via dcm2niibatch executable.

→ Batch Processing Reference

Supported Formats

• Transfer Syntaxes: Uncompressed, RLE, JPEG, JPEG-LS, JPEG2000
• Modalities: MR, CT, PET, US, CR
• Vendors: Siemens, GE, Philips, Canon, Toshiba, UIH, and others

→ Supported Formats Reference

Common Workflows

BIDS-Compliant Conversion

from dcm2niix import main

exit_code = main([
    "-z", "y",           # Compress output
    "-b", "y",           # Generate BIDS JSON
    "-ba", "y",          # Anonymize
    "-o", "/bids/output",
    "/dicom/input"
])

→ More Workflows

Error Handling

from dcm2niix import main

exit_code = main(["/input/folder"])

if exit_code == 0:
    print("Success")
elif exit_code == 2:
    print("No valid DICOM files found")
elif exit_code == 4:
    print("Corrupt DICOM file detected")

→ Complete Error Handling Guide

Batch Processing

from dcm2niix import main
from pathlib import Path

for subject_dir in Path("/data/subjects").iterdir():
    output_dir = Path("/data/nifti") / subject_dir.name
    output_dir.mkdir(parents=True, exist_ok=True)
    
    main(["-z", "y", "-b", "y", "-o", str(output_dir), str(subject_dir)])

→ Advanced Batch Processing

Documentation Structure

Guides

Step-by-step instructions for common tasks:

• Quick Start Guide - Getting started with dcm2niix

Examples

Real-world scenarios and use cases:

• Real-World Scenarios - Comprehensive usage examples
• Edge Cases - Advanced scenarios and troubleshooting

Reference

Complete API specifications and detailed documentation:

• Python API Reference - Complete Python API documentation
• CLI Options Reference - All command-line options
• BIDS JSON Reference - JSON metadata fields
• Image Processing Reference - Processing features
• Output Formats Reference - File formats and naming
• Filtering Reference - Series selection and filtering
• Batch Processing Reference - YAML batch configuration
• Supported Formats Reference - DICOM formats and vendors

Troubleshooting

Common Issues

No output files generated

• Check exit code (2 = no DICOM files, 5 = invalid input, 6 = invalid output)
• Verify input directory contains DICOM files
• Check output directory permissions

Wrong orientation

• dcm2niix converts DICOM LPS to NIfTI RAS+ automatically
• Check ImageOrientationPatientDICOM field in BIDS JSON

Multiple unwanted files

• Use -i y to ignore derived/localizer images
• Use -n <CRC> to convert specific series only

→ Complete Troubleshooting Guide

Performance Tips

• Use -z y with pigz for fast parallel compression
• Use -a y for organized PACS data (assumes series in same folder)
• Use -d 1 for shallow directory search when data is organized
• Use -i y to skip derived/scout images

→ Performance Optimization Guide

Vendor-Specific Notes

Siemens

• Mosaic format automatically detected and converted
• CSA header information extracted to BIDS JSON

Philips

• Use -p y for precise float scaling (required for quantitative analysis)
• Enhanced DICOM format supported

GE

• Diffusion gradient cycling mode auto-detected
• Use --diffCyclingModeGE to override if needed

→ Vendor-Specific Guide

Version Information

from dcm2niix import __version__
print(__version__)

dcm2niix --version

Additional Resources

• GitHub Repository
• BIDS Specification
• NIfTI Format