Quickstart — dicom_parser 0.0.1 documentation

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