Skip to content

Load DICOM

imgtools.dicom.load_dicom 

load_dicom(
    dicom_input: imgtools.dicom.dicom_reader.DicomInput,
    force: bool = True,
    stop_before_pixels: bool = True,
    **kwargs: typing.Any
) -> pydicom.dataset.FileDataset

Load a DICOM file and return the parsed FileDataset object.

This function supports various input types including file paths, byte streams, and file-like objects. It uses the pydicom.dcmread function to read the DICOM file.

Notes
  • If dicom_input is already a FileDataset, it is returned as is.
  • If dicom_input is a file path or file-like object, it is read using pydicom.dcmread.
  • If dicom_input is a byte stream, it is wrapped in a BytesIO object and then read.
  • An InvalidDicomError is raised if the input type is unsupported.

Parameters:

Name Type Description Default

dicom_input

pydicom.dataset.FileDataset | str | pathlib.Path | bytes | typing.BinaryIO

Input DICOM file as a pydicom.FileDataset, file path, byte stream, or file-like object.

 required

force

bool

Whether to allow reading DICOM files missing the File Meta Information header, by default True.

 True

stop_before_pixels

bool

Whether to stop reading the DICOM file before loading pixel data, by default True.

 True

**kwargs

typing.Any

Additional keyword arguments to pass to pydicom.dcmread. i.e specific_tags.

 {}

Returns:

Type Description
pydicom.dataset.FileDataset

Parsed DICOM dataset.

Raises:

Type Description
imgtools.exceptions.InvalidDicomError

If the input is of an unsupported type or cannot be read as a DICOM file.
Source code in src/imgtools/dicom/dicom_reader.py 
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
def load_dicom(
    dicom_input: DicomInput,
    force: bool = True,
    stop_before_pixels: bool = True,
    **kwargs: Any,  # noqa: ANN401
) -> FileDataset:
    """Load a DICOM file and return the parsed FileDataset object.

    This function supports various input types including file paths, byte streams,
    and file-like objects. It uses the `pydicom.dcmread` function to read the DICOM file.

    Notes
    -----
    - If `dicom_input` is already a `FileDataset`, it is returned as is.
    - If `dicom_input` is a file path or file-like object, it is read using `pydicom.dcmread`.
    - If `dicom_input` is a byte stream, it is wrapped in a `BytesIO` object and then read.
    - An `InvalidDicomError` is raised if the input type is unsupported.

    Parameters
    ----------
    dicom_input : FileDataset | str | Path | bytes | BinaryIO
        Input DICOM file as a `pydicom.FileDataset`, file path, byte stream, or file-like object.
    force : bool, optional
        Whether to allow reading DICOM files missing the *File Meta Information*
        header, by default True.
    stop_before_pixels : bool, optional
        Whether to stop reading the DICOM file before loading pixel data, by default True.
    **kwargs
        Additional keyword arguments to pass to `pydicom.dcmread`.
        i.e `specific_tags`.
    Returns
    -------
    FileDataset
        Parsed DICOM dataset.

    Raises
    ------
    InvalidDicomError
        If the input is of an unsupported type or cannot be read as a DICOM file.
    """
    match dicom_input:
        case FileDataset():
            return dicom_input
        case str() | Path() | BinaryIO():
            dicom_source = path_from_pathlike(dicom_input)
            return dcmread(
                dicom_source,
                force=force,
                stop_before_pixels=stop_before_pixels,
                **kwargs,
            )
        case bytes():
            return dcmread(
                BytesIO(dicom_input),
                force=force,
                stop_before_pixels=stop_before_pixels,
                **kwargs,
            )
        case _:
            msg = (
                f"Invalid input type for 'dicom_input': {type(dicom_input)}. "
                "Must be a FileDataset, str, Path, bytes, or BinaryIO object."
            )
            raise InvalidDicomError(msg)