Pydicom

---
name: pydicom
description: Python library for working with DICOM (Digital Imaging and Communications in Medicine) files. Use this skill when reading, writing, or modifying medical imaging data in DICOM format, extracting pixel data from medical images (CT, MRI, X-ray, ultrasound), anonymizing DICOM files, working with DICOM metadata and tags, converting DICOM images to other formats, handling compressed DICOM data, or processing medical imaging datasets. Applies to tasks involving medical image analysis, PACS systems, radiology workflows, and healthcare imaging applications.
license: https://github.com/pydicom/pydicom/blob/main/LICENSE
metadata: {"version": "1.0", "skill-author": "K-Dense Inc."}
---

# 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

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
```

## Core Workflows

### Reading DICOM Files

Read a DICOM file using `pydicom.dcmread()`:

```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')`

### Working with Pixel Data

Extract and manipulate image data from DICOM files:

```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
# pydicom 3.0+: pixel_array auto-converts YCbCr (YBR_FULL, YBR_FULL_422) to RGB
# by default, so ds.pixel_array already returns an RGB array for these formats.
# No manual convert_color_space() call is needed.
if ds.PhotometricInterpretation in ('RGB', 'YBR_FULL', 'YBR_FULL_422'):
    rgb_image = ds.pixel_array  # RGB array in all cases (pydicom 3.0+)
    plt.imshow(rgb_image)
```

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

```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')
```

### Converting DICOM to Image Formats

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

# 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`

### Modifying Metadata

Modify DICOM data elements:

```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')
```

### Anonymizing DICOM Files

**A keyword allowlist is not a de-identification profile.** DICOM PS3.15 Annex E
Table E.1-1 assigns action **X** (remove) to every Private Attribute
`(gggg,eeee)` where `gggg` is odd, action **U** (replace with a UID internally
consistent within a set of Instances) to `SOPInstanceUID (0008,0018)`,
`StudyInstanceUID (0020,000D)` and `SeriesInstanceUID (0020,000E)`, and applies
"whether contained in the top level Data Set or embedded in an Item of a Sequence
of Items". Annex E Note 1 states directly that the listed attributes "may not be
sufficient to guarantee confidentiality of patient identity". For data leaving an
institution use a maintained conformant implementation —
[`pydicom/deid`](https://github.com/pydicom/deid) or
[`dicognito`](https://github.com/blairconrad/dicognito), both MIT-licensed.

The example below and `scripts/anonymize_dicom.py` are demonstrations of the
pydicom API, **not** conformant profiles: neither reaches identifiers nested in
Sequence Items, structured report content, overlays, or text burned into Pixel
Data.

```python
import pydicom

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

# Action Z: replace with a zero-length or dummy value (Type 2, must stay present)
ds.PatientName = 'ANONYMOUS'
ds.PatientID = 'ANONYMOUS'
ds.PatientBirthDate = '19000101'
for tag in ['AccessionNumber', 'ReferringPhysicianName', 'StudyDate', 'StudyTime']:
    if hasattr(ds, tag):
        setattr(ds, tag, '')

# Action X: remove
for tag in ['PatientSex', 'PatientAge', 'PatientAddress', 'OtherPatientIDs',
            'InstitutionName', 'InstitutionAddress', 'PerformingPhysicianName',
            'OperatorsName', 'StudyDescription', 'SeriesDescription',
            'RequestAttributesSequence', 'SeriesDate', 'AcquisitionDate']:
    if hasattr(ds, tag):
        delattr(ds, tag)

# Private Attributes are action X. Many scanners store name, ID and accession
# number here, so an allowlist alone leaves them intact.
ds.remove_private_tags()

# Action U. entropy_srcs makes the mapping deterministic, so every Instance in a
# study or series gets the same replacement across separate invocations.
for tag in ['StudyInstanceUID', 'SeriesInstanceUID', 'SOPInstanceUID']:
    original = getattr(ds, tag, None)
    if original:
        setattr(ds, tag, pydicom.uid.generate_uid(entropy_srcs=[str(original)]))
ds.file_meta.MediaStorageSOPInstanceUID = ds.SOPInstanceUID

# PS3.15 E.1.1 requires both of these on a de-identified Data Set
ds.PatientIdentityRemoved = 'YES'
ds.DeidentificationMethod = 'keyword allowlist; not PS3.15 Annex E conformant'

# Pixel Data is untouched: check BurnedInAnnotation separately
ds.save_as('anonymized.dcm')
```

Demonstration script: `python scripts/anonymize_dicom.py input.dcm output.dcm`

### Writing DICOM Files

Create DICOM files from scratch:

```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')
```

### Compression and Decompression

Handle compressed DICOM files:

```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', enforce_file_format=True)

# 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.

### Working with DICOM Sequences

Handle nested data structures:

```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])
```

### Processing DICOM Series

Work with multiple related DICOM files:

```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)

# 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")
```

## Helper Scripts

This skill includes utility scripts in the `scripts/` directory:

### anonymize_dicom.py
Remove or replace Protected Health Information (PHI) in a DICOM file. Not a
PS3.15 Annex E conformant profile — see the warning under "Anonymizing DICOM
Files" before using it on real data.

```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
```

### 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
```

## 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

## 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

## Best Practices

1. **Always check for required attributes** before accessing them using `hasattr()` or `get()`
2. **Preserve file metadata** when modifying files by using `save_as()` with `enforce_file_format=False` (default; writes the dataset as-is). Use `enforce_file_format=True` only when you intentionally want DICOM File Format conformance. This replaces the deprecated `write_like_original` parameter removed in pydicom v4.0.
3. **Use Transfer Syntax UIDs** to understand compression format before processing pixel data
4. **Handle exceptions** when reading files from untrusted sources
5. **Apply proper windowing** (VOI LUT) for medical image visualization
6. **Maintain spatial information** (pixel spacing, slice thickness) when processing 3D volumes
7. **Verify anonymization** against DICOM PS3.15 Annex E before sharing medical data; a keyword allowlist is not a conformant profile
8. **Use UIDs correctly** - generate new UIDs when creating new instances, preserve them when modifying

## 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