Merge branch 'v0.27.0dev' into feature/pm_rebase

Author: CPBridge

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/highdicom_and_pydicom.rst

@@ -26,19 +26,19 @@ There is a wide variety of DICOM objects defined in the standard, covering many
 types of images (X-Ray, CT, MRI, Microscopy, Ophthalmic images) as well as
 various types of image-derived information, such as Structured Reports,
 Annotations, Presentation States, Segmentations, and Parametric Maps. Formally,
-these "types" are known as Information Object Definitions (IODs). The standard
-requires different combinations of attributes are required for different IODs
-(e.g. the "Echo Time" attribute exists with the *MRImage* IOD but not within
-the *CTImage* IOD) ``pydicom`` represents all of these objects using a general
-``Dataset`` class, which implements behavior that is common to all of these
-objects. However, it does not attempt to specialize its representation to
-implement specific behaviors of these various IODs, leaving it up to the user
-to interpret the individual attributes in the file in each case.
+these "types" are known as Information Object Definitions (IODs). Each IOD in
+the standard requires different combinations of attributes. For example, the
+"Echo Time" attribute exists with the *MRImage* IOD but not within the
+*CTImage* IOD. ``pydicom`` represents all of these objects using the same
+general ``Dataset`` class, which implements behavior that is common to all
+DICOM objects However, it does not attempt to specialize its representation to
+implement IOD-specific behavior, leaving this up to the user.
 
 The purpose of ``highdicom`` is to build upon ``pydicom`` to implement specific
-behaviors for various IODs, to make it easier to correctly create and work with
+behaviors for various IODs to make it easier to correctly create and work with
 **specific** types of DICOM object. ``highdicom`` defines sub-classes of
-``pydicom.Dataset`` that implement particular IODs, for example:
+``pydicom.Dataset`` that implement particular IODs, with a specific focus on
+IODs that store information derived from other images. For example:
 
 - :class:`highdicom.Image` (this actually covers many IODs)
 - :class:`highdicom.seg.Segmentation`
@@ -63,11 +63,11 @@ they also have:
   ensuring correctness. The constructors guide you through which attributes are
   required and enforce inter-relationships between them required by the
   standard.
-- Several of these IODs also have further methods that allow you to search,
-  filter, and access the information within them more easily.
+- Further methods that allow you to search, filter, and access the information
+  within them more easily.
 
-However, not all classes within ``highdicom`` are DICOM objects, and such
-objects are not sub-classes of ``pydicom.Dataset``. Notable examples include
+However, some classes within ``highdicom`` are not DICOM objects and as such
+are not sub-classes of ``pydicom.Dataset``. Notable examples include
 :class:`highdicom.Volume`,
 :class:`highdicom.spatial.ImageToReferenceTransformer` (and other similar
 objects), :class:`highdicom.io.ImageFileReader`.

docs/quickstart.rst

@@ -585,7 +585,7 @@ For more information see :doc:`tid1500parsing`.
     assert measurement.value == 10.0
 
     # Access the measurement's unit
-    assert measurement.unit == codes.UCUM.mm
+    assert measurement.unit == codes.UCUM.Millimeter
 
     # Get the diameter measurement in this group
     evaluation = group.get_qualitative_evaluations(

docs/remote.rst

@@ -56,7 +56,7 @@ spatial patch from a large whole slide image from the IDC.
   )
 
   # Read directly from the blob object using lazy frame retrieval
-  with blob.open(mode="rb") as reader:
+  with blob.open(mode="rb", chunk_size=500_000) as reader:
       im = hd.imread(reader, lazy_frame_retrieval=True)
 
       # Grab an arbitrary region of tile full pixel matrix
@@ -80,6 +80,13 @@ spatial patch from a large whole slide image from the IDC.
    Figure produced by the above code snippet showing an arbitrary spatial
    region of a slide loaded directly from a Google Cloud bucket
 
+It is important to set the `chunk_size` parameter carefully. This value is the
+number of bytes that are retrieved in a single request (set to around 500kB in
+the above example). Ideally this should be just large enough to retrieve a
+single frame of the image in one request, but any larger leads to unnecessary
+data being retrieved. The default value is 40MiB, which is orders of magnitude
+larger than the size of most image frames and therefore will be very inefficient.
+
 As a further example, we use lazy frame retrieval to load only a specific set
 of segments from a large multi-organ segmentation of a CT image in the IDC
 stored in binary format (meaning each segment is stored using a separate set of

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,

docs/tid1500.rst

@@ -641,7 +641,7 @@ highdicom test data within the highdicom repository at
     nodule_measurement = hd.sr.Measurement(
         name=codes.SCT.Diameter,
         value=10.0,
-        unit=codes.UCUM.mm,
+        unit=codes.UCUM.Millimeter,
     )
     nodule_evaluation = hd.sr.QualitativeEvaluation(
         name=codes.DCM.LevelOfSignificance,
@@ -677,15 +677,15 @@ highdicom test data within the highdicom repository at
     aorta_measurement = hd.sr.Measurement(
         name=codes.SCT.Diameter,
         value=20.0,
-        unit=codes.UCUM.mm,
+        unit=codes.UCUM.Millimeter,
     )
 
     # Construct the measurement group
     planar_group_2 = hd.sr.PlanarROIMeasurementsAndQualitativeEvaluations(
        referenced_region=region,
        tracking_identifier=aorta_roi_tracking_id,
        finding_type=codes.SCT.Aorta,
-       finding_category=structure_code,
+       finding_category=codes.SCT.AnatomicalStructure,
        measurements=[aorta_measurement],
     )
 
@@ -715,7 +715,7 @@ highdicom test data within the highdicom repository at
     vol_group = hd.sr.VolumetricROIMeasurementsAndQualitativeEvaluations(
        referenced_volume_surface=volume_surface,
        tracking_identifier=volumetric_roi_tracking_id,
-       finding_category=structure_code,
+       finding_category=codes.SCT.AnatomicalStructure,
        finding_type=codes.SCT.Vertebra,
        measurements=[vol_measurement],
     )

docs/tid1500parsing.rst

@@ -304,7 +304,7 @@ property (returns a ``float``), and the unit with the ``unit`` property.
     assert measurement.value == 10.0
 
     # Access the measurement's unit
-    assert measurement.unit == codes.UCUM.mm
+    assert measurement.unit == codes.UCUM.Millimeter
 
 Additionally, the properties ``method``, ``finding_sites``, ``qualifier``,
 ``referenced_images``, and ``derivation`` allow you to access further optional

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: