Introduction to pydicom

Brief overview of pydicom.

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.

Below is a simple example of using pydicom in an interactive session. In it we use the get_testdata_file() helper function to get the path to one of the pydicom test datasets, which in this case is a radiotherapy plan file. We read the dataset from the path using dcmread(), which returns a FileDataset instance ds. This is then used to print the Patient Name and change the Patient Position from head-first-supine (HFS) to head-first-prone (HFP). Finally, the changes are saved to a new file rtplan2.dcm:

>>> import pydicom
>>> from pydicom.data import get_testdata_file
>>> # Fetch the path to the example dataset
>>> path = get_testdata_file("rtplan.dcm")
>>> path
'/path/to/pydicom/data/test_files/rtplan.dcm'
>>> ds = pydicom.dcmread(path)
>>> 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")

A more thorough introduction to pydicom can be found in the dataset basics tutorial.

pydicom is not a DICOM server (see pynetdicom instead), 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 is that compressed pixel data (e.g. JPEG) can only be altered in an intelligent way if decompressing it first. Once decompressed, it 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

See the installation guide.

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.

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.