Output Formats and File Naming

dcm2niix supports multiple output formats and provides extensive file naming customization through postfixes and patterns.

Capabilities

Output File Formats

Export converted medical images to various formats.

-e n  # NIfTI format (default)

NIfTI (Neuroimaging Informatics Technology Initiative)

• Extensions: .nii (uncompressed) or .nii.gz (gzip compressed)
• Format: NIfTI-1.1 standard
• Coordinate system: RAS+ (Right-Anterior-Superior, Cartesian)
• Data types: INT16, UINT16, FLOAT32, RGB24, and others
• Usage: Standard format for neuroimaging analysis

-e y  # NRRD format

NRRD (Nearly Raw Raster Data)

• Extension: .nrrd
• Format: N-dimensional rectilinear grid with ASCII header
• Usage: Scientific visualization, medical image processing
• Features: Self-describing header, multiple data types, compression support

-e o  # MGH/MGZ format

MGH/MGZ (Massachusetts General Hospital format)

• Extensions: .mgh (uncompressed) or .mgz (gzip compressed)
• Format: FreeSurfer native format
• Usage: FreeSurfer neuroimaging suite workflows
• Features: Simple binary format with fixed header

-e j  # JNIfTI format (requires compile support)

JNIfTI (JSON NIfTI)

• Extension: .jnii
• Format: JSON-based NIfTI encoding
• Usage: Machine-readable, human-inspectable neuroimaging data
• Features: Metadata and image data in single JSON file
• Note: Requires JNIfTI support compiled into binary

-e b  # BJNIfTI format (requires compile support)

BJNIfTI (Binary JSON NIfTI)

• Extension: .bnii
• Format: Binary JSON-based NIfTI encoding
• Usage: Compact JSON-based format with binary data sections
• Features: Combines JSON metadata with efficient binary storage
• Note: Requires JNIfTI support compiled into binary

Compression Options

Control output file compression.

-z y   # Use pigz (parallel gzip)
-z i   # Internal compression (miniz/zlib)
-z n   # No compression
-z 3   # No compression, force 3D output
-z o   # Optimal pigz (Unix only)

Pigz Compression (-z y)

• Parallel gzip compression using pigz tool (must be installed separately)
• Fastest compression method for multi-core systems
• Same output format as standard gzip (.nii.gz)

Internal Compression (-z i)

• Uses built-in miniz or zlib library
• No external dependencies required
• Single-threaded compression

Compression Levels (-1 to -9)

• -1: Fastest compression, larger files
• -6: Default balance (MZ_DEFAULT_LEVEL)
• -9: Smallest files, slower compression

File Naming Patterns

Customize output filenames using template placeholders.

-f <pattern>

Available Placeholders:

Patient identifiers (anonymized when -ba y):

• %i = Patient ID (0010,0020)
• %n = Patient name (0010,0010)
• %w = Weird/personal data (DOB, gender, weight, institution - contains PHI)

Study identifiers:

• %g = Accession number (0008,0050)
• %x = Study ID (0020,0010)
• %k = Study instance UID (0020,000D)
• %t = Study time (formatted from 0008,0020 and 0008,0030)
• %l = Local procedure step description (0040,0254)

Series identifiers:

• %s = Series number (0020,0011)
• %j = Series instance UID (0020,000E)
• %d = Series description (0008,103E)
• %p = Protocol name (0018,1030)
• %z = Sequence name (0018,0024)
• %q = Sequence number (if compiled with mySegmentByAcq)

Instance identifiers:

• %r = Instance number (0020,0013)
• %u = Acquisition number (0020,0012)
• %e = Echo number (0018,0086)
• %y = Youth in series (GE RawDataRunNumber or TemporalPosition)

Hardware identifiers:

• %m = Manufacturer (short: GE, Ph, Si, To, UI, NA)
• %v = Vendor (long: Siemens, Philips, GE, etc.)
• %a = Antenna/coil name (Siemens-specific, 0051,100F)

File/folder identifiers:

• %f = Folder name (directory containing first DICOM)
• %b = Basename (filename of first DICOM file)

Other:

• %c = Comments (DICOM tag 0020,4000)
• %h = Hazardous/experimental BIDS naming (ReproIn format, use with caution)
• %o = Media object instance UID (0002,0003)

Default pattern: %f_%p_%t_%s

Automatic Postfixes

dcm2niix automatically appends postfixes to disambiguate multi-volume outputs (unless --terse is used).

Dimensional Postfixes

_e<N>        # Echo number (multi-echo sequences)
_c<N>        # Coil element (uncombined data)
_i<N>        # Image number (non-parallel slices)
_r<N>        # Repetition (multiple repetition times)
_t           # Trigger delay time (cardiac gating)

Examples:

• T2_FLAIR_5_e1.nii - First echo of multi-echo T2 FLAIR
• T1_MPRAGE_3_e1.nii, T1_MPRAGE_3_e2.nii - Two echoes
• EPI_bold_10_c1.nii through EPI_bold_10_c32.nii - 32-element coil array

Image Type Postfixes

_real        # Real component of complex image
_imaginary   # Imaginary component of complex image
_ph          # Phase map
_phMag       # Phase and magnitude combined as 4th dimension
_ADC         # Philips derived ADC volume
_fieldmaphz  # Philips B0 field map in Hz

Examples:

• GRE_5_real.nii, GRE_5_imaginary.nii - Complex gradient echo
• B0map_7_fieldmaphz.nii - Field map in Hertz
• DWI_12_ADC.nii - Apparent diffusion coefficient map

Processing Postfixes

_MoCo        # Motion corrected variant
_Eq          # Equidistant spacing (resliced)
_Tilt        # CT gantry tilt correction applied

Examples:

• EPI_8_MoCo.nii - Motion-corrected EPI
• CT_spine_2_Tilt.nii - Gantry tilt corrected

Vendor-Specific Postfixes

_Raw         # Philips Raw Data Storage (XX_*)
_PS          # Philips Presentation State (PS_*)

Overlay Postfixes

_ROI<N>      # DICOM binary overlay (N = 1-16)

Examples:

• T1_3_ROI1.nii - First region of interest overlay
• T2_5_ROI2.nii - Second overlay

Name Conflict Resolution

Control behavior when output files already exist.

-w 0  # Skip duplicates (don't overwrite)
-w 1  # Overwrite existing files
-w 2  # Add suffix (default)

Skip Mode (-w 0):

• Existing files are not overwritten
• No output generated if file exists
• Console message indicates file was skipped

Overwrite Mode (-w 1):

• Existing files are replaced
• No backup created
• Use with caution

Add Suffix Mode (-w 2, default):

• Appends _i, _j, _k, etc. to create unique filename
• Original file preserved
• Example: T1.nii already exists → creates T1_i.nii

Terse Mode

Disable automatic postfix generation.

--terse

When enabled:

• Omits _e, _c, _i, _r dimensional postfixes
• Retains only essential type postfixes (_real, _imaginary, _ph)
• Can cause files to overwrite each other if multiple volumes exist
• Use only when certain that series produces single volume

Usage Examples

NIfTI with Compression

dcm2niix -z y -o /output /input

Creates compressed NIfTI files (.nii.gz) using pigz.

NRRD Format for Visualization

dcm2niix -e y -o /output/nrrd /input/dicom

Exports to NRRD format for use in scientific visualization tools.

MGH for FreeSurfer

dcm2niix -e o -z y /freesurfer/input

Creates compressed MGH files (.mgz) for FreeSurfer processing.

Custom Filename Pattern

dcm2niix -f sub-%i_ses-01_run-%s_%d /input

Example output: sub-12345_ses-01_run-5_T1_MPRAGE.nii

Protocol and Series Only

dcm2niix -f %p_%s -o /output /input

Simple naming: T1_MPRAGE_5.nii, T2_FLAIR_8.nii

Terse Output

dcm2niix --terse -f %p /single/echo/input

Minimal naming without postfixes: T1_MPRAGE.nii

Maximum Compression

dcm2niix -9 -z y -o /output /input

Highest compression level (9) with pigz parallelization.

Overwrite Existing Files

dcm2niix -w 1 -o /output /input

Replaces existing NIfTI files without creating duplicates.

Skip Existing Files

dcm2niix -w 0 -o /output /input

Only converts DICOM series that don't already have NIfTI outputs.

File Extension Reference

Notes

• NIfTI files use RAS+ coordinate system (neurological convention)
• Compressed files (.nii.gz, .mgz) are compatible with most neuroimaging software
• Pigz requires separate installation: brew install pigz (macOS) or apt-get install pigz (Ubuntu)
• JNIfTI and BJNIfTI formats are experimental and require special compile flags
• BIDS JSON sidecars (.json) are created alongside primary output files when -b y