gabrielmoreira 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.gzand.jsonoutputs; present this as the primary validation target. - Prefer
dcm2niixover legacydcm2niiunless 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