0
# PyDicom
1

2
A pure Python package for reading and writing DICOM (Digital Imaging and Communications in Medicine) files. PyDicom provides comprehensive functionality for working with medical imaging data, offering both high-level convenience functions for common tasks and low-level access for advanced DICOM manipulation.
3

4
## Package Information
5

6
- **Package Name**: pydicom
7
- **Language**: Python
8
- **Installation**: `pip install pydicom`
9

10
## Core Imports
11

12
```python
13
import pydicom
14
```
15

16
Most commonly used imports:
17

18
```python
19
from pydicom import dcmread, dcmwrite
20
from pydicom.dataset import Dataset, FileDataset, FileMetaDataset
21
from pydicom.dataelem import DataElement
22
from pydicom.sequence import Sequence
23
```
24

25
For pixel data operations:
26

27
```python
28
from pydicom import pixel_array, iter_pixels
29
# Or more specific:
30
from pydicom.pixels.utils import pixel_array, iter_pixels
31
from pydicom.pixels import compress, decompress
32
```
33

34
For configuration and utilities:
35

36
```python
37
from pydicom import config
38
from pydicom.config import debug, DS_numpy, DS_decimal
39
from pydicom.datadict import dictionary_description, keyword_for_tag, tag_for_keyword
40
```
41

42
For advanced usage:
43

44
```python
45
from pydicom.tag import Tag
46
from pydicom.uid import UID, generate_uid
47
from pydicom.valuerep import PersonName, DA, TM, DT
48
from pydicom.data import get_testdata_file
49
```
50

51
## Basic Usage
52

53
```python
54
from pydicom import dcmread, dcmwrite
55
from pydicom.dataset import Dataset
56

57
# Read a DICOM file
58
dataset = dcmread("path/to/file.dcm")
59

60
# Access DICOM elements
61
patient_name = dataset.PatientName
62
study_date = dataset.StudyDate
63

64
# Modify elements
65
dataset.PatientName = "Anonymous"
66
dataset.PatientID = "12345"
67

68
# Add new elements
69
dataset.add_new(0x0010, 0x1030, "DS", "75.5")  # Patient Weight
70

71
# Save to new file
72
dcmwrite("output.dcm", dataset)
73

74
# Work with pixel data (requires NumPy)
75
if hasattr(dataset, 'pixel_array'):
76
    pixels = dataset.pixel_array
77
    print(f"Image shape: {pixels.shape}")
78
    print(f"Data type: {pixels.dtype}")
79
```
80

81
## Architecture
82

83
PyDicom follows the DICOM standard structure and provides a comprehensive object model:
84

85
- **Dataset**: The central container representing a DICOM dataset with dict-like access to data elements
86
- **DataElement**: Individual DICOM data elements containing tag, VR (Value Representation), and value
87
- **Sequence**: Containers for nested datasets within DICOM sequences
88
- **Tag**: DICOM tag identification using (group, element) tuples
89
- **UID**: Specialized string class for DICOM Unique Identifiers
90
- **Pixel Processing**: Comprehensive pixel data handling with support for various compression formats
91

92
The library supports the complete DICOM standard including advanced features like structured reporting, overlays, waveforms, and extensive pixel data processing capabilities.
93

94
## Capabilities
95

96
### File Operations
97

98
Core functionality for reading and writing DICOM files with support for various transfer syntaxes, partial reading, and metadata extraction.
99

100
```python { .api }
101
def dcmread(fp, force=False, specific_tags=None, stop_before_pixels=False): ...
102
def dcmwrite(filename, dataset, write_like_original=True): ...
103
```
104

105
[File Operations](./file-operations.md)
106

107
### Dataset Manipulation
108

109
Comprehensive dataset management including element access, modification, validation, and serialization with full support for the DICOM data model.
110

111
```python { .api }
112
class Dataset:
113
    def __getitem__(self, key): ...
114
    def __setitem__(self, key, value): ...
115
    def add(self, data_element): ...
116
    def add_new(self, tag, VR, value): ...
117
    def save_as(self, filename): ...
118
```
119

120
[Dataset Manipulation](./dataset-manipulation.md)
121

122
### Data Elements
123

124
Individual DICOM data element handling with support for all Value Representations (VRs) and proper type conversion.
125

126
```python { .api }
127
class DataElement:
128
    def __init__(self, tag, VR, value): ...
129
    @property
130
    def keyword(self): ...
131
    @property
132
    def description(self): ...
133
```
134

135
[Data Elements](./data-elements.md)
136

137
### Pixel Data Processing
138

139
Advanced pixel data manipulation including array extraction, compression, decompression, color space conversion, and various image processing operations.
140

141
```python { .api }
142
def pixel_array(dataset): ...
143
def iter_pixels(dataset): ...
144
def compress(dataset, transfer_syntax_uid): ...
145
def apply_windowing(arr, dataset): ...
146
```
147

148
[Pixel Data Processing](./pixel-data-processing.md)
149

150
### Tags and UIDs
151

152
DICOM tag and UID management with dictionary lookups, keyword conversion, and UID generation capabilities.
153

154
```python { .api }
155
class Tag:
156
    def __init__(self, *args): ...
157
class UID(str):
158
    def is_transfer_syntax(self): ...
159
def generate_uid(): ...
160
```
161

162
[Tags and UIDs](./tags-and-uids.md)
163

164
### Value Representations
165

166
Specialized handling for DICOM Value Representations including dates, times, person names, and numeric types with proper validation and conversion.
167

168
```python { .api }
169
class PersonName:
170
    @property
171
    def family_name(self): ...
172
    @property
173
    def given_name(self): ...
174
class DA:  # Date
175
    def __init__(self, val): ...
176
class TM:  # Time
177
    def __init__(self, val): ...
178
```
179

180
[Value Representations](./value-representations.md)
181

182
### Sequences and Collections
183

184
Management of DICOM sequences and multi-value elements with proper nesting and validation support.
185

186
```python { .api }
187
class Sequence(list):
188
    def __init__(self, iterable=None): ...
189
class MultiValue:
190
    def __init__(self, type_constructor, iterable): ...
191
```
192

193
[Sequences and Collections](./sequences-collections.md)
194

195
### Configuration and Utilities
196

197
Package configuration, debugging tools, data dictionary access, and various utility functions for DICOM file analysis and manipulation.
198

199
```python { .api }
200
def debug(debug_on=True): ...
201
def dictionary_description(tag): ...
202
def keyword_for_tag(tag): ...
203
def tag_for_keyword(keyword): ...
204
```
205

206
[Configuration and Utilities](./configuration-utilities.md)
207

208
## Types
209

210
```python { .api }
211
from typing import Union, Optional, List, Dict, Any, BinaryIO, Tuple
212
from pathlib import Path
213

214
# Core types
215
TagType = Union[int, Tuple[int, int], str]
216
VRType = str
217
ValueType = Any
218
FilePathType = Union[str, Path, BinaryIO]
219

220
# Pixel data types
221
ArrayType = Any  # NumPy ndarray when available
222
CompressionType = str
223
TransferSyntaxType = str
224
```