Skip to main content

DICOM files parser meant to facilitate data access.

Project description


Documentation Documentation Status
Code made-with-python Code style: black Imports: isort
Testing GitHub Actions
Codacy BadgeLanguage grade: Python
Packaging PyPI version PyPI status PyPI Format
Supported Versions Supported Implementations
Usage License Badge DOI PyPI download month

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 site.


To install the latest stable release of dicom_parser, simply run:

    pip install dicom_parser

Or, to install the latest development version:

    pip install


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)



The documentation site is built using Sphinx, to build the HTML pages locally, make sure you have the required dependencies by using the docs modifier for the installation. Assuming you have cloned the repository and created a virtual environment, run:

pip install -e .[docs]

from within your cloned project's root.


Build the site by running:

make html

from within the <root>/docs/ directory.

The generated HTML will be found under <root>/docs/_build/html. Open index.html in your browser to view the site.



Tests are executed using pytest and tox, and coverage is measured using the coverage package. Make sure you have the required dependencies by using the test modifier for the installation. Assuming you have cloned the repository and created a virtual environment, run:

pip install -e .[test]

from within your cloned project's root.



To run the tests within your virtual environment, run:

pytest tests


To run the tests in a number of dedicated virtual environments, simply execute the tox command from within the project's root directory. This will test all supported Python versions, and therefore will only be successful in an environment in which all supported Python versions are installed.

Use tox -p to run the tests in parallel, and tox -e py3?,py3? to run a subset of environments (replace ? with the desired version number).


To check code coverage using coverage, simply run:

coverage run && coverage html

Open <root>/htmlcov/index.html in the browser to view the report.

Project details

Download files

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

Source Distribution

dicom_parser-1.2.3.tar.gz (114.0 kB view hashes)

Uploaded source

Built Distribution

dicom_parser-1.2.3-py3-none-any.whl (103.1 kB view hashes)

Uploaded py3

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page