Saltar al contenido principal

DICOM De-identify (Pixel + Header)

Category: Healthcare Standards
Node id: dicom-deid

Standards: HIPAA, GDPR, SOC2

Device-grade DICOM de-identification: removes header PHI AND detects/masks burned-in PHI in pixel data (templates + on-device OCR), under a fixed RAM budget. Low-confidence files are routed to human review instead of being emitted.

What it does​

  • Header PHI de-identification (PS3.15 Annex E subset) with remove/replace/hash and deterministic UID regeneration
  • Burned-in PHI detection via deterministic device templates (Layer 1)
  • On-device OCR text localization for masking (Layer 2, -tags tesseract)
  • PHI-vs-clinical classification with header-cue, pattern, and dictionary signals (Layer 3)
  • Conservative emit-or-escalate decision with human-review routing (Layer 4)
  • Fixed RAM budget governing concurrency by predicted per-file memory
  • Multi-frame union masking (cine/secondary-capture)
  • Audit detection record without persisting PHI content

Use cases​

  • De-identify ultrasound and secondary-capture studies (name banners burned into pixels) before research sharing
  • Anonymize a dicomweb-retrieved study end-to-end in a visual pipeline
  • Gate a research export so burned-in PHI cannot leak, escalating uncertain frames to review

Runtime​

  • Performance tier: high

Input ports​

NameTypeRequiredDescription
dicom_datatextYesDICOM file data (base64 or raw) — single instance. May also be an array for batch processing.
instancesjsonNoArray of DICOM instances for batch processing — each element has inline bytes (dicom_b64/dicom_data) and/or a file_path (e.g. from a dicomweb retrieve). When present, every instance is processed and result.instances[] is returned.

Output ports​

NameTypeRequiredDescription
resultjsonNoDe-identification result: decision (emit|escalate), fast_path, deid_data (base64, only when emitted), regenerated_uids, peak_bytes. Array mode returns result.instances[].
detection_recordjsonNoAudit artifact (no PHI strings): masked-region geometry, classifications, confidences, detector/template/classifier versions, sampled frames, masked-area fraction, decision, escalation reasons.
successbooleanNoWhether the operation succeeded (a file routed to review still succeeds; check result.decision).
crosswalk_tablesjsonNoArray-mode only: table-load payload {uid_crosswalk: [{accession, orig/deid study/series/sop UIDs, orig_patient_id, orig_wadors_uri}]} mapping original PACS identifiers to the regenerated (2.25.*) ones. Wire to a RESTRICTED impala-direct sink — it is the re-identification key.

Settings​

Basic​

SettingNameTypeRequiredDefaultAllowed valuesDescription
Header De-id Methodmask_methodenumNoremoveremove, replace, hashHow header PHI tags are de-identified

Crosswalk​

SettingNameTypeRequiredDefaultAllowed valuesDescription
Concentrator Base URL (crosswalk)concentrator_base_urlstringNoDICOMweb base URL of the source PACS/concentrator. When set, each UID-crosswalk row records an original-PACS WADO-RS URI (orig_wadors_uri) so the source image stays retrievable by an authorized holder of the crosswalk. Empty = no orig wadors.
Accession (crosswalk)accessionstringNoAccession number stamped on each UID-crosswalk row. Optional: when absent, it is read from the source DICOM AccessionNumber (0008,0050). Set it only to a literal or a placeholder that this node actually receives as a runtime input — an unresolved {{...}} is ignored, never stamped.

Advanced​

SettingNameTypeRequiredDefaultAllowed valuesDescription
Keep UIDskeep_uidsbooleanNofalsePreserve study/series/SOP UIDs (otherwise regenerated deterministically)
Mask Fill Valuefill_valuenumberNo0min 0; max 255Pixel value written over masked PHI regions (0 = black)
Verify With OCRverify_with_layer2booleanNotrueRun OCR even where a template matched, as a verification net
Escalate Unknown Profileescalate_on_unknown_profilebooleanNotrueEscalate pixel-path files with no template and no OCR rather than emitting them
Max Mask Fractionmax_mask_fractionnumberNo0.5min 0; max 1If the mask covers more than this fraction of a frame, escalate (probable detector failure)
Sample Framessample_framesnumberNo5min 1; max 64Max frames OCR-sampled on multi-frame objects (first/last/sparse interior); the PHI region union is applied to all frames
CGO Codecs Linkedcgo_codecsbooleanNofalseJPEG2000/JPEG-LS decoders are compiled in (otherwise those syntaxes escalate)
Compressed Outputcompressed_outputbooleanNofalseFor JPEG-baseline input, emit encapsulated JPEG output (unmasked frames copied through losslessly; masked frames re-encoded as JPEG — a lossy recompression of those frames' unmasked pixels). Bounds output size for large compressed cines. Off = lossless uncompressed output.
JPEG Qualityjpeg_qualitynumberNo90min 1; max 100Re-encode quality (1-100) for masked frames when Compressed Output is on
VLM Recall-Net URLvlm_verify_urlstringNoOptional on-device granite-docling endpoint for a recall-net (escalation-only). Empty = disabled.
VLM Modelvlm_modelstringNogranite-doclingModel name for the VLM recall-net

Errors​

CodeDescription
DICOM_DATA_REQUIREDdicom_data input is missing or empty
INVALID_MASK_METHODmask_method is not remove, replace, or hash
TRANSFER_SYNTAX_NOT_DECODABLEBurned-in PHI suspected but the transfer syntax cannot be decoded (flagged for review)
OCR_NOT_COMPILEDOCR engine not compiled (build with -tags tesseract); affected files escalate

Runtime notes​

  • Routing: files without burned-in PHI take the FAST path (header de-id + verbatim pixel copy). Files with burned-in PHI (BurnedInAnnotation=YES, or US/SC/XA/XC/secondary-capture) take the SLOW path (frame decode + detect + mask + re-encode).
  • Detection is layered: Layer 1 deterministic device templates, Layer 2 on-device OCR localization (only with -tags tesseract; otherwise the file escalates), Layer 3 PHI-vs-clinical classification, Layer 4 emit-or-escalate decision. The bias is recall: ambiguous text is masked or escalated, never passed through.
  • Escalated files (decision=escalate) are NOT emitted (no deid_data) and carry escalation_reasons — route them to a human review queue.
  • Whole-slide imaging (modality SM) and undecodable transfer syntaxes (JPEG2000/JPEG-LS without cgo codecs) are flagged for manual review rather than emitted with PHI intact.
  • vlm_verify_url enables an optional on-device VLM recall-net (granite-docling): it can only ESCALATE (it returns text without coordinates), never mask. Must be an in-cluster/on-host service — a hosted cloud OCR would transmit pixel data off-host (prohibited).
  • Array mode mirrors the dicom node: a list of instances returns result.instances[] with result.instance_count/success_count/is_array; emitted instances carry deid_data, escalated ones carry decision/escalation_reasons.
  • Output encoding: the slow path emits lossless uncompressed by default. compressed_output=true keeps JPEG-baseline input encapsulated (unmasked frames copied through bit-identically; masked frames re-encoded as JPEG, a lossy step). The detection_record records output_encoding, lossy_recompression, recompressed_frames, verbatim_frames, and jpeg_quality so the lossy step is auditable (see HYDRA-DEID-ADR-001).

See Build any workflow for how to put nodes together and Ports, types and data flow for how port types connect.

¿Algo no está claro? Envíe sus comentarios sobre la documentación por correo electrónico..