v0.26.0dev (#366)

* Add option to use extended offset table (#354)

* Simplify decode_frame to use pydicom deocder directly (#353)

* Improvements to spatial calculations (#357)

* Add debug logging to spatial calculations

* Add perpencicular_tol as a parameter

* Improvements to volume docs

* Fix line length

* Improve logic to match segmentation frames to source images (#361)

* Add debug logging to spatial calculations

* Add perpencicular_tol as a parameter

* Improvements to volume docs

* Fix line length

* Refactor seg spatial metadata preparation

* Recover existing behavior after refactor

* WIP

* Complete implementation of matching; move generic parts to Image class

* Add volume reference tests

* Improve test comments

* Linterfixes

* Minor fixes

* Include further_source_images in plane matching

* Allow references to multiple frames on creation and parsing

* Add tests

* Lint

* Relax requirement for distinct dimensions

* Spell fixes

* Contributing Equipment (#356)

* Implement ContributingEquipment

* Add base_content file

* Remove unneeded import

* Refactor to _add_contributing_equipment method

* Version bump to 0.26.0

* "Usablility" improvements for working with volumes and segmentations (#367)

* Add affine conversion to volume constructors; add match_orientation

* Add ITK and NIfTI conversion docs

* Add pydicom and highdicom docs page

* Add missing docs page

* Rewrite of segmentation pixel array docstring

* lint

* Fix spelling

* Another spell fix

Author: CPBridge

README.md

@@ -7,9 +7,9 @@
 
 # Highdicom
 
-`highdicom` is a pure Python package providing a high-level application programming interface (API) for working with DICOM files, with a focus on common operations required for machine learning, computer vision, and other similar computational analyses. Broadly speaking the package helps with three types of task:
+`highdicom` is a pure Python package built on top of `pydicom` to provide a higher-level application programming interface (API) for working with DICOM files. Its focus is on common operations required for machine learning, computer vision, and other similar computational analyses. Broadly speaking, the package helps with three types of task:
 
-1. Reading existing DICOM image files of a wide variety of modalities (covering radiology, pathology, and more) and formatting the frames to prepare them for computational analysis.
+1. Reading existing DICOM image files of a wide variety of modalities (covering radiology, pathology, and more) and selecting and formatting its frames for computational analysis. This includes considerations such as spatial arrangements of frames, and application of pixel transforms, which are not handled by `pydicom`.
 2. Storing image-derived information, for example from computational analyses or human annotation, in derived DICOM objects for communication and storage. This includes:
     * Annotations
     * Parametric Map images
@@ -19,7 +19,8 @@
     * Key Object Selection documents
     * Legacy Converted Enhanced CT/PET/MR images (e.g., for single frame to multi-frame conversion)
     * Softcopy Presentation State instances (including Grayscale, Color, and Pseudo-Color)
-3. Reading existing derived DICOM files and filtering and accessing the information contained within them.
+
+3. Reading existing derived DICOM files of the above types and filtering and accessing the information contained within them.
 
 ## Documentation
 

docs/general.rst

@@ -10,6 +10,7 @@ parts of the library.
    :maxdepth: 2
    :caption: Contents:
 
+   highdicom_and_pydicom
    image
    pixel_transforms
    volume

docs/highdicom_and_pydicom.rst

@@ -0,0 +1,75 @@
+.. _pydicom-and-highdicom:
+
+Highdicom and Pydicom
+=====================
+
+The ``highdicom`` library is built on top of ``pydicom``. This page summarizes
+the relationship between the two.
+
+Pydicom
+-------
+
+`pydicom`_ is a widely-used Python package for working with DICOM files in
+Python. It uses a fundamental class, ``pydicom.Dataset``, to represent DICOM
+objects within Python programs. It handles operations such as:
+
+- Reading and writing ``Dataset`` objects to/from files.
+- Accessing and setting individual attributes on ``Dataset`` objects.
+- Decoding pixel data within DICOM files to NumPy arrays, and encoding pixel
+  data from NumPy to raw bytes to store within ``Dataset`` objects.
+
+
+Highdicom
+---------
+
+There is a wide variety of DICOM objects defined in the standard, covering many
+types of images (X-Ray, CT, MRI, Microscopy, Ophthalmic images) as well as
+various types of image-derived information, such as Structured Reports,
+Annotations, Presentation States, Segmentations, and Parametric Maps. Formally,
+these "types" are known as Information Object Definitions (IODs). The standard
+requires different combinations of attributes are required for different IODs
+(e.g. the "Echo Time" attribute exists with the *MRImage* IOD but not within
+the *CTImage* IOD) ``pydicom`` represents all of these objects using a general
+``Dataset`` class, which implements behavior that is common to all of these
+objects. However, it does not attempt to specialize its representation to
+implement specific behaviors of these various IODs, leaving it up to the user
+to interpret the individual attributes in the file in each case.
+
+The purpose of ``highdicom`` is to build upon ``pydicom`` to implement specific
+behaviors for various IODs, to make it easier to correctly create and work with
+**specific** types of DICOM object. ``highdicom`` defines sub-classes of
+``pydicom.Dataset`` that implement particular IODs, for example:
+
+- :class:`highdicom.Image` (this actually covers many IODs)
+- :class:`highdicom.seg.Segmentation`
+- :class:`highdicom.sr.EnhancedSR`
+- :class:`highdicom.sr.ComprehensiveSR`
+- :class:`highdicom.sr.Comprehensive3DSR`
+- :class:`highdicom.pm.ParametricMap`
+- :class:`highdicom.pr.GrayscaleSoftcopyPresentationState`
+- :class:`highdicom.pr.PseudoColorSoftcopyPresentationState`
+- :class:`highdicom.pr.AdvancedBlendingPresentationState`
+- :class:`highdicom.ko.KeyObjectSelectionDocument`
+- :class:`highdicom.ann.MicroscopyBulkSimpleAnnotations`
+- :class:`highdicom.sc.SCImage`
+
+Since each of these objects are sub-classes of ``pydicom.Dataset``, they all
+inherit its behaviors for accessing and setting individual attributes and
+writing to file. They should also be interoperable with ``pydicom.Dataset``,
+such that they can be used anywhere a ``pydicom.Dataset`` is expected. However
+they also have:
+
+- A constructor that dramatically simplifies the creation of the objects while
+  ensuring correctness. The constructors guide you through which attributes are
+  required and enforce inter-relationships between them required by the
+  standard.
+- Several of these IODs also have further methods that allow you to search,
+  filter, and access the information within them more easily.
+
+However, not all classes within ``highdicom`` are DICOM objects, and such
+objects are not sub-classes of ``pydicom.Dataset``. Notable examples include
+:class:`highdicom.Volume`,
+:class:`highdicom.spatial.ImageToReferenceTransformer` (and other similar
+objects), :class:`highdicom.io.ImageFileReader`.
+
+.. _`pydicom`: https://pydicom.github.io/pydicom/stable/index.html

docs/index.rst

@@ -1,9 +1,9 @@
 Documentation of the Highdicom Package
 ======================================
 
-``highdicom`` is a pure Python package providing a high-level application programming interface (API) for working with DICOM files, with a focus on common operations required for machine learning, computer vision, and other similar computational analyses. Broadly speaking, the package helps with three types of task:
+``highdicom`` is a pure Python package built on top of ``pydicom`` to provide a higher-level application programming interface (API) for working with DICOM files. Its focus is on common operations required for machine learning, computer vision, and other similar computational analyses. Broadly speaking, the package helps with three types of task:
 
-1. Reading existing DICOM image files of a wide variety of modalities (covering radiology, pathology, and more) and formatting the frames to prepare them for computational analysis.
+1. Reading existing DICOM image files of a wide variety of modalities (covering radiology, pathology, and more) and selecting and formatting its frames for computational analysis. This includes considerations such as spatial arrangements of frames, and application of pixel transforms, which are not handled by ``pydicom``.
 2. Storing image-derived information, for example from computational analyses or human annotation, in derived DICOM objects for communication and storage. This includes:
 
   - Annotations
@@ -15,7 +15,7 @@ Documentation of the Highdicom Package
   - Legacy Converted Enhanced CT/PET/MR images (e.g., for single frame to multi-frame conversion)
   - Softcopy Presentation State instances (including Grayscale, Color, and Pseudo-Color)
 
-3. Reading existing derived DICOM files and filtering and accessing the information contained within them.
+3. Reading existing derived DICOM files of the above types and filtering and accessing the information contained within them.
 
 For new users looking to get an overview of the library's capabilities and perform basic tasks, we recommend starting with the :ref:`quick-start` page. For a detailed introduction to many of the library's capabilities, see the rest of the :ref:`user-guide`. Documentation of all classes and functions may be found in the :ref:`api-docs`.
 

docs/quickstart.rst

@@ -135,7 +135,7 @@ Computed Tomography (CT) images:
             image_datasets[0].Rows,
             image_datasets[0].Columns
         ),
-        dtype=np.bool
+        dtype=bool
     )
     mask[1:-1, 10:-10, 100:-100] = True