nii2dcm

NIfTI to DICOM file creation with Python
Explore the docs »

View Repo · Report Bug · Request Feature

Overview

DICOM is the international standard used to store, transfer and display medical images in clinical institutions. It is a vast and complicated standard. The NIfTI file format is widely used within medical imaging research because it is a comparatively simple data format, generally stripped of identifiable patient data and with far fewer metadata fields.

Researchers often convert DICOM files to NIfTI files using tools such as dcm2niix. However, the reverse process is much harder.

nii2dcm is designed to convert a NIfTI file (.nii/.nii.gz) into a single-frame DICOM Series in one line, e.g.:

nii2dcm nifti-file.nii.gz dicom-output-directory/ --dicom-type MR

(back to top)

Installation

To install and run nii2dcm locally, you have two options:

• pip
• build from source

pip

Create a new Python virtual environment, then:

pip install nii2dcm

build from source

Clone this repo:

git clone https://github.com/tomaroberts/nii2dcm.git

Setup a Python virtual environment (recommended):

cd nii2dcm/
python -m venv nii2dcm-venv
source nii2dcm-venv/bin/activate
python -m pip install --upgrade pip

Install dependencies and nii2dcm:

pip install -r requirements.txt
pip install .

Verify installation by displaying nii2dcm help information

nii2dcm -h

(back to top)

Usage

nii2dcm is designed to be pointed at a single .nii or .nii.gz from which it generates a single-frame DICOM dataset.

It is recommended to specify the output DICOM modality using the -d or --dicom-type flag (see examples below). Without this, a generic DICOM is created without complete imaging modality metadata.

DicomMRI

Create an MRI 2D multi-slice DICOM dataset:

nii2dcm nifti-file.nii.gz dicom-output-directory/ -d MR

DicomMRISVR

Create an MRI 3D SVR DICOM dataset:

nii2dcm SVR-output.nii.gz dicom-output-directory/ -d SVR

Dicom

Create a generic DICOM dataset:

nii2dcm nifti-file.nii.gz dicom-output-directory/

Other

Eventually, nii2dcm will be extended to cover other imaging modalities including CT, Ultrasound, X-Ray, etc.

(back to top)

Reference DICOM metadata transferral

There are often situations where it can be useful to transfer information from an existing DICOM Study into a new DICOM Series. For example, if you want to store your new DICOM dataset alongside your original DICOM Study.

The -r or --ref-dicom flag attempts to transfer common DICOM attributes from a reference DICOM file into the output DICOM:

nii2dcm nifti-file.nii.gz dicom-output-directory/ -d MR -r reference-dicom-file.dcm

Currently, attributes to transfer are listed here in the DicomMRI class.

(back to top)

Docker

nii2dcm is also available as a Docker container.

Pull the latest container with:

docker pull ghcr.io/tomaroberts/nii2dcm:latest

For ease of use, rename the container on your local machine:

docker tag ghcr.io/tomaroberts/nii2dcm:latest nii2dcm

Run the containerised nii2dcm:

# display nii2dcm version
docker run nii2dcm -v

# perform nii2dcm conversion
docker run nii2dcm nifti-file.nii.gz dicom-output-directory/ -d MR

(back to top)

Roadmap

This project is in its infancy! Expect bugs 🐛 🐜 🪲

There are many things I would like to test and implement. Raise an Issue if you have ideas or suggestions.

Developer Note

If you would like to create another class of DICOM within nii2dcm, you can use the base DicomMRI class or the DicomMRISVR class for inspiration. You will also need to extend the command line interface to utilise your class, i.e. --dicom-type CT.

Please raise an Issue if you need developer support.

(back to top)

Acknowledgments

• SVRTK @ KCL - the original motivation for this project
• Chris Rorden for dcm2niix - inspiration for the reverse process
• NHS Topol Digital Fellowships scheme - for the protected time to work on this
• highdicom - beautiful and extensive Python library for various tasks, including DICOM creation
• SimpleITK - comprehensive software including DICOM reading and writing

(back to top)

Links

Some useful, free image viewing software:

• ITK-Snap - fast, simple interface. Opens NIfTI and DICOM
• MITK Workbench - excellent for viewing multiple image datasets in the same geometric space. Opens NIfTI and DICOM
• 3D Slicer - comprehensive imaging software
• Horos - similar to a hospital clinical information system

(back to top)

Disclaimer

The Software has been developed for research purposes only and is not a clinical tool.

Licence

BSD 3-Clause License can be found here

(back to top)