Lightbridge-KS/agent-fähigkeiten

DCMTK Befehlszeilen-Referenz

DCMTK ist das OFFIS DICOM Toolkit – eine ausgereifte, BSD-lizenzierte Referenzimplementierung großer Teile des DICOM-Standards. Diese Fähigkeit deckt seine Befehlszeilenwerkzeuge ab (die C++ API liegt außerhalb des Rahmens).

Wenn Sie etwas mit DICOM tun können, gibt es wahrscheinlich ein dcm*-Binary dafür. Der Haken: Die Tool-Sammlung ist groß (~70 Binärdateien in 12 Modulen) und die Flag-Konventionen (-x vs +x sind unterschiedliche Flags) sind überraschend. Diese Fähigkeit existiert, damit ein KI-Agent das richtige Werkzeug auswählen, einen korrekten Aufruf beim ersten Versuch schreiben und die klassischen DCMKT-Fallstricke vermeiden kann.

Mentales Modell

DCMTK gruppiert Werkzeuge nach Modulen, basierend darauf, was sie berühren:

dcmdata    DICOM-Dateien auf der Festplatte: parsen, dumpen, ändern, kodieren/dekodieren (kein Netzwerk)
dcmnet     DIMSE über TCP: ECHO, STORE, FIND, MOVE, GET
dcmimage   Rendern von DICOM-Pixeldaten in gängige Bildformate (PNG/PNM/BMP/TIFF)
dcmjpeg    JPEG (DCT) Komprimierung / Dekomprimierung von DICOM-Pixeldaten
dcmjpls    JPEG-LS Komprimierung / Dekomprimierung von DICOM-Pixeldaten
dcmsr      Strukturierte Berichte: dumpen, rendern, Round-Trip mit XML
dcmqrdb    ein kleiner eigenständiger Q/R-Datenbankserver (Test-PACS) + Indexer
dcmwlm     ein kleiner eigenständiger Modality Worklist-Server
dcmsign    DICOM digitale Signaturen (signieren / verifizieren / entfernen)
dcmrt      Strahlentherapie-Objekte prüfen (RT Plan / Struct / Dose / etc.)
dcmpstat   Präsentationszustände + Druck-SCP/SCU (fortgeschritten; hier nicht behandelt)
dcmtls     TLS-Unterstützung (wird von dcmnet-Werkzeugen verwendet; kein eigenes Werkzeug)

Die CLI-Benennung ist konsistent, sobald man sie einmal gesehen hat: Werkzeuge, die kodieren, beginnen mit dcmc* (dcmcjpeg, dcmcjpls, dcmcrle); Werkzeuge, die dekodieren, beginnen mit dcmd* (dcmdjpeg, dcmdjpls, dcmdrle); SCUs enden auf *scu (Netzwerk-Client) und SCPs enden auf *scp (Netzwerk-Server).

Die DIMSE-Dienstzuordnung

   Service-Klasse      Operation        SCU-Werkzeug         SCP-Werkzeug
   ─────────────────────────────────────────────────────────────────
   Verifikation       C-ECHO           echoscu              storescp akzeptiert
   Speicherung        C-STORE          storescu, dcmsend    storescp, dcmrecv
   Abfrage/Rückruf    C-FIND           findscu              dcmqrscp
                      C-MOVE           movescu              dcmqrscp
                      C-GET            getscu               dcmqrscp
   Worklist           C-FIND           findscu (mit -W)     wlmscpfs

Für ein echtes PACS würden Sie Orthanc / DCM4CHEE / ConQuest als SCP verwenden. DCMTKs eigene SCPs (dcmqrscp, wlmscpfs) dienen zum Testen und für Integrationsgerüste.

Die Flag-Präfix-Konvention

  -x   IMMER eine sich gegenseitig ausschließende Wahl (ein Modus aus mehreren)
  +x   IMMER schaltet eine Funktion ein oder fügt etwas hinzu
  --x  lange Form von -x oder +x; gleiche Semantik

Also sind -xe (Little-Endian vorschlagen) und +e1 (JPEG Baseline kodieren) nicht verwandt – unterschiedliches Präfix, unterschiedliche Werkzeugfamilie, unterschiedliche Bedeutung.

Welches Werkzeug für welche Aufgabe

Sie möchten …	Werkzeug	Referenz
Überprüfen, ob ein PACS erreichbar ist	echoscu	dcmnet.md
DICOM-Datei(en) an ein PACS senden	dcmsend (oder storescu für feine TS-Kontrolle)	dcmnet.md
DICOM in einen Ordner empfangen	storescp (oder dcmrecv)	dcmnet.md
Ein PACS abfragen (nach PatientID / Datum / Accession)	findscu	dcmnet.md
Studien von einem PACS abrufen	movescu oder getscu	dcmnet.md
Alle Tags in einer DICOM-Datei anzeigen	dcmdump	dcmdata.md
Ein Tag in einer DICOM-Datei finden	dcmdump --search KEY	dcmdata.md
Ein Tag anonymisieren / ändern	dcmodify	dcmdata.md
DICOM → JSON konvertieren	dcm2json	dcmdata.md
DICOM → XML konvertieren	dcm2xml	dcmdata.md
Überprüfen, ob eine Datei gültiges DICOM Part-10 ist	dcmftest	dcmdata.md
Ein DICOMDIR für den Medienaustausch erstellen	dcmmkdir (veralteter Alias: dcmgpdir)	dcmdata.md
Transfer-Syntax ändern (nur unkomprimiert)	dcmconv	dcmdata.md
DICOM mit JPEG komprimieren	dcmcjpeg	image-codecs.md
JPEG-kodiertes DICOM dekomprimieren	dcmdjpeg	image-codecs.md
Mit JPEG-LS komprimieren / dekomprimieren	dcmcjpls / dcmdjpls	image-codecs.md
Mit RLE komprimieren / dekomprimieren	dcmcrle / dcmdrle	dcmdata.md
DICOM → PNG / JPEG / TIFF / BMP / PNM rendern	dcm2img	image-codecs.md
Ein DICOM-Bild skalieren	dcmscale	image-codecs.md
JPEG/PNG/BMP/TIFF als DICOM verpacken	img2dcm	img-pdf-import.md
Ein PDF (oder CDA/STL/OBJ) als gekapseltes DICOM verpacken	dcmencap (veralteter Alias: pdf2dcm)	img-pdf-import.md
Eingebettetes PDF/CDA/STL/OBJ aus einem DICOM extrahieren	dcmdecap (veralteter Alias: dcm2pdf)	img-pdf-import.md
Den Inhaltsbaum eines strukturierten Berichts dumpen	dsrdump	dcmsr.md
SR → HTML rendern	dsr2html	dcmsr.md
SR Round-Trip durch XML	dsr2xml / xml2dsr	dcmsr.md
Ein Test-PACS aufsetzen	dcmqrscp + dcmqridx	dcmqrdb-wlm.md
Einen Test-Modality-Worklist-Server aufsetzen	wlmscpfs	dcmqrdb-wlm.md
DICOM digitale Signaturen signieren / verifizieren	dcmsign	dcmsign-dcmrt.md
RT Plan / Struct / Dose-Objekte prüfen	drtdump	dcmsign-dcmrt.md

Für gemeinsame Flags (Logging, Netzwerk, TLS, Transfer-Syntax-Aushandlung, Dateiformat) siehe common-options.md. Für Transfer-Syntax-UIDs und die passenden -x* / +t* Flags siehe transfer-syntax-uids.md.

Top-Rezepte

Die folgenden Beispiele verwenden diese Platzhalter – ersetzen Sie sie durch die tatsächlichen Werte für die Zielumgebung:

PACS_HOST       Hostname oder IP des entfernten PACS                  z.B. pacs.krankenhaus.local
PACS_PORT       DICOM-TCP-Port des entfernten PACS                   z.B. 104, 4242, 11112
PACS_AET        gerufener AE-Titel – muss mit der Konfiguration des entfernten PACS übereinstimmen   z.B. MAIN_PACS
MY_AET          unser rufender AE-Titel                             z.B. ACME_SCU

1. Überprüfen, ob ein PACS erreichbar ist (C-ECHO)

echoscu -v PACS_HOST PACS_PORT -aec PACS_AET -aet MY_AET

Erfolg sieht so aus: Received Echo Response (Success). Wenn Sie Association Rejected sehen, kennt der entfernte Rechner entweder Ihren -aec AE-Titel nicht oder Ihre IP ist nicht in seiner Konfiguration in der Whitelist.

2. DICOM-Dateien an ein PACS senden (C-STORE)

Einzelne Datei, volle TS-Kontrolle:

storescu -v PACS_HOST PACS_PORT -aec PACS_AET -aet MY_AET input.dcm

Ordner, rekursiv, mit Umbenennung pro Datei bei Erfolg:

dcmsend -v PACS_HOST PACS_PORT -aec PACS_AET -aet MY_AET +sd +r /path/to/studies/

Wann welches verwenden:

• storescu — kampferprobt, volle -x*-Kontrolle über die TS-Aushandlung, kein integrierter "Ordner durchsuchen"-Modus außer +sd +r. Greifen Sie darauf zurück, wenn Sie genaue Kontrolle darüber benötigen, welche TS vorgeschlagen werden.
• dcmsend — neuer, einfacher. Behandelt Verzeichnissuche, Statuszusammenfassung, .done / .bad-Umbenennung. Empfohlene Standardeinstellung für Batch-Übertragungen an einen bekannten entfernten Rechner.

Häufiger Fehler: Association Aborted: presentation context not supported. Der entfernte Rechner akzeptiert die SOP-Klasse oder die TS, in der die Datei kodiert ist, nicht. Mit -d ausführen, um die Aushandlung zu sehen; die angebotenen ACs im Vergleich zu den akzeptierten ACs machen das Problem offensichtlich.

3. DICOM in einen Ordner empfangen (C-STORE SCP)

storescp -v -aet MY_AET --output-directory /path/to/incoming/ \
         --sort-conc-studies study_ PACS_PORT

Die Dateien landen unter /path/to/incoming/study_<StudyInstanceUID>/.

Für flexiblere Dateinamen-Vorlagen und pro-Studien-Post-Processing-Hooks ist dcmrecv die moderne Alternative – gleiche Idee, einfachere Konfiguration:

dcmrecv -v --output-directory /path/to/incoming/ PACS_PORT

4. Ein PACS abfragen (C-FIND)

Eine C-FIND-Abfrage wird aus -k-Schlüsseln aufgebaut: Jeder -k schränkt die Suche entweder ein (-k "(0010,0020)=PATIENT_ID") oder fordert, dass dieses Attribut zurückgegeben wird (-k "(0010,0010)" mit leerem Wert).

Alle Studien für einen Patienten:

findscu -v -S \
  -k "(0008,0052)=STUDY" \
  -k "(0010,0020)=PATIENT_ID" \
  -k "(0010,0010)" \
  -k "(0020,000D)" \
  -k "(0008,0020)" \
  PACS_HOST PACS_PORT -aec PACS_AET -aet MY_AET

Wissenswerte Flags:

• -S Studienwurzel-Modell (Standard und am häufigsten); -P Patientenwurzel; -W Worklist
• (0008,0052) QueryRetrieveLevel – muss mit dem Modell übereinstimmen (STUDY/SERIES/IMAGE)
• Jeder -k mit einem Wert schränkt ein; jeder -k ohne Wert (nur das Tag) fordert den SCP auf, es zurückzugeben

5. Studien abrufen (C-MOVE)

C-MOVE fordert den SCP auf, Instanzen an ein Ziel-AE zu pushen – was bedeutet, dass das Ziel ein laufender storescp/dcmrecv sein muss, der vom SCP erreichbar ist, und der AE-Titel des Ziels muss im SCP vorregistriert sein.

Terminal A – den lokalen Listener starten:

storescp -v --output-directory ./retrieved/ -aet MY_AET 11112

Terminal B – den C-MOVE ausführen (Ziel = unser MY_AET auf Port 11112):

movescu -v -S \
  -k "(0008,0052)=STUDY" \
  -k "(0020,000D)=1.2.3.4.5.STUDY.UID" \
  -aem MY_AET \
  PACS_HOST PACS_PORT -aec PACS_AET -aet MY_AET

Wenn das PACS keinen Eintrag für MY_AET in seiner Konfiguration hat, schlägt der Move mit Move Destination Unknown fehl. movescu selbst kann auch als untergeordneter Listener mit --port 11112 --output-directory ./out/ fungieren – nützlich für Tests, bei denen Sie keinen separaten storescp-Terminal benötigen.

Für Punkt-zu-Punkt-Abruf, bei dem der SCP nichts über Ihren Listener wissen muss, ist C-GET (getscu) einfacher:

getscu -v -S -k "(0008,0052)=STUDY" -k "(0020,000D)=1.2.3.4.5.STUDY.UID" \
       --output-directory ./retrieved/ \
       PACS_HOST PACS_PORT -aec PACS_AET

Aber viele Produktions-PACS unterstützen C-GET nicht – C-MOVE ist die sicherere Standardeinstellung.

6. Tags aus einer Datei dumpen

Gesamte Datei, jedes Tag:

dcmdump input.dcm

Nur ein Tag (nach Name oder nach Gruppe/Element):

dcmdump --search PatientID input.dcm
dcmdump --search "0010,0010" input.dcm

Die Ausgabe ist eine Zeile pro Attribut:

(0010,0010) PN [DOE^JANE]                                #   8, 1 PatientName

Spalten: Tag, VR, Wert, Länge, Wertmultiplizität, Attributname.

Um in Sequenzelemente zu rekursieren (z.B. beim Lesen eines strukturierten Berichtsbaums) fügen Sie +R hinzu. Um den Roh-Pixeldaten-Dump zu überspringen, fügen Sie --max-read-length 4 hinzu. Die Ausgabe von dcmdump kann von dump2dcm wieder zurück in DICOM geparst werden, um einen Round-Trip zum Bearbeiten zu ermöglichen.

7. Tags anonymisieren / ändern

dcmodify ändert direkt (erstellt ein .bak-Backup, sofern nicht -nb):

# PatientName überall ersetzen, wo er vorkommt (Hauptsatz + jedes Sequenzelement)
dcmodify -nb -ma "(0010,0010)=ANON^PATIENT" input.dcm

# Ein Tag einfügen, das nicht vorhanden war
dcmodify -nb -i "(0010,4000)=anonymisiert 2026-05-25" input.dcm

# Jedes private Tag löschen (Gruppe ist ungerade)
dcmodify -nb -ep input.dcm

# Neue UIDs für die Studien-/Serien-/Instanz-Hierarchie generieren
dcmodify -nb -gst -gse -gsi input.dcm

Operations-Flags (sich gegenseitig ausschließend pro Tag):

• -i einfügen, wenn nicht vorhanden (Fehler, wenn vorhanden)
• -m ändern, wenn vorhanden (Fehler, wenn nicht vorhanden)
• -ma alles ändern (Hauptsatz + jedes Sequenzelement)
• -e löschen / -ea alles löschen / -ep private löschen
• -gst -gse -gsi Studien-/Serien-/SOPInstance-UIDs neu generieren

Achtung: Standardmäßig schreibt dcmodify ein .bak von jeder geänderten Datei. Bei einer 10k-Datei-Anonymisierung verdoppelt das Ihre Festplattennutzung und ist fast immer unerwünscht – übergeben Sie für Batch-Arbeiten immer -nb.

8. DICOM nach PNG / JPEG / TIFF / BMP / PNM rendern

dcm2img +on input.dcm out.png      # PNG (8-Bit)
dcm2img +on2 input.dcm out.png     # PNG (16-Bit – volle Bittiefe behalten)
dcm2img +oj input.dcm out.jpg      # JPEG (8-Bit verlustbehafteter Baseline)
dcm2img +ot input.dcm out.tiff     # TIFF
dcm2img +ob input.dcm out.bmp      # BMP
dcm2img +op input.dcm out.pgm      # PNM Roh (PGM für Graustufen, PPM für Farbe)

dcm2img Flag-Buchstaben-Konvention: +o<buchstabe> wählt das Ausgabeformat (n=PNG, j=JPEG, t=TIFF, b=BMP, p=PNM/PGM/PPM, l=JPEG-LS). +oa (--write-auto) wählt basierend auf der Ausgabedateinamenerweiterung.

dcm2img dekomprimiert JPEG / JPEG-LS / RLE-Eingaben automatisch – kein separater dcmdjpeg-Schritt ist erforderlich. Bei Multi-Frame-Daten schreibt +Fa eine Ausgabedatei pro Frame (Dateinamen erhalten einen Frame-Nummer-Suffix).

Wenn Sie die Fensterung steuern möchten, anstatt dcm2img die VOI-LUT der Datei verwenden zu lassen:

dcm2img +on +Wm input.dcm out.png         # Min/Max der Pixel als Fenster verwenden
dcm2img +on +W 50 350 input.dcm out.png   # WindowCenter=50, WindowWidth=350

dcm2pnm, dcmj2pnm, dcml2pnm sind veraltete Aliase für dcm2img.

9. DICOM-Pixeldaten JPEG-komprimieren

dcmcjpeg input.dcm output.dcm

Standardmäßig wählt dcmcjpeg den wirtschaftlichsten verlustbehafteten Codec (JPEG Extended). Flag +e1 erzwingt JPEG Baseline (8-Bit, verlustbehaftet); +e2 = Extended (12-Bit); +e3 = Lossless SV1; +eb = verlustfrei.

Wichtige Optionen:

• +e1 – JPEG Baseline (das, was browser nativ anzeigen können)
• +sm 1 – 1:1 Subsampling (kein Chroma-Untersampling, beste Qualität)
• +sq 100 – (numerisch) Qualitätsfaktor; 100 ≈ verlustfreie Schwellenkompression

10. JPEG-komprimiertes DICOM dekomprimieren

dcmdjpeg input.dcm output.dcm

Verwendet +fo (wie Store-Original-Data) oder überlassen Sie die Ziel-TS dem Standardverhalten von dcmdjpeg (Little Endian Explicit VR).

11. DICOM aus JSON / XML importieren

Um JSON- oder XML-Daten in eine gültige DICOM-Datei zu konvertieren:

json2dcm input.json output.dcm
xml2dsr input.xml output.dcm   # (für Structured Reports: dsr2xml ist der Rückweg)

Zitieren Sie die Eingabe nicht – json2dcm liest immer von einer Datei, nicht von stdin.

12. DICOM-Konsistenz prüfen

dcmftest input.dcm

Gibt einen Exit-Code 0 zurück, wenn die Datei ein gültiges DICOM Part-10-Format hat (magische Bytes, Preamble, Metadaten-Header). Keine Ausgabe im Erfolgsfall. Ein nicht-null Exit-Code + Fehlermeldung bedeutet, dass die Datei kein gültiges DICOM ist – zum Beispiel eine Roh-Pixel-Datei ohne Header.

13. DICOMDIR erstellen

dcmmkdir +r +I /pfad/zu/dicom/  # (veralteter Alias: dcmgpdir)

Erstellt eine DICOMDIR-Datei im angegebenen Verzeichnisbaum. +I fügt DicomDirectoryRecord-Einträge für jede gefundene Datei hinzu. +r verarbeitet Unterverzeichnisse rekursiv.

14. Transfer-Syntax konvertieren (nur unkomprimiert)

dcmconv +te input.dcm output.dcm    # Little Endian Explicit VR (Standard)
dcmconv +ti input.dcm output.dcm    # Little Endian Implicit VR
dcmconv +tb input.dcm output.dcm    # Big Endian Explicit VR (selten)

dcmconv kann nur zwischen unkomprimierten Transfer-Syntaxes konvertieren. Für die JPEG/JPEG-LS/RLE-Komprimierung verwenden Sie die dedizierten Codec-Werkzeuge.

Weitere nützliche dcmconv-Flags:

• +bd – Big Endian Byte Order für Metadaten (für DICOMDIR-Kompatibilität)
• +do – DICOM Only (schreibt striktes Part-10, keine Privat-Tag-Definitionen)

15. DICOM-Bild skalieren

dcmscale input.dcm output.dcm -xl 512 -yl 512    # Breite 512, Höhe 512 (Proportionen beibehalten)
dcmscale input.dcm output.dcm -xf 1 -yf 2       # Horizontale Skalierung 1x, Vertikale 2x
dcmscale input.dcm output.dcm -xl 256 -yl 256 -mm bilinear  # Bilineare Methode (Standard: benachbarter Pixel)

dcmscale behält die DICOM-Bildmetadaten bei (Pixelspacing, Rescale Slope/Intercept) und skaliert nur das vom Modality-Wert gelieferte Pixel-Array.

16. DICOM-Rohformate (CR/DX/MG) skalieren

dcm2img +on +Wm input.dcm out.png    # Fenster auf Pixel-Min/Max

Warnung: dcm2img kann (wird) die DICOM-Kopfzeileninformationen in das Ausgabebild einbetten. Wenn Sie ein Pixel-für-Pixel-identisches Roh-Bild benötigen, verwenden Sie dcm2pnm (veraltet) oder dcmj2pnm (veraltet) mit dem Rohmodus.

17. Demonstrations-Test-PACS aufsetzen

Eine vollständige Q/R-SCP-Umgebung für Tests:

# 1. Indexdatenbank initialisieren
dcmqridx pfad/zu/db/

# 2. SCP starten (Standard-Port 11112, speichere hereingekommene Dateien in db/)
dcmqrscp -v --db-dir pfad/zu/db/ --output-directory pfad/zu/studien/ 11112

Standardverhalten von dcmqrscp:

• Akzeptiert C-FIND, C-MOVE, C-STORE (kein C-GET)
• Kein C-ECHO per Default – +de hinzufügen, um Verifikation zu aktivieren
• Nur auf localhost binden; --bind-address für andere Netzwerke ändern

18. Worklist-Server aufsetzen

wlmscpfs -v -dfp pfad/zu/worklist/ -dfr +sp 11112

Jede gültige DICOM-Datei im dfp-Verzeichnis wird als Modality-Worklist-Element behandelt. findscu -W wird diese zurückgeben.

19. Strukturierte Berichte rendern / durch XML round-triften

# Inhalt des SR-Baums anzeigen
dsrdump input.dcm

# SR als HTML anzeigen
dsr2html input.dcm output.html

# SR in XML exportieren
dsr2xml input.dcm output.xml

# XML zurück in SR importieren
xml2dsr output.xml roundtrip.dcm

Wenn die Ausgabe von dsr2html leer ist, enthält die Datei verweise auf externe Inhalte (z.B. verknüpfte Bilder ohne eingebettete Daten).

Nächste Schritte / Verweise

• dcmnet.md (noch zu schreiben) – Nettools (echoscu, findscu, storescu, movescu, getscu, storescp, dcmrecv, dcmsend) – grundlegende Netzwerk-//400 Optionen, Aushandlung, Fehlerbehandlung.
• dcmdata.md (noch zu schreiben) – Datentools (dcmdump, dcmodify, dcm2json, dcm2xml, json2dcm, dump2dcm, dcmconv, dcmftest) – Tag-Bearbeitung, Konvertierung.
• image-codecs.md (noch zu schreiben) – Bildcodecs (dcmcjpeg, dcmdjpeg, dcmcjpls, dcmdjpls, dcmcrle, dcmdrle, dcm2img, dcmscale) – Komprimierung und Bildwiedergabe.
• img-pdf-import.md (noch zu schreiben) – Bild-/PDF-Import (-export) (img2dcm, dcmencap, dcmdecap) – Sekundärkapselung.
• dcmsr.md (noch zu schreiben) – Structured Reporting (dsrdump, dsr2html, dsr2xml, xml2dsr).
• dcmqrdb-wlm.md (noch zu schreiben) – Query / Worklist (dcmqrscp, dcmqridx, wlmscpfs) – Test-PACS / Worklist-Server.
• dcmsign-dcmrt.md (noch zu schreiben) – Signaturen / Strahlentherapie (dcmsign, drtdump) – Digitale Signaturen und RT-Dump.
• common-options.md (noch zu schreiben) – Gemeinsame Flags (Logging, Netzwerk, TLS, TS-Aushandlung).
• transfer-syntax-uids.md (noch zu schreiben) – TS-UID-Tabelle und passende -x* / +t* Flags.