Twee PDF's gemaakt door dezelfde rapportgenerator uit dezelfde data, één run uit elkaar, matchen zelden byte voor byte. Een binaire diff doet de kruisverwijzingstabel, de objectnummers en vaak de fontprogramma's oplichten, terwijl beide bestanden precies dezelfde pagina's printen. Gerenderde pixels vergelijken lijkt het middel totdat iemand een voorblad toevoegt: vanaf dat moment zit elke pagina één positie later dan zijn tegenhanger, en een pagina-voor-pagina-pixelcontrole meldt het hele document als veranderd. Een vergelijking die automatisering waard is, moet twee verschillende vragen beantwoorden, wat er binnenin het bestand veranderde en of een lezer het zou zien, en hij moet weten welke pagina in het ene bestand bij welke pagina in het andere hoort
Waarom verschillen twee identiek ogende PDF's byte voor byte?
Het grootste deel van de byte-opwinding komt uit administratie die een lezer nooit ziet. Objectnummers worden uitgedeeld in de volgorde waarin de schrijver toevallig objecten uitgeeft. Veel generators bouwen font-subsets in de volgorde waarin glyphs voor het eerst worden gebruikt, dus een net iets andere traversering levert andere glyphcodes op, en daarmee andere content-stream-bytes, voor dezelfde zichtbare tekst. Kruisverwijzingsoffsets schuiven zodra iets eerder in het bestand van lengte verandert, wat vrijwel altijd zo is
Objectnummers zijn dus nutteloos als identiteit over twee bestanden. THPDFDocComparison in HotPDF benoemt elk object naar het pad dat hem als eerste bereikt in een breedte-eerst-wandeling vanaf de documentcatalogus. Dictionary-sleutels worden in bytevolgorde bezocht en array-elementen op index, wat de wandeling deterministisch maakt: een fontresource op de eerste pagina belandt in beide bestanden typisch als zoiets als $Catalog/Pages/Kids[0]/Resources/Font/F1, welk objectnummer elke generator hem ook gaf. Ongebruikelijke bytes in een sleutel worden geëscaped als #xx, en een pad langer dan MaxPathBytes wordt ingekort en afgemaakt met een hash van het volledige pad, zodat twee lange paden die een prefix delen duidelijk van elkaar blijven
Elk object krijgt daarna een SHA-256-handtekening over zijn eigen inhoud. Een indirecte referentie levert alleen het feit dat daar een referentie zit, nooit het objectnummer waar hij naartoe wijst, en het doel wordt op zijn beurt aangemeld om ondertekend te worden. Elk object in een bestand hernummeren levert dus helemaal geen verschillen op. En wanneer één fontdictionary verandert, benoemt het rapport het pad van dat font als objectChanged in plaats van de pagina, de resourcedictionary en de paginaboom erboven te markeren. Een object waarvan de handtekening matcht maar wiens pad verschoof (een pagina die naar een andere tak van de paginaboom verhuisde, zeg) verschijnt als objectMoved; de rest zijn objectInserted of objectDeleted
Objecten die geen pad vanuit de catalogus bereikt, worden alsnog ondertekend, onder een synthetisch pad zoals $Unreachable[42:0] dat object- en generatienummer draagt. Weescontent is een echt verschil tussen twee bestanden, ook al toont geen enkele viewer hem ooit. Streamdata wordt in brokken van 64 KB rechtstreeks uit de stream gehasht, en de streampositie wordt daarna teruggezet, dus twee grote bestanden vergelijken betekent niet elke stream in het geheugen vasthouden
Pagina's uitlijnen als één document er een voorblad bij krijgt
Pagina 1 met pagina 1 koppelen en pagina 2 met pagina 2 klopt alleen totdat er iets wordt ingevoegd. Met een nieuw voorblad vooraan meldt positioneel koppelen elke pagina als veranderd, wat technisch waar is en de reviewer niets vertelt
Elke modus die pagina's bekijkt, lijnt ze eerst uit. Elke pagina krijgt een handtekening uit zijn geëxtraheerde tekst; pagina's zonder extraheerbare tekst vallen terug op een handtekening van de pagedictionary plus zijn content stream. Pagina's waarvan de handtekeningen exact matchen worden gekoppeld, en de vergelijking neemt dan de langste oplopende deelreeks van die paren, geordend op hun positie in het tweede bestand. Paren binnen die deelreeks zijn alleen mee verschoven bij een invoeging of verwijdering. Paren erbuiten zijn echt herschikt en worden gemeld als pageMoved. Wat helemaal niet matchte, wordt op volgorde gekoppeld als pageChanged, en elk overschot wordt pageInserted of pageDeleted. Voor een handleiding van 400 pagina's met één nieuw voorblad komen de pagina-level-entries uit op een enkele pageInserted, waar positioneel koppelen 400 veranderingen had opgeleverd. De objectpass werkt per pad, dus de verschoven paginaobjecten verschijnen daar typisch nog steeds als objectMoved, en filteren op het veld type scheidt ze van echte bewerkingen
Gekoppelde paren krijgen in de structurele modi nog één controle extra. De pagedictionary wordt een tweede keer ondertekend zonder /Contents, /Resources en /Parent, en wijkt die handtekening af, dan wordt het paar gemeld als pageChanged met detail page metadata changed. Dat vangt een pagina waarvan de tekst identiek is maar wiens /MediaBox of /Rotate verschoof, een verandering die tekstgebaseerde uitlijning alleen zou koppelen en doorgaan zou laten
Een structurele vergelijking draaien en het vonnis lezen
Een vergelijking neemt twee geladen THotPDF-instanties en een modus, en geeft een JSON-rapport terug als AnsiString. cmStructural draait de object- en paginawandeling, cmRenderedImage de pixelpass, cmFull allebei, en cmPageCount, cmPageText en cmObjectCount zijn lichtere controles voor rooktests. Compare gebruikt de standaardgrenzen en -opties; CompareWithLimits en CompareWithOptions nemen die van jou
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;
Het rapport draagt drie topfeiten die één boolean door elkaar zou halen. identical is alleen waar als er geen verschil is genoteerd en de vergelijking afrondde. comparisonComplete zegt of hij afrondde. differencesTruncated zegt of de lijst is ingekort, terwijl differenceCount het ware totaal vasthoudt en reportedDifferenceCount het aantal dat daadwerkelijk is opgesomd. Raakt een traversering een grens, dan zegt een comparisonBudget-entry in de array differences of de paginawandeling of de objectwandeling werd afgebroken
Meerdere dingen zetten comparisonComplete op false: een afgebroken pagina- of objecttraversering, een indirecte referentie die in één van de bestanden niet oplost, meer verschillen dan MaxDifferences toestaat, een pagina waarvan de structuur (of, in cmPageText, de tekst) niet kon worden gelezen, en een onvoltooide pixelpass. Elk ervan dwingt ook identical naar false; de API meldt geen gelijkheid vanuit een wandeling die vroeg stopte. Een CI-poort moet de twee soorten falen dus uit elkaar houden:
uses
SysUtils, HPDFJobJSON;
// Geeft True alleen voor een afgeronde vergelijking zonder verschillen;
// print anders de reden. De poort zelf is je eigen 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;
Behandel 'incomplete' als een eigen builduitkomst. Een job die hem op 'different' mapt, stuurt ingenieurs op jacht naar een regressie die in werkelijkheid een misvormde invoer of een te laag gezette grens is, en een job die hem op 'same' mapt laat een afgebroken wandeling een release passeren
Wat de wandeling begrensd houdt op bestanden die je niet zelf maakte?
THPDFStructuralCompareLimits.Default is gedimensioneerd op echte documenten: 250.000 objecten, 2.000.000 gevolgde referenties, 250.000 pagina's, nestdiepte 128, 10.000 opgesomde verschillen, 64 MB gelezen uit elke enkele stream en 512 MB uit alle streams samen, 1 MB per string- of naamwaarde, 4.096 bytes per pad en een plafon van 16 MB op het geserialiseerde rapport. Een veld op nul of negatief valt terug op zijn standaard, dus een half ingevuld record wordt nooit een onbeperkt record. Het record draagt ook een CancellationToken en een Checkpoint-event die de vergelijking tussen werkeenheden controleert, ook terwijl pagina's renderen
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; // houdt de lijst kort; differenceCount telt toch alles
Limits.MaxTotalStreamBytes := 128 * 1024 * 1024;
Limits.CancellationToken := Token; // een andere thread mag Token.Cancel aanroepen
Options := THPDFRenderedCompareOptions.Default;
Options.DPI := 150; // standaard is 72
Options.ColorSpace := rccLuminance; // vergelijk helderheid, negeer alleen-kleurtoeverschuivingen
Options.ColorTolerance := 2; // deltas van 1-2 niveaus tellen niet mee
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 := ''; // cancelled: there is no report
end;
end;
Annulering gooit een EHPDFOperationCancelled uit de aanroep in plaats van een partiëel rapport terug te geven. Een geannuleerde vergelijking heeft geen rapport om af te geven, en de exception is hoe de API dat zegt. Renderopties krijgen dezelfde normalisatie als grenzen. DPI wordt begrensd op 2.400, ColorTolerance op 0-255, TileSize op 8-1.024, en een gelijkenis- of ratio-drempel buiten 0-1 (of NaN) gaat stilletjes terug naar de standaard
De pixelpass schat de bitmapgrootte van elke pagina uit zijn paginafmetingen en de gevraagde DPI voordat er iets wordt gerenderd, en controleert de echte bitmap daarna opnieuw tegen MaxPixelsPerPage, zodat een pagina met verzonnen geometrie de schatting niet kan ontlopen. De kost groeit met het kwadraat van de DPI. Voor een document met US Letter-pagina's, 612 bij 792 points, kost elk paginapaar op de standaard 72 DPI zo'n 0,97 miljoen pixels, en de standaard MaxTotalPixels van 500 miljoen dekt ruim 500 paren. Op 300 DPI is een enkel paar zo'n 16,8 miljoen pixels, en het budget is na 29 paren op. De pass legt dan een renderBudget-entry vast, markeert die pagina als budgetExceeded en stopt, met renderComparisonComplete op false
Hoe gelijk is gelijk genoeg?
Met standaardopties eist de pixelpass een exacte match: ColorTolerance 0, MinimumSimilarity 1.0 en MaxChangedPixelRatio 0. Standaard streng blijven houdt de beslissing om te soepelen expliciet: iemand moet hem opschrijven, en een pijplijn zou de drempels pas moeten verlagen nadat hij heeft gezien hoe anti-aliasruis er in zijn eigen renders uitziet
Per pixel is de delta in rccRGB-modus het grootste verschil tussen de rode, groene en blauwe kanalen; in rccLuminance-modus is het het verschil in Rec. 709-luminantie. Een pixel geldt als veranderd zodra zijn delta ColorTolerance overstijgt. Het gelijkeniscijfer is een structural-similarity-score (SSIM) berekend over de luminantie van de hele pagina tegelijk. Een paar is pas similar als de veranderde-pixelratio op of onder MaxChangedPixelRatio zit en de gelijkenis op of boven MinimumSimilarity. Twee poorten, want een paar honderd helemaal verkeerde pixels in een barcode en een flauwe tint over de hele pagina zijn verschillende falen, en elke workflow tolereert ze anders. De drempelcontroles gebruiken onafgeronde waarden; de zes decimalen in de JSON houden rapporten van run tot run stabiel
Veranderde pixels worden op een raster van vaste tegels, standaard 64 pixels vierkant, tot regio's gegroepeerd die via hun vier randburen worden verbonden. Elke regio in changedRegions geeft zijn bounding box, zijn aantal veranderde pixels en zijn grootste delta. Hooguit MaxChangedRegions (standaard 256) worden opgesomd; changedRegionCount meldt nog steeds het ware aantal, en als de lijst is ingekort staat changedRegionsTruncated aan en telt de pixelpass als onvolledig. Met GenerateHeatmaps aan krijgt elke pagina met veranderde pixels een PNG met een naam als page-000003-diff.png in HeatmapDirectory: de pagina uit het eerste bestand met veranderde pixels getint van geel (net over de drempel) naar rood (maximale delta), en zijn pad staat in het rapport als overlayPath
Falen worden gemeld, nooit ingeslikt. Een renderer-exception, een ontbrekende bitmap of een ongeldig paginaformaat wordt een renderError-entry met de melding, de pagina-entry krijgt status error, en renderComparisonComplete gaat naar false. Twee renders met verschillende pixelformaten krijgen status sizeMismatch en een verschil renderedImageSize dat beide formaten noemt. Een pagina die niemand heeft kunnen vergelijken, telt nooit als identiek
Waar elke modus thuishoort in een pijplijn
De pixelpass koppelt pagina's strikt op index, pagina i tegen pagina i, tot aan het kortste document. Pagina-uitlijning draait in elke modus behalve cmPageCount en cmRenderedImage. Met een ingevoegd voorblad markeert cmRenderedImage alleen elke pagina erna, en cmFull geeft je de uitlijning uit zijn structurele helft naast die positionele pixelresultaten. Lees eerst het structurele vonnis, en vertrouw de pixelresultaten pas als de paginalijsten op een rij liggen
Draai cmStructural op elke build. Hij is goedkoop, hij benoemt het pad, de pagina-index en de objectnummers die ermee gemoeid zijn, en een onverwachte objectChanged wijst recht naar de code die hem produceerde. Houd cmFull met heatmaps voor releasekandidaten en om te controleren dat een optimalisatiepas echt verliesvrij was, terwijl iemand naar de overlays kijkt. cmPageText past bij documenten waar alleen de formulering telt. Review op markup-niveau is een andere optie: PDF-pagina's naar SVG exporteren geeft een tekstbeeld dat gewone diff-tools kunnen lezen, en de controles in preflight-rapportautomatisering dekken conformantievragen die geen van beide vergelijkingsmodi probeert te beantwoorden
Vergelijking, preflight en rendering werken allemaal op hetzelfde geladen THotPDF-document, dus één load kan alle drie dienen. Alles wat het component voor Delphi- en C++Builder-ontwikkelaars dekt, staat op de HotPDF Delphi PDF-componentpagina