README.md
1[](https://circleci.com/gh/pydicom/pydicom/tree/master)
2[](https://codecov.io/gh/pydicom/pydicom)
3[](https://img.shields.io/pypi/pyversions/pydicom.svg)
4[](https://badge.fury.io/py/pydicom)
5[](https://doi.org/10.5281/zenodo.5164413)
6[](https://gitter.im/pydicom/Lobby?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge)
7
8# *pydicom*
9
10*pydicom* is a pure Python package for working with [DICOM](https://www.dicomstandard.org/) files. It lets you read, modify and write DICOM data in an easy "pythonic" way.
11
12As a pure Python package, *pydicom* can run anywhere Python runs without any other requirements, although if you're working with *Pixel Data* then we recommend you also install [NumPy](http://www.numpy.org).
13
14If you're looking for a Python library for DICOM networking then you might be interested in another of our projects: [pynetdicom](https://github.com/pydicom/pynetdicom).
15
16## Installation
17
18Using [pip](https://pip.pypa.io/en/stable/):
19```
20pip install pydicom
21```
22Using [conda](https://docs.conda.io/en/latest/):
23```
24conda install -c conda-forge pydicom
25```
26
27For more information, including installation instructions for the development version, see the [installation guide](https://pydicom.github.io/pydicom/stable/tutorials/installation.html).
28
29
30## Documentation
31
32The *pydicom* [user guide](https://pydicom.github.io/pydicom/stable/old/pydicom_user_guide.html), [tutorials](https://pydicom.github.io/pydicom/stable/tutorials/index.html), [examples](https://pydicom.github.io/pydicom/stable/auto_examples/index.html) and [API reference](https://pydicom.github.io/pydicom/stable/reference/index.html) documentation is available for both the [current release](https://pydicom.github.io/pydicom/stable) and the [development version](https://pydicom.github.io/pydicom/dev) on GitHub Pages.
33
34## *Pixel Data*
35
36Compressed and uncompressed *Pixel Data* is always available to
37be read, changed and written as [bytes](https://docs.python.org/3/library/stdtypes.html#bytes-objects):
38```python
39>>> from pydicom import dcmread
40>>> from pydicom.data import get_testdata_file
41>>> path = get_testdata_file("CT_small.dcm")
42>>> ds = dcmread(path)
43>>> type(ds.PixelData)
44<class 'bytes'>
45>>> len(ds.PixelData)
4632768
47>>> ds.PixelData[:2]
48b'\xaf\x00'
49
50```
51
52If [NumPy](http://www.numpy.org) is installed, *Pixel Data* can be converted to an [ndarray](https://numpy.org/doc/stable/reference/generated/numpy.ndarray.html) using the [Dataset.pixel_array](https://pydicom.github.io/pydicom/stable/reference/generated/pydicom.dataset.Dataset.html#pydicom.dataset.Dataset.pixel_array) property:
53
54```python
55>>> arr = ds.pixel_array
56>>> arr.shape
57(128, 128)
58>>> arr
59array([[175, 180, 166, ..., 203, 207, 216],
60 [186, 183, 157, ..., 181, 190, 239],
61 [184, 180, 171, ..., 152, 164, 235],
62 ...,
63 [906, 910, 923, ..., 922, 929, 927],
64 [914, 954, 938, ..., 942, 925, 905],
65 [959, 955, 916, ..., 911, 904, 909]], dtype=int16)
66```
67### Compressed *Pixel Data*
68#### JPEG, JPEG-LS and JPEG 2000
69Converting JPEG compressed *Pixel Data* to an ``ndarray`` requires installing one or more additional Python libraries. For information on which libraries are required, see the [pixel data handler documentation](https://pydicom.github.io/pydicom/stable/old/image_data_handlers.html#guide-compressed).
70
71Compressing data into one of the JPEG formats is not currently supported.
72
73#### RLE
74Encoding and decoding RLE *Pixel Data* only requires NumPy, however it can
75be quite slow. You may want to consider [installing one or more additional
76Python libraries](https://pydicom.github.io/pydicom/stable/old/image_data_compression.html) to speed up the process.
77
78## Examples
79More [examples](https://pydicom.github.io/pydicom/stable/auto_examples/index.html) are available in the documentation.
80
81**Change a patient's ID**
82```python
83from pydicom import dcmread
84
85ds = dcmread("/path/to/file.dcm")
86# Edit the (0010,0020) 'Patient ID' element
87ds.PatientID = "12345678"
88ds.save_as("/path/to/file_updated.dcm")
89```
90
91**Display the Pixel Data**
92
93With [NumPy](http://www.numpy.org) and [matplotlib](https://matplotlib.org/)
94```python
95import matplotlib.pyplot as plt
96from pydicom import dcmread
97from pydicom.data import get_testdata_file
98
99# The path to a pydicom test dataset
100path = get_testdata_file("CT_small.dcm")
101ds = dcmread(path)
102# `arr` is a numpy.ndarray
103arr = ds.pixel_array
104
105plt.imshow(arr, cmap="gray")
106plt.show()
107```
108
109## Contributing
110
111To contribute to *pydicom*, read our [contribution guide](https://github.com/pydicom/pydicom/blob/master/CONTRIBUTING.md).
112
113To contribute an example or extension of *pydicom* that doesn't belong with the core software, see our contribution repository:
114[contrib-pydicom](https://www.github.com/pydicom/contrib-pydicom).
115
){kind=link}
){kind=link}
){kind=link}
){kind=link}
){kind=link}
){kind=link}