redactRegions

Redact rectangular regions of page (rectangles in page user space).

This is true redaction: text whose box intersects a region has its bytes REMOVED from the content stream (so it can't be extracted or recovered), surviving text keeps its position, intersecting images are dropped from the page, and an opaque black box is painted over each region. It does not merely paint over still-present content.

Calls compose: redacting a second region does not undo the first, and a stamp or content edit staged earlier is redacted along with the original page content. The black box from an earlier call is repainted along with the new one even when the two regions overlap, so a later call cannot uncover part of an earlier redaction (see redactedRegionsByPage).

Conservative by design. A run touching a region is removed wholesale, so partial overlaps over-remove. Content inside referenced form XObjects IS recursed into (redacted in the form's own coordinate space); a dropped image's XObject entry is pruned from /Resources /XObject so saveRewritten's reachability GC drops the image stream; and annotations whose /Rect intersects a region are removed from the page /Annots.

A removed widget takes its form field with it. A widget annotation is usually the field dictionary too (ISO 32000-1, 12.7.3.3), so it is also detached from /AcroForm /Fields and /CO (12.7.2), or from its parent field's /Kids when it is one of several. Otherwise the field's /V, /DV, /T and appearance stream stay reachable from the catalog and survive the rewrite. A field that still has a widget outside every region keeps that widget and its place in the form.

An annotation removed from the page keeps nothing. Reachability is not the only thing keeping redacted content out of the rewrite, so the object itself is emptied: text (/Contents, /RC), appearance (/AP), attached file (/FS), sound, movie, and the actions and appearance characteristics that reach the rest (/A, /AA, /MK) all go, and a detached field loses its value, its appearance state and its names on top of that. A structure this editor does not rewrite (an /XFA payload, a tagged document's /StructTreeRoot) then cannot ship the content by keeping the object alive. One thing this does not reach: an embedded file the catalog's /Names /EmbeddedFiles tree names as well stays in the document, since that copy of it is not on the page.

The page may come out with more XObjects than it went in with. One form XObject can be drawn in several places (ISO 32000-1, 8.10), and each place sees the region in a different part of the form. One rewritten stream cannot be right for all of them, so each place that needs a different redaction gets its OWN copy of the form, /Resources /XObject gains a generated name for it (the original name plus R1, R2, ...), and that one Do is repointed. Places that no region touches are left alone and keep drawing the original.

A vector path in a region is removed, not covered. A signature or a chart drawn as line art IS its coordinates, so the path's construction operators go with its painting operator, and the pen's width counts towards the ink a stroke lays down (ISO 32000-1, 8.4.3.2). A stroke inside a form XObject that sets no w or M of its own is judged by the invoking stream's, the same way PageRenderer draws it (8.10.2): the form does not restart the pen at the 1.0/10.0 defaults. One exception (RedactionEngine): a path that also sets a clip (W) keeps its coordinates and loses only its paint, because everything up to the matching Q is clipped by it (8.5.4) and dropping it would let all of that paint over the rest of the page.