nifti-to-dicom 0.1.0

Convert NIfTI files to standards-compliant DICOM series

nifti-to-dicom

Convert 3D NIfTI files to standards-compliant DICOM series.

Disclaimer

Research Use Only: This software is provided for research, educational, and development purposes only. This software has not been reviewed, cleared, approved, or certified by any regulatory authority and is not intended for use in patient care, diagnosis, treatment planning, or any clinical decision-making process. The authors assume no liability for any damages arising from its use. See LICENSE for more information.

Accurate conversion is not guaranteed, although steps have been taken to verify output (see Validation for more).

Installation

pip install nifti-to-dicom

Using the dicom-anonymizer package, a reference DICOM can be anonymized while preserving some acquisition-specific DICOM tags (see below for more):

pip install nifti-to-dicom[anonymize]

Usage

from nifti_to_dicom import NiftiToDicom

# Explicitly specifying modality and subject
NiftiToDicom.convert("scan.nii.gz", modality="MR", sub="S001")

# Subject and modality inferred from a BIDS-formatted filename
NiftiToDicom.convert("sub-R001_T1w.nii.gz")

NiftiToDicom can infer some information from paths in BIDS format.

Using a reference DICOM

Preserve specific scanner parameters from a reference DICOM file:

# Keeping scanner parameters from a reference DICOM
NiftiToDicom.convert("sub-R001_CT.nii.gz", ref_dcm="orig0001.dcm")

# The reference DICOM can be anonymized beforehand also
NiftiToDicom.convert(
    "sub-R001_CT.nii.gz",
    ref_dcm="orig0001.dcm",
    ref_anonymize=True,
)

Other helpful settings

If the DICOM series is not loading in a certain software, try changing encoding_dir. The conversion slices along the third NIfTI dimension by default. Adjusting the slice encoding direction has been found to resolve compatibility issues with certain software:

# Specify encoding direction to generate axial, coronal, or sagittal slices
NiftiToDicom.convert("scan.nii.gz", modality="MR", encoding_dir="ax")
NiftiToDicom.convert("scan.nii.gz", modality="MR", encoding_dir="cor")
NiftiToDicom.convert("scan.nii.gz", modality="MR", encoding_dir="sag")

Additional DICOM tags can be injected by name:

added_tags = {
    "InstitutionName": "University Medical Center",
    "SeriesDescription": "Sag T1 (MPRAGE) w/o Contrast"
}
NiftiToDicom.convert("sub-01_T1w.nii.gz", added_dcm_tags=added_tags)

Validation

Conversion is not guaranteed in all cases as validation has only been performed on a limited set of images. However, at the time of writing:

• MR and CT synthetic DICOM output has been validated using dciodvfy.
• MR and CT synthetic DICOM output has been verified to load correctly in ITK-Snap and 3D Slicer.

Contributing

Bug reports are welcome via GitHub Issues.

The package is structured such that additional imaging modalities can be added relatively easily, simply inheriting the Dicom class. See Structure.

Citation

If you use this package in published research, please open an issue on this repository or otherwise reach out. If there is interest in citing the package, I can create a DOI and provide citation information.

Package structure

classDiagram
    class NiftiToDicom {
        +nifti_path Path
        +dcm_tpl Dataset
        +nifti_to_dicom(overwrite)
        +convert(...)$
    }

    class Dicom {}
    class MRDicom {}
    class CTDicom {}
    class RefDicom {
        +from_path(dcm_path, anonymize, verbose) Dataset
    }

    Dicom <|-- MRDicom
    Dicom <|-- CTDicom
    NiftiToDicom ..> Dicom : if no ref_dcm
    NiftiToDicom ..> RefDicom : if ref_dcm supplied