Add properties and methods to SR content items and templates

src/highdicom/sr/value_types.py

@@ -1,6 +1,6 @@
 """DICOM structured reporting content item value types."""
 import datetime
-from typing import Any, List, Optional, Sequence, Union
+from typing import Any, List, Optional, Sequence, Tuple, Union
 
 import numpy as np
 from pydicom.dataset import Dataset
@@ -72,7 +72,7 @@ def name(self) -> CodedConcept:
     @property
     def value_type(self) -> str:
         """str: type of the content item
-        (see `highdicom.sr.value_types.ValueTypeValues`)
+        (see `highdicom.sr.enum.ValueTypeValues`)
 
         """
         return self.ValueType
@@ -204,6 +204,11 @@ def __init__(
             value = CodedConcept(*value)
         self.ConceptCodeSequence = [value]
 
+    @property
+    def value(self) -> CodedConcept:
+        """highdicom.sr.coding.CodedConcept: coded concept"""
+        return self.ConceptCodeSequence[0]
+
 
 class PnameContentItem(ContentItem):
 
@@ -233,6 +238,11 @@ def __init__(
         )
         self.PersonName = PersonName(value)
 
+    @property
+    def value(self) -> str:
+        """str: person name"""
+        return self.PersonName
+
 
 class TextContentItem(ContentItem):
 
@@ -262,6 +272,11 @@ def __init__(
         )
         self.TextValue = str(value)
 
+    @property
+    def value(self) -> str:
+        """str: text value"""
+        return self.TextValue
+
 
 class TimeContentItem(ContentItem):
 
@@ -291,6 +306,23 @@ def __init__(
         )
         self.Time = TM(value)
 
+    @property
+    def value(self) -> datetime.time:
+        """datetime.time: time"""
+        allowed_formats = [
+            '%H:%M:%S.%f',
+            '%H:%M:%S',
+            '%H:%M',
+            '%H',
+        ]
+        for fmt in allowed_formats:
+            try:
+                dt = datetime.datetime.strptime(self.Time.isoformat(), fmt)
+                return dt.time()
+            except ValueError:
+                continue
+        raise ValueError(f'Could not decode time value "{self.Time}"')
+
 
 class DateContentItem(ContentItem):
 
@@ -320,6 +352,12 @@ def __init__(
         )
         self.Date = DA(value)
 
+    @property
+    def value(self) -> datetime.date:
+        """datetime.date: date"""
+        fmt = '%Y-%m-%d'
+        return datetime.datetime.strptime(self.Date.isoformat(), fmt).date()
+
 
 class DateTimeContentItem(ContentItem):
 
@@ -349,6 +387,30 @@ def __init__(
         )
         self.DateTime = DT(value)
 
+    @property
+    def value(self) -> datetime.datetime:
+        """datetime.datetime: datetime"""
+        allowed_formats = [
+            '%Y-%m-%dT%H:%M:%S.%f%z',
+            '%Y-%m-%dT%H:%M:%S.%f',
+            '%Y-%m-%dT%H:%M:%S',
+            '%Y-%m-%dT%H:%M:%S%z',
+            '%Y-%m-%dT%H:%M',
+            '%Y-%m-%dT%H:%M%z',
+            '%Y-%m-%dT%H',
+            '%Y-%m-%dT%H%z',
+            '%Y-%m-%d',
+            '%Y-%m',
+            '%Y',
+        ]
+        for fmt in allowed_formats:
+            try:
+                dt = datetime.datetime.strptime(self.DateTime.isoformat(), fmt)
+                return dt
+            except ValueError:
+                continue
+        raise ValueError(f'Could not decode datetime value "{self.DateTime}"')
+
 
 class UIDRefContentItem(ContentItem):
 
@@ -378,6 +440,11 @@ def __init__(
         )
         self.UID = value
 
+    @property
+    def value(self) -> str:
+        """str: UID"""
+        return str(self.UID)
+
 
 class NumContentItem(ContentItem):
 
@@ -452,6 +519,21 @@ def __init__(
                 'upon creation of NumContentItem.'
             )
 
+    @property
+    def value(self) -> Union[int, float]:
+        """Union[int, float]: measured value"""
+        item = self.MeasuredValueSequence[0]
+        try:
+            return float(item.FloatingPointValue)
+        except AttributeError:
+            return item.NumericValue
+
+    @property
+    def unit(self) -> CodedConcept:
+        """highdicom.sr.coding.CodedConcept: unit"""
+        item = self.MeasuredValueSequence[0]
+        return item.MeasurementUnitsCodeSequence[0]
+
 
 class ContainerContentItem(ContentItem):
 
@@ -493,6 +575,15 @@ def __init__(
             item.TemplateIdentifier = str(template_id)
             self.ContentTemplateSequence = [item]
 
+    @property
+    def template_id(self) -> Union[str, None]:
+        """Union[str, None]: template identifier"""
+        try:
+            item = self.ContentTemplateSequence[0]
+            return item.TemplateIdentifier
+        except (AttributeError, IndexError):
+            return None
+
 
 class CompositeContentItem(ContentItem):
 
@@ -528,6 +619,12 @@ def __init__(
         item.ReferencedSOPInstanceUID = str(referenced_sop_instance_uid)
         self.ReferencedSOPSequence = [item]
 
+    @property
+    def value(self) -> Tuple[str, str]:
+        """Tuple[str, str]: referenced SOP Class UID and SOP Instance UID"""
+        item = self.ReferencedSOPSequence[0]
+        return (item.ReferencedSOPClassUID, item.ReferencedSOPInstanceUID)
+
 
 class ImageContentItem(ContentItem):
 
@@ -579,6 +676,12 @@ def __init__(
             item.ReferencedSegmentNumber = referenced_segment_numbers
         self.ReferencedSOPSequence = [item]
 
+    @property
+    def value(self) -> Tuple[str, str]:
+        """Tuple[str, str]: referenced SOP Class UID and SOP Instance UID"""
+        item = self.ReferencedSOPSequence[0]
+        return (item.ReferencedSOPClassUID, item.ReferencedSOPInstanceUID)
+
 
 class ScoordContentItem(ContentItem):
 
@@ -639,7 +742,7 @@ def __init__(
             if graphic_data.shape[0] != 1 or not graphic_data.shape[1] == 2:
                 raise ValueError(
                     'Graphic data of a scoord of graphic type "POINT" '
-                    'must be a single (column row) pair in two-dimensional '
+                    'must be a single (column, row) pair in two-dimensional '
                     'image coordinate space.'
                 )
         elif graphic_type == GraphicTypeValues.CIRCLE:
@@ -676,6 +779,13 @@ def __init__(
         if fiducial_uid is not None:
             self.FiducialUID = fiducial_uid
 
+    @property
+    def value(self) -> np.ndarray:
+        """numpy.ndarray: spatial coordinates"""
+        graphic_data = np.array(self.GraphicData)
+        n_points = len(graphic_data) / 2
+        return np.array(np.array_split(graphic_data, n_points))
+
 
 class Scoord3DContentItem(ContentItem):
 
@@ -758,6 +868,13 @@ def __init__(
         if fiducial_uid is not None:
             self.FiducialUID = fiducial_uid
 
+    @property
+    def value(self) -> np.ndarray:
+        """numpy.ndarray: spatial coordinates"""
+        graphic_data = np.array(self.GraphicData)
+        n_points = len(graphic_data) / 3
+        return np.array(np.array_split(graphic_data, n_points))
+
 
 class TcoordContentItem(ContentItem):
 
@@ -817,3 +934,15 @@ def __init__(
                     ])
                 )
             )
+
+    @property
+    def value(self) -> Union[List[int], List[float], List[datetime.datetime]]:
+        """Union[List[int], List[float], List[datetime.datetime]]: time points
+        """
+        try:
+            return self.ReferencedSamplePositions
+        except AttributeError:
+            try:
+                return self.ReferencedTimeOffsets
+            except AttributeError:
+                return self.ReferencedDateTime