Feature/itk volume conversions

pyproject.toml

@@ -63,6 +63,10 @@ docs = [
     "sphinxcontrib-autoprogram==0.1.7",
     "sphinxcontrib-websupport==1.2.4",
 ]
+itk = [
+    "itk>=5.4.0",
+    "SimpleITK>=2.5.0"
+]
 
 [project.urls]
 homepage = "https://github.com/imagingdatacommons/highdicom"

src/highdicom/volume.py

@@ -1,4 +1,5 @@
 """Representations of multidimensional arrays with spatial metadata."""
+from __future__ import annotations
 from abc import ABC, abstractmethod
 from enum import Enum
 import itertools
@@ -44,6 +45,7 @@
     keyword_for_tag,
 )
 
+from highdicom._dependency_utils import import_optional_dependency
 
 _DCM_PYTHON_TYPE_MAP = {
     'CS': str,
@@ -3583,6 +3585,150 @@ def pad_array(array: np.ndarray, cval: float) -> float:
             channels=self._channels,
         )
 
+    def to_sitk(self) -> SimpleITK.Image: # noqa
+        """Convert the Volume to `SimpleITK.Image` format.
+
+        Returns
+        -------
+        SimpleITK.Image:
+            Image constructed from the Volume.
+
+        """
+        func = self.to_sitk
+        sitk = import_optional_dependency(
+            module_name='SimpleITK',
+            feature=f'{func.__module__}.{func.__qualname__}'
+        )
+
+        array = self.array.transpose(2, 1, 0)
+
+        if self.dtype == np.bool_:
+            array = array.astype(int)
+
+        sitk_im = sitk.GetImageFromArray(array)
+        sitk_im.SetSpacing(self.spacing)
+        sitk_im.SetDirection(self.direction.flatten())
+        sitk_im.SetOrigin(self.position)
+
+        return sitk_im
+
+    @classmethod
+    def from_sitk(
+        cls,
+        sitk_im: SimpleITK.Image, # noqa
+        coordinate_system: CoordinateSystemNames | str = 'PATIENT',
+        frame_of_reference_uid: str | None = None,
+    ) -> Self:
+        """Construct a Volume from a `SimpleITK.Image`.
+
+        Parameters
+        ----------
+        sitk_im: SimpleITK.Image
+            A `SimpleITK.Image` to convert to a volume.
+        coordinate_system: highdicom.CoordinateSystemNames | str
+            Coordinate system (``"PATIENT"`` or ``"SLIDE"``) in which the volume
+            is defined.
+        frame_of_reference_uid: Union[str, None], optional
+            Frame of reference UID for the frame of reference, if known.
+
+        Returns
+        -------
+        highdicom.Volume:
+            Volume constructed from the `SimpleITK.Image`.
+
+        """
+        func = cls.from_sitk
+        sitk = import_optional_dependency(
+            module_name='SimpleITK',
+            feature=f'{func.__module__}.{func.__qualname__}'
+        )
+
+        array = sitk.GetArrayFromImage(sitk_im).transpose(2, 1, 0)
+
+        if array.dtype == np.bool_:
+            array = array.astype(int)
+
+        return cls.from_components(
+            array=array,
+            spacing=sitk_im.GetSpacing(),
+            coordinate_system=coordinate_system,
+            direction=np.reshape(sitk_im.GetDirection(), (3, 3)),
+            position=sitk_im.GetOrigin(),
+            frame_of_reference_uid=frame_of_reference_uid
+        )
+
+    def to_itk(self) -> itk.Image: # noqa
+        """Convert the volume to `itk.Image` format.
+
+        Returns
+        -------
+        itk.Image:
+            Image constructed from the volume.
+
+        """
+        func = self.to_itk
+        itk = import_optional_dependency(
+            module_name='itk',
+            feature=f'{func.__module__}.{func.__qualname__}'
+        )
+
+        array = self.array
+
+        if self.dtype == np.bool_:
+            array = array.astype(int)
+
+        itk_im = itk.GetImageFromArray(array)
+        itk_im.SetSpacing(self.spacing)
+        itk_im.SetDirection(self.direction)
+        itk_im.SetOrigin(self.position)
+
+        return itk_im
+
+    @classmethod
+    def from_itk(
+        cls,
+        itk_im: itk.Image, # noqa
+        coordinate_system: CoordinateSystemNames | str = 'PATIENT',
+        frame_of_reference_uid: str | None = None,
+    ) -> Self:
+        """Construct a Volume from an `itk.Image`.
+
+        Parameters
+        ----------
+        itk_im: itk.Image
+            A `itk.Image` to convert to a volume.
+        coordinate_system: highdicom.CoordinateSystemNames | str
+            Coordinate system (``"PATIENT"`` or ``"SLIDE"``) in which the volume
+            is defined.
+        frame_of_reference_uid: Union[str, None], optional
+            Frame of reference UID for the frame of reference, if known.
+
+        Returns
+        -------
+        highdicom.Volume:
+            Volume constructed from the `itk.Image`.
+
+        """
+        func = cls.from_itk
+        itk = import_optional_dependency(
+            module_name='itk',
+            feature=f'{func.__module__}.{func.__qualname__}'
+        )
+
+        array = itk.GetArrayFromImage(itk_im)
+
+        if array.dtype == np.bool_:
+            array = array.astype(int)
+
+        return cls.from_components(
+            array=array,
+            spacing=np.array(itk_im.GetSpacing()),
+            coordinate_system=coordinate_system,
+            direction=np.reshape(itk_im.GetDirection(), (3, 3)),
+            position=np.array(itk_im.GetOrigin()),
+            frame_of_reference_uid=frame_of_reference_uid
+        )
+
 
 class VolumeToVolumeTransformer: