Add read functions

Author: Chris Bridge

src/highdicom/legacy/__init__.py

@@ -5,6 +5,9 @@
     LegacyConvertedEnhancedCTImage,
     LegacyConvertedEnhancedMRImage,
     LegacyConvertedEnhancedPETImage,
+    lcectimread,
+    lcepetimread,
+    lcemrimread,
 )
 
 SOP_CLASS_UIDS = {
@@ -17,4 +20,7 @@
     'LegacyConvertedEnhancedCTImage',
     'LegacyConvertedEnhancedMRImage',
     'LegacyConvertedEnhancedPETImage',
+    'lcectimread',
+    'lcepetimread',
+    'lcemrimread',
 ]

src/highdicom/legacy/sop.py

@@ -2205,3 +2205,90 @@ class LegacyConvertedEnhancedMRImage(_CommonLegacyConvertedEnhancedImage):
     _MODALITY_NAME = "MR"
     _LEGACY_SOP_CLASS_UID = "1.2.840.10008.5.1.4.1.1.4"
     _ENHANCED_SOP_CLASS_UID = "1.2.840.10008.5.1.4.1.1.4.4"
+
+
+def lcectimread(
+    fp: str | bytes | PathLike | BinaryIO,
+    lazy_frame_retrieval: bool = False
+) -> LegacyConvertedEnhancedCTImage:
+    """Read an LegacyConvertedEnhancedCTImage from DICOM file.
+
+    Parameters
+    ----------
+    fp: Union[str, bytes, os.PathLike]
+        Any file-like object representing a DICOM file containing an
+        Legacy Converted Enhanced CT Image.
+    lazy_frame_retrieval: bool
+        If True, the returned image will retrieve frames from the file as
+        requested, rather than loading in the entire object to memory
+        initially. This may be a good idea if file reading is slow and you are
+        likely to need only a subset of the frames in the image.
+
+    Returns
+    -------
+    highdicom.legacy.LegacyConvertedEnhancedCTImage:
+        Image read from the file.
+
+    """
+    return LegacyConvertedEnhancedCTImage.from_file(
+        fp,
+        lazy_frame_retrieval=lazy_frame_retrieval
+    )
+
+
+def lcemrimread(
+    fp: str | bytes | PathLike | BinaryIO,
+    lazy_frame_retrieval: bool = False
+) -> LegacyConvertedEnhancedMRImage:
+    """Read an LegacyConvertedEnhancedMRImage from DICOM file.
+
+    Parameters
+    ----------
+    fp: Union[str, bytes, os.PathLike]
+        Any file-like object representing a DICOM file containing an
+        Legacy Converted Enhanced MR Image.
+    lazy_frame_retrieval: bool
+        If True, the returned image will retrieve frames from the file as
+        requested, rather than loading in the entire object to memory
+        initially. This may be a good idea if file reading is slow and you are
+        likely to need only a subset of the frames in the image.
+
+    Returns
+    -------
+    highdicom.legacy.LegacyConvertedEnhancedMRImage:
+        Image read from the file.
+
+    """
+    return LegacyConvertedEnhancedMRImage.from_file(
+        fp,
+        lazy_frame_retrieval=lazy_frame_retrieval
+    )
+
+
+def lcepetimread(
+    fp: str | bytes | PathLike | BinaryIO,
+    lazy_frame_retrieval: bool = False
+) -> LegacyConvertedEnhancedPETImage:
+    """Read an LegacyConvertedEnhancedPETImage from DICOM file.
+
+    Parameters
+    ----------
+    fp: Union[str, bytes, os.PathLike]
+        Any file-like object representing a DICOM file containing an
+        Legacy Converted Enhanced PET Image.
+    lazy_frame_retrieval: bool
+        If True, the returned image will retrieve frames from the file as
+        requested, rather than loading in the entire object to memory
+        initially. This may be a good idea if file reading is slow and you are
+        likely to need only a subset of the frames in the image.
+
+    Returns
+    -------
+    highdicom.legacy.LegacyConvertedEnhancedPETImage:
+        Image read from the file.
+
+    """
+    return LegacyConvertedEnhancedPETImage.from_file(
+        fp,
+        lazy_frame_retrieval=lazy_frame_retrieval
+    )

tests/test_legacy.py

@@ -1,5 +1,6 @@
 from concurrent.futures import ProcessPoolExecutor
 from copy import deepcopy
+from io import BytesIO
 from datetime import datetime, timedelta
 import enum
 import re
@@ -20,6 +21,9 @@
     LegacyConvertedEnhancedCTImage,
     LegacyConvertedEnhancedMRImage,
     LegacyConvertedEnhancedPETImage,
+    lcectimread,
+    lcemrimread,
+    lcepetimread,
 )
 from highdicom import UID
 
@@ -1374,3 +1378,42 @@ def test_from_dataset_wrong_modality(modality: Modality) -> None:
         WrongLegacyConverterClass.from_dataset(
             write_and_read_dataset(converted)
         )
+
+
+@pytest.mark.parametrize("lazy", [True, False])
+def test_read_function(modality: Modality, lazy: bool) -> None:
+    LegacyConverterClass = MODALITY_CLASS_MAP[modality]
+    data_generator = DicomGenerator(5)
+    legacy_datasets = data_generator.generate_mixed_framesets(
+        modality, 1, True, True
+    )
+
+    output_series_uid = UID()
+    output_sop_uid = UID()
+    output_series_number = 23
+    output_instance_number = 2
+    series_description = 'Converted Series'
+
+    converted = LegacyConverterClass(
+        legacy_datasets,
+        series_instance_uid=output_series_uid,
+        sop_instance_uid=output_sop_uid,
+        series_number=output_series_number,
+        instance_number=output_instance_number,
+        series_description=series_description,
+    )
+
+    read_fn = {
+        Modality.PT: lcepetimread,
+        Modality.CT: lcectimread,
+        Modality.MR: lcemrimread,
+    }[modality]
+
+    with BytesIO() as fp:
+        converted.save_as(fp)
+        fp.seek(0)
+        reread = read_fn(fp, lazy_frame_retrieval=lazy)
+
+    assert isinstance(reread, LegacyConverterClass)
+    assert ('PixelData' in reread) == (not lazy)
+    assert converted.pixel_array.shape == (5, 2, 2)