Metadata-Version: 2.4
Name: nifti-to-dicom
Version: 0.1.0
Summary: Convert NIfTI files to standards-compliant DICOM series
Project-URL: Homepage, https://github.com/joelswhite/nifti-to-dicom
Project-URL: Repository, https://github.com/joelswhite/nifti-to-dicom
Project-URL: Issues, https://github.com/joelswhite/nifti-to-dicom/issues
License: BSD-3-Clause
License-File: LICENSE
Keywords: ct,dicom,medical imaging,mri,neuroimaging,nifti
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: BSD License
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Scientific/Engineering :: Medical Science Apps.
Requires-Python: >=3.13
Requires-Dist: nibabel>=5.3.2
Requires-Dist: numpy>=2.3.5
Requires-Dist: pydicom>=3.0.1
Requires-Dist: tqdm>=4.67.3
Provides-Extra: anonymize
Requires-Dist: dicom-anonymizer>=1.0.12; extra == 'anonymize'
Description-Content-Type: text/markdown

# nifti-to-dicom

[![PyPI](https://img.shields.io/pypi/v/nifti-to-dicom)](https://pypi.org/project/nifti-to-dicom/)
[![Python](https://img.shields.io/pypi/pyversions/nifti-to-dicom)](https://pypi.org/project/nifti-to-dicom/)
[![License](https://img.shields.io/badge/License-BSD_3--Clause-blue.svg)](https://opensource.org/licenses/BSD-3-Clause)

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](LICENSE) for more information.

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

## Installation

```bash
pip install nifti-to-dicom
```

Using [the dicom-anonymizer package](https://github.com/KitwareMedical/dicom-anonymizer), a reference DICOM can be anonymized while preserving some acquisition-specific DICOM tags ([see below for more](#using-a-reference-dicom)):

```bash
pip install nifti-to-dicom[anonymize]
```

## Usage

```python
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](https://bids.neuroimaging.io/index.html).

### Using a reference DICOM

Preserve specific scanner parameters from a reference DICOM file:

```python
# 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:

```python
# 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:

```python
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](https://dclunie.com/dicom3tools/dciodvfy.html).
- MR and CT synthetic DICOM output has been verified to load correctly in [ITK-Snap](https://www.itksnap.org/pmwiki/pmwiki.php) and [3D Slicer](https://www.slicer.org/).

## Contributing

Bug reports are welcome via [GitHub Issues](https://github.com/joelswhite/nifti-to-dicom/issues).

The package is structured such that additional imaging modalities can be added relatively easily, simply inheriting the `Dicom` class. See [Structure](#package-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

```mermaid
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
```
