Getting Started with pydicom¶
Brief overview of pydicom and how to install.
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") >>> 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 (0018, 5100) Patient Position CS: 'HFS' (300a, 0182) Patient Setup Number IS: '1' (300a, 01b2) Setup Technique Description ST: '' >>> ds.PatientSetupSequence.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.
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).
Python 2.7, 3.4 or later
- Optional dependencies:
pytest (if running pydicom’s test suite). pytest<5 if in Python 2.
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
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
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.
In v1.3 run under Python 2, if pytest is not found, please python2 -m pip install “pytest<5”
Or, in linux you can also use:
To test the coverage of your versions in linux:
Once installed, the package can be imported at a Python command line or used
in your own Python program with
See the examples directory
for both kinds of uses. Also see the User Guide
for more details of how to use the package.
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.
To start learning how to use pydicom, see the Pydicom User Guide.
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).