Load DICOM

imgtools.dicom.load_dicom

load_dicom(
    dicom_input: imgtools.dicom.input.dicom_reader.DicomInput,
    force: bool = True,
    stop_before_pixels: bool = True,
) -> 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

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/input/dicom_reader.py

def load_dicom(
    dicom_input: DicomInput,
    force: bool = True,
    stop_before_pixels: bool = True,
) -> 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.

    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,
            )
        case bytes():
            return dcmread(
                BytesIO(dicom_input),
                force=force,
                stop_before_pixels=stop_before_pixels,
            )
        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)

imgtools.dicom.load_rtstruct_dcm

load_rtstruct_dcm(
    rtstruct_input: imgtools.dicom.input.dicom_reader.DicomInput,
    force: bool = True,
    stop_before_pixels: bool = True,
) -> pydicom.dataset.FileDataset

Load an RTSTRUCT DICOM file and return the parsed FileDataset object.

Parameters:

Name	Type	Description	Default
rtstruct_input	pydicom.dataset.FileDataset | str | pathlib.Path | bytes	Input DICOM file as a pydicom.FileDataset, file path, or byte stream.	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

Returns:

Type	Description
pydicom.dataset.FileDataset	Parsed RTSTRUCT DICOM dataset.

Raises:

Type	Description
imgtools.exceptions.InvalidDicomError	If the input is of an unsupported type or cannot be read as a DICOM file.
imgtools.exceptions.NotRTSTRUCTError	If the input file is not an RTSTRUCT (i.e., Modality field is not "RTSTRUCT").

Source code in src/imgtools/dicom/input/dicom_reader.py

def load_rtstruct_dcm(
    rtstruct_input: DicomInput,
    force: bool = True,
    stop_before_pixels: bool = True,
) -> FileDataset:
    """Load an RTSTRUCT DICOM file and return the parsed FileDataset object.

    Parameters
    ----------
    rtstruct_input : FileDataset | str | Path | bytes
        Input DICOM file as a `pydicom.FileDataset`, file path, or byte stream.
    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.

    Returns
    -------
    FileDataset
        Parsed RTSTRUCT DICOM dataset.

    Raises
    ------
    InvalidDicomError
        If the input is of an unsupported type or cannot be read as a DICOM file.
    NotRTSTRUCTError
        If the input file is not an RTSTRUCT (i.e., `Modality` field is not "RTSTRUCT").
    """

    dicom = load_dicom(rtstruct_input, force, stop_before_pixels)

    if dicom.Modality != "RTSTRUCT":
        msg = f"The provided DICOM is not an RTSTRUCT file. Found Modality: {dicom.Modality}"
        raise NotRTSTRUCTError(msg)

    return dicom

imgtools.dicom.load_seg_dcm

load_seg_dcm(
    seg_input: imgtools.dicom.input.dicom_reader.DicomInput,
    force: bool = True,
    stop_before_pixels: bool = True,
) -> pydicom.dataset.FileDataset

Load a SEG DICOM file and return the parsed FileDataset object.

Parameters:

Name	Type	Description	Default
seg_input	pydicom.dataset.FileDataset | str | pathlib.Path | bytes	Input DICOM file as a pydicom.FileDataset, file path, or byte stream.	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

Returns:

Type	Description
pydicom.dataset.FileDataset	Parsed SEG DICOM dataset.

Raises:

Type	Description
imgtools.exceptions.InvalidDicomError	If the input is of an unsupported type or cannot be read as a DICOM file.
imgtools.exceptions.NotSEGError	If the input file is not a SEG (i.e., Modality field is not "SEG").

Source code in src/imgtools/dicom/input/dicom_reader.py

def load_seg_dcm(
    seg_input: DicomInput,
    force: bool = True,
    stop_before_pixels: bool = True,
) -> FileDataset:
    """Load a SEG DICOM file and return the parsed FileDataset object.

    Parameters
    ----------
    seg_input : FileDataset | str | Path | bytes
        Input DICOM file as a `pydicom.FileDataset`, file path, or byte stream.
    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.

    Returns
    -------
    FileDataset
        Parsed SEG DICOM dataset.

    Raises
    ------
    InvalidDicomError
        If the input is of an unsupported type or cannot be read as a DICOM file.
    NotSEGError
        If the input file is not a SEG (i.e., `Modality` field is not "SEG").
    """
    dicom = load_dicom(seg_input, force, stop_before_pixels)

    if dicom.Modality != "SEG":
        msg = f"The provided DICOM is not a SEG file. Found Modality: {dicom.Modality}"
        raise NotSEGError(msg)

    return dicom