Add CIELabColor to AnnotationGroup

docs/ann.rst

@@ -35,7 +35,7 @@ contains. The required metadata elements include:
 * A ``uid`` (``str`` or :class:`highdicom.UID`) uniquely identifying the group.
   Usually, you will want to generate a UID for this.
 * An ``annotated_property_category`` and ``annotated_property_type``
-  (:class:`highdicom.sr.CodedConcept`) coded values (see :ref:`coding`)
+  (:class:`highdicom.sr.CodedConcept`), coded values (see :ref:`coding`)
   describing the category and specific structure that has been annotated.
 * A ``graphic_type`` (:class:`highdicom.ann.GraphicTypeValues`) indicating the
   "form" of the annotations. Permissible values are ``"ELLIPSE"``, ``"POINT"``,
@@ -45,8 +45,23 @@ contains. The required metadata elements include:
   algorithm used to generate the annotations (``"MANUAL"``,
   ``"SEMIAUTOMATIC"``, or ``"AUTOMATIC"``).
 
-Further optional metadata may optionally be provided, see the API documentation
-for more information.
+Further optional metadata may optionally be provided, including:
+
+* An ``algorithm_identification``
+  (:class:`highdicom.AlgorithmIdentificationSequence`), specifying information
+  about an algorithm that generated the annotations.
+* A list of ``anatomic_regions`` (a sequence of
+  :class:`highdicom.sr.CodedConcept` objects), giving coded values (see
+  :ref:`coding`) describing regions containing the annotations.
+* A list of ``primary_anatomic_structures`` (a sequence of
+  :class:`highdicom.sr.CodedConcept` objects) giving coded values (see
+  :ref:`coding`) describing anatomic structures of interest.
+* A free-text ``description`` (``str``) of the annotation group.
+* A ``display_color`` (:class:`highdicom.color.CIELabColor`) giving a
+  recommended value for viewers to use to render these annotations. This is in
+  CIE-Lab color space, but alternative constructors of the
+  :class:`highdicom.color.CIELabColor` class allow conversion from RGB values
+  or well-known color names.
 
 The actual annotation data is passed to the group as a list of
 ``numpy.ndarray`` objects, each of shape (*N* x *D*). *N* is the number of
@@ -88,6 +103,7 @@ Here is a simple example of constructing an annotation group:
         algorithm_type=hd.ann.AnnotationGroupGenerationTypeValues.MANUAL,
         graphic_type=hd.ann.GraphicTypeValues.POINT,
         graphic_data=graphic_data,
+        display_color=hd.color.CIELabColor.from_string('turquoise'),
     )
 
 Note that including two nuclei would be very unusual in practice: annotations
@@ -141,6 +157,7 @@ Here is the above example with an area measurement included:
         graphic_type=hd.ann.GraphicTypeValues.POINT,
         graphic_data=graphic_data,
         measurements=[area_measurement],
+        display_color=hd.color.CIELabColor.from_string('lawngreen'),
     )
 
 Constructing MicroscopyBulkSimpleAnnotation Objects
@@ -256,7 +273,7 @@ of matching groups, since the filters may match multiple groups.
 
     # If there are no matches, an empty list is returned
     groups = ann.get_annotation_groups(
-        annotated_property_type=Code('53982002', "SCT", "Cell membrane"),
+        annotated_property_type=Code('53982002', 'SCT', 'Cell membrane'),
     )
     assert len(groups) == 0
 

docs/seg.rst

@@ -85,6 +85,13 @@ description includes the following information:
   a human readable ID and unique ID to a specific segment. This can be used,
   for example, to uniquely identify particular lesions over multiple imaging
   studies. These are passed as strings.
+- **Display Color**: (Optional) You can provide a recommended color as a
+  :class:`highdicom.color.CIELabColor` to use when displaying this segment.
+  Some viewers will use this information to decide what color to render the
+  segment by default. This color should be provided in CIE-Lab color space, but
+  alternative constructors of the :class:`highdicom.color.CIELabColor` class
+  allow conversion from RGB values or well-known color names.
+
 
 Notice that the segment description makes use of coded concepts to ensure that
 the way a particular anatomical structure is described is standardized and
@@ -108,6 +115,7 @@ representing a liver that has been manually segmented.
         segmented_property_category=codes.SCT.Organ,
         segmented_property_type=codes.SCT.Liver,
         algorithm_type=hd.seg.SegmentAlgorithmTypeValues.MANUAL,
+        display_color=hd.color.CIELabColor.from_string('red'),
     )
 
 In this second example, we describe a segment representing a tumor that has
@@ -134,6 +142,7 @@ we must first provide more information about the algorithm used in an
         algorithm_type=hd.seg.SegmentAlgorithmTypeValues.AUTOMATIC,
         algorithm_identification=algorithm_identification,
         anatomic_regions=[codes.SCT.Kidney]
+        display_color=hd.color.CIELabColor.from_rgb(0, 0, 255),
     )
 
 For a description of how to access segment metadata in existing segmentations,

src/highdicom/ann/content.py

@@ -13,6 +13,7 @@
     AnnotationGroupGenerationTypeValues,
     GraphicTypeValues,
 )
+from highdicom.color import CIELabColor
 from highdicom.content import AlgorithmIdentificationSequence
 from highdicom.sr.coding import CodedConcept
 from highdicom.uid import UID
@@ -194,7 +195,8 @@ def __init__(
         ) = None,
         primary_anatomic_structures: None | (
             Sequence[Code | CodedConcept]
-        ) = None
+        ) = None,
+        display_color: CIELabColor | None = None,
     ):
         """
         Parameters
@@ -238,6 +240,8 @@ def __init__(
         primary_anatomic_structures: Union[Sequence[Union[highdicom.sr.Code, highdicom.sr.CodedConcept]], None], optional
             Anatomic structure(s) the annotations represent
             (see CIDs for domain-specific primary anatomic structures)
+        display_color: Union[highdicom.color.CIELabColor, None], optional
+            A recommended color to render this annotation group.
 
         """  # noqa: E501
         super().__init__()
@@ -293,6 +297,16 @@ def __init__(
         graphic_type = GraphicTypeValues(graphic_type)
         self.GraphicType = graphic_type.value
 
+        if display_color is not None:
+            if not isinstance(display_color, CIELabColor):
+                raise TypeError(
+                    '"display_color" must be of type '
+                    'highdicom.color.CIELabColor.'
+                )
+            self.RecommendedDisplayCIELabValue = list(
+                display_color.value
+            )
+
         for i in range(len(graphic_data)):
             num_coords = graphic_data[i].shape[0]
             if graphic_type == GraphicTypeValues.POINT: