Filtering and Selection Options

Control which DICOM images are converted by filtering and selecting specific series or image types.

Capabilities

Ignore Derived and 2D Images

Filter out secondary captures, scout images, and 2D slices.

-i <y/n>

Ignore derived, localizer, and 2D images:

• y = skip derived images, localizers, and 2D acquisitions
• n = include all images (default)

What Gets Filtered:

• Derived Images: Secondary captures, reformats, processed images (ImageType contains "DERIVED")
• Localizer Images: Scout scans, survey images (ImageType contains "LOCALIZER")
• 2D Images: Single-slice acquisitions when 3D volumes are expected

When to Use:

• Processing large datasets with many derived/scout images
• Focus only on primary acquisitions
• Reduce clutter in output directory

Example:

dcm2niix -i y /mixed/dicom/folder

Series Selection by CRC

Convert only specific series identified by CRC checksum.

-n <CRC_number>

Only convert series matching specified CRC. Can be used up to 16 times for multiple series.

How It Works:

• dcm2niix calculates CRC checksum for each series
• Use -q l to list all series with their CRC values
• Specify desired CRC values with -n to convert only those series

Use Cases:

• Convert specific sequences from large multi-series exam
• Reproducible series selection across subjects
• Avoid converting unwanted series

Example:

# First, list series to find CRC values
dcm2niix -q l /dicom/folder

# Then convert only desired series
dcm2niix -n 52301 -n 52305 -n 52310 /dicom/folder

Single File Mode

Convert a single DICOM file without searching the folder.

-s <y/n>

Single file mode:

• y = only convert the specified DICOM file
• n = search folder for related files (default)

When to Use:

• Processing individual DICOM files
• Testing conversion on single image
• Converting single-slice localizer

Example:

dcm2niix -s y /path/to/single_image.dcm

Note: Output may be incomplete if the file is part of a multi-slice volume.

2D Slice Merging Control

Control whether 2D slices from the same series are merged into volumes.

-m <n/y/0/1/2>

Merge 2D slices mode:

• n or 0 = don't merge, create separate file for each slice
• y or 1 = merge all 2D slices from same series into volume
• 2 = auto mode (default, intelligent merging)

Auto Mode Behavior:

• Merges slices when they form a consistent 3D/4D volume
• Keeps slices separate when they have different:
  • Echo times
  • Acquisition times (beyond threshold)
  • Image orientations
  • Exposure settings (CT)
  • Repetition times (within series)

Use Cases:

• n: Keep 2D slices separate for manual inspection
• y: Force merging even with parameter variations (may create incorrect volumes)
• 2: Recommended for most use cases, smart merging

Example:

# Don't merge, one file per slice
dcm2niix -m n /2d/slices/folder

# Force merge all slices
dcm2niix -m y /2d/slices/folder

# Auto mode (default)
dcm2niix -m 2 /2d/slices/folder

Directory Search Depth

Control how deep to search for DICOM files in subdirectories.

-d <0-9>

Search depth (0-9 levels):

• 0 = only search specified folder, no subdirectories
• 1 = search one level deep
• 5 = search five levels deep (default)
• 9 = search nine levels deep

When to Adjust:

• Large nested directory structures: increase depth
• Flat directory structure: set to 0 or 1 for faster processing
• Avoid searching unrelated subdirectories: decrease depth

Example:

# Only search specified folder
dcm2niix -d 0 /flat/dicom/folder

# Search deeply nested structure
dcm2niix -d 9 /deeply/nested/dicoms

Adjacent DICOMs Mode

Optimize for datasets where series are pre-organized into folders.

-a <y/n>

Adjacent DICOMs:

• y = assume all images from same series are in same folder (faster)
• n = search all folders for series members (default, safer)

When to Use:

• y: Pre-organized datasets (e.g., PACS exports where each series has its own folder)
• n: Mixed datasets where series may span multiple folders

Performance:

• Adjacent mode is significantly faster for large datasets
• Non-adjacent mode is safer but slower

Example:

# Fast mode for organized data
dcm2niix -a y /organized/pacs/export

# Safe mode for mixed data
dcm2niix -a n /mixed/dicoms

Search Reporting

Control console output during DICOM file discovery.

-q <y/l/n>

Directory search reporting:

• y = show number of DICOM files found (default)
• l = list all DICOM files found with details (including CRC)
• n = no search reporting (quiet)

Use Cases:

• y: Standard feedback during conversion
• l: Identify series CRC values for selective conversion with -n
• n: Minimal output for batch processing scripts

Example:

# List all series with CRC values
dcm2niix -q l /dicom/folder

Output Format (with -q l):

Found 240 DICOM files in /dicom/folder
Series 001: T1_MPRAGE [52301] - 176 files
Series 002: T2_FLAIR [52305] - 32 files
Series 003: BOLD_fMRI [52310] - 240 files

Ignore Series Instance UID

Allow merging of series with different SeriesInstanceUIDs.

# Controlled by isIgnoreSeriesInstanceUID setting (default: false)
# Typically set via configuration file

What This Does:

• By default, series are separated by SeriesInstanceUID
• When enabled, merges series based on other criteria (series number, description)
• Useful for some older scanners or non-conformant DICOM

Risk:

• May merge unrelated series if SeriesNumber is reused

Filtering Workflow Examples

Clean Dataset: Primary Sequences Only

dcm2niix -i y -d 5 /mixed/dicom/export

Converts only primary acquisitions, skipping scouts, localizers, and derived images.

Specific Series Conversion

# Step 1: Identify series
dcm2niix -q l /dicom/folder

# Step 2: Convert only T1 MPRAGE and BOLD
dcm2niix -n 52301 -n 52310 /dicom/folder

Fast Conversion of Organized Data

dcm2niix -a y -d 1 -q y /organized/pacs/export

Assumes adjacent organization, shallow search, with progress feedback.

Single Sequence from Exam

dcm2niix -n 52305 -i y /large/exam/folder

Converts only series 52305, ignoring derived/localizer images.

Conservative Merging

dcm2niix -m 2 -i n /mixed/2d/slices

Auto mode for slice merging, includes all image types.

No Merging, All Slices Separate

dcm2niix -m n /2d/localizers

Creates one NIfTI file per DICOM slice, useful for quality control.

Shallow Search, Quiet Output

dcm2niix -d 1 -q n /flat/dicom/folder

Searches only one level deep, minimal console output.

Filtering Decision Tree

Question 1: Do you want to include derived/localizer images?

• No → Use -i y
• Yes → Use -i n (default)

Question 2: Do you know which series to convert?

• Yes → Use -q l to find CRC, then -n <CRC> for each series
• No → Convert all (default)

Question 3: Are series organized into separate folders?

• Yes → Use -a y for faster conversion
• No → Use -a n (default)

Question 4: How should 2D slices be handled?

• Merge into volumes → Use -m 2 (auto, default)
• Force merge → Use -m y
• Keep separate → Use -m n

Question 5: How deep is your directory structure?

• Flat → Use -d 0 or -d 1
• Nested → Use -d 5 (default) or higher

Notes

• Filtering is applied during DICOM discovery phase, before conversion
• Series CRC is calculated from series UID, number, and description
• Derived images have "DERIVED" in ImageType DICOM tag (0008,0008)
• Localizers have "LOCALIZER" in ImageType or are identified by slice count
• 2D images are typically single-slice acquisitions (number of slices = 1)
• Some filtered images may still appear in verbose output but won't be converted
• Filtering reduces processing time and output clutter significantly