dcm2niix

dcm2niix ¶

dcm2niix integration for DICOM conversion.

This module provides a wrapper around the dcm2niix tool for converting DICOM to NIfTI with BIDS-compliant sidecar generation.

References

dcm2niix: https://github.com/rordenlab/dcm2niix

Dcm2niixError ¶

Bases: IOError

Raised when dcm2niix conversion fails.

Examples:

>>> raise Dcm2niixError("dcm2niix not found")
Traceback (most recent call last):
    ...
osipy.common.io.converters.dcm2niix.Dcm2niixError: dcm2niix not found

Dcm2niixConverter ¶

Dcm2niixConverter(dcm2niix_path=None)

Wrapper for dcm2niix DICOM to NIfTI conversion.

This class provides integration with dcm2niix for converting DICOM data to NIfTI format with automatic BIDS sidecar generation.

ATTRIBUTE	DESCRIPTION
`dcm2niix_path`	Path to dcm2niix executable, or None if not found. TYPE: `str \| None`

Examples:

>>> converter = Dcm2niixConverter()
>>> if converter.is_available():
...     nifti_path, sidecar = converter.convert("dicom_dir/")
...     print(f"Converted to: {nifti_path}")

Notes

dcm2niix must be installed and available in PATH. Install via: https://github.com/rordenlab/dcm2niix#install

Initialize the converter.

PARAMETER	DESCRIPTION
`dcm2niix_path`	Path to dcm2niix executable. If None, searches PATH. TYPE: `str \| None` DEFAULT: `None`

is_available ¶

is_available()

Check if dcm2niix is available.

RETURNS	DESCRIPTION
`bool`	True if dcm2niix is installed and accessible.

convert ¶

convert(
    dicom_dir,
    output_dir=None,
    filename_format="%p_%s",
    compress=True,
    merge_2d=True,
    single_file=True,
)

Convert DICOM to NIfTI using dcm2niix.

PARAMETER	DESCRIPTION
`dicom_dir`	Path to DICOM directory. TYPE: `str \| Path`
`output_dir`	Output directory. If None, uses a temporary directory. TYPE: `str \| Path \| None` DEFAULT: `None`
`filename_format`	dcm2niix filename format. %p=protocol, %s=series. TYPE: `str` DEFAULT: `'%p_%s'`
`compress`	Compress output with gzip (.nii.gz). TYPE: `bool` DEFAULT: `True`
`merge_2d`	Merge 2D slices into 3D volumes. TYPE: `bool` DEFAULT: `True`
`single_file`	Prefer single file output. TYPE: `bool` DEFAULT: `True`

RETURNS	DESCRIPTION
`tuple[Path, dict[str, Any]]`	Tuple of (NIfTI file path, sidecar JSON content).

RAISES	DESCRIPTION
`Dcm2niixError`	If dcm2niix is not available or conversion fails.
`FileNotFoundError`	If DICOM directory does not exist.

Examples:

>>> converter = Dcm2niixConverter()
>>> nifti_path, sidecar = converter.convert("dicom_series/")
>>> print(f"TR: {sidecar.get('RepetitionTime')}")