Getting Started with pydicom

Brief overview of pydicom and how to install.

Introduction

Pydicom is a pure Python package for working with DICOM files such as medical images, reports, and radiotherapy objects.

Pydicom makes it easy to read these complex files into natural pythonic structures for easy manipulation. Modified datasets can be written again to DICOM format files.

Here is a simple example of using pydicom in an interactive session, to read a radiotherapy plan file, change the patient setup from head-first-supine to head-first-prone, and save to a new file:

>>> import os
>>> import pydicom
>>> from pydicom.data import get_testdata_files
>>> filename = get_testdata_files("rtplan.dcm")[0]
>>> ds = pydicom.dcmread(filename)  # plan dataset
>>> ds.PatientName
'Last^First^mid^pre'
>>> ds.dir("setup")    # get a list of tags with "setup" somewhere in the name
['PatientSetupSequence']
>>> ds.PatientSetupSequence[0]
(0018, 5100) Patient Position                    CS: 'HFS'
(300a, 0182) Patient Setup Number                IS: '1'
(300a, 01b2) Setup Technique Description         ST: ''
>>> ds.PatientSetupSequence[0].PatientPosition = "HFP"
>>> ds.save_as("rtplan2.dcm")

Pydicom is not a DICOM server [1], and is not primarily about viewing images. It is designed to let you manipulate data elements in DICOM files with Python code.

Pydicom is easy to install and use, and because it is a pure Python package, it should run wherever Python runs.

One limitation of pydicom: compressed pixel data (e.g. JPEG) can only be altered in an intelligent way if decompressing them first. Once decompressed, they can be altered and written back to a DICOM file the same way as initially uncompressed data.

License

Pydicom has an MIT-based license.

Installing

As a pure Python package, pydicom is easy to install and has no requirements other than Python itself (the NumPy library is recommended, but is only required if manipulating pixel data).

Prerequisites

  • Python 2.7, 3.4 or later
  • Optional dependencies:
    • numpy
    • pillow
    • gdcm
    • jpeg_ls
    • jpeg2000
    • pytest (if running pydicom’s test suite)

Installing pydicom

Pydicom is currently available on PyPi . The simplest way to install pydicom alone is using pip at a command line:

pip install -U pydicom

which installs the latest release. To install the latest code from the repository (usually stable, but may have undocumented changes or bugs):

pip install -U git+https://github.com/pydicom/pydicom.git

Pydicom is also available on conda-forge:

conda install pydicom --channel conda-forge

To install pydicom along with image handlers for compressed pixel data, we encourage you to use Miniconda or Anaconda. For example:

conda create --name pydicomenv python=3.6 pip numpy
conda install pydicom --channel conda-forge

will install pip, pydicom, and numpy in an environment called pydicomenv. To add gdcm after activating the environment:

conda install -c conda-forge gdcm

The environment is optional; see the conda software for details of its setup and use of environments.

For developers, you can clone the pydicom repository and run the setup.py file. Use the following commands to get a copy from GitHub and install all dependencies:

git clone https://github.com/pydicom/pydicom.git
cd pydicom
pip install .

or, for the last line, instead use:

pip install -e .

to install in ‘develop’ or ‘editable’ mode, where changes can be made to the local working code and Python will use the updated pydicom code.

Test and coverage

To test the installed code on any platform, change to the directory of pydicom’s setup.py file and:

python setup.py test

This will install pytest if it is not already installed.

Or, in linux you can also use:

make test-code

To test the coverage of your versions in linux:

make test-coverage

Using pydicom

Once installed, the package can be imported at a Python command line or used in your own Python program with import pydicom. See the examples directory for both kinds of uses. Also see the User Guide for more details of how to use the package.

Support

Please join the pydicom discussion group to ask questions or give feedback. Bugs can be submitted through the issue tracker. Besides the example directory, cookbook recipes are encouraged to be posted on the wiki page.

New versions, major bug fixes, etc. will also be announced through the group.

Next Steps

To start learning how to use pydicom, see the Pydicom User Guide.

Footnotes::

[1]For DICOM network capabilities, see the pynetdicom and the newer pynetdicom3 projects.
[2]If using python(x,y), other packages you might be interested in include IPython (an indispensable interactive shell with auto-completion, history etc), NumPy (optionally used by pydicom for pixel data), and ITK/VTK or PIL (image processing and visualization).