Pydicom

Overview

概述

Pydicom is a pure Python package for working with DICOM files, the standard format for medical imaging data. This skill provides guidance on reading, writing, and manipulating DICOM files, including working with pixel data, metadata, and various compression formats.

Pydicom是一个纯Python包，用于处理医学影像数据的标准格式——DICOM文件。本技能提供了读取、写入和操作DICOM文件的指导，包括处理像素数据、元数据以及各种压缩格式。

When to Use This Skill

何时使用本技能

Use this skill when working with:

Medical imaging files (CT, MRI, X-ray, ultrasound, PET, etc.)
DICOM datasets requiring metadata extraction or modification
Pixel data extraction and image processing from medical scans
DICOM anonymization for research or data sharing
Converting DICOM files to standard image formats
Compressed DICOM data requiring decompression
DICOM sequences and structured reports
Multi-slice volume reconstruction
PACS (Picture Archiving and Communication System) integration

当您处理以下内容时可以使用本技能：

医学影像文件（CT、MRI、X光、超声、PET等）
需要提取或修改元数据的DICOM数据集
从医学扫描中提取像素数据并进行图像处理
用于研究或数据共享的DICOM文件匿名化
将DICOM文件转换为标准图像格式
需要解压缩的压缩DICOM数据
DICOM序列和结构化报告
多层体素重建
PACS（图像存档与通信系统）集成

Installation

安装

Install pydicom and common dependencies:

bash

uv pip install pydicom
uv pip install pillow  # For image format conversion
uv pip install numpy   # For pixel array manipulation
uv pip install matplotlib  # For visualization

For handling compressed DICOM files, additional packages may be needed:

bash

uv pip install pylibjpeg pylibjpeg-libjpeg pylibjpeg-openjpeg  # JPEG compression
uv pip install python-gdcm  # Alternative compression handler

安装pydicom及常见依赖：

bash

uv pip install pydicom
uv pip install pillow  # For image format conversion
uv pip install numpy   # For pixel array manipulation
uv pip install matplotlib  # For visualization

若要处理压缩DICOM文件，可能需要额外安装以下包：

bash

uv pip install pylibjpeg pylibjpeg-libjpeg pylibjpeg-openjpeg  # JPEG compression
uv pip install python-gdcm  # Alternative compression handler

Core Workflows

核心工作流

Reading DICOM Files

读取DICOM文件

Read a DICOM file using

pydicom.dcmread()

:

python

import pydicom

使用

pydicom.dcmread()

读取DICOM文件：

python

import pydicom

Read a DICOM file

ds = pydicom.dcmread('path/to/file.dcm')

Access metadata

print(f"Patient Name: {ds.PatientName}") print(f"Study Date: {ds.StudyDate}") print(f"Modality: {ds.Modality}")

Display all elements

print(ds)


**Key points:**
- `dcmread()` returns a `Dataset` object
- Access data elements using attribute notation (e.g., `ds.PatientName`) or tag notation (e.g., `ds[0x0010, 0x0010]`)
- Use `ds.file_meta` to access file metadata like Transfer Syntax UID
- Handle missing attributes with `getattr(ds, 'AttributeName', default_value)` or `hasattr(ds, 'AttributeName')`

print(ds)


**关键点：**
- `dcmread()`返回一个`Dataset`对象
- 使用属性表示法（如`ds.PatientName`）或标签表示法（如`ds[0x0010, 0x0010]`）访问数据元素
- 使用`ds.file_meta`访问文件元数据，如传输语法UID
- 使用`getattr(ds, 'AttributeName', default_value)`或`hasattr(ds, 'AttributeName')`处理缺失的属性

Working with Pixel Data

处理像素数据

Extract and manipulate image data from DICOM files:

python

import pydicom
import numpy as np
import matplotlib.pyplot as plt

从DICOM文件中提取并操作图像数据：

python

import pydicom
import numpy as np
import matplotlib.pyplot as plt

Read DICOM file

ds = pydicom.dcmread('image.dcm')

Get pixel array (requires numpy)

pixel_array = ds.pixel_array

Image information

print(f"Shape: {pixel_array.shape}") print(f"Data type: {pixel_array.dtype}") print(f"Rows: {ds.Rows}, Columns: {ds.Columns}")

Apply windowing for display (CT/MRI)

if hasattr(ds, 'WindowCenter') and hasattr(ds, 'WindowWidth'): from pydicom.pixel_data_handlers.util import apply_voi_lut windowed_image = apply_voi_lut(pixel_array, ds) else: windowed_image = pixel_array

Display image

plt.imshow(windowed_image, cmap='gray') plt.title(f"{ds.Modality} - {ds.StudyDescription}") plt.axis('off') plt.show()


**Working with color images:**

```python

plt.imshow(windowed_image, cmap='gray') plt.title(f"{ds.Modality} - {ds.StudyDescription}") plt.axis('off') plt.show()


**处理彩色图像：**

```python

RGB images have shape (rows, columns, 3)

if ds.PhotometricInterpretation == 'RGB': rgb_image = ds.pixel_array plt.imshow(rgb_image) elif ds.PhotometricInterpretation == 'YBR_FULL': from pydicom.pixel_data_handlers.util import convert_color_space rgb_image = convert_color_space(ds.pixel_array, 'YBR_FULL', 'RGB') plt.imshow(rgb_image)


**Multi-frame images (videos/series):**

```python

if ds.PhotometricInterpretation == 'RGB': rgb_image = ds.pixel_array plt.imshow(rgb_image) elif ds.PhotometricInterpretation == 'YBR_FULL': from pydicom.pixel_data_handlers.util import convert_color_space rgb_image = convert_color_space(ds.pixel_array, 'YBR_FULL', 'RGB') plt.imshow(rgb_image)


**多帧图像（视频/序列）：**

```python

For multi-frame DICOM files

if hasattr(ds, 'NumberOfFrames') and ds.NumberOfFrames > 1: frames = ds.pixel_array # Shape: (num_frames, rows, columns) print(f"Number of frames: {frames.shape[0]}")

# Display specific frame
plt.imshow(frames[0], cmap='gray')

undefined

if hasattr(ds, 'NumberOfFrames') and ds.NumberOfFrames > 1: frames = ds.pixel_array # Shape: (num_frames, rows, columns) print(f"Number of frames: {frames.shape[0]}")

# Display specific frame
plt.imshow(frames[0], cmap='gray')

undefined

Converting DICOM to Image Formats

将DICOM转换为图像格式

Use the provided

dicom_to_image.py

script or convert manually:

python

from PIL import Image
import pydicom
import numpy as np

ds = pydicom.dcmread('input.dcm')
pixel_array = ds.pixel_array

使用提供的

dicom_to_image.py

脚本或手动转换：

python

from PIL import Image
import pydicom
import numpy as np

ds = pydicom.dcmread('input.dcm')
pixel_array = ds.pixel_array

Normalize to 0-255 range

if pixel_array.dtype != np.uint8: pixel_array = ((pixel_array - pixel_array.min()) / (pixel_array.max() - pixel_array.min()) * 255).astype(np.uint8)

Save as PNG

image = Image.fromarray(pixel_array) image.save('output.png')


Use the script: `python scripts/dicom_to_image.py input.dcm output.png`

image = Image.fromarray(pixel_array) image.save('output.png')


使用脚本：`python scripts/dicom_to_image.py input.dcm output.png`

Modifying Metadata

修改元数据

Modify DICOM data elements:

python

import pydicom
from datetime import datetime

ds = pydicom.dcmread('input.dcm')

修改DICOM数据元素：

python

import pydicom
from datetime import datetime

ds = pydicom.dcmread('input.dcm')

Modify existing elements

ds.PatientName = "Doe^John" ds.StudyDate = datetime.now().strftime('%Y%m%d') ds.StudyDescription = "Modified Study"

Add new elements

ds.SeriesNumber = 1 ds.SeriesDescription = "New Series"

Remove elements

if hasattr(ds, 'PatientComments'): delattr(ds, 'PatientComments')

Or using del

if 'PatientComments' in ds: del ds.PatientComments

Save modified file

ds.save_as('modified.dcm')

undefined

ds.save_as('modified.dcm')

undefined

Anonymizing DICOM Files

匿名化DICOM文件

Remove or replace patient identifiable information:

python

import pydicom
from datetime import datetime

ds = pydicom.dcmread('input.dcm')

移除或替换患者可识别信息：

python

import pydicom
from datetime import datetime

ds = pydicom.dcmread('input.dcm')

Tags commonly containing PHI (Protected Health Information)

tags_to_anonymize = [ 'PatientName', 'PatientID', 'PatientBirthDate', 'PatientSex', 'PatientAge', 'PatientAddress', 'InstitutionName', 'InstitutionAddress', 'ReferringPhysicianName', 'PerformingPhysicianName', 'OperatorsName', 'StudyDescription', 'SeriesDescription', ]

Remove or replace sensitive data

for tag in tags_to_anonymize: if hasattr(ds, tag): if tag in ['PatientName', 'PatientID']: setattr(ds, tag, 'ANONYMOUS') elif tag == 'PatientBirthDate': setattr(ds, tag, '19000101') else: delattr(ds, tag)

Update dates to maintain temporal relationships

if hasattr(ds, 'StudyDate'): # Shift dates by a random offset ds.StudyDate = '20000101'

Keep pixel data intact

ds.save_as('anonymized.dcm')


Use the provided script: `python scripts/anonymize_dicom.py input.dcm output.dcm`

ds.save_as('anonymized.dcm')


使用提供的脚本：`python scripts/anonymize_dicom.py input.dcm output.dcm`

Writing DICOM Files

写入DICOM文件

Create DICOM files from scratch:

python

import pydicom
from pydicom.dataset import Dataset, FileDataset
from datetime import datetime
import numpy as np

从头创建DICOM文件：

python

import pydicom
from pydicom.dataset import Dataset, FileDataset
from datetime import datetime
import numpy as np

Create file meta information

file_meta = Dataset() file_meta.MediaStorageSOPClassUID = pydicom.uid.generate_uid() file_meta.MediaStorageSOPInstanceUID = pydicom.uid.generate_uid() file_meta.TransferSyntaxUID = pydicom.uid.ExplicitVRLittleEndian

Create the FileDataset instance

ds = FileDataset('new_dicom.dcm', {}, file_meta=file_meta, preamble=b"\0" * 128)

Add required DICOM elements

ds.PatientName = "Test^Patient" ds.PatientID = "123456" ds.Modality = "CT" ds.StudyDate = datetime.now().strftime('%Y%m%d') ds.StudyTime = datetime.now().strftime('%H%M%S') ds.ContentDate = ds.StudyDate ds.ContentTime = ds.StudyTime

Add image-specific elements

ds.SamplesPerPixel = 1 ds.PhotometricInterpretation = "MONOCHROME2" ds.Rows = 512 ds.Columns = 512 ds.BitsAllocated = 16 ds.BitsStored = 16 ds.HighBit = 15 ds.PixelRepresentation = 0

Create pixel data

pixel_array = np.random.randint(0, 4096, (512, 512), dtype=np.uint16) ds.PixelData = pixel_array.tobytes()

Add required UIDs

ds.SOPClassUID = pydicom.uid.CTImageStorage ds.SOPInstanceUID = file_meta.MediaStorageSOPInstanceUID ds.SeriesInstanceUID = pydicom.uid.generate_uid() ds.StudyInstanceUID = pydicom.uid.generate_uid()

Save the file

ds.save_as('new_dicom.dcm')

undefined

ds.save_as('new_dicom.dcm')

undefined

Compression and Decompression

压缩与解压缩

Handle compressed DICOM files:

python

import pydicom

处理压缩DICOM文件：

python

import pydicom

Read compressed DICOM file

ds = pydicom.dcmread('compressed.dcm')

Check transfer syntax

print(f"Transfer Syntax: {ds.file_meta.TransferSyntaxUID}") print(f"Transfer Syntax Name: {ds.file_meta.TransferSyntaxUID.name}")

Decompress and save as uncompressed

ds.decompress() ds.save_as('uncompressed.dcm', write_like_original=False)

Or compress when saving (requires appropriate encoder)

ds_uncompressed = pydicom.dcmread('uncompressed.dcm') ds_uncompressed.compress(pydicom.uid.JPEGBaseline8Bit) ds_uncompressed.save_as('compressed_jpeg.dcm')


**Common transfer syntaxes:**
- `ExplicitVRLittleEndian` - Uncompressed, most common
- `JPEGBaseline8Bit` - JPEG lossy compression
- `JPEGLossless` - JPEG lossless compression
- `JPEG2000Lossless` - JPEG 2000 lossless
- `RLELossless` - Run-Length Encoding lossless

See `references/transfer_syntaxes.md` for complete list.

ds_uncompressed = pydicom.dcmread('uncompressed.dcm') ds_uncompressed.compress(pydicom.uid.JPEGBaseline8Bit) ds_uncompressed.save_as('compressed_jpeg.dcm')


**常见传输语法：**
- `ExplicitVRLittleEndian` - 无压缩，最常用
- `JPEGBaseline8Bit` - JPEG有损压缩
- `JPEGLossless` - JPEG无损压缩
- `JPEG2000Lossless` - JPEG 2000无损
- `RLELossless` - 行程编码无损

完整列表请查看`references/transfer_syntaxes.md`。

Working with DICOM Sequences

处理DICOM序列

Handle nested data structures:

python

import pydicom

ds = pydicom.dcmread('file.dcm')

处理嵌套数据结构：

python

import pydicom

ds = pydicom.dcmread('file.dcm')

Access sequences

if 'ReferencedStudySequence' in ds: for item in ds.ReferencedStudySequence: print(f"Referenced SOP Instance UID: {item.ReferencedSOPInstanceUID}")

Create a sequence

from pydicom.sequence import Sequence

sequence_item = Dataset() sequence_item.ReferencedSOPClassUID = pydicom.uid.CTImageStorage sequence_item.ReferencedSOPInstanceUID = pydicom.uid.generate_uid()

ds.ReferencedImageSequence = Sequence([sequence_item])

undefined

from pydicom.sequence import Sequence

sequence_item = Dataset() sequence_item.ReferencedSOPClassUID = pydicom.uid.CTImageStorage sequence_item.ReferencedSOPInstanceUID = pydicom.uid.generate_uid()

ds.ReferencedImageSequence = Sequence([sequence_item])

undefined

Processing DICOM Series

处理DICOM序列

Work with multiple related DICOM files:

python

import pydicom
import numpy as np
from pathlib import Path

处理多个相关DICOM文件：

python

import pydicom
import numpy as np
from pathlib import Path

Read all DICOM files in a directory

dicom_dir = Path('dicom_series/') slices = []

for file_path in dicom_dir.glob('*.dcm'): ds = pydicom.dcmread(file_path) slices.append(ds)

dicom_dir = Path('dicom_series/') slices = []

for file_path in dicom_dir.glob('*.dcm'): ds = pydicom.dcmread(file_path) slices.append(ds)

Sort by slice location or instance number

slices.sort(key=lambda x: float(x.ImagePositionPatient[2]))

Or: slices.sort(key=lambda x: int(x.InstanceNumber))

Create 3D volume

volume = np.stack([s.pixel_array for s in slices]) print(f"Volume shape: {volume.shape}") # (num_slices, rows, columns)

Get spacing information for proper scaling

pixel_spacing = slices[0].PixelSpacing # [row_spacing, col_spacing] slice_thickness = slices[0].SliceThickness print(f"Voxel size: {pixel_spacing[0]}x{pixel_spacing[1]}x{slice_thickness} mm")

undefined

pixel_spacing = slices[0].PixelSpacing # [row_spacing, col_spacing] slice_thickness = slices[0].SliceThickness print(f"Voxel size: {pixel_spacing[0]}x{pixel_spacing[1]}x{slice_thickness} mm")

undefined

Helper Scripts

辅助脚本

This skill includes utility scripts in the

scripts/

directory:

本技能在

scripts/

目录中包含以下实用脚本：

anonymize_dicom.py

Anonymize DICOM files by removing or replacing Protected Health Information (PHI).

bash

python scripts/anonymize_dicom.py input.dcm output.dcm

通过移除或替换受保护健康信息（PHI）来匿名化DICOM文件。

bash

python scripts/anonymize_dicom.py input.dcm output.dcm

dicom_to_image.py

Convert DICOM files to common image formats (PNG, JPEG, TIFF).

bash

python scripts/dicom_to_image.py input.dcm output.png
python scripts/dicom_to_image.py input.dcm output.jpg --format JPEG

将DICOM文件转换为常见图像格式（PNG、JPEG、TIFF）。

bash

python scripts/dicom_to_image.py input.dcm output.png
python scripts/dicom_to_image.py input.dcm output.jpg --format JPEG

extract_metadata.py

Extract and display DICOM metadata in a readable format.

bash

python scripts/extract_metadata.py file.dcm
python scripts/extract_metadata.py file.dcm --output metadata.txt

提取并以可读格式显示DICOM元数据。

bash

python scripts/extract_metadata.py file.dcm
python scripts/extract_metadata.py file.dcm --output metadata.txt

Reference Materials

参考资料

Detailed reference information is available in the

references/

directory:

common_tags.md: Comprehensive list of commonly used DICOM tags organized by category (Patient, Study, Series, Image, etc.)
transfer_syntaxes.md: Complete reference of DICOM transfer syntaxes and compression formats

详细的参考信息位于

references/

目录中：

common_tags.md：按类别（患者、检查、序列、图像等）组织的常用DICOM标签综合列表
transfer_syntaxes.md：DICOM传输语法和压缩格式的完整参考

Common Issues and Solutions

常见问题与解决方案

Issue: "Unable to decode pixel data"

Solution: Install additional compression handlers:

uv pip install pylibjpeg pylibjpeg-libjpeg python-gdcm

Issue: "AttributeError" when accessing tags

Solution: Check if attribute exists with

hasattr(ds, 'AttributeName')

or use

ds.get('AttributeName', default)

Issue: Incorrect image display (too dark/bright)

Solution: Apply VOI LUT windowing:
```
apply_voi_lut(pixel_array, ds)
```
or manually adjust with
```
WindowCenter
```
and
```
WindowWidth
```

Issue: Memory issues with large series

Solution: Process files iteratively, use memory-mapped arrays, or downsample images

问题："无法解码像素数据"

解决方案：安装额外的压缩处理库：

uv pip install pylibjpeg pylibjpeg-libjpeg python-gdcm

问题：访问标签时出现"AttributeError"

解决方案：使用

hasattr(ds, 'AttributeName')

检查属性是否存在，或使用

ds.get('AttributeName', default)

问题：图像显示不正确（过暗/过亮）

解决方案：应用VOI LUT窗宽窗位：
```
apply_voi_lut(pixel_array, ds)
```
，或使用
```
WindowCenter
```
和
```
WindowWidth
```
手动调整

问题：处理大型序列时出现内存问题

解决方案：迭代处理文件，使用内存映射数组，或对图像进行下采样

Best Practices

最佳实践

Always check for required attributes before accessing them using
```
hasattr()
```
or
```
get()
```
Preserve file metadata when modifying files by using
```
save_as()
```
with
```
write_like_original=True
```
Use Transfer Syntax UIDs to understand compression format before processing pixel data
Handle exceptions when reading files from untrusted sources
Apply proper windowing (VOI LUT) for medical image visualization
Maintain spatial information (pixel spacing, slice thickness) when processing 3D volumes
Verify anonymization thoroughly before sharing medical data
Use UIDs correctly - generate new UIDs when creating new instances, preserve them when modifying

访问前始终检查必填属性，使用
```
hasattr()
```
或
```
get()
```
修改文件时保留文件元数据，使用
```
save_as()
```
并设置
```
write_like_original=True
```
处理像素数据前使用传输语法UID了解压缩格式
处理来自不可信源的文件时捕获异常
医学影像可视化时应用正确的窗宽窗位（VOI LUT）
处理3D体素时保留空间信息（像素间距、层厚）
共享医疗数据前彻底验证匿名化效果
正确使用UID - 创建新实例时生成新UID，修改时保留原有UID

Documentation

文档

Official pydicom documentation: https://pydicom.github.io/pydicom/dev/

User Guide: https://pydicom.github.io/pydicom/dev/guides/user/index.html
Tutorials: https://pydicom.github.io/pydicom/dev/tutorials/index.html
API Reference: https://pydicom.github.io/pydicom/dev/reference/index.html
Examples: https://pydicom.github.io/pydicom/dev/auto_examples/index.html

Pydicom官方文档：https://pydicom.github.io/pydicom/dev/

用户指南：https://pydicom.github.io/pydicom/dev/guides/user/index.html
教程：https://pydicom.github.io/pydicom/dev/tutorials/index.html
API参考：https://pydicom.github.io/pydicom/dev/reference/index.html
示例：https://pydicom.github.io/pydicom/dev/auto_examples/index.html

pydicom

Original

Translation

Pydicom

Pydicom

Overview

概述

When to Use This Skill

何时使用本技能

Installation

安装

Core Workflows

核心工作流

Reading DICOM Files

读取DICOM文件

Read a DICOM file

Read a DICOM file

Access metadata

Access metadata

Display all elements

Display all elements

Working with Pixel Data

处理像素数据

Read DICOM file

Read DICOM file

Get pixel array (requires numpy)

Get pixel array (requires numpy)

Image information

Image information

Apply windowing for display (CT/MRI)

Apply windowing for display (CT/MRI)

Display image

Display image

RGB images have shape (rows, columns, 3)

RGB images have shape (rows, columns, 3)

For multi-frame DICOM files

For multi-frame DICOM files

Converting DICOM to Image Formats

将DICOM转换为图像格式

Normalize to 0-255 range

Normalize to 0-255 range

Save as PNG

Save as PNG

Modifying Metadata

修改元数据

Modify existing elements

Modify existing elements

Add new elements

Add new elements

Remove elements

Remove elements

Or using del

Or using del

Save modified file

Save modified file

Anonymizing DICOM Files

匿名化DICOM文件

Tags commonly containing PHI (Protected Health Information)

Tags commonly containing PHI (Protected Health Information)

Remove or replace sensitive data

Remove or replace sensitive data

Update dates to maintain temporal relationships

Update dates to maintain temporal relationships

Keep pixel data intact

Keep pixel data intact

Writing DICOM Files

写入DICOM文件

Create file meta information

Create file meta information

Create the FileDataset instance

Create the FileDataset instance

Add required DICOM elements

Add required DICOM elements

Add image-specific elements

Add image-specific elements

Create pixel data

Create pixel data

Add required UIDs

Add required UIDs

Save the file