The Image Class

The most basic usage case is reading a single DICOM image (.dcm file) as an Image instance.

>>> from dicom_parser import Image
>>> image = Image('/path/to/dicom/file.dcm')

Images have a header attribute, which stores the parsed Header instance.

>>> image.header
             Keyword                      VR                VM  Value
(0008, 0005)  SpecificCharacterSet         Code String       1   ISO_IR 100
(0008, 0008)  ImageType                    Code String       5   ('ORIGINAL', 'PRIMARY', ...
(0008, 0012)  InstanceCreationDate         Date              1   2018-05-01

dicom_parser provides dict-like access to the parsed values of the header's data-elements. The raw values as read by pydicom remain accessible through the raw attribute. For a full comparison of the expected return types, see Value Representation.


The dict-like functionality also includes safe getting:

>>> image.header.get('MissingKey')

>>> image.header.get('MissingKey', 'DefaultValue')

As well as raising a KeyError for missing keys with the indexing operator:

>>> image.header['MissingKey']
KeyError: "The keyword: 'MissingKey' does not exist in the header!"

The Series Class

Another useful class this package offers is the Series class, which enables reading an entire series’ directory.

>>> from dicom_parser import Series
>>> series = Series('/some/dicom/series/')

Header Information

We can easily query the underlying images’ headers using the get() method:

# Single value
>>> series.get('EchoTime')

# Multiple values
>>> series.get('InstanceNumber')
[1, 2, 3]

# No value
>>> series.get('MissingKey')

# Default value
>>> series.get('MissingKey', 'default_value')

Similarly to the Image class, we can also use the indexing operator:

# Single value
>>> series['RepetitionTime']

# Multiple values
>>> series['SOPInstanceUID']

# No value
>>> series['MissingKey']
KeyError: "The keyword: 'MissingKey' does not exist in the header!"

Image Instances

Another useful feature of the indexing operator is for querying an Image instance based on its index in the series:

>>> series[6]
>>> series[6].header['InstanceNumber]
7   # InstanceNumber is 1-indexed

Pixel Arrays

The data property returns a stacked volume of the images’ pixel arrays:

>>> type(series.data)
>>> series.data.shape
(224, 224, 208)