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). Each IOD in the standard requires different combinations of attributes. For example, the “Echo Time” attribute exists with the MRImage IOD but not within the CTImage IOD. pydicom represents all of these objects using the same general Dataset class, which implements behavior that is common to all DICOM objects However, it does not attempt to specialize its representation to implement IOD-specific behavior, leaving this up to the user.

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, with a specific focus on IODs that store information derived from other images. For example:

• highdicom.Image (this actually covers many IODs)

• highdicom.seg.Segmentation

• highdicom.sr.EnhancedSR

• highdicom.sr.ComprehensiveSR

• highdicom.sr.Comprehensive3DSR

• highdicom.pm.ParametricMap

• highdicom.pr.GrayscaleSoftcopyPresentationState

• highdicom.pr.PseudoColorSoftcopyPresentationState

• highdicom.pr.AdvancedBlendingPresentationState

• highdicom.ko.KeyObjectSelectionDocument

• highdicom.ann.MicroscopyBulkSimpleAnnotations

• 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.

• Further methods that allow you to search, filter, and access the information within them more easily.

However, some classes within highdicom are not DICOM objects and as such are not sub-classes of pydicom.Dataset. Notable examples include highdicom.Volume, highdicom.spatial.ImageToReferenceTransformer (and other similar objects), highdicom.io.ImageFileReader.