SaveAsRedacted - TPdf - PDFium Delphi Component

Component: TPdf · Unit: PDFium

Applies PDF redaction annotations to an isolated snapshot and writes a clean single-revision result without modifying the loaded document

Syntax

function SaveAsRedacted(Stream: TStream;
const Options: TPdfRedactionOptions;
out Report: TPdfRedactionReport): Boolean; overload;

function SaveAsRedacted(const FileName: string;
const Options: TPdfRedactionOptions;
out Report: TPdfRedactionReport): Boolean; overload;

Description

SaveAsRedacted captures the current document into an isolated random-access snapshot, opens that snapshot as a separate TPdf, and processes every /Redact annotation rectangle

Defaults enable PreservePartialObjects and PreserveComplexObjects together to keep supported safe geometry; this resource-limited profile reconstructs retained text fragments, clips solid-filled paths and clears intersecting affine-image pixels

If there is any redaction annotation, the detailed profile expands every Form XObject instance on all pages, including unredacted ones, before applying cuts; composed instance transforms allow the original shared Form streams to be pruned afterwards

Set PreservePartialObjects := False to remove entire intersecting objects, or leave it enabled and use PreserveComplexObjects := False for simpler text, axis-aligned rectangle and axis-aligned image fragmentation; all three profiles run the source safety checks

The method removes redaction annotations, optionally removes other intersecting annotations, drops file-attachment annotations on redacted pages and deletes native embedded attachments; the sanitised rewrite strips catalog /AF, active content, forms, metadata and unreachable objects

After page content is regenerated, precise resource pruning scans page, Form XObject, pattern, appearance, inherited and nested resource scopes and removes only unused names before unreachable objects are discarded

Output contains one clean revision without earlier revisions, and the loaded source stays as it was; unsupported source semantics or detailed geometry abort the operation instead of yielding partial redaction

Options

FillColor — the opaque replacement colour, initially clBlack
RemoveIntersectingAnnotations — removes non-redaction annotations whose rectangles overlap a redaction rectangle, default True
MaxPageObjects — maximum number of top-level page objects scanned across redacted pages, default 1000000
PreservePartialObjects — retains supported non-intersecting text, path and image fragments, default True
MaxSplitObjects — maximum number of safe fragments created across the operation, default 1000000
PreserveComplexObjects — with PreservePartialObjects enabled, allows limited Form expansion, solid-fill path clipping and affine-image pixel clearing; defaults to True
MaxFormDepth — deepest nested Form expansion, initially 32, accepting 1..64
MaxPathPoints — allowance for segments in each affected path and total generated path points, initially 262144, accepting 1..1000000
MaxImagePixels — total decoded pixels handled by detailed image replacement, initially 16777216, accepting 1..67108864
MaxGeometryOperations — accumulated detailed work, including annotation/text scans, path subdivision and clipping, and pixel intersections, initially 67108864, accepting 1..1000000000
CurveTolerancePdfPoints — page-space cubic-flattening tolerance, initially 0.01, accepting finite 0.0001..0.1; cuts expand by this tolerance plus 0.001 PDF points, which may remove a narrow extra safe margin

The detailed profile validates and uses the Form, path, image, geometry and tolerance settings above; none raises the separate source-inspection allowances

Report

TPdfRedactionReport returns RedactionCount, RedactedPageCount, ScannedObjectCount, RemovedObjectCount, RemovedAnnotationCount, RemovedAttachmentCount, OverlayCount, SplitTextObjectCount, SplitPathObjectCount, SplitImageObjectCount, PreservedFragmentCount, the byte counts, nested SanitiseReport and ResourcePruneReport, Succeeded, and ErrorMessage

Detailed processing adds ExpandedFormCount, ScannedFormChildCount, FlattenedCurveCount, GeneratedPathPointCount, MaskedImageCount, ScannedImagePixelCount, MaskedImagePixelCount, PixelIntersectionTestCount and GeometryOperationCount; successful processing records the chosen tolerance in CurveTolerancePdfPoints

ScannedFormChildCount includes every native object visited during expansion, including root Form instances; GeneratedPathPointCount includes intermediate clipping points and flattened-curve points alike

MaskedImagePixelCount counts pixels cleared in every colour and alpha sample; PreservedFragmentCount counts replacement objects rather than pixels or contours, and failed processing may leave partial counters without committed output

Security boundary

Text splitting requires reproducible Unicode mappings for every retained character; a mapping failure aborts the operation instead of emitting ambiguous text
Detailed paths must have a solid fill and no stroke; line and cubic segments retain their winding or even-odd rule, with curves approximated to the page-space tolerance and surviving contours in the same fill operation
Detailed image handling needs a nonsingular affine matrix and a supported decoded Gray, BGR, BGRx or BGRA bitmap; rotation, reflection and skew are allowed, and each shared instance gets a newly created replacement image
When a transformed pixel quadrilateral touches a rectangle expanded by 0.001 PDF points, RGB and alpha are both cleared; an opaque FillColor overlay then covers the redaction rectangle
Detailed expansion and affected partial objects refuse transparency, groups, blending and complex or nonredundant clips; an accepted redundant rectangular clip must enclose the object's full bounds
Completely covered bounds can be removed outright; unsupported partially retained geometry aborts detailed processing, whereas simpler fragmentation removes unsupported intersecting objects in full
All profiles refuse signed input, Tagged PDF structure, /ActualText or /Alt replacement data, XFA and optional-content layer semantics, including /OCProperties, /OCG and /OCMD; logical structure is not rebuilt and those hidden semantics are not retained
Source checks also refuse image/soft masks, transfer functions, halftone or overprint states, inline images, text clipping, unknown Tr operands and scn/SCN pattern or special-colour-space painting; checked streams must be unfiltered or have one named /FlateDecode filter
Source inspection permits 256 MiB of source data, 64 MiB per active body, 256 MiB of active bodies, 64 MiB per decoded object stream and 256 MiB of them altogether, and 1000000 object slots; checked-content decoding separately allows 32 MiB per stream and 64 MiB overall
Invalid geometry, missing native functions, unsupported source semantics and exhausted allowances preserve destination bytes and position, or any existing destination file; failures during commitment to a supplied stream still depend on that stream's own I/O behaviour
Catalogue /AF, the /Names tree, native embedded attachments and file-attachment annotations on redacted pages are removed; arbitrary associated-file entries nested in unrelated structure dictionaries are outside this method's explicit guarantee
Even with no /Redact annotations, calling the method produces sanitised single-revision security output
Signed input is refused before any redaction output is written

Example

var
  Options: TPdfRedactionOptions;
  Report: TPdfRedactionReport;
begin
  Options := TPdfRedactionOptions.Default;
  Options.FillColor := clBlack;
  if not Pdf1.SaveAsRedacted('C:\redacted.pdf', Options, Report) then
    raise Exception.Create(Report.ErrorMessage);
end;

SaveAsRedacted method