pydicom
Reads, inspects, writes, and transforms local DICOM files with pydicom 3.x (dcmread, dcmwrite, pydicom.pixels), including metadata, transfer syntaxes, compressed pixel data plugins, frame decoding, private elements, DICOM JSON, and bounded pseudonymization review using bundled helper scripts. Use when extracting aggregate metadata from DICOM datasets without printing PHI, checking which transfer syntaxes and codec plugins a deployment needs, planning frame or memory limits before decoding pixel data, rendering one non-diagnostic frame, compressing or decompressing pixel data, or building and auditing a pseudonymized derivative. Not for diagnostic viewing, or for claiming DICOM PS3.15, HIPAA, or GDPR compliance.
Install this skill
Works with Claude Code, Codex, Cursor, Gemini CLI, GitHub Copilot, OpenCode, and 70+ other harnesses.
npx skills add KalarisLabs/research-agent-skills --skill pydicomuvx research-agent-skills install pydicomDocumentation & Instructions
pydicom
Use pydicom for DICOM dataset I/O and pixel processing. Version 3.0.2 is the
current stable release reviewed here. It fixes CVE-2026-32711, a crafted
DICOMDIR path-traversal issue. pydicom 3.0.2 declares Python >=3.10; its
bundled DICOM dictionary is 2024c, while the live DICOM Standard may be newer.
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. - pydicom is a general DICOM framework, not a diagnostic viewer. Pixel output, validation, conversion, and plugin availability are not diagnostic claims.
- 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. Preserve originals and audit derived outputs.
- Treat deterministic pseudonymization keys and UID maps as re-identification secrets: use least privilege and encrypted/managed secret storage, never commit, sync, log, or share them with derivatives, and define backup, rotation, revocation, and destruction procedures. A leaked key invalidates the intended separation; rotation also changes deterministic mappings.
- Set explicit input-file, file-count, frame-count, decoded-byte, and output limits before parsing untrusted or unusually large datasets.
Installation
Create or activate an isolated environment, then install the exact reviewed release:
uv pip install "pydicom==3.0.2"
Uncompressed pixel arrays and image rendering:
uv pip install "pydicom==3.0.2" "numpy==2.5.1" "Pillow==12.3.0"
Install only the transfer-syntax plugins required by the deployment:
# JPEG/JPEG-LS, JPEG 2000/HTJ2K, and faster RLE through pylibjpeg
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 encoder/decoder
uv pip install "numpy==2.5.1" "pyjpegls==1.5.1"
# Alternative decoder with platform-specific wheels
uv pip install "python-gdcm==3.2.6"
Plugin licenses and wheels differ by package/platform; review them before deployment. Pillow has documented decoding limitations and pydicom cautions that plugin output must be independently checked.
Native codec wheels widen the supply-chain and memory-safety boundary. For a controlled deployment, resolve these exact pins on a trusted build host, lock and verify wheel hashes/provenance, mirror approved artifacts internally, scan them, and install with hash enforcement rather than resolving from the public index at runtime.
Choose the workflow
- Need an aggregate overview: run
scripts/extract_metadata.py. - Need bounded technical checks: run
scripts/dicom_inventory.py. - Need codec deployment preflight: run
scripts/transfer_syntax_inspector.py. - Need frame/memory planning: run
scripts/pixel_frame_planner.py. - Need one non-diagnostic rendered frame: run
scripts/dicom_to_image.py. - Need a pseudonymized derivative: read the de-identification section, create
a site-reviewed action profile, then run
scripts/anonymize_dicom.pyandscripts/deidentification_audit.py. - Need to check a sensitive UID map: run
scripts/uid_mapping_validator.py.
Read datasets safely
dcmread() returns a FileDataset, a Dataset subclass with File Format
state such as file_meta, preamble, and original encoding.
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",
],
)
technical = {
"sop_class": ds.get("SOPClassUID"),
"modality": ds.get("Modality"),
"rows": ds.get("Rows"),
"columns": ds.get("Columns"),
}
Use:
stop_before_pixels=Truefor metadata-only work.specific_tags=[...]for a minimum allowlist.defer_size="1 MiB"when a later write must preserve large values.force=False(default).force=Trueonly bypasses the File Format header check; it does not prove the bytes are valid DICOM.
Do not call print(ds), repr(ds), or iterate values into logs on clinical
data.
Dataset, DataElement, and sequences
Access standard elements by keyword and check for absence:
modality = ds.get("Modality", "UNSPECIFIED")
if "ReferencedImageSequence" in ds:
for item in ds.ReferencedImageSequence:
referenced_class = item.get("ReferencedSOPClassUID")
Tag access, such as ds[0x0010, 0x0010], returns a DataElement; its .value
is separate. Sequence behaves like a list of nested Dataset items. Privacy
actions must recurse through every sequence item, not only the top level.
When creating a file, use FileMetaDataset for group 0002, keep dataset and
file-meta SOP UIDs consistent, set a Transfer Syntax UID, and write in enforced
File Format:
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
# Add all attributes required by the selected IOD before writing.
dcmwrite("new.dcm", ds, enforce_file_format=True, overwrite=False)
write_like_original is deprecated in pydicom 3.0; use
enforce_file_format. A successful write is not full PS3.3 IOD conformance.
UIDs and transfer syntax
The File Meta Information Transfer Syntax UID controls dataset encoding and pixel compression:
ts = ds.file_meta.TransferSyntaxUID
summary = {
"uid": str(ts),
"name": ts.name,
"compressed": ts.is_compressed,
"implicit_vr": ts.is_implicit_VR,
"little_endian": ts.is_little_endian,
}
pydicom 3.0 chooses write encoding from the Transfer Syntax UID before legacy dataset flags. Do not replace structural UIDs (Transfer Syntax, SOP Class, or coding-scheme UIDs) during pseudonymization. Instance/reference UID replacement must be one-to-one and consistent across the complete declared scope.
Read references/transfer_syntaxes.md before compression, decompression, or encapsulation.
Pixel data and frames
The stable pydicom.pixels API supports path-based, frame-specific decoding:
from pydicom.pixels import pixel_array
# Reads only the selected frame where the source permits it.
frame = pixel_array("authorized/image.dcm", index=0, raw=False)
Shape semantics:
- grayscale single frame:
(rows, columns) - grayscale multi-frame:
(frames, rows, columns) - color single frame:
(rows, columns, samples) - color multi-frame:
(frames, rows, columns, samples)
raw=False converts YCbCr pixel data to RGB when possible; raw=True retains
the decoded color space after mandatory minimal processing. Use
iter_pixels(path, indices=[...]) for bounded multi-frame iteration.
For grayscale display, apply transforms in this order:
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)
Modality LUT/rescale and VOI/windowing change display/value semantics.
MONOCHROME1 may require presentation inversion. Palette Color requires
apply_color_lut(). Presentation states and ICC behavior may require a
validated viewer. Never use per-frame min/max normalization for quantitative
analysis.
Compression, decompression, and encapsulation
- Accessing
pixel_arraydecodes as needed but does not change the dataset. Dataset.decompress()changes Pixel Data in place, sets Explicit VR Little Endian, updates image metadata, and generates a new SOP Instance UID by default.Dataset.compress(uid)changes Pixel Data and Transfer Syntax in place and generates a new SOP Instance UID by default.- pydicom 3.0 built-in/found encoders cover RLE Lossless, JPEG-LS, and JPEG 2000 combinations documented in the stable plugin matrix.
- Each compressed frame is separately encoded and then encapsulated. Use
encapsulate()orencapsulate_extended()for externally encoded frames. - Read frames with current
pydicom.encaps.generate_frames()orget_frame(); legacy encapsulation generator names are deprecated for pydicom 4.
Always inspect capabilities first, limit decoded bytes/frames, and verify pixel correctness independently. Lossy compression acceptability is outside pydicom and the DICOM encoding specification.
DICOM JSON and private elements
Dataset.to_json(), to_json_dict(), and Dataset.from_json() implement the
DICOM JSON Model, but pydicom documents JSON support as beta. Full JSON may
inline binary data and expose every identifier and pixel payload. Do not emit
it as a metadata report. A BulkDataURI handler introduces separate storage,
authorization, and retrieval obligations.
Private elements are not standardized and may contain PHI:
# Recursive removal, but not sufficient de-identification by itself.
ds.remove_private_tags()
Retain private elements only under an explicit reviewed safe-private policy. Read references/common_tags.md for tag access, privacy classes, and standard pointers.
De-identification workflow
DICOM PS3.15 Annex E explicitly states that confidentiality profiles do not guarantee removal of all identifying information and do not replace a complete de-identification process.
- Define purpose, recipients, linkage needs, regulations, threat model, and acceptable re-identification risk.
- Select the Basic Application Level Confidentiality Profile and needed options (pixel, recognizable visual features, graphics, structured content, descriptors, temporal information, patient characteristics, devices, institutions, UIDs, and safe private data).
- Preserve source objects unchanged in controlled storage.
- Apply every action recursively, including nested sequences.
- Replace instance/reference UIDs consistently across the complete scope; preserve structural UIDs.
- Decide date/time handling explicitly. A fixed shift can preserve intervals but partial dates, time zones, standalone times, leap days, longitudinal linkage, and external events require reviewed policy.
- Inspect pixels, overlays, graphics, structured content, and recognizable
visual features. Do not infer clean pixels from missing metadata or set
BurnedInAnnotation=NOwithout verification. - Rebuild File Meta Information and preamble to prevent leakage.
- Run technical validation and a de-identification audit, then perform expert verification and documented risk review.
The bundled script intentionally sets PatientIdentityRemoved to NO because
it cannot establish successful de-identification.
Helper CLIs
All --help paths are dependency-free. The tools perform no network access and
emit no DICOM values beyond narrow technical allowlists.
Bundled content consists of the two linked references, the documented helper scripts, and synthetic tests. The pydicom runtime dependency is installed from the pinned PyPI release.
# Redacted aggregate metadata
python scripts/extract_metadata.py authorized/ --recursive
# Metadata-only technical inventory
python scripts/dicom_inventory.py authorized/ --recursive
# Installed codec/plugin capabilities
python scripts/transfer_syntax_inspector.py --input authorized/image.dcm
# Frame shape, byte, and transform plan
python scripts/pixel_frame_planner.py authorized/image.dcm --frames 0,2-4
# One non-diagnostic frame
python scripts/dicom_to_image.py authorized/image.dcm frame.png \
--acknowledge-pixel-phi
# Create a secret key, then a scoped pseudonymized derivative plus audit
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
# Audit candidate metadata; no pixel decompression
python scripts/deidentification_audit.py derived/out.dcm
# Validate an explicitly requested sensitive UID mapping
python scripts/uid_mapping_validator.py derived/uid-map.json \
--uid-key-file project.key --uid-scope export-v1
The generated raw key file is a controlled-local convenience and is created with owner-only permissions. For production, materialize key bytes from an approved secret manager into a locked ephemeral file, restrict access to the de-identification service, and securely remove it afterward. Store any optional UID map separately from derivatives; it directly links original and replacement identifiers.
pydicom 3.0 migration notes
read_file()andwrite_file()were removed; usedcmread()anddcmwrite().write_like_originalis deprecated; useenforce_file_format.pydicom.pixel_data_handlersis deprecated for removal in v4; usepydicom.pixels.Dataset.pixel_arrayuses the new pixels backend by default and converts YCbCr to RGB when possible.JPEGLosslessnow means UID1.2.840.10008.1.2.4.57;JPEGLosslessSV1is.70.Dataset.is_little_endianandis_implicit_VRare deprecated for v4.
Sources (verified 2026-07-23)
- pydicom 3.0.2 on PyPI — released
2026-03-19; Python
>=3.10. - pydicom releases — 3.0.2 and CVE-2026-32711 details.
- Stable release notes
- Stable installation guide
- Dataset basics
- Stable pixel tutorial
- Stable pixel plugins
- Stable compression tutorial
- Stable DICOM JSON tutorial
- Stable private-element guide
- Current DICOM Standard
- DICOM PS3.3, PS3.5, PS3.6, and PS3.15
Agent operating procedure
- Check the environment. Confirm data access permissions, de-identification status and the governing regulations or protocols.
- Pin down the inputs. Confirm formats, identifiers and parameters from the data or the user. Ask rather than guess any value that changes the result.
- Run a small version first. Work on a de-identified sample or synthetic data first.
- Execute the full task using the instructions and references above.
- Validate the result. Check outputs against clinical guidelines and reporting standards; have a qualified human review clinical content.
- Report. State what was run (versions, commands, parameters), what was checked, and what is still uncertain.
| If this happens | Do this |
|---|---|
| Data appears to contain identifiable patient information | Stop and ask the user before processing further. |
| A function, flag or endpoint in these instructions is missing in the installed version | Check the installed version's own documentation (help(), --help, official docs), adapt, and tell the user. Never invent an API. |
| A required input, identifier or parameter is ambiguous | Ask the user, or state the assumption explicitly before running. |
Integrity rules
- Never fabricate results, parameters, identifiers, citations or statistics. If something cannot be run or verified, say so plainly.
- Outputs are decision support for qualified professionals, not medical advice; never present them as diagnoses or orders.
- Treat version-specific details here as possibly outdated: confirm them against the official documentation for the installed version.
- Ask before actions that cost money, consume shared GPUs or cloud quota, touch personal or patient data, or cannot be undone.
Trigger Prompts & Evaluation Corpus
These evaluation prompts test that the agent correctly selects pydicom for relevant tasks and leaves it out for near misses.
Should trigger (3)
- should trigger
“Can you give me a quick summary of the modalities and transfer syntaxes across the DICOM files in ./scans without dumping any patient info?”
expects Uses the bundled aggregate scripts (extract_metadata.py or dicom_inventory.py) with bounded file-count and size limits. Reports only aggregate counts such as modality and transfer syntax. Does not print Datasets, patient names, IDs, or element values.
- should trigger
“I have a 4D cardiac cine MR series in ./cine/ (about 400 multi-frame files, JPEG 2000 Lossless compressed). Running ds.pixel_array on one file killed my kernel with a MemoryError, and some files raise 'missing required dependencies' for the pixel handler. Help me work out which codec plugins I need to install and how many frames I can safely decode at a time, then pull out frame 12 of one file as a PNG to eyeball.”
expects Runs transfer_syntax_inspector.py to identify the required plugin for JPEG 2000 (e.g. pylibjpeg/openjpeg). Runs pixel_frame_planner.py to estimate decoded bytes per frame and set frame and byte limits. Uses path-based single-frame decoding (pydicom.pixels.pixel_array with index) or dicom_to_image.py for one frame. States the PNG is non-diagnostic and applies the proper window/rescale order. Notes that plugin output should be independently verified.
- should trigger
“I need to share a set of CT studies with an external collaborator for a methods project. Patient names, IDs and dates have to be replaced, but I still want the series and studies to stay linked to each other. How should I go about producing that copy?”
expects Describes a pseudonymized derivative workflow. Starts by defining purpose, recipients and threat model, and keeps the originals unchanged. Recommends a site-reviewed action profile and runs anonymize_dicom.py, then deidentification_audit.py. Replaces UIDs consistently while preserving structural UIDs, handles nested sequences, and makes an explicit date-shift decision. Warns that keys and UID maps are secrets and must be stored separately. Says burned-in pixel annotations need review. Does not claim DICOM PS3.15, HIPAA or GDPR compliance, and calls for expert verification.
Near misses (2)
- near miss
“I'm training a 3D U-Net in PyTorch on NIfTI brain MRI volumes. Can you write the data augmentation pipeline with random flips, elastic deformation and intensity scaling, and a Dice loss?”
expects Recognizes this as deep learning model training and augmentation on NIfTI data, which does not involve reading or writing DICOM files. Does not use the pydicom skill. Handles it with general PyTorch or medical-imaging ML knowledge.
- near miss
“Our radiologist wants to open this chest X-ray DICOM and make a primary diagnosis of a possible nodule. Can you render it and tell us it's diagnostic quality?”
expects Declines to treat any rendered output as diagnostic. The skill is not a diagnostic viewer, and pydicom output cannot support a diagnostic-quality claim. Directs the user to a validated, certified clinical viewer (PACS) for diagnosis. May offer a non-diagnostic preview only.