Technischer Artikel

Zwei PDF-Dateien in Delphi vergleichen: Struktur und Pixel

Zwei PDFs, vom selben Reportgenerator aus denselben Daten erzeugt, einen Lauf auseinander, matchen selten Byte für Byte. Ein binärer Diff leuchtet die Kreuzreferenz-Tabelle an, die Objektnummern und oft die Font-Programme, während beide Dateien exakt dieselben Seiten drucken. Gerenderte Pixel zu vergleichen sieht nach der Heilung aus, bis jemand ein Deckblatt ergänzt: Von da an sitzt jede Seite eine Position später als ihr Gegenstück, und eine seitenweise Pixel-Prüfung meldet das ganze Dokument als geändert. Ein Vergleich, den man automatisieren will, muss zwei verschiedene Fragen beantworten, was sich innerhalb der Datei geändert hat und ob ein Leser es sehen würde, und er muss wissen, welche Seite in der einen Datei welcher Seite in der anderen entspricht

Warum unterscheiden sich zwei gleich aussehende PDFs Byte für Byte?

Der Großteil des Byte-Rauschens kommt aus Buchhaltung, die ein Leser nie sieht. Objektnummern werden vergeben, in welcher Reihenfolge der Writer gerade Objekte ausgibt. Viele Generatoren bauen Font-Subsets in der Reihenfolge, in der Glyphen zuerst verwendet werden, also produziert ein leicht anderer Durchlauf andere Glyphen-Codes und damit andere Content-Stream-Bytes für denselben sichtbaren Text. Kreuzreferenz-Offsets verschieben sich, wann immer etwas Früheres in der Datei die Länge ändert, was fast immer der Fall ist

Diagramm: HotPDF führt einen strukturellen Objektgraph-Durchlauf und einen gerenderten Pixel-Durchlauf über zwei PDF-Dateien in einen JSON-Vergleichsreport
Beide Durchläufe bleiben innerhalb expliziter Grenzen, und der JSON-Bericht paart identical mit comparisonComplete und comparisonBudget, sodass Automatisierung einen abgebrochenen Durchlauf nie für einen echten Unterschied hält

Objektnummern sind also als Identität über zwei Dateien hinweg unbrauchbar. THPDFDocComparison in HotPDF benennt jedes Objekt über den Pfad, der es zuerst erreicht, in einem Breitensuch-Durchlauf ab dem Dokumentkatalog. Dictionary-Schlüssel werden in Byte-Reihenfolge besucht, Array-Elemente nach Index, was den Durchlauf deterministisch macht: Eine Font-Ressource auf der ersten Seite landet typischerweise als etwas wie $Catalog/Pages/Kids[0]/Resources/Font/F1 in beiden Dateien, egal welche Objektnummer jeder Generator ihr gegeben hat. Ungewöhnliche Bytes in einem Schlüssel werden als #xx escaped, und ein Pfad länger als MaxPathBytes wird abgeschnitten und mit einem Hash des vollen Pfades abgeschlossen, sodass zwei lange Pfade mit gemeinsamem Präfix trotzdem unterscheidbar bleiben

Jedes Objekt bekommt dann eine SHA-256-Signatur über seinen eigenen Inhalt. Eine indirekte Referenz trägt nur die Tatsache bei, dass dort eine Referenz sitzt, nie die Objektnummer, auf die sie zeigt, und das Ziel wird eingereiht, um separat signiert zu werden. Alle Objekte einer Datei umzunummerieren produziert also überhaupt keine Unterschiede. Und wenn sich ein Font-Dictionary ändert, benennt der Report den Pfad dieses Fonts als objectChanged, statt die Seite, das Ressourcen-Dictionary und den Seitenbaum darüber anzumarkieren. Ein Objekt, dessen Signatur matcht, dessen Pfad sich aber verschoben hat (etwa eine Seite, die an einen anderen Zweig des Seitenbaums gerückt ist), erscheint als objectMoved; der Rest ist objectInserted oder objectDeleted

Objekte, die kein Pfad vom Katalog erreicht, werden trotzdem signiert, unter einem synthetischen Pfad wie $Unreachable[42:0], der Objekt- und Generationsnummer trägt. Verwaister Inhalt ist eine echte Differenz zwischen zwei Dateien, auch wenn ihn kein Viewer je anzeigt. Stream-Daten werden in 64-KB-Chunks direkt aus dem Stream gehasht, und die Stream-Position wird danach zurückgesetzt, also bedeutet der Vergleich zweier großer Dateien nicht, eine Kopie jedes Streams im Speicher zu halten

Seiten ausrichten, wenn ein Dokument ein Deckblatt dazubekommt

Seite 1 mit Seite 1 und Seite 2 mit Seite 2 zu paaren ist nur solange korrekt, bis etwas eingefügt wird. Mit einem neuen Deckblatt vorne meldet die Positionspaarung jede Seite als geändert, was technisch stimmt und dem Reviewer nichts sagt

Jeder Modus, der Seiten ansieht, richtet sie zuerst aus. Jede Seite bekommt eine Signatur aus ihrem extrahierten Text; Seiten ohne extrahierbaren Text fallen auf eine Signatur aus Seiten-Dictionary plus Content-Stream zurück. Seiten, deren Signaturen exakt matchen, werden gepaart, und der Vergleich bildet dann die längste aufsteigende Teilfolge dieser Paare, geordnet nach ihrer Position in der zweiten Datei. Paare innerhalb dieser Teilfolge haben sich lediglich mit einer Einfügung oder Löschung verschoben. Paare außerhalb wurden wirklich umgeordnet und werden als pageMoved gemeldet. Was überhaupt nicht matchte, wird der Reihe nach als pageChanged gepaart, und jeder Überschuss wird pageInserted oder pageDeleted. Für ein 400-Seiten-Handbuch mit einem neuen Deckblatt läuft die Seitenebene auf ein einziges pageInserted hinaus, wo die Positionspaarung 400 Änderungen produziert hätte. Der Objekt-Durchlauf arbeitet über Pfade, also erscheinen die verschobenen Seitenobjekte dort typischerweise weiterhin als objectMoved, und ein Filter auf dem type-Feld trennt sie von echten Bearbeitungen

Diagramm: naive Position-für-Position-PDF-Seitenpaarung gegenüber HotPDF-Signaturalignment mit einer längsten aufsteigenden Teilsequenz
Die signaturbasierte Ausrichtung gleicht die verschobenen Originalseiten ab und isoliert das eingefügte Deckblatt; aus Hunderten Falsch-Positiven wird eine lesbare Zeile

Ausgerichtete Paare bekommen in den strukturellen Modi noch eine Prüfung. Das Seiten-Dictionary wird ein zweites Mal ohne /Contents, /Resources und /Parent signiert, und weicht diese Signatur ab, wird das Paar als pageChanged mit dem Detail page metadata changed gemeldet. Das erwischt eine Seite, deren Text identisch ist, deren /MediaBox oder /Rotate sich aber verschoben hat — eine Änderung, die die textbasierte Ausrichtung allein durchwinken würde

Einen strukturellen Vergleich fahren und das Urteil lesen

Ein Vergleich nimmt zwei geladene THotPDF-Instanzen und einen Modus und liefert einen JSON-Report als AnsiString. cmStructural fährt den Objekt- und Seitendurchlauf, cmRenderedImage den Pixel-Durchlauf, cmFull beide, und cmPageCount, cmPageText und cmObjectCount sind leichtere Prüfungen für Smoke-Tests. Compare verwendet die Default-Limits und -Optionen; CompareWithLimits und CompareWithOptions nehmen Ihre eigenen

uses
  Classes, SysUtils, HPDFDoc, HPDFDocCompare;

function CompareFiles(const BaselineFile, CandidateFile: string): AnsiString;
var
  DocA, DocB: THotPDF;
begin
  Result := '';
  DocA := THotPDF.Create(nil);
  DocB := THotPDF.Create(nil);
  try
    if (DocA.LoadFromFile(BaselineFile) <= 0) or
       (DocB.LoadFromFile(CandidateFile) <= 0) then
      raise Exception.Create('Could not load one of the files');
    Result := THPDFDocComparison.Compare(DocA, DocB, cmStructural);
    with TFileStream.Create('diff.json', fmCreate) do
    try
      if Result <> '' then
        WriteBuffer(Result[1], Length(Result));
    finally
      Free;
    end;
  finally
    DocB.Free;
    DocA.Free;
  end;
end;

Der Report trägt drei Tatsachen auf oberster Ebene, die ein einzelnes Boolean vermischen würde. identical ist nur wahr, wenn kein Unterschied aufgezeichnet wurde und der Vergleich abgeschlossen ist. comparisonComplete sagt, ob er abgeschlossen ist. differencesTruncated sagt, ob die Liste abgeschnitten wurde, während differenceCount die wahre Gesamtzahl hält und reportedDifferenceCount die tatsächlich gelistete. Trifft ein Durchlauf auf ein Limit, sagt ein comparisonBudget-Eintrag im differences-Array, ob der Seitendurchlauf oder der Objektdurchlauf abgeschnitten wurde

Mehreres setzt comparisonComplete auf false: ein abgeschnittener Seiten- oder Objektdurchlauf, eine indirekte Referenz, die in einer der Dateien nicht auflöst, mehr Unterschiede als MaxDifferences erlaubt, eine Seite, deren Struktur (oder, in cmPageText, deren Text) sich nicht lesen ließ, und ein unvollständiger Pixel-Durchlauf. Jedes davon erzwingt auch identical auf false; die API meldet keine Gleichheit aus einem Durchlauf, der früh aufhörte. Ein CI-Gate muss die beiden Arten des Scheiterns also auseinanderhalten:

uses
  SysUtils, HPDFJobJSON;

// Liefert True nur für einen abgeschlossenen Vergleich ohne Unterschiede;
// gibt sonst den Grund aus. Das Gate selbst ist Ihr Code
function DiffGatePasses(const Report: AnsiString): Boolean;
var
  Parser: THPDFJSONParser;
  Root, Diffs, Item: THPDFJSONValue;
  I: Integer;
begin
  Parser := THPDFJSONParser.Create(Report);
  try
    Root := Parser.Parse;
  finally
    Parser.Free;
  end;
  try
    Result := Root.GetBool('identical');
    if Result then
      Exit;
    if not Root.GetBool('comparisonComplete') then
      Writeln('INCOMPLETE: a limit or unreadable input stopped the comparison');
    Writeln(Format('%d difference(s), %d listed',
      [Root.GetInt('differenceCount'), Root.GetInt('reportedDifferenceCount')]));
    Diffs := Root.GetArr('differences');
    if Diffs <> nil then
      for I := 0 to Diffs.ItemCount - 1 do
      begin
        Item := Diffs.Item(I);
        Writeln(Item.GetStr('type'), '  ', Item.GetStr('detail'), '  ',
          Item.GetStr('pathA'), ' -> ', Item.GetStr('pathB'));
      end;
  finally
    Root.Free;
  end;
end;

Behandeln Sie „unvollständig“ als eigenes Build-Ergebnis. Ein Job, der es auf „unterschiedlich“ mappt, schickt Ingenieure auf die Jagd nach einer Regression, die in Wahrheit eine fehlerhafte Eingabe oder ein zu niedrig gesetztes Limit ist, und ein Job, der es auf „gleich“ mappt, lässt einen abgeschnittenen Durchlauf ein Release passieren

Was den Durchlauf auf Dateien, die Sie nicht erzeugt haben, in Schranken hält

THPDFStructuralCompareLimits.Default ist für reale Dokumente bemessen: 250.000 Objekte, 2.000.000 gefolgte Referenzen, 250.000 Seiten, Verschachtelungstiefe 128, 10.000 gelistete Unterschiede, 64 MB aus jedem einzelnen Stream und 512 MB aus allen Streams zusammen, 1 MB pro String- oder Name-Wert, 4.096 Bytes pro Pfad und ein 16-MB-Deckel für den serialisierten Report. Ein Feld mit null oder negativem Wert fällt auf seinen Default zurück, also wird ein teilgefüllter Record nie zu einem unbegrenzten. Der Record trägt außerdem ein CancellationToken und ein Checkpoint-Ereignis, die der Vergleich zwischen Arbeitseinheiten prüft, auch während Seiten rendern

uses
  SysUtils, HPDFDoc, HPDFDocCompare, HPDFTypes;

function CompareForRelease(DocA, DocB: THotPDF;
  Token: THPDFCancellationToken): AnsiString;
var
  Limits: THPDFStructuralCompareLimits;
  Options: THPDFRenderedCompareOptions;
begin
  Limits := THPDFStructuralCompareLimits.Default;
  Limits.MaxDifferences := 200;              // hält die Liste kurz; differenceCount zählt weiterhin alles
  Limits.MaxTotalStreamBytes := 128 * 1024 * 1024;
  Limits.CancellationToken := Token;         // ein anderer Thread darf Token.Cancel aufrufen

  Options := THPDFRenderedCompareOptions.Default;
  Options.DPI := 150;                        // Default ist 72
  Options.ColorSpace := rccLuminance;        // Helligkeit vergleichen, rein farbtonbedingte Verschiebungen ignorieren
  Options.ColorTolerance := 2;               // Deltas von 1-2 Stufen zählen nicht
  Options.MinimumSimilarity := 0.9995;
  Options.MaxChangedPixelRatio := 0.0005;
  Options.GenerateHeatmaps := True;
  Options.HeatmapDirectory := 'diff-overlays';

  try
    Result := THPDFDocComparison.CompareWithOptions(DocA, DocB, cmFull,
      Limits, Options);
  except
    on EHPDFOperationCancelled do
      Result := '';                          // abgebrochen: es gibt keinen Report
  end;
end;

Ein Abbruch wirft eine EHPDFOperationCancelled aus dem Aufruf heraus, statt einen Teil-Report zurückzugeben. Ein abgebrochener Vergleich hat keinen Report, den er zurückgeben könnte, und die Exception ist die Art, wie die API das sagt. Render-Optionen bekommen dieselbe Normalisierung wie Limits. DPI wird bei 2.400 geklemmt, ColorTolerance auf 0–255, TileSize auf 8–1.024, und ein Ähnlichkeits- oder Ratio-Schwellwert außerhalb von 0–1 (oder NaN) kehrt still zum Default zurück

Der Pixel-Durchlauf schätzt die Bitmap-Größe jeder Seite aus ihren Seitendimensionen und der angeforderten DPI, bevor er irgendetwas rendert, und prüft die echte Bitmap danach erneut gegen MaxPixelsPerPage, also kann eine Seite mit Unsinn-Geometrie nicht an der Schätzung vorbeischlüpfen. Die Kosten wachsen mit dem Quadrat der DPI. Für ein Dokument aus US-Letter-Seiten, 612 mal 792 Punkte, kostet jedes Seitenpaar bei den Default-72-DPI etwa 0,97 Millionen Pixel, und das Default-MaxTotalPixels von 500 Millionen deckt mehr als 500 Paare. Bei 300 DPI kostet ein einzelnes Paar etwa 16,8 Millionen Pixel, und das Budget ist nach 29 Paaren aufgebraucht. Der Durchlauf zeichnet dann einen renderBudget-Eintrag auf, markiert diese Seite als budgetExceeded und stoppt, und lässt renderComparisonComplete auf false

Wie ähnlich ist ähnlich genug?

Mit Default-Optionen verlangt der Pixel-Durchlauf exakte Übereinstimmung: ColorTolerance 0, MinimumSimilarity 1.0 und MaxChangedPixelRatio 0. Standardmäßig streng zu bleiben hält die Lockermachungs-Entscheidung explizit: Irgendjemand muss sie niederschreiben, und eine Pipeline sollte die Schwellwerte erst lockern, nachdem sie gesehen hat, wie Anti-Aliasing-Rauschen in ihren eigenen Renders aussieht

Pro Pixel ist das Delta im rccRGB-Modus die größte Differenz unter den Rot-, Grün- und Blau-Kanälen; im rccLuminance-Modus ist es die Differenz in Rec.-709-Luminanz. Ein Pixel zählt als geändert, wenn sein Delta ColorTolerance übersteigt. Die Ähnlichkeitszahl ist ein Structural-Similarity-Score (SSIM), berechnet über die Luminanz der ganzen Seite auf einmal. Ein Paar gilt nur als similar, wenn der Geänderte-Pixel-Anteil bei oder unter MaxChangedPixelRatio liegt und die Ähnlichkeit bei oder über MinimumSimilarity. Zwei Tore, denn ein paar hundert grob falsche Pixel in einem Barcode und ein schwacher Farbton über die ganze Seite sind verschiedene Fehler, und jeder Workflow verträgt sie anders. Die Schwellwert-Prüfungen verwenden ungerundete Werte; die sechs Dezimalstellen im JSON halten Reports von Lauf zu Lauf stabil

Diagramm der zwei Ähnlichkeitsschwellen im HotPDF-Rendervergleich mit Farbtoleranz, geändertem Pixelanteil und Mindestähnlichkeit
Ein Paar ist nur ähnlich, wenn verändertes Pixelverhältnis und Ähnlichkeit beide Schwellen gemeinsam überschreiten, und ein fehlgeschlagenes Rendering wird vermerkt, statt stillschweigend identisch genannt zu werden

Geänderte Pixel werden zu Regionen auf einem Raster aus festen Kacheln gruppiert, standardmäßig 64 Pixel im Quadrat, verbunden über ihre vier Kanten-Nachbarn. Jede Region in changedRegions gibt ihre Begrenzungsbox, ihre Anzahl geänderter Pixel und ihr größtes Delta an. Höchstens MaxChangedRegions (standardmäßig 256) werden gelistet; changedRegionCount meldet weiterhin die wahre Anzahl, und wenn die Liste abgeschnitten wurde, ist changedRegionsTruncated gesetzt und der Pixel-Durchlauf zählt als unvollständig. Mit GenerateHeatmaps bekommt jede Seite mit geänderten Pixeln ein PNG mit Namen wie page-000003-diff.png in HeatmapDirectory: die Seite aus der ersten Datei, mit geänderten Pixeln getönt von Gelb (kaum über der Toleranz) bis Rot (maximales Delta), und ihr Pfad erscheint im Report als overlayPath

Fehler werden gemeldet, nie geschluckt. Eine Renderer-Exception, eine fehlende Bitmap oder eine ungültige Seitengröße wird ein renderError-Eintrag mit der Meldung, der Seiteneintrag bekommt den Status error, und renderComparisonComplete geht auf false. Zwei Renders mit verschiedenen Pixel-Dimensionen bekommen den Status sizeMismatch und eine renderedImageSize-Differenz, die beide Größen listet. Eine Seite, die niemand zu vergleichen schaffte, zählt nie als identisch

Wo gehört welcher Modus in eine Pipeline?

Der Pixel-Durchlauf paart Seiten streng nach Index, Seite i gegen Seite i, bis zum kürzeren Dokument. Die Seitenausrichtung läuft in jedem Modus außer cmPageCount und cmRenderedImage. Mit eingefügtem Deckblatt markiert cmRenderedImage allein jede Seite danach, und cmFull liefert Ihnen die Ausrichtung aus seiner strukturellen Hälfte neben diesen positionalen Pixel-Ergebnissen. Lesen Sie das strukturelle Urteil zuerst, und vertrauen Sie den Pixel-Ergebnissen erst, wenn die Seitenlisten sich decken

Fahren Sie cmStructural bei jedem Build. Es ist billig, es benennt Pfad, Seitenindex und Objektnummern, und ein unerwartetes objectChanged zeigt direkt auf den Code, der es produziert hat. Halten Sie cmFull mit Heatmaps für Release-Kandidaten und dafür bereit, zu prüfen, dass ein Optimierungsdurchlauf wirklich verlustfrei war, wenn jemand da ist, der auf die Overlays schaut. cmPageText eignet sich für Dokumente, bei denen nur der Wortlaut zählt. Markup-Level-Review ist eine weitere Option: PDF-Seiten nach SVG exportieren liefert eine Textansicht, die gewöhnliche Diff-Werkzeuge lesen können, und die Prüfungen in Preflight-Report-Automatisierung decken Konformitätsfragen ab, die kein Vergleichsmodus beantworten will

Vergleich, Preflight und Rendering arbeiten alle auf demselben geladenen THotPDF-Dokument, also kann ein einziges Laden alle drei bedienen. Alles, was die Komponente für Delphi- und C++Builder-Entwickler abdeckt, steht auf der HotPDF-Delphi-PDF-Komponentenseite