Quickstart

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')

Coversion to Python’s native types

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.

Examples

Decimal String (DS) to float using the Header class’s get() method:

>>> raw_value = image.header.raw['ImagingFrequency'].value
>>> raw_value
"123.25993"
>>> type(raw_value)
str

>>> parsed_value = image.header.get('ImagingFrequency')
>>> parsed_value
123.25993
>>> type(parsed_value)
float

Age String (AS) to float:

>>> raw_value = image.header.raw['PatientAge'].value
>>> raw_value
"027Y"
>>> type(raw_value)
str

>>> parsed_value = image.header.get('PatientAge')
>>> parsed_value
27.0
>>> type(parsed_value)
float

Date String (DA) to datetime.date using the Header class’s indexing operator/subscript notation:

>>> raw_value = image.header.raw['PatientBirthDate'].value
>>> raw_value
"19901214"
>>> type(raw_value)
str

>>> parsed_value = image.header['PatientBirthDate']
>>> parsed_value
datetime.date(1990, 12, 14)
>>> type(parsed_value)
datetime.date

Code String (CS) to a verbose value or set of values:

>>> raw_value = image.header.raw['SequenceVariant'].value
>>> raw_value
['SP', 'OSP']
>>> type(raw_value)
pydicom.multival.MultiValue

>>> parsed_value = image.header['SequenceVariant']
>>> parsed_value
{'Oversampling Phase', 'Spoiled'}
>>> type(parsed_value)
set

Et cetera.

Note

The dict-like functionality also includes safe getting:

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

>>> image.header.get('MissingKey', 'DefaultValue')
'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!"

Read DICOM series directory as a Series

Another useful class this package offers is the Series class:

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

The Series instance allows us to easily query the underlying images’ headers using its get() method:

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

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

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

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

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

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

# Multiple values
>>> series['SOPInstanceUID']
["1.123.1241.123124124.12.1",
 "1.123.1241.123124124.12.2",
 "1.123.1241.123124124.12.3"]

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

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

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

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

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

Siemens 4D data

Reading Siemens 4D data encoded as mosaics is also supported:

>>> fmri_series = Series('/path/to/dicom/fmri/')
>>> fmri_series.data.shape
(96, 96, 64, 200)