Bounded redaction geometry helpers

FPdfRedaction provides conservative source inspection and geometry operations used by TPdf.SaveAsRedacted; the high-level method supplies the transaction, annotation processing, opaque overlays, content regeneration, sanitization, and resource pruning

The helpers mutate native objects in the caller's isolated transaction copy and raise EPdfRedactionGeometry on unsupported geometry or exhausted budgets; they do not perform a complete secure export by themselves

Public declarations

type
  EPdfRedactionGeometry = class(Exception);
  TPdfRedactionGeometryOptions = record
    MaxFormDepth, MaxObjects, MaxPathSegments, MaxFragments: Integer;
    MaxImagePixels, MaxGeometryOperations: Int64;
    CurveTolerance: Double;
    class function Default: TPdfRedactionGeometryOptions; static;
  end;
  TPdfRedactionGeometryReport = record
    ExpandedFormCount, ScannedChildCount, ClippedPathCount: Integer;
    FlattenedCurveCount, GeneratedPointCount, FragmentCount: Integer;
    MaskedImageCount: Integer;
    ScannedPixelCount, MaskedPixelCount, PixelIntersectionTestCount: Int64;
    GeometryOperationCount: Int64;
  end;

procedure ValidateDetailedRedactionSource(Source: TStream);
procedure ValidateDetailedRedactionText(PageObject: FPDF_PAGEOBJECT);
procedure ExpandRedactionForms(Page: FPDF_PAGE;
  const Options: TPdfRedactionGeometryOptions;
  var Report: TPdfRedactionGeometryReport);
procedure ClipRedactionPath(Page: FPDF_PAGE; PageObject: FPDF_PAGEOBJECT;
  ObjectIndex: Integer; const Redactions: array of FS_RECTF;
  const Options: TPdfRedactionGeometryOptions;
  var Report: TPdfRedactionGeometryReport);
procedure MaskRedactionImage(Document: FPDF_DOCUMENT; Page: FPDF_PAGE;
  PageObject: FPDF_PAGEOBJECT; ObjectIndex: Integer;
  const Redactions: array of FS_RECTF;
  const Options: TPdfRedactionGeometryOptions;
  var Report: TPdfRedactionGeometryReport);

Coordinates and supported geometry

All redaction rectangles and curve tolerances use PDF user-space points; path points are transformed to page space before clipping, and ObjectIndex is the original zero-based native page-object index used to preserve painting order

• ExpandRedactionForms recursively detaches text, path, and image children, composes nonsingular instance transforms and native clips, and inserts the expanded objects at the original Form position; a separate expansion of each shared instance avoids editing the original shared Form stream in place
• ClipRedactionPath requires a solid filled path with no stroke, flattens cubic segments with a bounded subdivision depth, subtracts rectangular cuts, and preserves winding or even-odd filling across retained contours
• Path cuts expand by CurveTolerance + 0.001 PDF points; the tolerance bounds curve approximation and can remove a small additional margin outside the requested rectangle
• MaskRedactionImage accepts nonsingular affine transforms including rotation, reflection, and skew, and supported decoded Gray, BGR, BGRx, or BGRA samples; it retains the decoded resolution and creates a fresh replacement image
• Every pixel whose transformed quadrilateral touches a redaction rectangle expanded by 0.001 PDF points has both its color and alpha bytes cleared; retained pixels keep their decoded color samples
• ValidateDetailedRedactionText requires normal filled text for partial retention; character mapping and fragment reconstruction remain the responsibility of the high-level method

Expansion and partial geometry reject transparency or blend states, unsupported child types, singular matrices, patterned fills, and complex or nonredundant clip paths; a supported redundant rectangular clip must contain the complete object bounds

Options and cumulative report

Option	Default	Meaning
MaxFormDepth	32	Nested Form expansion depth
MaxObjects	1000000	Page enumeration and cumulative expanded child limits
MaxPathSegments	262144	Input segments per path and cumulative generated path points
MaxFragments	1000000	Retained rectangle regions and cumulative replacement fragments
MaxImagePixels	16777216	Cumulative decoded image pixels processed
MaxGeometryOperations	67108864	Cumulative geometry and pixel intersection work
CurveTolerance	0.01	Cubic flattening tolerance in PDF points

Initialize options with TPdfRedactionGeometryOptions.Default and zero the report once before a transaction; keep the same report across helper calls so generated points, image pixels, fragments, and operation budgets accumulate

ExpandedFormCount and ScannedChildCount describe expansion; the visited count includes root Form instances as well as children; ClippedPathCount, FlattenedCurveCount, and GeneratedPointCount describe path work, including intermediate clipping points; MaskedImageCount, ScannedPixelCount, MaskedPixelCount, and PixelIntersectionTestCount describe image work

FragmentCount counts replacement objects rather than polygon contours or pixels, and GeometryOperationCount accumulates bounded helper work; a report left by an exception can describe partial work on the discarded transaction copy

Source inspection and export boundary

ValidateDetailedRedactionSource inspects active objects and decoded content before mutation; TPdf.SaveAsRedacted invokes it for every profile, including whole-object removal and the simpler partial profile

• Signed sources, Tagged PDF structure, /ActualText and /Alt replacement data, XFA, and optional-content semantics including /OCProperties, /OCG, and /OCMD are rejected
• Image masks, soft masks, transfer functions, halftone and overprint states, inline images, text clipping or an unknown Tr operand, and scn/SCN pattern or special-color-space paint are rejected
• Inspected content streams must be unfiltered or have a single named /FlateDecode filter; decoding is limited to 32 MiB per content stream and 64 MiB total
• The active-object reader uses its default source, object-body, object-stream expansion, and object-count budgets; changing geometry options does not bypass these independent inspection limits

The current profile does not rebuild Tagged PDF structure, preserve arbitrary transparency, support arbitrary strokes or clipping, or promise lossless encoded-image preservation; secure output requires removal of original streams and unused resources after regeneration, as performed by TPdf.SaveAsRedacted

Direct callers must provide an isolated document copy, validate native capabilities and finite positive budgets, discard the copy on failure, regenerate modified page content, and complete sanitization and resource pruning before exporting

See Also

TPdf.SaveAsRedacted, TPdf.SaveAsSanitised, FPdfCompress