pydicom

用途

pydicom 是一个通用 DICOM 框架，用于对本地 DICOM 文件进行数据集 I/O 与像素处理。它可读取、检查、写入和转换 DICOM 文件，适用于元数据提取、技术盘点、传输语法检查、像素帧规划、非诊断性图像渲染以及去标识化派生等任务。它并非诊断查看器，像素输出、校验、转换和插件可用性均不构成诊断声明。

主要能力

• 数据集读写：dcmread() 返回 FileDataset，dcmwrite() 写入文件，支持 enforce_file_format。
• 元数据访问：按关键字访问标准元素，支持 specific_tags 允许列表、stop_before_pixels、defer_size。
• 序列与私有元素：Sequence 表现为嵌套 Dataset 列表，remove_private_tags() 可递归移除私有标签。
• 传输语法：通过 file_meta.TransferSyntaxUID 控制编码与像素压缩，可查询名称、是否压缩、隐式 VR、字节序。
• 像素处理：pydicom.pixels 提供 pixel_array、iter_pixels、apply_modality_lut、apply_voi_lut、apply_color_lut 等。
• 压缩与解封装：Dataset.decompress()、Dataset.compress(uid)、encapsulate()、encapsulate_extended()，以及 encaps.generate_frames()/get_frame()。
• DICOM JSON：to_json()、to_json_dict()、from_json()，官方标注为 beta。
• 辅助 CLI：extract_metadata.py、dicom_inventory.py、transfer_syntax_inspector.py、pixel_frame_planner.py、dicom_to_image.py、anonymize_dicom.py、deidentification_audit.py、uid_mapping_validator.py。

使用方式

安装（隔离环境）：

uv pip install "pydicom==3.0.2"

含未压缩像素数组与渲染：

uv pip install "pydicom==3.0.2" "numpy==2.5.1" "Pillow==12.3.0"

按需安装传输语法插件（JPEG/JPEG-LS、JPEG 2000/HTJ2K、RLE）：

uv pip install "numpy==2.5.1" "pylibjpeg==2.1.0" "pylibjpeg-libjpeg==2.4.0" "pylibjpeg-openjpeg==2.5.0" "pylibjpeg-rle==2.2.0"

JPEG-LS 编解码：

uv pip install "numpy==2.5.1" "pyjpegls==1.5.1"

替代解码器：

uv pip install "python-gdcm==3.2.6"

安全读取示例：

from pathlib import Path import pydicom

path = Path("authorized/input.dcm") ds = pydicom.dcmread( path, stop_before_pixels=True, specific_tags=["SOPClassUID", "Modality", "Rows", "Columns", "NumberOfFrames"], )

像素帧读取：

from pydicom.pixels import pixel_array frame = pixel_array("authorized/image.dcm", index=0, raw=False)

灰度显示变换顺序：

from pydicom.pixels import apply_modality_lut, apply_voi_lut modality_values = apply_modality_lut(frame, ds) display_values = apply_voi_lut(modality_values, ds, index=0)

创建文件时使用 FileMetaDataset 管理 0002 组，保持数据集与文件元信息 SOP UID 一致，设置传输语法 UID，并以强制文件格式写入：

from pydicom import dcmwrite from pydicom.dataset import FileDataset, FileMetaDataset from pydicom.uid import CTImageStorage, ExplicitVRLittleEndian, generate_uid

meta = FileMetaDataset() meta.MediaStorageSOPClassUID = CTImageStorage meta.MediaStorageSOPInstanceUID = generate_uid() meta.TransferSyntaxUID = ExplicitVRLittleEndian

ds = FileDataset(None, {}, file_meta=meta, preamble=b"\0" * 128) ds.SOPClassUID = meta.MediaStorageSOPClassUID ds.SOPInstanceUID = meta.MediaStorageSOPInstanceUID dcmwrite("new.dcm", ds, enforce_file_format=True, overwrite=False)

辅助 CLI 示例：

python scripts/extract_metadata.py authorized/ --recursive python scripts/dicom_inventory.py authorized/ --recursive python scripts/transfer_syntax_inspector.py --input authorized/image.dcm python scripts/pixel_frame_planner.py authorized/image.dcm --frames 0,2-4 python scripts/dicom_to_image.py authorized/image.dcm frame.png --acknowledge-pixel-phi python scripts/anonymize_dicom.py --generate-uid-key project.key python scripts/anonymize_dicom.py authorized/in.dcm derived/out.dcm --uid-key-file project.key --uid-scope export-v1 --audit-report derived/out.audit.json python scripts/deidentification_audit.py derived/out.dcm python scripts/uid_mapping_validator.py derived/uid-map.json --uid-key-file project.key --uid-scope export-v1

适用场景

• 聚合元数据概览与技术盘点。
• 传输语法与编解码器部署预检。
• 帧与内存规划。
• 单帧非诊断性渲染。
• 去标识化派生与审计。
• 敏感 UID 映射校验。

限制与安全边界

• 仅处理用户有权访问的本地数据。
• DICOM 元数据、文件名、私有元素、叠加层、结构化内容和像素可能含 PHI；默认不得打印 Dataset、导出完整元数据/JSON 或记录元素值。
• 去标识化依赖具体用途、接收方、司法辖区和威胁模型，需隐私/DICOM 专家验证；不得声称标签移除脚本符合 PS3.15、HIPAA、GDPR 等合规要求。
• 确定性假名化密钥与 UID 映射属于再识别机密，应最小权限、加密/托管存储，不得提交、同步、记录或随派生数据共享，并定义备份、轮换、撤销和销毁流程。
• 解析不可信或超大数据集前应设置输入文件、文件数、帧数、解码字节和输出限制。
• 原生编解码器 wheel 扩大供应链与内存安全边界，受控部署应锁定并校验哈希/来源、内部镜像、扫描并以哈希强制安装。
• 插件许可证与 wheel 因包/平台而异，部署前需审查；Pillow 有已知解码限制，插件输出须独立核验。
• 有损压缩可接受性超出 pydicom 与 DICOM 编码规范范围。
• DICOM JSON 支持为 beta，完整 JSON 可能内联二进制数据并暴露所有标识符与像素载荷，不应作为元数据报告输出。
• 成功写入不等于完整 PS3.3 IOD 一致性。
• 去标识化脚本有意将 PatientIdentityRemoved 设为 NO，因其无法确认去标识化成功。
• 输出为面向合格专业人员的决策支持，非医疗建议，不得作为诊断或医嘱。

版本迁移要点

• read_file()/write_file() 已移除，改用 dcmread()/dcmwrite()。
• write_like_original 已弃用，改用 enforce_file_format。
• pydicom.pixel_data_handlers 将在 v4 移除，改用 pydicom.pixels。
• Dataset.pixel_array 默认使用新像素后端，并在可能时将 YCbCr 转为 RGB。
• JPEGLossless 现指 UID 1.2.840.10008.1.2.4.57；JPEGLosslessSV1 为 .70。
• Dataset.is_little_endian 与 is_implicit_VR 将在 v4 弃用。