Skip to main content

DICOM files parser meant to facilitate data access.

Project description

PyPI version PyPI status CircleCI Documentation Status


dicom_parser is a utility python package meant to facilitate access to DICOM header information by extending the functionality of pydicom.

Essentially, dicom_parser uses DICOM's data-element value-representation (VR), as well as prior knowledge on vendor-specific private tags or encoding schemes, in order to transform them to more "pythonic" data structures when possible.

For more information, please see the documentation.


To install the latest version of dicom_parser, simply run:

    pip install dicom_parser


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.


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

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

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

Age String (AS) to float:

    >>> raw_value = image.header.raw['PatientAge'].value
    >>> raw_value
    >>> type(raw_value)

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

Date String (DA) to using the Header class's indexing operator/subscript notation:

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

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

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)

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

Et cetera.

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!"

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

    # 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!"

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

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

    >>> type(
    (224, 224, 208)

Siemens 4D data

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

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

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Files for dicom-parser, version 0.1.6
Filename, size File type Python version Upload date Hashes
Filename, size dicom_parser-0.1.6-py3-none-any.whl (10.3 MB) File type Wheel Python version py3 Upload date Hashes View
Filename, size dicom_parser-0.1.6.tar.gz (20.7 MB) File type Source Python version None Upload date Hashes View

Supported by

AWS AWS Cloud computing Datadog Datadog Monitoring DigiCert DigiCert EV certificate Facebook / Instagram Facebook / Instagram PSF Sponsor Fastly Fastly CDN Google Google Object Storage and Download Analytics Pingdom Pingdom Monitoring Salesforce Salesforce PSF Sponsor Sentry Sentry Error logging StatusPage StatusPage Status page