Copy subject context (#298)

* Add SubjectContextSpecimen.from_image() method

* Import related fixes; remove fix_meta_info, now unnecessary

* Drop support for python<3.10

* Fixes to codes and RLE encoding

* Remove fix for resolved pydicom bug in decode_frame

* Fix frame encoding and decoding, add further transfer syntaxes

* Various fixes

* Enforce repo-review rules (#296)

* Enforce repo-review rule PP302

PP302: Sets a minimum pytest to at least 6

Must have a `minversion=`, and must be at least 6 (first version to
support `pyproject.toml` configuration).

* Enforce repo-review rule PP305

PP305: Specifies xfail_strict

`xfail_strict` should be set. You can manually specify if a check should
be strict when setting each xfail.

* Enforce repo-review rule PP306

PP306: Specifies strict config

`--strict-config` should be in `addopts = [...]`. This forces an error
if a config setting is misspelled.

* Enforce repo-review rule PP307

PP307: Specifies strict markers

`--strict-markers` should be in `addopts = [...]`. This forces all
markers to be specified in config, avoiding misspellings.

* Enforce repo-review rule PP308

PP308: Specifies useful pytest summary

An explicit summary flag like `-ra` should be in `addopts = [...]` (print
summary of all fails/errors).

* Enforce pytest ≥ 7.3.2

This is the first version to support Python 3.12:
https://docs.pytest.org/en/stable/changelog.html#pytest-7-3-2-2023-06-10

* Enforce repo-review rule MY104

MY104: MyPy enables ignore-without-code

Must have `"ignore-without-code"` in `enable_error_code = [...]`. This
will force all skips in your project to include the error code, which
makes them more readable, and avoids skipping something unintended.

* Enforce repo-review rule MY105

MY105: MyPy enables redundant-expr

Must have `"redundant-expr"` in `enable_error_code = [...]`. This helps
catch useless lines of code, like checking the same condition twice.

* Enforce repo-review rule MY106

MY106: MyPy enables truthy-bool

Must have `"truthy-bool"` in `enable_error_code = []`. This catches
mistakes in using a value as truthy if it cannot be falsy.

* Remove pillow-jpls dependency as functionality now comes from pylibjpeg

* Add details of single bit JPEG2000 to the docs

* Better workaround for floating point pixel decoding

* Adjust dependencies

* Deprecate row_stack for vstack

* Bump pydicom version to 3.0.1

* Error message typo

* Add SubjectContext.for_image() method

---------

Co-authored-by: Dimitri Papadopoulos Orfanos <3234522+DimitriPapadopoulos@users.noreply.github.com>

Author: CPBridge

src/highdicom/sr/templates.py

@@ -1703,7 +1703,7 @@ def __init__(
             Identifier of the observed specimen (may have limited scope,
             e.g., only relevant with respect to the corresponding container)
         container_identifier: Union[str, None], optional
-            Identifier of the container holding the speciment (e.g., a glass
+            Identifier of the container holding the specimen (e.g., a glass
             slide)
         specimen_type: Union[pydicom.sr.coding.Code, highdicom.sr.CodedConcept, None], optional
             Type of the specimen (see
@@ -1809,6 +1809,49 @@ def specimen_type(self) -> Union[CodedConcept, None]:
             return matches[0].value
         return None
 
+    @classmethod
+    def from_image(
+        cls,
+        image: Dataset,
+    ) -> 'SubjectContextSpecimen':
+        """Deduce specimen information from an existing image.
+
+        This is appropriate, for example, when copying the specimen information
+        from a source image into a derived SR or similar object.
+
+        Parameters
+        ----------
+        image: pydicom.Dataset
+            An image from which to infer specimen information. There is no
+            limitation on the type of image, however it must have the Specimen
+            module included.
+
+        Raises
+        ------
+        ValueError:
+            If the input image does not contain specimen information.
+
+        """
+        if not hasattr(image, 'ContainerIdentifier'):
+            raise ValueError("Image does not contain specimen information.")
+
+        description = image.SpecimenDescriptionSequence[0]
+
+        # Specimen type code sequence is optional
+        if hasattr(description, 'SpecimenTypeCodeSequence'):
+            specimen_type: Optional[CodedConcept] = CodedConcept.from_dataset(
+                description.SpecimenTypeCodeSequence[0]
+            )
+        else:
+            specimen_type = None
+
+        return cls(
+            container_identifier=image.ContainerIdentifier,
+            identifier=description.SpecimenIdentifier,
+            uid=description.SpecimenUID,
+            specimen_type=specimen_type,
+        )
+
     @classmethod
     def from_sequence(
         cls,
@@ -2124,6 +2167,41 @@ def __init__(
             raise TypeError('Unexpected subject class specific context.')
         self.extend(subject_class_specific_context)
 
+    @classmethod
+    def from_image(cls, image: Dataset) -> 'Optional[SubjectContext]':
+        """Get a subject context inferred from an existing image.
+
+        Currently this is only supported for subjects that are specimens.
+
+        Parameters
+        ----------
+        image: pydicom.Dataset
+            Dataset of an existing DICOM image object
+            containing metadata on the imaging subject. Highdicom will attempt
+            to infer the subject context from this image. If successful, it
+            will be returned as a ``SubjectContext``, otherwise ``None``.
+
+        Returns
+        -------
+        Optional[highdicom.sr.SubjectContext]:
+            SubjectContext, if it can be inferred from the image. Otherwise,
+            ``None``.
+
+        """
+        try:
+            subject_context_specimen = SubjectContextSpecimen.from_image(
+                image
+            )
+        except ValueError:
+            pass
+        else:
+            return cls(
+                subject_class=codes.DCM.Specimen,
+                subject_class_specific_context=subject_context_specimen,
+            )
+
+        return None
+
     @property
     def subject_class(self) -> CodedConcept:
         """highdicom.sr.CodedConcept: type of subject"""

tests/test_sr.py

@@ -1398,6 +1398,113 @@ def test_construction_all(self):
         assert context[5].TextValue == self._physical_location
 
 
+class TestSubjectContextSpecimen(unittest.TestCase):
+
+    def setUp(self):
+        super().setUp()
+        file_path = Path(__file__)
+        data_dir = file_path.parent.parent.joinpath('data')
+        self._sm_image = dcmread(
+            str(data_dir.joinpath('test_files', 'sm_image.dcm'))
+        )
+
+    def test_from_image(self):
+        specimen_context = SubjectContextSpecimen.from_image(
+            self._sm_image
+        )
+
+        assert (
+            specimen_context.container_identifier ==
+            self._sm_image.ContainerIdentifier
+        )
+        description = self._sm_image.SpecimenDescriptionSequence[0]
+        assert (
+            specimen_context.specimen_identifier ==
+            description.SpecimenIdentifier
+        )
+        assert (
+            specimen_context.specimen_uid == description.SpecimenUID
+        )
+        assert specimen_context.specimen_type == codes.SCT.TissueSection
+
+    def test_from_image_no_specimen_type(self):
+        # Specimen type is optional, for_image method should cope corectly if
+        # it is missing
+        image = deepcopy(self._sm_image)
+        delattr(
+            image.SpecimenDescriptionSequence[0],
+            'SpecimenTypeCodeSequence'
+        )
+        specimen_context = SubjectContextSpecimen.from_image(image)
+
+        assert (
+            specimen_context.container_identifier ==
+            self._sm_image.ContainerIdentifier
+        )
+        description = self._sm_image.SpecimenDescriptionSequence[0]
+        assert (
+            specimen_context.specimen_identifier ==
+            description.SpecimenIdentifier
+        )
+        assert (
+            specimen_context.specimen_uid == description.SpecimenUID
+        )
+        assert specimen_context.specimen_type is None
+
+
+class TestSubjectContext(unittest.TestCase):
+
+    def setUp(self):
+        super().setUp()
+        file_path = Path(__file__)
+        data_dir = file_path.parent.parent.joinpath('data')
+        self._sm_image = dcmread(
+            str(data_dir.joinpath('test_files', 'sm_image.dcm'))
+        )
+        self._ct_image = dcmread(
+            str(data_dir.joinpath('test_files', 'ct_image.dcm'))
+        )
+
+    def test_from_image(self):
+        subject_context = SubjectContext.from_image(
+            self._sm_image
+        )
+
+        assert subject_context is not None
+
+        has_specimen_uid = False
+        has_specimen_id = False
+        has_container_id = False
+
+        for item in subject_context:
+
+            # SpecimenUID
+            if item.ConceptNameCodeSequence[0].CodeValue == '121039':
+                assert item.UID == '2.25.281821656492584880365678271074145532563'
+                has_specimen_uid = True
+
+            # Specimen Identifier
+            elif item.ConceptNameCodeSequence[0].CodeValue == '121041':
+                assert item.TextValue == 'S19-1_A_1_1'
+                has_specimen_id = True
+
+            # Specimen Container Identifier
+            elif item.ConceptNameCodeSequence[0].CodeValue == '111700':
+                assert item.TextValue == 'S19-1_A_1_1'
+                has_container_id = True
+
+        assert has_specimen_uid
+        assert has_specimen_id
+        assert has_container_id
+
+    def test_from_image_no_subject_info(self):
+        subject_context = SubjectContext.from_image(
+            self._ct_image
+        )
+
+        assert subject_context is None
+
+
 class TestObservationContext(unittest.TestCase):
 
     def setUp(self):