Skip to content

Redacted PDF Rendering And Fidelity

OpenMed can turn projected PDF PHI rectangles into a clean, locally rendered PDF and produce enforceable, PHI-safe fidelity evidence. Install the optional PDF stack first:

pip install "openmed[multimodal]"

Render A Redacted PDF

For an in-memory service that already renders or OCRs pages, use render_redacted_raster_pages with RasterRedactionPage inputs. It takes no file paths and returns verified bytes, excluding all source text layers, metadata, annotations and attachments. PDF output requires explicit source page sizes in points; PNG accepts one page and does not invent physical resolution.

from openmed.multimodal import RasterRedactionPage, render_redacted_raster_pages

# rendered_image is a bounded Pillow image; the caller retains ownership.
# Rectangles use integer pixels, top-left origin and exclusive right/bottom edges.
page = RasterRedactionPage(
    image=rendered_image,
    regions=[(80, 100, 280, 140)],
    size_points=(595.2756, 841.8898),
)
export = render_redacted_raster_pages([page], output_format="pdf")
file_bytes = export.content  # Pass to a private response or atomic output writer.
safe_report = export.to_dict()  # Geometry/counts/hashes; never file bytes or PHI.

The memory exporter pads each rectangle by three pixels by default, burns black pixels, and verifies that every padded rectangle is black and all outside RGB pixels are unchanged. It reopens the encoded output to verify exact decoded pixel hashes and the restricted image-only object graph. PNG output contains only image chunks. Transparent source pixels are composited on white and input images are not mutated. PDF output has no searchable text layer.

Limits bound pages, total/per-page pixels, region count and encoded bytes during writing. Cancellation is checked between pages and encoding/verification steps; services should also enforce a native-process deadline. These checks verify selected pixels and encoding, not OCR completeness, detection accuracy or every PDF viewer's rendering. Compare output with the source in the intended workflow.

The path-based API below has a separate selectable-text and layout-fidelity contract.

render_redacted_pdf accepts the top-origin, 0-based page rectangles returned by project_text_spans:

from pathlib import Path

from openmed.multimodal import (
    extract_pdf,
    project_text_spans,
    render_redacted_pdf,
)

source = Path("synthetic-source.pdf")
output = Path("synthetic-redacted.pdf")
document = extract_pdf(source)

# These offsets normally come from an OpenMed PII detector.
start = document.text.index("SYNTHETIC_PATIENT")
end = start + len("SYNTHETIC_PATIENT")
rectangles = project_text_spans(document, [(start, end)])

result = render_redacted_pdf(source, output, rectangles)
assert result.passed
print(result.to_dict())

The destination is written atomically only after all verification gates pass. Existing destinations are protected unless overwrite=True is explicit.

Annotation Safety

Both PDF rasterizing redaction paths omit all annotation appearances by default. This includes FreeText, Stamp, Text and widget appearances: their pixels must not enter the output merely because ordinary page-text detection cannot see them. Annotation removal happens in memory without modifying the source or writing an intermediate source PDF. Default layout verification compares with that annotation-free source, so omitted appearances are not fidelity failures.

Owned multi-phase operations capture one immutable in-memory source before extraction, detection, mapping and rendering. Updating the input path or stream during a detector callback cannot switch the document that is rendered. A seekable caller-owned binary stream stays open, and its name is never opened as a replacement path. Caller-supplied document= values or regions calculated in a separate call must still be matched to the source by the caller.

result.to_dict()["annotations"] contains one entry per page with page, annotation_count, omitted_annotation_count, and a subtypes count mapping. Subtype names come from a closed vocabulary; other values become Other. Annotation contents, field names, appearance text and source paths never enter these annotation reports.

To explicitly inspect and keep supported text appearances, supply a local detector that returns character offsets into its input:

def annotation_detector(text):
    # Replace this synthetic example with your local PHI detector.
    marker = "SYNTHETIC_PATIENT"
    start = text.find(marker)
    return [] if start < 0 else [(start, start + len(marker))]

result = render_redacted_pdf(
    source,
    output,
    rectangles,
    annotation_detector=annotation_detector,
)

The detector sees both annotation Contents and the selected normal appearance text, which can disagree. Mapped visual words and PDF text-operation order are both provided when they differ, including rotated or mirrored text. Any detected span masks the entire annotation rectangle. Inspected appearances with no detected spans may remain as flattened page content; interactive annotation objects never survive. Internal fidelity checks use this inspected, flattened source in opt-in mode. The standalone measure_pdf_layout_fidelity helper uses an annotation-free source and should not be used to independently accept retained annotation appearances.

extract_pdf(source, include_annotations=True) exposes the same additional text and full-extent source spans without rendering. The document-ingestion path accepts policy={"include_annotations": True, "return_bytes": True} only with an injected detector. It preserves full annotation masks even when a table or caption also covers a detected span.

Opt-in processing fails closed with annotation_appearance_unmappable before writing output when an appearance has no reliable text/coordinate map. Unsupported cases include image or nested-form appearances, vector painting, Type 3 fonts, missing appearance states, invalid transforms, text outside its rectangle, clipped rectangles, shifted media origins and distinct crop boxes. These cases need a separately verified OCR/geometry workflow; they do not silently fall back to retaining unchecked pixels. Detector failures use annotation_detection_failed. Coordinate verification does not establish detector recall or clinical correctness. Each detector is invoked once after its call signature is checked. Results must be explicit span sequences (or supported entities/pii_entities/spans wrappers) with non-boolean integral offsets in range and a coordinate map for every span. Malformed results, callback failures and excessive result iteration fail closed. The verified renderer bounds detector results with max_regions; document ingestion accepts at most 10,000 detections in annotation opt-in mode.

What The Renderer Preserves

Each page is rendered locally at a fixed resolution, the requested rectangles plus a one-point glyph-overhang safety margin are burned into the pixels, and a new PDF is assembled at the original page size. This preserves visible non-redacted content, page order, pagination, and page geometry while severing the output from the source content streams.

An invisible clean text layer is rebuilt from extractable WinAnsi words that do not touch a redaction rectangle. This keeps common non-PHI text selectable and searchable without copying selected source words. Visible Unicode content is still preserved in the page raster; words that cannot be represented safely in the clean text-layer font are omitted from that optional layer rather than encoded incorrectly.

The output intentionally does not preserve interactive forms, annotations, embedded files, thumbnails, search indexes, or source metadata. If those are required, treat them as separate data that must be independently de-identified.

Mandatory Verification

Rendering runs three independent checks before publishing the output:

  1. verify_redacted_pdf confirms each rectangle has no selectable residual text and is covered by an opaque box.
  2. verify_redacted_text_removed accounts for every selected source-word occurrence across the complete output text layer. It detects partial, separated, reordered, split, merged, moved, and duplicated residual text while allowing unrelated identical words to remain. Use assert_redacted_text_removed for a raising helper.
  3. measure_pdf_layout_fidelity confirms page count and dimensions, then masks the requested rectangles and measures changed pixels everywhere else.
from openmed.multimodal import (
    assert_redacted_text_removed,
    measure_pdf_layout_fidelity,
)

assert_redacted_text_removed(source, output, rectangles)
layout = measure_pdf_layout_fidelity(source, output, rectangles, strict=True)
assert layout.pagination_preserved

The layout report records, per page, the compared non-redacted pixel count, changed-pixel count and fraction, normalized mean absolute error, page sizes, and pass/fail result. The default gate ignores channel differences of 4 or less and allows at most a 0.0005 changed-pixel fraction outside redaction regions. Pin the OpenMed lockfile and PDF stack when comparing reports across machines.

All report dictionaries omit input/output paths and plaintext. They contain only geometry, counts, thresholds, and SHA-256 digests. Caller-supplied entity labels are hashed before serialization, so reports can be attached to privacy audit evidence without copying identifiers.

Resource And Font Safety Limits

Raster work is bounded before page images are allocated. Defaults accept at most 100 pages, 40 million pixels on one page, 100 million pixels in total, and 10,000 redaction rectangles. Trusted local callers can lower or deliberately raise these limits with max_pages, max_page_pixels, max_total_pixels, and max_regions; the active pixel limits are recorded in the fidelity report.

Type 3 fonts are rejected before rendering because their character procedures can paint arbitrary content outside logical glyph bounds. Standard digital PDF fonts receive the one-point burn margin described above. A rejected source is never published as an output.

Security And Licensing Boundary

The implementation uses only the existing multimodal extra and never sends a document to a network service:

Component Role License
pdfplumber Word geometry, extraction, and local page rendering MIT
pypdfium2 / PDFium Local raster backend used by pdfplumber BSD-3-Clause / Apache-2.0
Pillow In-memory pixel redaction and comparison MIT-CMU
pikepdf / qpdf Fresh PDF assembly and deterministic serialization MPL-2.0 / Apache-2.0

No AGPL renderer is imported or bundled, and no GPL bridge is needed.

Scanned or image-only source PDFs are outside this API's text-removal proof: their redaction rectangles must come from the OCR pipeline, and residual text must be verified by re-OCR. PDF redaction is an assistive privacy control, not a diagnostic or clinical decision system.

Identifier-bearing barcodes and 2D codes

redact_image, redact_dicom_pixels, render_redacted_pdf and render_redacted_raster_pages scan each source frame/page for codes independently of OCR. PDF output through redact_document also scans each rasterized page and records source and residual coverage in the result metadata. Every located code is treated as an identifier-bearing redaction region, including a symbol with an unreadable payload. Code boxes join the existing OCR or caller-selected boxes; PDF pixel boxes are converted to page points before text exclusion and layout verification. Image-only code regions keep their measured zero source-word counts and set source_text_required: false; ordinary text regions still require measurable source text. Residual verification scans the redacted pixels again and rejects any remaining detectable code before writing output.

The issue's implementation surface is Python. OpenMedKit currently has no image, PDF or DICOM pixel-redaction API to extend; this change adds no cloud bridge or Apple Foundation Models fallback.

Local providers and availability policy

Pass code_detector and code_detection_policy as arguments to the image, DICOM and raster APIs, or as PDF redaction policy keys for redact_document. The policy defaults to "coverage_incomplete": a missing or failing detector produces an explicit coverage_incomplete: true in the code coverage report, rather than claiming codes were absent. Select "fail_closed" to reject unavailable detection before output publication. Malformed boxes and exhausted region limits always fail closed. A residual-pass outage follows the same policy and is recorded in its separate coverage report. Existing OCR/pixel clean or passed flags describe those checks; callers must inspect both code coverage reports for completeness. Disabling image/DICOM residual verification does not disable the source code scan.

The default adapter is ZXingCodeRegionDetector. Install its optional local backend separately; no dependency, weights, downloads or network transport are added to the core SDK:

pip install "zxing-cpp==2.3.0"

The ZXing Python binding and license are Apache-2.0. The adapter supports linear, QR and DataMatrix classes (other detected symbologies are still redacted). It requests located decoding failures as well as valid codes and never reads the backend's decoded text, bytes or error detail. This is detection support, not measured clinical qualification: distorted, partially hidden or unsupported codes can still be missed. Synthetic tests and generated sentinel codes do not establish real-world recall.

from openmed.multimodal import ZXingCodeRegionDetector, redact_image

result = redact_image(
    "synthetic-label.png",
    models=local_pii_models,
    code_detector=ZXingCodeRegionDetector(),
    code_detection_policy="fail_closed",
)
coverage = result.code_coverage.to_dict()
residual = result.residual_report.code_coverage.to_dict()

DICOM accepts these options directly or in DicomPixelRedactionPolicy. Code findings have null text and model-confidence fields, rather than invented text evidence or confidence scores. For redact_document image dispatch, inject models["code_detector"] and put "code_detection_policy" in the policy mapping alongside the output destination.

Provider and report contract

CodeRegionDetector.detect(image) receives an in-memory Pillow image or uint8 array and returns CodeRegion(symbology, bbox) values. Boxes use a top-left origin and exclusive right/bottom pixel edges. The caller assigns the zero-based page or frame index. Provider geometry must be finite, non-empty and within image bounds. FakeCodeRegionDetector returns fixed synthetic boxes for offline tests; use a pixel-aware fake or independent verification provider when testing residuals.

Reports expose only controlled symbology classes (linear, qr, datamatrix, other), counts, boxes and coverage status. If an injected provider returns a mapping with payload, text or bytes, the boundary reduces that value to an opaque SHA-256 digest in the in-memory region; neither the payload nor its digest is included in the coverage report. Backend exception messages are suppressed. Providers must themselves avoid logging decoded content. Code-free images keep the same encoded output bytes as the existing redaction path; metadata stripping and existing OCR redaction continue to apply. No source-byte identity is claimed for metadata-bearing or re-encoded source images.

Example safe report:

{"count": 1, "boxes": [{"symbology": "qr", "bbox": [10, 10, 60, 60], "page": 0}], "coverage_incomplete": false}

No regional coverage audit, mask-lineage implementation, autonomous clinical action or release qualification is added by this detector integration.

Annotation source and detector refusals use fixed diagnostics and discard underlying exception context, including document and provider error details.