Merge pull request #415 from ImagingDataCommons/v0.28.0dev

v0.28.0

Author: CPBridge

.codespellrc

@@ -1,4 +1,4 @@
 [codespell]
 skip = .git,*.pdf,*.svg,*.ipynb
 # te,fo - either abbreviations of variables
-ignore-words-list = te,fo,socio-economic,laf
+ignore-words-list = te,fo,socio-economic,laf,re-use

.github/workflows/run_unit_tests.yml

@@ -11,15 +11,35 @@ on:
 
 jobs:
   build:
+    runs-on: ${{ matrix.os }}
 
-    runs-on: ubuntu-latest
     strategy:
+      fail-fast: false
+
       matrix:
         # NB no 3.12 because an issue with coverage makes it extremely slow
         # and the likelihood of 3.12-specific bugs is considered low at this
         # stage
+        os: [ubuntu-latest]
         python-version: ["3.10", "3.11", "3.13", "3.14"]
-        dependencies: [".", "'.[libjpeg]'"]
+        dependencies: [".", ".[libjpeg,itk,simpleitk,nibabel]"]
+
+        include:
+          - os: windows-latest
+            python-version: "3.14"
+            dependencies: "."
+
+          - os: windows-latest
+            python-version: "3.14"
+            dependencies: ".[libjpeg,itk,simpleitk,nibabel]"
+
+          - os: macos-latest
+            python-version: "3.14"
+            dependencies: "."
+
+          - os: macos-latest
+            python-version: "3.14"
+            dependencies: ".[libjpeg,itk,simpleitk,nibabel]"
 
     env:
       # Set this otherwise coverage on python 3.12 is absurdly slow
@@ -38,8 +58,7 @@ jobs:
         pip install ${{ matrix.dependencies }}
     - name: Lint with flake8
       run: |
-        flake8 --exclude='bin,build,.eggs,src/highdicom/_*'
+        flake8 --exclude='bin,build,.eggs'
     - name: Test with pytest
       run: |
         pytest --cov=highdicom --cov-fail-under=80
-

bin/create_iods_modules.py

@@ -12,11 +12,12 @@
 logger = logging.getLogger(__name__)
 
 
-PGK_PATH = os.path.join(
+PKG_JSON_PATH = os.path.join(
     os.path.dirname(__file__),
     '..',
     'src',
-    'highdicom'
+    'highdicom',
+    '_standard',
 )
 
 
@@ -25,10 +26,6 @@ def _load_json_from_file(filename):
         return json.load(f)
 
 
-def _dump_json(data):
-    return json.dumps(data, indent=4, sort_keys=True)
-
-
 def _create_sop_to_iods(directory):
     filename = os.path.join(directory, 'sops.json')
     sops = _load_json_from_file(filename)
@@ -97,14 +94,16 @@ def _create_modules(directory):
     return modules
 
 
-if __name__ == '__main__':
-
+if __name__ == "__main__":
     logging.basicConfig()
     logger.setLevel(logging.DEBUG)
 
     # Positional argument is path to directory containing JSON files generated
     # using the dicom-standard Python package, see
     # https://github.com/innolitics/dicom-standard/tree/master/standard
+    # If generating yourself using the instructions in that repo, be sure to
+    # use "make all" instead of just "make", otherwise some of the required
+    # files are skipped
     try:
         directory = sys.argv[1]
     except IndexError as e:
@@ -119,37 +118,16 @@ def _create_modules(directory):
     current_time = datetime.datetime.time(now).strftime('%H:%M:%S')
 
     iods = _create_iods(directory)
-    iods_docstr = '\n'.join([
-        '"""DICOM Information Object Definitions (IODs)',
-        f'auto-generated on {current_date} at {current_time}.',
-        '"""',
-        'from typing import Dict, List'
-    ])
+    iods_filename = os.path.join(PKG_JSON_PATH, 'iods.json')
+    with open(iods_filename, 'w') as jf:
+        json.dump(iods, jf, indent=2)
+
     sop_to_iods = _create_sop_to_iods(directory)
-    iods_filename = os.path.join(PGK_PATH, '_iods.py')
-    with open(iods_filename, 'w') as fp:
-        fp.write(iods_docstr)
-        fp.write('\n\n')
-        iods_formatted = _dump_json(iods).replace('null', 'None')
-        fp.write(
-            f'IOD_MODULE_MAP: Dict[str, List[Dict[str, str]]] = {iods_formatted}'
-        )
-        fp.write('\n\n')
-        sop_to_iods_formatted = _dump_json(sop_to_iods).replace('null', 'None')
-        fp.write(f'SOP_CLASS_UID_IOD_KEY_MAP = {sop_to_iods_formatted}')
+    sop_to_iods_filename = os.path.join(PKG_JSON_PATH, 'sop_class_to_iod.json')
+    with open(sop_to_iods_filename, 'w') as jf:
+        json.dump(sop_to_iods, jf, indent=2)
 
     modules = _create_modules(directory)
-    modules_docstr = '\n'.join([
-        '"""DICOM modules'
-        f'auto-generated on {current_date} at {current_time}.'
-        '"""',
-        'from typing import Dict, List, Sequence, Union'
-    ])
-    modules_filename = os.path.join(PGK_PATH, '_modules.py')
-    with open(modules_filename, 'w') as fp:
-        fp.write(modules_docstr)
-        fp.write('\n\n')
-        modules_formatted = _dump_json(modules).replace('null', 'None')
-        fp.write(
-            f'MODULE_ATTRIBUTE_MAP: Dict[str, List[Dict[str, Union[str, Sequence[str]]]]] = {modules_formatted}'  # noqa: E501
-        )
+    modules_filename = os.path.join(PKG_JSON_PATH, 'modules.json')
+    with open(modules_filename, 'w') as jf:
+        json.dump(modules, jf, indent=2)

docs/coding.rst

@@ -182,3 +182,16 @@ documentation for the coding scheme itself. This
 `webpage <https://fedorov.github.io/dcmterms/terminology.html>`_ is a nice
 interactive tool for searching the terms and Context Groups defined within
 DICOM.
+
+UCUM
+----
+
+UCUM works a little differently to the other coding schemes discussed here.
+Rather than a finite set of codes, it defines codes for a set of units and a
+syntax for combining them to give derived units (e.g. `"mm/s"` for millimeters
+per second), meaning there are potentially infinite codes. Pydicom defines
+a list of the most common units, but this will not cover every use case.
+
+We recommend this `page
+<https://ucum.nlm.nih.gov/ucum-lhc/demo.html>`_, a useful validator for
+checking UCUM syntax.

docs/general.rst

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

docs/image.rst

@@ -243,6 +243,26 @@ matrix. In these cases, the first spatial dimension will always have shape 1.
 
 See :doc:`volume` for an overview of the :class:`highdicom.Volume` class.
 
+Accessing Frames By Derivation Source
+-------------------------------------
+
+Some DICOM images are derived from other DICOM images. This pattern is common
+in IODs designed specifically for derived images, such as Parametric Maps, but
+can also occur in many other types of image. In this case, the image *may*
+contain frame-level references that communicate which frames/instance each
+frame was derived from. If such information is present in a file, highdicom
+provides methods to access derived frames by specifying information about
+the source frame.
+
+The two methods implementing this behavior are:
+
+* :meth:`highdicom.Image.get_pixels_by_source_instance` is used when each
+  frame of the image is derived from a different instance of a series of
+  single-frame images, identified by its SOP Instance UID.
+* :meth:`highdicom.Image.get_pixels_by_source_frame` is used when each frame of
+  the image is derived from a different frame of a multi-frame source image,
+  identified by the source frame number.
+
 .. _lazy:
 
 Lazy Frame Retrieval

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_image = vol.to_itk()
+
+Creating a volume from an ITK Image:
+
+.. code-block:: python
+
+    import itk
+    import highdicom as hd
+
+
+    itk_image = itk.Image(...)
+
+    vol = hd.Volume.from_itk(
+        itk_image=itk_image,
+        coordinate_system='PATIENT',
+        frame_of_reference_uid=None
+    )
+
+
+.. _`ITK`: https://itk.org/