Feature/itk volume conversions

.github/workflows/run_unit_tests.yml

@@ -19,7 +19,7 @@ jobs:
         # and the likelihood of 3.12-specific bugs is considered low at this
         # stage
         python-version: ["3.10", "3.11", "3.13", "3.14"]
-        dependencies: [".", "'.[libjpeg]'"]
+        dependencies: [".", "'.[libjpeg,itk,sitk]'"]
 
     env:
       # Set this otherwise coverage on python 3.12 is absurdly slow

docs/general.rst

@@ -16,3 +16,4 @@ parts of the library.
    volume
    coding
    remote
+   other_libraries

docs/itk_lib.rst

@@ -0,0 +1,49 @@
+.. _itk_lib:
+
+ITK
+===
+
+`ITK`_ is a widely-used library for volumetric image processing. In order to
+use ITK with highdicom, the ``itk`` python package must be installed separately.
+Version 5.4.0 or later is required.
+
+.. _itk_vol:
+
+Volume Conversions
+------------------
+
+Highdicom supports conversions with the ``itk.Image`` class through the
+:meth:`highdicom.Volume.to_itk` and :meth:`highdicom.Volume.from_itk` methods.
+Like highdicom, ITK uses the "LPS" convention. However, when converting to and
+from NumPy arrays, ITK reverses the order of dimensions. This permutation is
+handled automatically by highdicom and requires no intervention by the user.
+
+Creating an ITK Image from a Volume:
+
+.. code-block:: python
+
+    import highdicom as hd
+
+
+    vol = hd.Volume(...)
+
+    itk_im = vol.to_itk()
+
+Creating a volume from an ITK Image:
+
+.. code-block:: python
+
+    import itk
+    import highdicom as hd
+
+
+    itk_im = itk.image(...)
+
+    vol = hd.Volume.from_itk(
+        itk_im=itk_im,
+        coordinate_system='PATIENT',
+        frame_of_reference_uid=None
+    )
+
+
+.. _`ITK`: https://itk.org/

docs/other_libraries.rst

@@ -0,0 +1,24 @@
+.. _other_libraries:
+
+Interactions with Other Libraries
+=================================
+
+Highdicom is able to interact with other imaging and scientific python
+libraries. These integrations are intended to provide streamlined access to
+complementary functionality available in external ecosystems that would
+otherwise require custom user code.
+
+Because these libraries are not required for all workflows, they are
+treated as optional dependencies and are not installed as part of the
+default ``highdicom`` installation. Functionality requiring an external
+library becomes available when an appropriate version of the corresponding
+package is installed alongside ``highdicom``. The following sections describe
+which libraries are currently supported and the additional features each
+library enables.
+
+.. toctree::
+   :maxdepth: 3
+   :caption: Contents:
+
+   itk_lib
+   sitk_lib

docs/sitk_lib.rst

@@ -0,0 +1,51 @@
+.. _sitk_lib:
+
+SimpleITK
+=========
+
+`SimpleITK`_ provides a simplified interface for the algorithms and data structures
+of `ITK`_. In order to use ITK with highdicom, the ``SimpleITK`` python package must
+be installed separately. Version 2.2.1 or later is required.
+
+.. _sitk_vol:
+
+Volume Conversions
+------------------
+
+Highdicom supports conversions with the ``SimpleITK.Image`` class through the
+:meth:`highdicom.Volume.to_sitk` and :meth:`highdicom.Volume.from_sitk` methods.
+Like highdicom, SimpleITK uses the "LPS" convention. However, when converting to
+and from NumPy arrays, SimpleITK reverses the order of dimensions. This permutation
+is handled automatically by highdicom and requires no intervention by the user.
+
+
+Creating a SimpleITK Image from a Volume:
+
+.. code-block:: python
+
+    import highdicom as hd
+
+
+    vol = hd.Volume(...)
+
+    sitk_im = vol.to_sitk()
+
+Creating a volume from a SimpleITK Image:
+
+.. code-block:: python
+
+    import SimpleITK as sitk
+    import highdicom as hd
+
+
+    sitk_im = sitk.image(...)
+
+    vol = hd.Volume.from_sitk(
+        sitk_im=sitk_im,
+        coordinate_system='PATIENT',
+        frame_of_reference_uid=None
+    )
+
+
+.. _`ITK`: https://itk.org/
+.. _`SimpleITK`: https://simpleitk.org/

docs/volume.rst

@@ -731,60 +731,20 @@ Writing a volume to a NIfTI file:
     nifti_path = '/path/to/nifti.nii'  # or .nii.gz
     nib.save(nifti, nifti_path)
 
-Volumes To/From ITK Images
---------------------------
 
-`ITK`_ is a widely-used library for volumetric image processing. Its ``Image``
-class shares many similarities with our :class:`highdicom.Volume` class. Like
-highdicom, ITK uses the "LPS" convention. However, when converting to and from
-NumPy arrays, ITK reverses the order of dimensions. It is important to account
-for this when performing conversions.
+Volumes To/From Other Libraries
+-------------------------------
 
-We plan to add tools to handle this conversion in the near future, but for now
-these snippets should correctly handle simple situations converting to and from
-ITK Images.
-
-Creating a volume from an ITK Image:
-
-.. code-block:: python
-
-    import itk
-    import numpy as np
-    import highdicom as hd
-
-
-    im = itk.image(...)
-
-    # Reverse array dimension order
-    array = itk.array_from_image(im).transpose([2, 1, 0])
-
-    vol2 = hd.Volume.from_components(
-        array=array,
-        direction=np.asarray(im.GetDirection()),
-        spacing=np.asarray(im.GetSpacing()),
-        position=np.asarray(im.GetOrigin()),
-        coordinate_system="PATIENT"
-    )
-
-Creating an ITK Image from a Volume:
-
-.. code-block:: python
-
-    import itk
-    import highdicom as hd
-
-
-    vol = hd.Volume(...)
-
-    # Reverse array dimension order
-    array = vol.array.transpose([2, 1, 0])
+Many other libraries have classes that share similarities with our
+:class:`highdicom.Volume` class and allow for simple conversions between
+formats. For commonly used libraries, highdicom Volumes provide
+``to_<library>()`` and ``from_<library>()`` methods to simplify moving to and
+from other libraries as much as possible. For more information about each library,
+visit the following:
 
-    im = itk.image_from_array(array)
-    im.SetOrigin(vol.position)
-    im.SetDirection(vol.direction)
-    im.SetSpacing(vol.spacing)
+  - :ref:`ITK <itk_vol>`
+  - :ref:`SimpleITK <sitk_vol>`
 
 
 .. _`NIfTI`: https://nifti.nimh.nih.gov/
-.. _`ITK`: https://itk.org/
 .. _`nibabel`: https://nipy.org/nibabel/

pyproject.toml

@@ -48,6 +48,8 @@ libjpeg = [
     "pylibjpeg-openjpeg>=2.0.0",
     "pylibjpeg>=2.0",
 ]
+itk = ["itk>=5.4.0"]
+sitk = ["SimpleITK>=2.2.1"]
 
 [dependency-groups]
 test = [