.. _getting_started:
============================
Getting Started with pydicom
============================
.. rubric:: 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")
..
>>> os.remove("rtplan2.dcm")
Pydicom is not a DICOM server [#]_, 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 :doc:`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 :doc:`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 :doc:`pydicom_user_guide`.
.. rubric:: Footnotes::
.. [#] For DICOM network capabilities, see the
`pynetdicom `_ and the newer
`pynetdicom3 `_ projects.
.. [#] 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).