nii2dcm

name	nii2dcm
description	Use this skill whenever the user wants to convert NIfTI files (.nii or .nii.gz) to DICOM format, create DICOM series from processed neuroimaging results, write segmentation/registration/analysis outputs back to DICOM for PACS compatibility or clinical viewer comparison, or transfer metadata from reference DICOM files. Triggers include: mentions of 'NIfTI to DICOM', 'nii to dcm', 'convert nii.gz to DICOM', 'dicomify segmentation', 'nii2dcm', 'bring results back to DICOM', 'create DICOM from NIfTI', 'nii to dicom series', or any request to take post-processed neuroimaging results (segmentation, registration, bias field correction, synthesis, etc.) and store/view them alongside original patient DICOM data. Also use when modality-specific metadata (especially MR, SVR) or preservation of patient/study information from a reference DICOM is needed. Do NOT use for the reverse conversion (DICOM to NIfTI), non-medical imaging file conversions, or any clinical diagnostic or treatment-related workflows.
license	BSD 3-Clause (original nii2dcm license). See https://github.com/tomaroberts/nii2dcm/blob/main/LICENSE for complete terms.
layer	base
skill_type	tool
dependencies	["claw-shell"]

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

Task	Approach / Command Flag
Basic conversion (generic)	nii2dcm input.nii.gz output_dir/
MRI multi-slice series	--dicom-type MR or -d MR
SVR (3D swept volume recon)	--dicom-type SVR or -d SVR
Copy patient/study metadata	--ref-dicom ref.dcm or -r ref.dcm
Custom series description	Add via wrapper or post-process
Verify output	Open in Horos, 3D Slicer, ITK-Snap

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