Nii2dcm

NIfTI to DICOM conversion

Overview

A NIfTI file (.nii/.nii.gz) is a compact format widely used in neuroimaging research, typically stripped of patient metadata.
DICOM is the clinical standard for medical images, including rich metadata and interoperability with PACS/hospital systems.

This skill wraps nii2dcm (v0.1.6, May 2025) to convert NIfTI volumes into single-frame DICOM series (multi-slice 2D), primarily for MRI-derived data.
It supports modality-specific metadata (MR, SVR) and optional metadata transfer from a reference DICOM file.

Research use only — not certified for clinical diagnosis, treatment, or patient care.

Quick Reference

Installation

Via pip (recommended for NeuroClaw)

pip install nii2dcm>=0.1.6
# or latest
pip install git+https://github.com/tomaroberts/nii2dcm.git

From source (for customization / debugging)

git clone https://github.com/tomaroberts/nii2dcm.git
cd nii2dcm
python -m venv venv
source venv/bin/activate
pip install --upgrade pip
pip install -r requirements.txt
pip install .
nii2dcm -h   # Verify

Core dependencies (automatically installed):

• highdicom >= 0.9.0
• SimpleITK >= 2.2.0
• pydicom
• numpy

Docker alternative (if preferred in containerized env):

docker pull ghcr.io/tomaroberts/nii2dcm:latest
docker tag ghcr.io/tomaroberts/nii2dcm:latest nii2dcm
docker run nii2dcm -v   # check version

Usage Examples

Core command pattern:

nii2dcm <input.nii[.gz]> <output_directory> [options]

Create standard MRI DICOM series

nii2dcm processed_t1.nii.gz dicom_mr/ -d MR

Create SVR (swept volume reconstruction) series

nii2dcm svr_recon.nii.gz dicom_svr/ -d SVR

Generic conversion (no modality metadata)

nii2dcm seg_result.nii.gz dicom_generic/

With reference DICOM (copy patient/study metadata)

nii2dcm hippocampus_seg.nii.gz dicom_seg/ -d MR -r original_T1_001.dcm

Transferred attributes (from DicomMRI class, see source):

• PatientName, PatientID, PatientBirthDate, PatientSex
• StudyInstanceUID, StudyDate, StudyTime, StudyDescription
• SeriesInstanceUID, SeriesNumber, SeriesDescription, etc. (Full list: https://github.com/tomaroberts/nii2dcm/blob/main/nii2dcm/dcm.py#L236)

NeuroClaw recommended wrapper (simpler for agent calling)

Use a thin wrapper script (to be provided in skill dir):

python nii2dcm_wrapper.py \
  --input seg_postop.nii.gz \
  --output-dir dicom_results/ \
  --modality MR \
  --ref-dcm ref_series/0001.dcm \
  --series-desc "U-Net v3 Segmentation"

Important Notes & Limitations

• Supports only 3D single-volume → multi-slice 2D DICOM series (common in structural MRI, segmentations)
• No 4D support (fMRI, DWI, perfusion, DTI) — split volumes first if needed
• Without --dicom-type, output is generic (lacks modality-specific tags)
• Without --ref-dicom, patient/study info is anonymized/generic
• Orientation, spacing, slice thickness read from NIfTI; verify alignment
• Always visually validate output in DICOM viewer (Horos, 3D Slicer, ITK-Snap, MITK)
• Project still in early stage — expect occasional bugs
• Research purpose only — not a clinical tool

When to Call This Skill

• Finished NIfTI-space processing (bias correction, registration, segmentation, synthesis, etc.)
• Need to compare AI/model outputs visually with original clinical DICOM images
• Want to store results in same format/framework as source study
• Preparing outputs for PACS import, clinical collaboration, or archiving

Complementary / Related Skills

• dependency-planner → install dependencies
• claw-shell → safe execution of conversion commands

Reference

Original: https://github.com/tomaroberts/nii2dcm (v0.1.6, May 2025)
Built on: highdicom (DICOM creation), SimpleITK (image I/O)
Inspired by: dcm2niix (reverse tool), SVRTK project

Report issues or request extensions (e.g., CT support, 4D handling) in NeuroClaw repo.

Created At: 2026-03-18 20:09 HKT Last Updated At: 2026-03-26 00:21 HKT
Author: chengwang96