pydicom

Was macht pydicom?

Verwenden Sie pydicom für DICOM-Datensatz-I/O und Pixelverarbeitung. Version 3.0.2 ist der aktuelle stabile Release, der hier überprüft wird. Er behebt CVE-2026-32711, ein Problem mit manipulierten DICOMDIR-Pfaden. pydicom 3.0.2 benötigt Python >=3.10; das enthaltene DICOM-Wörterbuch ist 2024c, während der lebende DICOM-Standard neuer sein kann.

Obligatorische Sicherheitsgrenze

• Arbeiten Sie nur mit lokalen Daten, auf die der Benutzer zugreifen darf.
• DICOM-Metadaten, Dateinamen, private Elemente, Overlays, strukturierte Inhalte und Pixel können geschützte Gesundheitsinformationen (PHI) enthalten.
• Geben Sie Dataset niemals standardmäßig aus, exportieren Sie keine vollständigen Metadaten/JSON und protokollieren Sie keine Elementwerte. Verwenden Sie eine dokumentierte Positivliste und aggregierte Ausgabe.
• pydicom ist ein allgemeines DICOM-Framework, kein diagnostischer Viewer. Pixelausgabe, Validierung, Konvertierung und Plugin-Verfügbarkeit sind keine diagnostischen Aussagen.
• De-Identifikation ist profil-, zweck-, empfänger-, rechtsraum- und bedrohungskontextspezifisch. Sie erfordert eine Überprüfung durch Privatsphäre-/DICOM-Experten.
• Behaupten Sie niemals, dass ein Skript zur Entfernung von Tags DICOM PS3.15, HIPAA, GDPR oder anderen Vorschriften entspricht. Bewahren Sie Originale auf und prüfen Sie abgeleitete Ausgaben.
• Behandeln Sie deterministische Pseudonymisierungsschlüssel und UID-Karten als Geheimnisse zur Re-Identifikation: Verwenden Sie das Least-Privilege-Prinzip und verschlüsselte/verwaltete Geheimnisspeicher, committen, synchronisieren, protokollieren oder teilen Sie sie niemals mit Ableitungen und definieren Sie Backup-, Rotations-, Widerrufs- und Vernichtungsverfahren. Ein durchgesickerter Schlüssel macht die beabsichtigte Trennung ungültig; eine Rotation ändert auch die deterministischen Zuordnungen.
• Legen Sie explizite Grenzen für Eingabedateien, Dateianzahl, Frame-Anzahl, dekorierte Bytes und Ausgabe fest, bevor Sie nicht vertrauenswürdige oder ungewöhnlich große Datensätze parsen.

Installation

Erstellen oder aktivieren Sie eine isolierte Umgebung und installieren Sie dann den exakt überprüften Release:

uv pip install "pydicom==3.0.2"

Unkomprimierte Pixel-Arrays und Bildrendering:

uv pip install "pydicom==3.0.2" "numpy==2.5.1" "Pillow==12.3.0"

Installieren Sie nur die Transfer-Syntax-Plugins, die für die Bereitstellung erforderlich sind:

# JPEG/JPEG-LS, JPEG 2000/HTJ2K und schnelleres RLE über 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-Kodierer/Dekodierer
uv pip install "numpy==2.5.1" "pyjpegls==1.5.1"

# Alternativer Dekodierer mit plattformspezifischen Rädern
uv pip install "python-gdcm==3.2.6"

Plugin-Lizenzen und Räder unterscheiden sich je nach Paket/Plattform; überprüfen Sie sie vor der Bereitstellung. Pillow hat dokumentierte Dekodierungseinschränkungen und pydicom warnt davor, dass die Plugin-Ausgabe unabhängig überprüft werden muss.

Native Codec-Räder erweitern die Grenzen der Lieferkette und Speichersicherheit. Für eine kontrollierte Bereitstellung lösen Sie diese genauen Pins auf einem vertrauenswürdigen Build-Host auf, sperren und überprüfen Sie Rad-Hashes/-Herkunft, spiegeln Sie genehmigte Artefakte intern, scannen Sie sie und installieren Sie sie mit Hash-Durchsetzung, anstatt zur Laufzeit vom öffentlichen Index aufzulösen.

Wählen Sie den Workflow

1. Benötigen Sie eine aggregierte Übersicht: Führen Sie scripts/extract_metadata.py aus.
2. Benötigen Sie begrenzte technische Prüfungen: Führen Sie scripts/dicom_inventory.py aus.
3. Benötigen Sie eine Codec-Bereitstellungsvorprüfung: Führen Sie scripts/transfer_syntax_inspector.py aus.
4. Benötigen Sie eine Frame-/Speicherplanung: Führen Sie scripts/pixel_frame_planner.py aus.
5. Benötigen Sie ein nicht-diagnostisches gerendertes Frame: Führen Sie scripts/dicom_to_image.py aus.
6. Benötigen Sie eine pseudonymisierte Ableitung: Lesen Sie den Abschnitt zur De-Identifikation, erstellen Sie ein standortgeprüftes Aktionsprofil und führen Sie dann scripts/anonymize_dicom.py und scripts/deidentification_audit.py aus.
7. Benötigen Sie eine Überprüfung einer sensiblen UID-Karte: Führen Sie scripts/uid_mapping_validator.py aus.

Datensätze sicher lesen

dcmread() gibt ein FileDataset zurück, eine Unterklasse von Dataset mit Dateiformatzustand wie file_meta, Präambel und ursprünglicher Kodierung.

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"),
}

Verwenden Sie:

• stop_before_pixels=True für reine Metadatenarbeit.
• specific_tags=[...] für eine minimale Positivliste.
• defer_size="1 MiB", wenn ein späterer Schreibvorgang große Werte bewahren muss.
• force=False (Standard). force=True umgeht nur die Prüfung des Dateiformat-Headers; es beweist nicht, dass die Bytes gültiges DICOM sind.

Rufen Sie print(ds), repr(ds) nicht auf und iterieren Sie keine Werte in Protokolle bei klinischen Daten.

Dataset, DataElement und Sequenzen

Greifen Sie auf Standardelemente per Schlüsselwort zu und prüfen Sie auf Abwesenheit:

modality = ds.get("Modality", "UNSPECIFIED")
if "ReferencedImageSequence" in ds:
    for item in ds.ReferencedImageSequence:
        referenced_class = item.get("ReferencedSOPClassUID")

Tag-Zugriff, z.B. ds[0x0010, 0x0010], gibt ein DataElement zurück; sein .value ist getrennt. Sequence verhält sich wie eine Liste von verschachtelten Dataset-Elementen. Datenschutzaktionen müssen jedes Sequenzelement rekursiv durchlaufen, nicht nur die oberste Ebene.

Beim Erstellen einer Datei verwenden Sie FileMetaDataset für Gruppe 0002, halten Sie die SOP-UIDs von Datensatz und Dateimetadaten konsistent, setzen Sie eine Transfer-Syntax-UID und schreiben Sie im erzwungenen Dateiformat:

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
# Fügen Sie vor dem Schreiben alle vom ausgewählten IOD erforderlichen Attribute hinzu.
dcmwrite("new.dcm", ds, enforce_file_format=True, overwrite=False)

write_like_original ist in pydicom 3.0 veraltet; verwenden Sie enforce_file_format. Ein erfolgreicher Schreibvorgang ist keine vollständige PS3.3-IOD-Konformität.

UIDs und Transfer-Syntax

Die Transfer-Syntax-UID der Dateimetadaten steuert die Datensatzkodierung und Pixelkomprimierung:

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 wählt die Schreibkodierung anhand der Transfer-Syntax-UID vor veralteten Datensatzflags. Ersetzen Sie keine strukturellen UIDs (Transfer-Syntax, SOP-Klasse oder Kodierungsschema-UIDs) während der Pseudonymisierung. Der Ersatz von Instanz-/Referenz-UIDs muss eins-zu-eins und konsistent innerhalb des vollständig deklarierten Bereichs erfolgen.

Lesen Sie references/transfer_syntaxes.md vor der Komprimierung, Dekomprimierung oder Kapselung.

Pixeldaten und Frames

Die stabile pydicom.pixels-API unterstützt pfadbasierte, framespezifische Dekodierung:

from pydicom.pixels import pixel_array

# Liest nur das ausgewählte Frame, wenn die Quelle dies zulässt.
frame = pixel_array("authorized/image.dcm", index=0, raw=False)

Formatsemantik:

• Graustufen Einzelframe: (rows, columns)
• Graustufen Multiframe: (frames, rows, columns)
• Farb Einzelframe: (rows, columns, samples)
• Farb Multiframe: (frames, rows, columns, samples)

raw=False konvertiert YCbCr-Pixeldaten nach Möglichkeit in RGB; raw=True behält den dekodierten Farbraum nach der obligatorischen minimalen Verarbeitung bei. Verwenden Sie iter_pixels(path, indices=[...]) für eine begrenzte Multiframe-iteration.

Für die Graustufendarstellung wenden Sie Transformationen in dieser Reihenfolge an:

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 und VOI/Fensterung ändern die Anzeige-/Wertesemantik. MONOCHROME1 erfordert möglicherweise eine Präsentationsinversion. Palette-Farbe erfordert apply_color_lut(). Präsentationszustände und ICC-Verhalten erfordern möglicherweise einen validierten Viewer. Verwenden Sie niemals die Min/Max-Normalisierung pro Frame für die quantitative Analyse.

Komprimierung, Dekomprimierung und Kapselung

• Der Zugriff auf pixel_array dekodiert bei Bedarf, ändert aber den Datensatz nicht.
• Dataset.decompress() ändert Pixeldaten direkt, setzt Explicit VR Little Endian, aktualisiert Bildmetadaten und generiert standardmäßig eine neue SOP-Instance-UID.
• Dataset.compress(uid) ändert Pixeldaten und Transfer-Syntax direkt und generiert standardmäßig eine neue SOP-Instance-UID.
• Die integrierten/gefundenen Kodierer von pydicom 3.0 decken die in der stabilen Plugin-Matrix dokumentierten RLE Lossless-, JPEG-LS- und JPEG-2000-Kombinationen ab.
• Jedes komprimierte Frame wird separat kodiert und dann gekapselt. Verwenden Sie encapsulate() oder encapsulate_extended() für extern kodierte Frames.
• Lesen Sie Frames mit dem aktuellen pydicom.encaps.generate_frames() oder get_frame(); veraltete Kapselungsgeneratornamen sind für pydicom 4 veraltet.

Überprüfen Sie zuerst immer die Fähigkeiten, begrenzen Sie die dekorierte Bytes/Frames und verifizieren Sie die Pixelkorrektheit unabhängig. Die Akzeptanz verlustbehafteter Komprimierung liegt außerhalb von pydicom und der DICOM-Kodierungsspezifikation.

DICOM JSON und private Elemente

Dataset.to_json(), to_json_dict() und Dataset.from_json() implementieren das DICOM-JSON-Modell, aber pydicom dokumentiert die JSON-Unterstützung als Beta. Vollständiges JSON kann Binärdaten inline einbetten und jeden Bezeichner und jede Pixel-Nutzlast offenlegen. Geben Sie es nicht als Metadatenbericht aus. Ein BulkDataURI-Handler führt zu separaten Speicher-, Autorisierungs- und Abrufverpflichtungen.

Private Elemente sind nicht standardisiert und können PHI enthalten:

# Rekursive Entfernung, aber keine ausreichende De-Identifikation für sich allein.
ds.remove_private_tags()

Behalten Sie private Elemente nur unter einer explizit geprüften sicheren Privatrichtlinie bei. Lesen Sie references/common_tags.md für Tag-Zugriff, Datenschutzklassen und Standardverweise.

De-Identifikations-Workflow

DICOM PS3.15 Annex E erklärt ausdrücklich, dass Vertraulichkeitsprofile nicht garantieren, dass alle identifizierenden Informationen entfernt werden, und keinen vollständigen De-Identifikationsprozess ersetzen.

1. Definieren Sie Zweck, Empfänger, Verknüpfungsanforderungen, Vorschriften, Bedrohungsmodell und akzeptables Re-Identifikationsrisiko.
2. Wählen Sie das Basic Application Level Confidentiality Profile und die erforderlichen Optionen (Pixel, erkennbare visuelle Merkmale, Grafiken, strukturierte Inhalte, Deskriptoren, zeitliche Informationen, Patientenmerkmale, Geräte, Einrichtungen, UIDs und sichere private Daten).
3. Bewahren Sie Quellobjekte unverändert in kontrolliertem Speicher.
4. Wenden Sie jede Aktion rekursiv an, einschließlich verschachtelter Sequenzen.
5. Ersetzen Sie Instanz-/Referenz-UIDs konsistent über den gesamten Bereich; bewahren Sie strukturelle UIDs.
6. Entscheiden Sie explizit über die Behandlung von Datum/Uhrzeit. Eine feste Verschiebung kann Intervalle bewahren, aber Teilangaben zu Daten, Zeitzonen, eigenständige Zeiten, Schalttage, Längsschnittverknüpfungen und externe Ereignisse erfordern eine überprüfte Richtlinie.
7. Überprüfen Sie Pixel, Overlays, Grafiken, strukturierte Inhalte und erkennbare visuelle Merkmale. Schließen Sie nicht aus fehlenden Metadaten auf saubere Pixel oder setzen Sie BurnedInAnnotation=NO ohne Verifizierung.
8. Erstellen Sie Dateimetadaten und Präambel neu, um Datenlecks zu verhindern.
9. Führen Sie eine technische Validierung und ein De-Identifikations-Audit durch, gefolgt von einer Expertenüberprüfung und dokumentierten Risikobewertung.

Das enthaltene Skript setzt absichtlich PatientIdentityRemoved auf NO, da es keine erfolgreiche De-Identifikation sicherstellen kann.

Hilfs-CLIs

Alle --help-Pfade sind abhängigkeitsfrei. Die Tools führen keinen Netzwerkzugriff durch und geben keine DICOM-Werte außerhalb enger technischer Positivlisten aus.

die enthaltenen Inhalte bestehen aus den beiden verlinkten Referenzen, den dokumentierten Hilfsskripten und synthetischen Tests. Die pydicom-Laufzeitabhängigkeit wird aus dem festgelegten PyPI-Release installiert.

# Redigierte aggregierte Metadaten
python scripts/extract_metadata.py authorized/ --recursive

# Nur-Metadaten technisches Inventar
python scripts/dicom_inventory.py authorized/ --recursive

# Installierte Codec-/Plugin-Fähigkeiten
python scripts/transfer_syntax_inspector.py --input authorized/image.dcm

# Frame-Form, Byte- und Transformationsplan
python scripts/pixel_frame_planner.py authorized/image.dcm --frames 0,2-4

# Ein nicht-diagnostisches Frame
python scripts/dicom_to_image.py authorized/image.dcm frame.png \
  --acknowledge-pixel-phi

# Erstellen Sie einen geheimen Schlüssel, dann eine bereichsbezogene pseudonymisierte Ableitung 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-Kandidaten-Metadaten; keine Pixel-Dekomprimierung
python scripts/deidentification_audit.py derived/out.dcm

# Validieren einer explizit angeforderten sensiblen UID-Zuordnung
python scripts/uid_mapping_validator.py derived/uid-map.json \
  --uid-key-file project.key --uid-scope export-v1

Die generierte rohe Schlüsseldatei ist ein lokaler kontrollierter Komfort und wird mit Berechtigungen nur für den Besitzer erstellt. Für die Produktion materialisieren Sie Schlüsselbytes aus einem genehmigten Secret Manager in eine gesperrte temporäre Datei, beschränken Sie den Zugriff auf den De-Identifikationsdienst und entfernen Sie ihn danach sicher. Speichern Sie optionale UID-Karten separat von Ableitungen; sie verknüpfen direkt Original- und Ersatzbezeichner.

pydicom 3.0 Migrationshinweise

• read_file() und write_file() wurden entfernt; verwenden Sie dcmread() und dcmwrite().
• write_like_original ist veraltet; verwenden Sie enforce_file_format.
• pydicom.pixel_data_handlers ist für die Entfernung in v4 veraltet; verwenden Sie pydicom.pixels.
• Dataset.pixel_array verwendet standardmäßig das neue Pixel-Backend und konvertiert YCbCr nach Möglichkeit in RGB.
• JPEGLossless bedeutet jetzt UID 1.2.840.10008.1.2.4.57; JPEGLosslessSV1 ist .70.
• Dataset.is_little_endian und is_implicit_VR sind für v4 veraltet.

Quellen (überprüft am 23.07.2026)

• pydicom 3.0.2 auf PyPI — veröffentlicht 2026

… [für die Übersetzung gekürzt]