domains / science / dicom-processing / pydicom

pydicom

Skill card

combined

The K-Dense-AI copy is a highly specialized, security-focused skill that mandates strict PHI handling, specific version pins (pydicom 3.0.2), and a 'local-only' boundary. The other three copies (Vibe-Skills, medical-research-skills, OpenClaw-Medical-Skills) are nearly identical 'generalist' tutorials that explicitly encourage printing patient metadata (e.g., `print(ds.PatientName)`) and lack the safety constraints of the K-Dense version. Because the K-Dense version contains critical safety procedures (de-identification, UID mapping, supply chain security) that the others omit, and the others contain general visualization workflows (matplotlib, windowing) that the K-Dense version restricts or omits in favor of specific scripts, no single copy is a complete superset. Combining them allows for a skill that is both functionally comprehensive and safe.

Repositories

Other copies

Combined skill

---
name: pydicom
description: Reads, inspects, writes, transforms, and preflights local DICOM datasets and pixel data. Applies to DICOM metadata, transfer syntaxes, compression plugins, frames, private elements, JSON, and bounded de-identification review.
license: MIT
metadata:
  version: "1.5"
  skill-author: "K-Dense Inc. / Community"
---

# pydicom

Use pydicom for DICOM dataset I/O and pixel processing. This skill covers both secure, production-grade handling of PHI and general exploratory analysis.

## Mandatory Safety Boundary

- Work only with local data that the user is authorized to access.
- DICOM metadata, file names, private elements, overlays, structured content, and pixels may contain protected health information (PHI).
- **Never** print `Dataset`, export full metadata/JSON, or log element values by default. Use a documented allowlist and aggregate output.
- De-identification is profile-, purpose-, recipient-, jurisdiction-, and threat-context-specific. It requires privacy/DICOM expert verification.
- Never claim that a tag-removal script is DICOM PS3.15, HIPAA, GDPR, or other compliance.
- Treat deterministic pseudonymization keys and UID maps as re-identification secrets.

## Installation

For production or secure environments, use pinned versions and hash verification:

```bash
uv pip install "pydicom==3.0.2" "numpy==2.5.3" "Pillow==12.3.0"
```

For exploratory or non-sensitive local analysis, unpinned installation is acceptable:

```bash
uv pip install pydicom numpy pillow matplotlib
```

Install only the transfer-syntax plugins required by the deployment (e.g., `pylibjpeg`, `python-gdcm`).

## Core Workflows

### 1. Reading Datasets Safely

`dcmread()` returns a `FileDataset`. For metadata-only work, use `stop_before_pixels=True` and `specific_tags` to limit exposure.

```python
import pydicom
from pathlib import Path

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

# Safe access pattern
technical = {
    "sop_class": ds.get("SOPClassUID"),
    "modality": ds.get("Modality"),
}
```

**Note:** In non-sensitive exploratory contexts, you may use `print(ds)` or `print(ds.PatientName)`, but this is **forbidden** in any workflow involving real PHI or production data.

### 2. Pixel Data and Visualization

Extract pixel arrays and apply windowing for display.

```python
import numpy as np
import matplotlib.pyplot as plt
from pydicom.pixel_data_handlers.util import apply_voi_lut

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

# Apply windowing if available
if hasattr(ds, 'WindowCenter') and hasattr(ds, 'WindowWidth'):
    windowed_image = apply_voi_lut(pixel_array, ds)
else:
    windowed_image = pixel_array

plt.imshow(windowed_image, cmap='gray')
plt.show()
```

### 3. Converting to Image Formats

Convert DICOM to PNG/JPEG for non-diagnostic use.

```python
from PIL import Image

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

# Normalize to 0-255 if necessary
if pixel_array.dtype != np.uint8:
    pixel_array = ((pixel_array - pixel_array.min()) / (pixel_array.max() - pixel_array.min()) * 255).astype(np.uint8)

Image.fromarray(pixel_array).save('output.png')
```

### 4. Anonymization and De-identification

Use `scripts/anonymize_dicom.py` for site-reviewed de-identification. Do not rely on ad-hoc tag removal for compliance.

Common PHI tags to handle:
- `PatientName`, `PatientID`, `PatientBirthDate`
- `InstitutionName`, `ReferringPhysicianName`
- `StudyDescription`, `SeriesDescription`

## Scripts

- `scripts/extract_metadata.py`: Aggregate overview.
- `scripts/dicom_inventory.py`: Bounded technical checks.
- `scripts/dicom_to_image.py`: Non-diagnostic rendered frame.
- `scripts/anonymize_dicom.py`: Pseudonymized derivative.
- `scripts/deidentification_audit.py`: Audit derived outputs.