--- 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. --- # 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 # RGB images have shape (rows, columns, 3) if ds.PhotometricInterpretation == 'RGB': rgb_image = ds.pixel_array plt.imshow(rgb_image) elif ds.PhotometricInterpretation == 'YBR_FULL': from pydicom.pixel_data_handlers.util import convert_color_space rgb_image = convert_color_space(ds.pixel_array, 'YBR_FULL', 'RGB') 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 Remove or replace patient identifiable information: ```python import pydicom from datetime import datetime ds = pydicom.dcmread('input.dcm') # Tags commonly containing PHI (Protected Health Information) tags_to_anonymize = [ 'PatientName', 'PatientID', 'PatientBirthDate', 'PatientSex', 'PatientAge', 'PatientAddress', 'InstitutionName', 'InstitutionAddress', 'ReferringPhysicianName', 'PerformingPhysicianName', 'OperatorsName', 'StudyDescription', 'SeriesDescription', ] # Remove or replace sensitive data for tag in tags_to_anonymize: if hasattr(ds, tag): if tag in ['PatientName', 'PatientID']: setattr(ds, tag, 'ANONYMOUS') elif tag == 'PatientBirthDate': setattr(ds, tag, '19000101') else: delattr(ds, tag) # Update dates to maintain temporal relationships if hasattr(ds, 'StudyDate'): # Shift dates by a random offset ds.StudyDate = '20000101' # Keep pixel data intact ds.save_as('anonymized.dcm') ``` Use the provided 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', write_like_original=False) # 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 Anonymize DICOM files by removing or replacing Protected Health Information (PHI). ```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 `write_like_original=True` 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** thoroughly before sharing medical data 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 --- Source attribution: Dicklesworthstone Original project: https://github.com/Dicklesworthstone/pi_agent_rust/blob/f28fc46ee0db8e710d95b8b55592cd38d60f2b26/tests/ext_conformance/artifacts/templates-davila7/cli-tool/components/skills/scientific/pydicom/SKILL.md License: MIT License information: https://opensource.org/license/mit Original upstream instructions; downloaded from Dave AI. ## Upstream license notice MIT License (with OpenAI/Anthropic Rider) Copyright (c) 2026 Jeffrey Emanuel Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: ADDITIONAL RIDER / RESTRICTION (OpenAI / Anthropic): This rider is part of the "conditions" of this License. In the event of any conflict between this rider and any other portion of this License, this rider controls. "Restricted Parties" means OpenAI, L.L.C.; Anthropic, PBC; any of their respective Affiliates; and any person or entity acting directly or indirectly on behalf of, for the benefit of, or under the direction of any of the foregoing (including any officer, director, employee, contractor, agent, consultant, service provider, or representative). Notwithstanding any other provision of this License, no rights are granted to any Restricted Party. Any purported license, sublicense, assignment, transfer, or other permission to any Restricted Party is null and void absent the express prior written permission of Jeffrey Emanuel. You may not provide, disclose, distribute, sublicense, sell, lease, lend, host, make available, or otherwise permit access to the Software or any derivative work of the Software (as defined in applicable copyright law) (collectively, "Derivative Works") to or for any Restricted Party. For purposes of this rider, "use" includes, without limitation: copying, modifying, merging, publishing, distributing, sublicensing, selling, transferring, making available, hosting, deploying, executing, benchmarking, testing, analyzing, indexing, or incorporating the Software or any Derivative Works into any dataset, training corpus, evaluation harness, or pipeline for machine learning or other automated systems. This rider applies to the Software and all Derivative Works. As a condition of use, you agree that this rider is a precondition to exercising any rights under this License, and you agree that any distribution of the Software or any Derivative Works must include this rider provision unmodified. Any breach of this rider automatically and immediately terminates the permissions granted by this License. Upon termination, you must immediately cease all use and distribution of the Software and any Derivative Works and destroy all copies under your control. You agree that a breach of this rider would cause irreparable harm and that Jeffrey Emanuel may seek injunctive or other equitable relief to enforce this rider, in addition to any other remedies available at law. To the maximum extent permitted by applicable law, the prevailing party in any action to enforce this rider shall be entitled to recover reasonable attorneys' fees and costs. For purposes of this rider, "Affiliate" means any entity that directly or indirectly controls, is controlled by, or is under common control with the specified party. "Control" means ownership of more than 50% of the voting securities or other ownership interest, or the power to direct management or policies by contract or otherwise. The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. # Dave AI resource metadata Creator / publisher: Dicklesworthstone Original project: https://github.com/Dicklesworthstone/pi_agent_rust/blob/f28fc46ee0db8e710d95b8b55592cd38d60f2b26/tests/ext_conformance/artifacts/templates-davila7/cli-tool/components/skills/scientific/pydicom/SKILL.md Attribution basis: Source repository record Fields of work: Healthcare & Life Sciences Roles: Clinical Research, Health Informatics, Medical Writer Specialties: API, Backend, Cross Platform Tools: Pydicom Country applicability: Country not specified Classification basis: Source catalog labels Instruction SHA-256: 5ee0e26c037b15015e4dcbe40613d890ff71a9e0d2b800002a801d8baa941d07