alterlab-pydicom

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.

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

Installation

Targets pydicom 3.x (3.0 reorganized the pixel APIs — see the version note below). Install pydicom and common dependencies:

uv pip install "pydicom>=3.0"
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:

uv pip install pylibjpeg pylibjpeg-libjpeg pylibjpeg-openjpeg  # JPEG / JPEG 2000
uv pip install python-gdcm  # Alternative compression handler
uv pip install pyjpegls     # JPEG-LS encode/decode (replaces older JPEG-LS handlers)

pydicom 3.0 API changes (important)

3.0 moved all pixel handling into the pydicom.pixels module and deprecated some long-standing APIs (the old names still work but emit warnings and are removed in 4.0):

• from pydicom.pixel_data_handlers.util import apply_voi_lut → from pydicom.pixels import apply_voi_lut (same for convert_color_space).
• pydicom.encoders → pydicom.pixels.encoders.
• ds.save_as(path, write_like_original=False) → ds.save_as(path, enforce_file_format=True) (write_like_original=True, the default, became implicit and is no longer needed).