dcm2niix

dcm2niix is a tool designed to convert DICOM images to the NIfTI format. It supports DICOM files from various manufacturers, including Mediso.

Mediso files (used in preclinical PET, MRI, SPECT, and CT) typically use public tags and generate simple DICOM headers. While they may lack the extensive metadata found in other manufacturers' files, their simplicity makes them straightforward to parse with dcm2niix.

dcm2niix is a core dependency for many BIDS (Brain Imaging Data Structure) converters. If your goal is to convert DICOM data into BIDS-compliant datasets, consider these tools that leverage dcm2niix:

• Dcm2Bids: A popular tool for creating BIDS datasets.
• BIDScoin: A DICOM to BIDS converter with a GUI.
• ezBIDS: A web service for converting DICOM directories to BIDS.
• heudiconv: Can use dcm2niix to create BIDS datasets.
• niix2bids: Specifically attempts to convert Siemens MRI images converted by dcm2niix to BIDS.
• py2bids: A Python wrapper for DICOM to BIDS conversion.

For developers looking to integrate dcm2niix into automated pipelines using specific programming languages:

• Python:
  • dcm2niixpy: A Python package of dcm2niix.
  • pydcm2niix: A Python module for working with dcm2niix.
  • bidsify: Converts DICOM and Philips PAR/REC to BIDS.
  • conversion: A library to convert NIfTI to NRRD.
• R:
  • dcm2niir: An R wrapper for dcm2niix.
  • divest: An R interface to dcm2niix.
• Matlab:
  • dicom2nifti_batch: A Matlab script for automating dcm2niix.

dcm2niix supports converting Philips PAR/REC format images to NIfTI.

Important Compatibility Notes:

• XML/REC Support: dcm2niix does not support the Philips XML/REC format (where information is stored in an XML file instead of a plain text .par file).
• Licensing: While DICOM and XML/REC are supported in the base product, NIfTI conversion for PAR/REC may require a research agreement depending on the version/release.
• Volume Integrity: dcm2niix assumes data is stored in complete 3D volumes. It will fail to convert datasets where a scan was interrupted mid-volume (e.g., the number of 2D slices is not divisible by the number of slices in a volume). If this occurs, the tool suggests using dicm2nii instead.

The dcm2niix tool supports the conversion of UIH (United Imaging Healthcare) DICOM format images into NIfTI and BIDS format files. UIH data may be archived in two ways:

1. One DICOM file per slice.
2. One DICOM file per volume (referred to by UIH as GRID format, similar to the Siemens Mosaic format).

dcm2niix uses specific private DICOM tags to correctly interpret and generate these formats.

The BidsGuess feature is an experimental tool designed exclusively for wrapper developers who build BIDS-compatible dataset converters. It is not intended to be used in isolation to create BIDS files.

Starting from dcm2niix version v1.0.20230731 and later, the tool inserts a BidsGuess field into the BIDS JSON sidecar files. This field provides suggested BIDS <datatype> and <entities> (like _acq- and _run-) based on the DICOM series. This helps wrappers automate conversion or flag improbable naming configurations.

Note: BidsGuess converts each DICOM series in isolation and lacks context regarding user intention. It cannot resolve IntendedFor metadata, distinguish fMRI tasks from resting state, or determine BIDS subject IDs, session numbers, or dataset descriptions.

When working with transfer syntaxes and encapsulation:

• JPEG2000: kCompressJP2K is the transfer syntax marker, but it does not act as the runtime decode toggle. Use compressFlag to control runtime decoding.
• RLE: Uses the kCompressRLE marker.
• JPEG Lossless C3: If a multi-item offset table is present, it bypasses the generic dti4D->offsetTable[] loop.
• Multi-fragment Single-frame Encapsulation: This is only admitted when numberOfFrames <= 1 and utilizes reassembleEncapsulatedFragments().

For Philips ASL sequences, dcm2niix (v1.0.20210819 and later) attempts to store volumes in temporal order, regardless of whether the input is classic or enhanced DICOM.

Note on BIDS Compliance: BIDS BEP005 requires ASL sequences to report PostLabelingDelay relative to the first slice of the volume. Philips, however, reports label delay independently for each slice using tags 0020,9153 and 0018,1060. While this may allow for slice-timing inference, users should be aware of this discrepancy when preparing BIDS-compliant datasets.

The parser includes specific gates for geometry and warning suppression:

• 3D PhaseEncodingDirection: The gate is set to !SE to prevent regressions in SPACE/FLAIR sequences while still allowing 3D EPI/GRE and detected EPI (where ETL is unset, see bandwidthPerPixelPhaseEncode gate).
• Warning Suppression: To prevent diagnostic cascades, slice-direction and "missing 0020,0037" orientation warnings are intentionally suppressed for derived or non-spatial images (e.g., Siemens color-FA).

You can emit ReproIn/heudiconv-style BIDS filenames in a single pass using the -f %H format specifier. This is often used in conjunction with the following flags:

• -bi: Subject ID
• -bv: Session ID
• -br: Project subdirectory

For complex cross-series concerns (like fmap pairing or session backfilling), use the companion script tools/reproinx.py. This script supports anonymization via the -ba flag with three modes:

• y (default): Strip dates and patient PII.
• n: Keep both dates and PII.
• o: Omit patient PII only (keeps acquisition timestamps for better pairing).

dcm2niix -f %H -bi subject_id -bv session_id /path/to/dicom

Philips often generates Instance Number (0020,0013) values in a random order, which can cause jumbled images in standard DICOM viewers.

dcm2niix uses heuristics to automatically resolve this ordering:

• fMRI: Ordered temporally.
• Diffusion: Ordered by gradient number (with derived TRACE/ADC maps as the final volume).
• ASL: Follows the hierarchical order of repeat -> phase -> label/control.

Warning: These heuristics are based on observed patterns and may not be robust if the DICOM data has been manipulated (e.g., anonymized or processed by a PACS). Always verify the volume order for critical analyses.