Refactor Image Pixel and General Image modules into _init_multiframe

Author: CPBridge

src/highdicom/__init__.py

@@ -48,6 +48,7 @@
     PatientSexValues,
     PhotometricInterpretationValues,
     PixelIndexDirections,
+    PixelDataKeywords,
     PixelRepresentationValues,
     PlanarConfigurationValues,
     PatientOrientationValuesBiped,
@@ -80,7 +81,6 @@
 
 
 __all__ = [
-    'RGB_COLOR_CHANNEL_DESCRIPTOR',
     'AlgorithmIdentificationSequence',
     'AnatomicalOrientationTypeValues',
     'AxisHandedness',
@@ -104,18 +104,20 @@
     'PatientOrientationValuesQuadruped',
     'PatientSexValues',
     'PhotometricInterpretationValues',
-    'PixelMeasuresSequence',
+    'PixelDataKeywords',
     'PixelIndexDirections',
+    'PixelMeasuresSequence',
     'PixelRepresentationValues',
     'PlanarConfigurationValues',
     'PlaneOrientationSequence',
     'PlanePositionSequence',
     'PresentationLUT',
     'PresentationLUTShapeValues',
     'PresentationLUTTransformation',
+    'RGBColorChannels',
+    'RGB_COLOR_CHANNEL_DESCRIPTOR',
     'ReferencedImageSequence',
     'RescaleTypeValues',
-    'RGBColorChannels',
     'SOPClass',
     'SegmentedPaletteColorLUT',
     'SpecimenCollection',
@@ -136,6 +138,7 @@
     'ann',
     'color',
     'frame',
+    'get_volume_from_series',
     'imread',
     'io',
     'ko',
@@ -148,5 +151,4 @@
     'spatial',
     'sr',
     'utils',
-    'get_volume_from_series',
 ]

src/highdicom/content.py

@@ -2,12 +2,14 @@
 from collections import Counter
 import datetime
 from copy import deepcopy
+from io import BytesIO
 from typing import cast
 from collections.abc import Sequence
 from typing_extensions import Self
 
 import numpy as np
 from PIL import ImageColor
+from PIL.ImageCms import ImageCmsProfile
 from pydicom.dataset import Dataset
 from pydicom import DataElement
 from pydicom.sequence import Sequence as DataElementSequence
@@ -3706,3 +3708,73 @@ def _add_content_information(
             )
         dataset.ContentCreatorIdentificationCodeSequence = \
             content_creator_identification
+
+
+def _add_icc_profile_attributes(
+    dataset: Dataset,
+    icc_profile: bytes
+) -> None:
+    """Add attributes of module ICC Profile.
+
+    Parameters
+    ----------
+    dataset: pydicom.Dataset
+        Dataset to which attributes should be added
+    icc_profile: bytes
+        ICC color profile to include in the presentation state.
+        The profile must follow the constraints listed in :dcm:`C.11.15
+        <part03/sect_C.11.15.html>`.
+
+    """
+    if icc_profile is None:
+        raise TypeError('Argument "icc_profile" is required.')
+
+    cms_profile = ImageCmsProfile(BytesIO(icc_profile))
+    device_class = cms_profile.profile.device_class.strip()
+    if device_class not in ('scnr', 'spac'):
+        raise ValueError(
+            'The device class of the ICC Profile must be "scnr" or "spac", '
+            f'got "{device_class}".'
+        )
+    color_space = cms_profile.profile.xcolor_space.strip()
+    if color_space != 'RGB':
+        raise ValueError(
+            'The color space of the ICC Profile must be "RGB", '
+            f'got "{color_space}".'
+        )
+    pcs = cms_profile.profile.connection_space.strip()
+    if pcs not in ('Lab', 'XYZ'):
+        raise ValueError(
+            'The profile connection space of the ICC Profile must '
+            f'be "Lab" or "XYZ", got "{pcs}".'
+        )
+
+    dataset.ICCProfile = icc_profile
+
+
+def _add_palette_color_lookup_table_attributes(
+    dataset: Dataset,
+    palette_color_lut_transformation: PaletteColorLUTTransformation
+) -> None:
+    """Add attributes from the Palette Color Lookup Table module.
+
+    Parameters
+    ----------
+    dataset: pydicom.Dataset
+        Dataset to which attributes should be added
+    palette_color_lut_transformation: highdicom.PaletteColorLUTTransformation
+        Description of the Palette Color LUT Transformation for transforming
+        grayscale into RGB color pixel values
+
+    """  # noqa: E501
+    if not isinstance(
+        palette_color_lut_transformation,
+        PaletteColorLUTTransformation
+    ):
+        raise TypeError(
+            'Argument "palette_color_lut_transformation" must be of type '
+            'PaletteColorLUTTransformation.'
+        )
+
+    for element in palette_color_lut_transformation:
+        dataset[element.tag] = element

src/highdicom/enum.py

@@ -380,3 +380,17 @@ class InterpolationMethods(Enum):
 
     LINEAR = 'LINEAR'
     """Linear (or bi-linear or tri-linear) interpolator."""
+
+
+class PixelDataKeywords(Enum):
+
+    """Keywords used to store pixel data."""
+
+    PIXEL_DATA = 'PixelData'
+    """Integer-valued pixel data of any size (Image Pixel Module)."""
+
+    FLOAT_PIXEL_DATA = 'FloatPixelData'
+    """32-bit-float-valued pixel data (Floating Point Image Pixel Module)."""
+
+    DOUBLE_FLOAT_PIXEL_DATA = 'DoubleFloatPixelData'
+    """64-bit-float-valued pixel data (Double Floating Point Image Pixel Module)."""  # noqa: E501

src/highdicom/frame.py

@@ -24,6 +24,7 @@
     PhotometricInterpretationValues,
     PixelRepresentationValues,
     PlanarConfigurationValues,
+    PixelDataKeywords,
 )
 
 logger = logging.getLogger(__name__)
@@ -345,6 +346,7 @@ def encode_frame(
                 planar_configuration=planar_configuration,
                 **kwargs,
             )
+
     return data
 
 
@@ -360,7 +362,7 @@ def decode_frame(
     pixel_representation: PixelRepresentationValues | int | None = 0,
     planar_configuration: PlanarConfigurationValues | int | None = None,
     index: int = 0,
-    pixel_keyword: str = 'PixelData',
+    pixel_keyword: PixelDataKeywords | str = PixelDataKeywords.PIXEL_DATA,
 ) -> np.ndarray:
     """Decode pixel data of an individual frame.
 
@@ -398,7 +400,7 @@ def decode_frame(
         the byte array. In all other situations, this parameter is not
         required and will have no effect (since decoding a frame does not
         depend on the index of the frame).
-    pixel_keyword: str, optional
+    pixel_keyword: highdicom.enum.PixelDataKeywords | str, optional
         Keyword of the attribute where the pixel data value was stored. Should be
         ``'PixelData'``, ``'FloatPixelData'``, or ``'DoubleFloatPixelData'``.
 
@@ -445,7 +447,8 @@ def decode_frame(
         pixel_array = unpacked_frame[pixel_offset:pixel_offset + n_pixels]
         return pixel_array.reshape(rows, columns)
 
-    if pixel_keyword == 'PixelData':
+    pixel_keyword = PixelDataKeywords(pixel_keyword)
+    if pixel_keyword == PixelDataKeywords.PIXEL_DATA:
         pixel_representation = PixelRepresentationValues(
             pixel_representation
         ).value
@@ -481,7 +484,7 @@ def decode_frame(
         bits_stored=bits_stored,
         photometric_interpretation=photometric_interpretation,
         pixel_representation=pixel_representation,
-        pixel_keyword=pixel_keyword,
+        pixel_keyword=pixel_keyword.value,
         **kwargs,
     )
     return array

src/highdicom/image.py

@@ -55,7 +55,10 @@
 from highdicom.base import SOPClass, _check_little_endian
 from highdicom.color import ColorManager
 from highdicom.content import (
+    _add_icc_profile_attributes,
+    _add_palette_color_lookup_table_attributes,
     LUT,
+    PaletteColorLUTTransformation,
     PixelMeasuresSequence,
     PlaneOrientationSequence,
     PlanePositionSequence,
@@ -64,6 +67,10 @@
 from highdicom.enum import (
     CoordinateSystemNames,
     DimensionOrganizationTypeValues,
+    PhotometricInterpretationValues,
+    PixelDataKeywords,
+    PixelRepresentationValues,
+    PlanarConfigurationValues,
 )
 from highdicom.frame import decode_frame, encode_frame
 from highdicom.io import ImageFileReader, _wrapped_dcmread
@@ -485,11 +492,11 @@ def __init__(
 
         # Determine what pixel data keyword is present in the image
         for kw in [
-            'PixelData',
-            'FloatPixelData',
-            'DoubleFloatPixelData',
+            PixelDataKeywords.PIXEL_DATA,
+            PixelDataKeywords.FLOAT_PIXEL_DATA,
+            PixelDataKeywords.DOUBLE_FLOAT_PIXEL_DATA,
         ]:
-            if kw in image:
+            if kw.value in image:
                 self.pixel_keyword = kw
                 break
         else:
@@ -504,14 +511,16 @@ def __init__(
             ):
                 if image.BitsAllocated == 32:
                     self.input_dtype = np.dtype(np.float32)
-                    self.pixel_keyword = 'FloatPixelData'
+                    self.pixel_keyword = PixelDataKeywords.FLOAT_PIXEL_DATA
                 elif image.BitsAllocated == 64:
                     self.input_dtype = np.dtype(np.float64)
-                    self.pixel_keyword = 'DoubleFloatPixelData'
+                    self.pixel_keyword = (
+                        PixelDataKeywords.DOUBLE_FLOAT_PIXEL_DATA
+                    )
             else:
-                self.pixel_keyword = 'PixelData'
+                self.pixel_keyword = PixelDataKeywords.PIXEL_DATA
 
-        if self.pixel_keyword == 'PixelData':
+        if self.pixel_keyword == PixelDataKeywords.PIXEL_DATA:
             if image.PixelRepresentation == 1:
                 if image.BitsAllocated == 8:
                     self.input_dtype = np.dtype(np.int8)
@@ -1244,9 +1253,24 @@ def coordinate_system(self) -> CoordinateSystemNames | None:
 
     def _init_multiframe_image(
         self,
-        source_images: Sequence[Dataset],
         pixel_array: np.ndarray | Volume,
         *,
+        source_images: Sequence[Dataset],
+        image_type: Sequence[str],
+        photometric_interpretation: PhotometricInterpretationValues | str,
+        bits_allocated: int,
+        bits_stored: int | None = None,
+        samples_per_pixel: int = 1,
+        planar_configuration: (
+            PlanarConfigurationValues | int
+        ) = PlanarConfigurationValues.COLOR_BY_PIXEL,
+        pixel_representation: (
+            PixelRepresentationValues | int
+        ) = PixelRepresentationValues.UNSIGNED_INTEGER,
+        contains_recognizable_visual_features: bool | None = None,
+        burned_in_annotation: bool | None = None,
+        palette_color_lut_transformation: PaletteColorLUTTransformation | None,
+        icc_profile: bytes | None = None,
         pixel_measures: PixelMeasuresSequence | None = None,
         plane_orientation: PlaneOrientationSequence | None = None,
         plane_positions: Sequence[PlanePositionSequence] | None = None,
@@ -1263,7 +1287,7 @@ def _init_multiframe_image(
         pyramid_label: str | None = None,
         pyramid_uid: str | None = None,
         use_extended_offset_table: bool = False,
-        pixel_data_attr: str = 'PixelData',
+        pixel_data_keyword: PixelDataKeywords = PixelDataKeywords.PIXEL_DATA,
         channel_values: Sequence[Any] | None = None,  # TODO generalize
         add_channel_callback: (
             Callable[[Dataset, Any], Dataset] | None
@@ -1345,6 +1369,57 @@ def _init_multiframe_image(
                     "with the source images."
                 )
 
+        # (Float/DoubleFloat) Image Pixel module
+        self.BitsAllocated = bits_allocated
+        self.SamplesPerPixel = samples_per_pixel
+        if samples_per_pixel > 1:
+            self.PlanarConfiguration = PlanarConfigurationValues(
+                planar_configuration
+            ).value
+        photometric_interpretation = PhotometricInterpretationValues(
+            photometric_interpretation
+        )
+        self.PhotometricInterpretation = photometric_interpretation.value
+
+        pixel_data_keyword = PixelDataKeywords(pixel_data_keyword)
+
+        if pixel_data_keyword == PixelDataKeywords.PIXEL_DATA:
+            # Attributes in the Image Pixel Module but not the
+            # Float/DoubleFloat Image Pixel modules
+            if bits_stored is None:
+                bits_stored = bits_allocated
+            self.BitsStored = bits_stored
+            self.HighBit = bits_allocated - 1
+            self.PixelRepresentation = PixelRepresentationValues(
+                pixel_representation
+            ).value
+
+        # General Image module
+        self.ImageType = list(image_type)
+        if burned_in_annotation is not None:
+            self.BurnedInAnnotation = (
+                'YES' if burned_in_annotation else 'NO'
+            )
+        if contains_recognizable_visual_features is not None:
+            self.RecognizableVisualFeatures = (
+                'YES' if contains_recognizable_visual_features else 'NO'
+            )
+        self.PresentationLUTShape = (
+            'INVERSE'
+            if photometric_interpretation ==
+            PhotometricInterpretationValues.MONOCHROME1
+            else 'IDENTITY'
+        )
+
+        if palette_color_lut_transformation is not None:
+            _add_palette_color_lookup_table_attributes(
+                self,
+                palette_color_lut_transformation,
+            )
+
+        if icc_profile is not None:
+            _add_icc_profile_attributes(self, icc_profile)
+
         self._add_source_image_references(
             source_images=source_images,
             further_source_images=further_source_images,
@@ -1916,7 +1991,7 @@ def preprocess_channel_callback(
             if len(remainder_pixels) > 0:
                 frames.append(self._encode_pixels_native(remainder_pixels))
 
-            setattr(self, pixel_data_attr, b''.join(frames))
+            setattr(self, pixel_data_keyword.value, b''.join(frames))
 
         # Add a null trailing byte if required (can't happen for floating pixel
         # data)