Quickstart¶
The most basic usage case is reading a single DICOM image (.dcm file) as
an Image
instance.
from dicom_parser import Image
# Create a DICOM Image object
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)