Implementation of Softcopy Presentation States

MANIFEST.in

@@ -3,3 +3,4 @@ include src/highdicom/legacy/*
 include src/highdicom/sc/*
 include src/highdicom/seg/*
 include src/highdicom/sr/*
+include src/highdicom/_icc_profiles/*

README.md

@@ -13,6 +13,7 @@ It currently provides tools for creating and decoding the following DICOM inform
 * Secondary Capture images
 * Key Object Selection documents
 * Legacy Converted Enhanced CT/PET/MR images (e.g., for single frame to multi-frame conversion)
+* Softcopy Presentation State instances (including Grayscale, Color, and Pseudo-Color)
 
 ## Documentation
 

docs/package.rst

@@ -113,6 +113,17 @@ highdicom.pm package
    :undoc-members:
    :show-inheritance:
 
+.. _highdicom-pr-subpackage:
+
+highdicom.pr package
+---------------------
+
+.. automodule:: highdicom.pr
+   :members:
+   :special-members: __call__
+   :undoc-members:
+   :show-inheritance:
+
 .. _highdicom-seg-subpackage:
 
 highdicom.seg package

docs/usage.rst

@@ -506,6 +506,97 @@ overlay a segmentation that is stored in a NumPy array called "seg_out".
 
         sc_image.save_as(os.path.join("output", 'sc_output_' + str(iz) + '.dcm'))
 
+
+Creating Grayscale Softcopy Presentation State (GSPS) Objects
+-------------------------------------------------------------
+
+A presentation state contains information about how another image should be
+rendered, and may include "annotations" in the form of basic shapes, polylines,
+and text overlays. Note that a GSPS is not recommended for storing annotations
+for any purpose except visualization. A structured report would usually be
+preferred for storing annotations for clinical or research purposes.
+
+.. code-block:: python
+
+    import highdicom as hd
+
+    import numpy as np
+    from pydicom import dcmread
+    from pydicom.valuerep import PersonName
+
+
+    # Read in an example CT image
+    image_dataset = dcmread('path/to/image.dcm')
+
+    # Create an annotation containing a polyline
+    polyline = hd.pr.GraphicObject(
+        graphic_type=hd.pr.GraphicTypeValues.POLYLINE,
+        graphic_data=np.array([
+            [10.0, 10.0],
+            [20.0, 10.0],
+            [20.0, 20.0],
+            [10.0, 20.0]]
+        ),  # coordinates of polyline vertices
+        units=hd.pr.AnnotationUnitsValues.PIXEL,  # units for graphic data
+        tracking_id='Finding1',  # site-specific ID
+        tracking_uid=hd.UID()  # highdicom will generate a unique ID
+    )
+
+    # Create a text object annotation
+    text = hd.pr.TextObject(
+        text_value='Important Finding!',
+        bounding_box=np.array(
+            [30.0, 30.0, 40.0, 40.0]  # left, top, right, bottom
+        ),
+        units=hd.pr.AnnotationUnitsValues.PIXEL,  # units for bounding box
+        tracking_id='Finding1Text',  # site-specific ID
+        tracking_uid=hd.UID()  # highdicom will generate a unique ID
+    )
+
+    # Create a single layer that will contain both graphics
+    # There may be multiple layers, and each GraphicAnnotation object
+    # belongs to a single layer
+    layer = hd.pr.GraphicLayer(
+        layer_name='LAYER1',
+        order=1,  # order in which layers are displayed (lower first)
+        description='Simple Annotation Layer',
+    )
+
+    # A GraphicAnnotation may contain multiple text and/or graphic objects
+    # and is rendered over all referenced images
+    annotation = hd.pr.GraphicAnnotation(
+        referenced_images=[image_dataset],
+        graphic_layer=layer,
+        graphic_objects=[polyline],
+        text_objects=[text]
+    )
+
+    # Assemble the components into a GSPS object
+    gsps = hd.pr.GrayscaleSoftcopyPresentationState(
+        referenced_images=[image_dataset],
+        series_instance_uid=hd.UID(),
+        series_number=123,
+        sop_instance_uid=hd.UID(),
+        instance_number=1,
+        manufacturer='Manufacturer',
+        manufacturer_model_name='Model',
+        software_versions='v1',
+        device_serial_number='Device XYZ',
+        content_label='ANNOTATIONS',
+        graphic_layers=[layer],
+        graphic_annotations=[annotation],
+        institution_name='MGH',
+        institutional_department_name='Radiology',
+        content_creator_name=PersonName.from_named_components(
+            family_name='Doe',
+            given_name='John'
+        ),
+    )
+
+    # Save the GSPS file
+    gsps.save_as('gsps.dcm')
+
+
 .. .. _creation-legacy:
 
 .. Creating Legacy Converted Enhanced Images

setup.py

@@ -10,13 +10,17 @@
 readme_filepath = root_directory.joinpath('README.md')
 long_description = readme_filepath.read_text()
 
-with io.open('src/highdicom/version.py', 'rt', encoding='utf8') as f:
-    version = re.search(r'__version__ = \'(.*?)\'', f.read()).group(1)
+
+def get_version():
+    version_filepath = Path('src', 'highdicom', 'version.py')
+    with io.open(version_filepath, 'rt', encoding='utf8') as f:
+        version = re.search(r'__version__ = \'(.*?)\'', f.read()).group(1)
+    return version
 
 
 setuptools.setup(
     name='highdicom',
-    version=version,
+    version=get_version(),
     description='High-level DICOM abstractions.',
     long_description=long_description,
     long_description_content_type='text/markdown',

src/highdicom/__init__.py

@@ -3,35 +3,52 @@
 from highdicom import ko
 from highdicom import legacy
 from highdicom import pm
+from highdicom import pr
 from highdicom import sc
 from highdicom import seg
 from highdicom import sr
 from highdicom.base import SOPClass
 from highdicom.content import (
     AlgorithmIdentificationSequence,
+    ContentCreatorIdentificationCodeSequence,
     IssuerOfIdentifier,
+    LUT,
+    ModalityLUT,
+    ModalityLUTTransformation,
+    PaletteColorLUT,
+    PaletteColorLUTTransformation,
     PixelMeasuresSequence,
-    PlanePositionSequence,
     PlaneOrientationSequence,
+    PlanePositionSequence,
+    PresentationLUT,
+    PresentationLUTTransformation,
+    ReferencedImageSequence,
+    SegmentedPaletteColorLUT,
     SpecimenCollection,
     SpecimenDescription,
     SpecimenPreparationStep,
+    SpecimenProcessing,
     SpecimenSampling,
     SpecimenStaining,
+    VOILUT,
+    VOILUTTransformation,
 )
 from highdicom.enum import (
+    AnatomicalOrientationTypeValues,
     CoordinateSystemNames,
     ContentQualificationValues,
     DimensionOrganizationTypeValues,
+    LateralityValues,
     PatientSexValues,
     PhotometricInterpretationValues,
-    PlanarConfigurationValues,
     PixelRepresentationValues,
-    LateralityValues,
-    AnatomicalOrientationTypeValues,
+    PlanarConfigurationValues,
     PatientOrientationValuesBiped,
     PatientOrientationValuesQuadruped,
-    UniversalEntityIDTypeValues
+    PresentationLUTShapeValues,
+    RescaleTypeValues,
+    UniversalEntityIDTypeValues,
+    VOILUTFunctionValues,
 )
 from highdicom import frame
 from highdicom import io
@@ -43,11 +60,17 @@
 __all__ = [
     'AlgorithmIdentificationSequence',
     'AnatomicalOrientationTypeValues',
+    'ContentCreatorIdentificationCodeSequence',
     'ContentQualificationValues',
     'CoordinateSystemNames',
     'DimensionOrganizationTypeValues',
     'IssuerOfIdentifier',
     'LateralityValues',
+    'LUT',
+    'ModalityLUT',
+    'ModalityLUTTransformation',
+    'PaletteColorLUT',
+    'PaletteColorLUTTransformation',
     'PatientOrientationValuesBiped',
     'PatientOrientationValuesQuadruped',
     'PatientSexValues',
@@ -57,21 +80,32 @@
     'PlanarConfigurationValues',
     'PlaneOrientationSequence',
     'PlanePositionSequence',
+    'PresentationLUT',
+    'PresentationLUTShapeValues',
+    'PresentationLUTTransformation',
+    'ReferencedImageSequence',
+    'RescaleTypeValues',
+    'SegmentedPaletteColorLUT',
     'SpecimenCollection',
     'SpecimenDescription',
     'SpecimenPreparationStep',
+    'SpecimenProcessing',
     'SpecimenSampling',
     'SpecimenStaining',
     'SOPClass',
     'UID',
     'UniversalEntityIDTypeValues',
+    'VOILUT',
+    'VOILUTFunctionValues',
+    'VOILUTTransformation',
     'ann',
     'color',
     'frame',
     'io',
     'ko',
     'legacy',
     'pm',
+    'pr',
     'sc',
     'seg',
     'spatial',

src/highdicom/_module_utils.py

@@ -4,6 +4,10 @@
 from pydicom import Dataset
 
 from highdicom._modules import MODULE_ATTRIBUTE_MAP
+from highdicom._iods import (
+    IOD_MODULE_MAP,
+    SOP_CLASS_UID_IOD_KEY_MAP
+)
 
 
 # Allowed values for the type of an attribute
@@ -167,3 +171,65 @@ def construct_module_tree(module: str) -> Dict[str, Any]:
             'type': AttributeTypeValues(item['type'])
         }
     return tree
+
+
+def is_attribute_in_iod(attribute: str, sop_class_uid: str) -> bool:
+    """Check whether an attribute is present within an IOD.
+
+    Parameters
+    ----------
+    attribute: str
+        Keyword for the attribute
+    sop_class_uid: str
+        SOP Class UID identifying the IOD.
+
+    Returns
+    -------
+    bool:
+        True if the attribute is present within any module within the IOD
+        specified by the sop_class_uid. False otherwise.
+
+    """
+    try:
+        iod_name = SOP_CLASS_UID_IOD_KEY_MAP[sop_class_uid]
+    except KeyError as e:
+        msg = f'No IOD found for SOP Class UID: {sop_class_uid}.'
+        raise KeyError(msg) from e
+
+    for module in IOD_MODULE_MAP[iod_name]:
+        module_attributes = MODULE_ATTRIBUTE_MAP[module['key']]
+        for attr in module_attributes:
+            if attr['keyword'] == attribute:
+                return True
+
+    return False
+
+
+def does_iod_have_pixel_data(sop_class_uid: str) -> bool:
+    """Check whether any pixel data attribute is present within an IOD.
+
+    This may be used to determine whether a particular SOP class represents an
+    image.
+
+    Parameters
+    ----------
+    sop_class_uid: str
+        SOP Class UID identifying the IOD.
+
+    Returns
+    -------
+    bool:
+        True if the any pixel data attribute is present within any module
+        within the IOD specified by the sop_class_uid. False otherwise. Pixel
+        data attributes include ``PixelData``, ``FloatPixelData``, and
+        ``DoubleFloatPixelData``.
+
+    """
+    pixel_attrs = [
+        'PixelData',
+        'FloatPixelData',
+        'DoubleFloatPixelData',
+    ]
+    return any(
+        is_attribute_in_iod(attr, sop_class_uid) for attr in pixel_attrs
+    )