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
| Name | Type | Required | Description |
|---|---|---|---|
dicom_data | text | Yes | DICOM file data (base64 or raw) — single instance. May also be an array for batch processing. |
instances | json | No | Array 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
| Name | Type | Required | Description |
|---|---|---|---|
result | json | No | De-identification result: decision (emit|escalate), fast_path, deid_data (base64, only when emitted), regenerated_uids, peak_bytes. Array mode returns result.instances[]. |
detection_record | json | No | Audit artifact (no PHI strings): masked-region geometry, classifications, confidences, detector/template/classifier versions, sampled frames, masked-area fraction, decision, escalation reasons. |
success | boolean | No | Whether the operation succeeded (a file routed to review still succeeds; check result.decision). |
crosswalk_tables | json | No | Array-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
| Setting | Name | Type | Required | Default | Allowed values | Description |
|---|---|---|---|---|---|---|
| Header De-id Method | mask_method | enum | No | remove | remove, replace, hash | How header PHI tags are de-identified |
Crosswalk
| Setting | Name | Type | Required | Default | Allowed values | Description |
|---|---|---|---|---|---|---|
| Concentrator Base URL (crosswalk) | concentrator_base_url | string | No | DICOMweb 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) | accession | string | No | Accession 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
| Setting | Name | Type | Required | Default | Allowed values | Description |
|---|---|---|---|---|---|---|
| Keep UIDs | keep_uids | boolean | No | false | Preserve study/series/SOP UIDs (otherwise regenerated deterministically) | |
| Mask Fill Value | fill_value | number | No | 0 | min 0; max 255 | Pixel value written over masked PHI regions (0 = black) |
| Verify With OCR | verify_with_layer2 | boolean | No | true | Run OCR even where a template matched, as a verification net | |
| Escalate Unknown Profile | escalate_on_unknown_profile | boolean | No | true | Escalate pixel-path files with no template and no OCR rather than emitting them | |
| Max Mask Fraction | max_mask_fraction | number | No | 0.5 | min 0; max 1 | If the mask covers more than this fraction of a frame, escalate (probable detector failure) |
| Sample Frames | sample_frames | number | No | 5 | min 1; max 64 | Max frames OCR-sampled on multi-frame objects (first/last/sparse interior); the PHI region union is applied to all frames |
| CGO Codecs Linked | cgo_codecs | boolean | No | false | JPEG2000/JPEG-LS decoders are compiled in (otherwise those syntaxes escalate) | |
| Compressed Output | compressed_output | boolean | No | false | For 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 Quality | jpeg_quality | number | No | 90 | min 1; max 100 | Re-encode quality (1-100) for masked frames when Compressed Output is on |
| VLM Recall-Net URL | vlm_verify_url | string | No | Optional on-device granite-docling endpoint for a recall-net (escalation-only). Empty = disabled. | ||
| VLM Model | vlm_model | string | No | granite-docling | Model name for the VLM recall-net |
Errors
| Code | Description |
|---|---|
DICOM_DATA_REQUIRED | dicom_data input is missing or empty |
INVALID_MASK_METHOD | mask_method is not remove, replace, or hash |
TRANSFER_SYNTAX_NOT_DECODABLE | Burned-in PHI suspected but the transfer syntax cannot be decoded (flagged for review) |
OCR_NOT_COMPILED | OCR 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..