Semantic comparison of annotations and forms

ComparePdfSemantics checks annotation and AcroForm widget properties separately from rendering; a form value can differ whilst its appearance pixels remain identical

Supply the alignment's TPdfDiffPagePairs or your own mapping; nil pairs positions, whereas an explicit mapping must cover each document exactly once, with -1 for an absent side

An annotation is identified by its /NM name and a form widget by its fully qualified field name; these identities apply within the mapped page and item kind

Absent or repeated names produce psckAmbiguous with a reason, including multiple widgets for a field on one page; annotation-array position is not an identity

The supported profile checks strings, flags, colours, opacity, borders, markup, line/vertex/ink geometry, URI actions, field values, choice labels and selections, and checkbox or radio states

Enable CompareAppearanceStreams to compare annotation appearance content as well; the option is off by default

Choose item kinds with CompareAnnotations and CompareForms; the default GeometryTolerance is 0.001 PDF user-space points

Added, removed and altered items carry properties and bounds from both sides; BuildSemanticDiffOverlays supplies separate before/after rectangles with page and change indexes

Indexes start at zero and bounds stay in PDF user space measured in points; apply page rotation, crop and viewport transformations before drawing to a bitmap

Independent native page handles keep the caller's page selection and form focus unchanged and avoid invoking form actions

Non-widget fields, arbitrary custom dictionaries, embedded files, script actions and non-URI destinations are outside this profile; XFA comparison is refused explicitly

Defaults allow 10,000 page pairs, 4,096 scanned items, 4,096 changes, 1 MiB per string, 16 MiB of strings altogether and 16,777,216 comparisons; an exhausted allowance refuses incomplete output

Complete separates a completed comparison from a refused one; even completed results can contain explicitly ambiguous identities, so consult AmbiguousCount before relying on item matches

Real Delphi/FPC Win32/Win64 acceptance runs cover 92 assertions per target, including saved/reopened input, values changed without pixel changes, Unicode identities, moved pages, ambiguity and resource limits

Options := TPdfSemanticDiffOptions.Default;
if not ComparePdfSemantics(BeforePdf, AfterPdf, PagePairs, Options, Report) then
  raise EPdfError.Create(Report.ErrorMessage);
Overlays := BuildSemanticDiffOverlays(Report);

Public declarations

type
  TPdfSemanticItemKind = (psikAnnotation, psikFormWidget);
  TPdfSemanticChangeKind = (psckAdded, psckRemoved, psckChanged, psckAmbiguous);
  TPdfSemanticSide = (pssBefore, pssAfter);
  TPdfSemanticProperty = record
    Name: string;
    Value: WideString;
  end;
  TPdfSemanticProperties = array of TPdfSemanticProperty;
  TPdfSemanticItem = record
    Kind: TPdfSemanticItemKind;
    Identity: WideString;
    PageIndex, AnnotationIndex: Integer;
    HasBounds: Boolean;
    Bounds: TPdfRectangle;
    Properties: TPdfSemanticProperties;
  end;
  TPdfSemanticPropertyChange = record
    Name: string;
    HasBefore, HasAfter: Boolean;
    BeforeValue, AfterValue: WideString;
  end;
  TPdfSemanticPropertyChanges = array of TPdfSemanticPropertyChange;
  TPdfSemanticChange = record
    Kind: TPdfSemanticChangeKind;
    ItemKind: TPdfSemanticItemKind;
    Identity: WideString;
    HasBefore, HasAfter: Boolean;
    BeforeItem, AfterItem: TPdfSemanticItem;
    Properties: TPdfSemanticPropertyChanges;
    AmbiguityReason: string;
  end;
  TPdfSemanticChanges = array of TPdfSemanticChange;
  TPdfSemanticOverlay = record
    Side: TPdfSemanticSide;
    PageIndex, ChangeIndex: Integer;
    Kind: TPdfSemanticChangeKind;
    Bounds: TPdfRectangle;
  end;
  TPdfSemanticOverlays = array of TPdfSemanticOverlay;
  TPdfSemanticDiffOptions = record
    CompareAnnotations, CompareForms, CompareAppearanceStreams: Boolean;
    GeometryTolerance: Double;
    MaxPagePairs, MaxItems, MaxChanges, MaxStringBytes: Integer;
    MaxTotalStringBytes, MaxComparisons: Int64;
    class function Default: TPdfSemanticDiffOptions; static;
  end;
  TPdfSemanticDiffReport = record
    Complete: Boolean;
    Changes: TPdfSemanticChanges;
    AddedCount, RemovedCount, ChangedCount, AmbiguousCount: Integer;
    ComparedItemCount: Integer;
    ErrorMessage: string;
  end;

// Indices are zero based. Nil PagePairs selects positional pairing. Explicit
// pairs must cover both documents exactly once; -1 denotes an absent side
// Identity is scoped to a mapped page and item kind. Missing names and repeated
// names (including repeated widgets of one field) are reported as ambiguous
// No rendering, focus changes, form actions, or positional identity guessing
// are performed. Pages are opened independently of the caller's current page
// The supported profile covers strings, flags, colors, opacity, borders,
// markup/line/vertex/ink geometry, URI actions, field values/options/checks,
// and optionally appearance streams. Arbitrary dictionaries, embedded files,
// script actions, non-URI destinations, and non-widget fields are not compared
function ComparePdfSemantics(BeforePdf, AfterPdf: TPdf;
  const PagePairs: TPdfDiffPagePairs; const Options: TPdfSemanticDiffOptions;
  out Report: TPdfSemanticDiffReport): Boolean;

// Bounds remain in PDF user space, in points. Transform with the destination
// page's rotation/crop/viewport rather than treating them as bitmap pixels
function BuildSemanticDiffOverlays(const Report: TPdfSemanticDiffReport):
  TPdfSemanticOverlays;