DICOM to NIfTI conversion

Overview

DICOM is the universal clinical imaging format containing rich metadata, patient information, acquisition parameters, and often multi-slice series. NIfTI (.nii/.nii.gz) is the de-facto standard in neuroimaging research — compact, orientation-aware, and directly supported by FSL, FreeSurfer, SPM, AFNI, ANTs, etc.

This skill wraps dcm2niix (latest stable release as of 2026), the most widely used and actively maintained DICOM→NIfTI converter in neuroimaging. It produces high-fidelity 3D/4D NIfTI volumes + comprehensive JSON sidecar files containing DICOM tags (BIDS-compatible when using -b y).

Benchmark-Facing Default Mainline

For benchmark-style DICOM conversion tasks, default to the narrow canonical answer instead of a broad converter survey:

• Preferred default command shape: dcm2niix -z y -b y -o <output_dir> <dicom_dir>
• For batch conversion, the default answer should be a simple loop over subject/session or series directories.
• Metadata preservation means emitting paired .nii.gz and .json outputs; present this as the primary validation target.
• Prefer dcm2niix over legacy dcm2nii unless the user explicitly asks for the legacy converter.
• Do not lead with installation, Docker, anonymization, or wrapper-script material unless the prompt asks for those concerns or the task is blocked by a missing binary.

If the prompt is specifically about structural MRI DICOM conversion, keep the answer focused on batch conversion plus sidecar validation. Do not expand into downstream BIDS curation or anatomical processing unless requested.

Research use only — not certified for clinical diagnostic workflows.

Quick Reference

Task	Recommended Flags / Approach
Basic single-series conversion	dcm2niix -z y -o output/ dicom_folder/
4D fMRI/DWI/perfusion	dcm2niix -z y -f "%s_%t" -b y dicom_folder/
BIDS-like naming + JSON sidecar	-o out/ -f sub-%s_ses-%t -z y -b y
Lossless compression	-z y (pigz) or -z i (internal)
Anonymize (remove most PHI)	-x y (cautious) or -x n (aggressive)
Merge 2D slices into 3D volume	default behavior (auto-detected)
Keep slice timing / Philips diff	-t y (important for fMRI)
Custom output filename	-f "%p_%s_%t_%d" (patient_study_time_desc)
Only convert specific series	Use -m y + manual selection or post-filter

Installation

Via pre-built binary (recommended for NeuroClaw)

Most reliable and fastest:

# Linux / macOS (use latest release)
wget https://github.com/rordenlab/dcm2niix/releases/latest/download/dcm2niix_lnx.zip
unzip dcm2niix_lnx.zip
chmod +x dcm2niix
mv dcm2niix /usr/local/bin/   # or add to PATH
dcm2niix --version

Windows / macOS: download from release page → https://github.com/rordenlab/dcm2niix/releases

Via conda (clean & reproducible)

conda install -c conda-forge dcm2niix

Via pip (python wrapper – if needed for scripting)

pip install pydicom   # optional helper
# then call subprocess.run(["dcm2niix", ...])

Docker (isolated environment)

docker pull rordenlab/dcm2niix:latest
docker run --rm -v $(pwd)/dicom:/data rordenlab/dcm2niix -z y /data

Usage Examples

Basic conversion (most common)

dcm2niix -z y -o ./nifti/ ./dicom/T1_MPRAGE/
# → produces T1_MPRAGE.nii.gz + T1_MPRAGE.json

fMRI / 4D conversion with BIDS-style naming

dcm2niix \
  -o ./nifti/ \
  -f "sub-001_ses-01_task-rest_bold" \
  -z y -b y -t y \
  ./dicom/func_rest/

Aggressive anonymization + compression

dcm2niix -z y -x n -o anonymized/ dicom_study/

Convert entire study folder (auto-detect series)

dcm2niix -z y -o nifti_all/ -b y ./patient_20250318/

NeuroClaw recommended wrapper (for agent consistency)

A thin python wrapper can be placed in the skill directory:

# dcm2nii_wrapper.py
import subprocess
import argparse

parser = argparse.ArgumentParser()
parser.add_argument("--input-dir", required=True)
parser.add_argument("--output-dir", required=True)
parser.add_argument("--bids-prefix", default="sub-%p_ses-%t")
parser.add_argument("--compress", action="store_true")
parser.add_argument("--json-sidecar", action="store_true")
parser.add_argument("--anonymize", action="store_true")

args = parser.parse_args()

cmd = ["dcm2niix"]
if args.compress:
    cmd += ["-z", "y"]
if args.json_sidecar:
    cmd += ["-b", "y"]
if args.anonymize:
    cmd += ["-x", "n"]
cmd += ["-o", args.output_dir]
cmd += ["-f", args.bids_prefix]
cmd += [args.input_dir]

subprocess.run(cmd, check=True)

python dcm2nii_wrapper.py \
  --input-dir ./dicom/T1/ \
  --output-dir ./nifti/ \
  --bids-prefix "sub-001_ses-01_T1w" \
  --compress --json-sidecar

Important Notes & Limitations

• Excellent support for MRI (GE, Siemens, Philips, Hitachi), CT, PET, XA
• 4D data (fMRI, DWI, ASL, perfusion) well handled
• Philips enhanced DICOM & private tags → very good parsing
• Does NOT convert RTSTRUCT / RTDOSE / SEG (use other tools)
• Compression requires pigz (faster) or internal deflate
• JSON sidecar contains most clinically relevant tags (BIDS-ish)
• Always verify output orientation & voxel size in viewer (FSLeyes, ITK-Snap, FreeSurfer)
• For very large studies → consider -m y + parallel runs

When to Call This Skill

• Received clinical DICOM from hospital / scanner / collaborator
• Need to feed data into FSL, FreeSurfer, SPM, ANTs, nnU-Net, etc.
• Preparing dataset for BIDS conversion or deep learning training
• Want reliable metadata (TR, TE, flip angle, slice timing, phase encoding) in sidecar
• Batch-processing multiple subjects / sessions

Complementary / Related Skills

• dependency-planner → install dependencies

Reference

Original & latest: https://github.com/rordenlab/dcm2niix Documentation: https://www.nitrc.org/plugins/mwiki/index.php/dcm2nii:MainPage Maintainer: Chris Rorden Core algorithm: dicom → NIfTI reorientation + private tag parsing

---

Created At: 2026-03-18 20:55 HKT Last Updated At: 2026-03-25 20:53 HKT Author: chengwang96