Due PDF prodotti dallo stesso generatore di report dagli stessi dati, a una corsa di distanza, raramente combaciano byte per byte. Un diff binario accende la cross-reference table, i numeri degli oggetti e spesso i programmi dei font, mentre entrambi i file stampano esattamente le stesse pagine. Confrontare i pixel renderizzati sembra la cura, finché qualcuno non aggiunge una copertina: da quel momento ogni pagina sta una posizione dopo la sua controparte, e un controllo pixel per pagina riporta l'intero documento come modificato. Un confronto che vale la pena automatizzare deve rispondere a due domande diverse, cosa è cambiato dentro il file e se un lettore lo vedrebbe, e deve sapere quale pagina di un file corrisponde a quale pagina dell'altro
Perché due PDF dall'aspetto identico differiscono byte per byte?
La maggior parte del fruscio di byte viene da contabilità che un lettore non vede mai. I numeri degli oggetti vengono distribuiti nell'ordine in cui lo scrittore capita di emettere gli oggetti. Molti generatori costruiscono i subset dei font nell'ordine in cui i glifi vengono usati la prima volta, così un attraversamento leggermente diverso produce codici glifo diversi, e quindi byte di content stream diversi, per lo stesso testo visibile. Gli offset della cross-reference si spostano ogni volta che qualcosa più indietro nel file cambia lunghezza, il che è quasi sempre
Quindi i numeri degli oggetti sono inutili come identità attraverso due file. THPDFDocComparison in HotPDF nomina ogni oggetto con il percorso che lo raggiunge per primo in un attraversamento in ampiezza dal catalogo del documento. Le chiavi dei dizionari vengono visitate in ordine di byte e gli elementi degli array per indice, il che rende il percorso deterministico: una risorsa font sulla prima pagina finisce tipicamente come qualcosa tipo $Catalog/Pages/Kids[0]/Resources/Font/F1 in entrambi i file, qualunque numero di oggetto gli abbia dato ciascun generatore. I byte insoliti in una chiave vengono escaped come #xx, e un percorso più lungo di MaxPathBytes viene troncato e completato con un hash del percorso intero, così due percorsi lunghi che condividono un prefisso restano distinti
Ogni oggetto riceve poi una firma SHA-256 sul proprio contenuto. Un riferimento indiretto contribuisce solo al fatto che un riferimento sta lì, mai al numero di oggetto a cui punta, e la destinazione viene messa in coda per essere firmata da sola. Rinumerare ogni oggetto in un file non produce quindi alcuna differenza. E quando cambia un dizionario di font, il report nomina il percorso di quel font come objectChanged invece di segnalare la pagina, il dizionario risorse e l'albero di pagine sopra di lui. Un oggetto la cui firma combacia ma il cui percorso si è mosso (una pagina spostata su un ramo diverso dell'albero di pagine, diciamo) appare come objectMoved; gli altri sono objectInserted o objectDeleted
Gli oggetti che nessun percorso dal catalogo raggiunge vengono comunque firmati, sotto un percorso sintetico tipo $Unreachable[42:0] che porta il numero di oggetto e di generazione. Il contenuto orfano è una differenza reale tra due file anche se nessun viewer lo mostrerà mai. I dati degli stream vengono hashati in chunk da 64 KB direttamente dallo stream, e la posizione dello stream viene rimessa a posto dopo, quindi confrontare due file grandi non significa tenere in memoria una copia di ogni stream
Allineare le pagine quando un documento si guadagna una copertina
Accoppiare pagina 1 con pagina 1 e pagina 2 con pagina 2 è corretto solo fino a quando non viene inserito qualcosa. Con una nuova copertina davanti, l'accoppiamento posizionale riporta ogni pagina come modificata, il che è tecnicamente vero e non dice al revisore niente
Ogni modalità che ispeziona le pagine le allinea prima. Ogni pagina riceve una firma dal proprio testo estratto; le pagine senza testo estraibile ripiegano su una firma del dizionario di pagina più il proprio content stream. Le pagine le cui firme combaciano esattamente vengono accoppiate, e il confronto prende poi la più lunga sottosequenza crescente di quelle coppie, ordinata per la loro posizione nel secondo file. Le coppie dentro quella sottosequenza si sono solo spostate insieme a un inserimento o una cancellazione. Le coppie fuori da essa sono state davvero riordinate e vengono riportate come pageMoved. Ciò che non ha combaciato affatto viene accoppiato in ordine come pageChanged, e qualsiasi surplus diventa pageInserted o pageDeleted. Per un manuale di 400 pagine con una nuova copertina, le voci a livello pagina scendono a un solo pageInserted dove l'accoppiamento posizionale avrebbe prodotto 400 modifiche. Il passaggio sugli oggetti lavora per percorso, quindi gli oggetti pagina spostati tipicamente appaiono comunque lì come objectMoved, e filtrare sul campo type li separa dalle modifiche vere
Le coppie allineate ricevono un controllo ulteriore nelle modalità strutturali. Il dizionario di pagina viene firmato una seconda volta senza /Contents, /Resources e /Parent, e se quella firma differisce la coppia viene riportata come pageChanged con dettaglio page metadata changed. Questo becca una pagina il cui testo è identico ma la cui /MediaBox o /Rotate si è mossa, una modifica che il solo allineamento testuale accopperebbe e lascerebbe passare
Eseguire un confronto strutturale e leggere il verdetto
Un confronto prende due istanze THotPDF caricate e una modalità, e restituisce un report JSON come AnsiString. cmStructural esegue il percorso su oggetti e pagine, cmRenderedImage esegue il passaggio sui pixel, cmFull esegue entrambi, e cmPageCount, cmPageText e cmObjectCount sono controlli più leggeri per gli smoke test. Compare usa i limiti e le opzioni di default; CompareWithLimits e CompareWithOptions prendono i vostri
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;
Il report porta tre fatti di primo livello che un singolo booleano confonderebbe insieme. identical è vero solo quando nessuna differenza è stata registrata e il confronto è finito. comparisonComplete dice se è finito. differencesTruncated dice se la lista è stata tagliata, mentre differenceCount conserva il totale vero e reportedDifferenceCount il numero effettivamente elencato. Quando un attraversamento colpisce un limite, una voce comparisonBudget nell'array differences dice se è stato troncato il percorso delle pagine o quello degli oggetti
Varie cose portano comparisonComplete a false: un attraversamento di pagine o oggetti troncato, un riferimento indiretto che non si risolve in uno dei file, più differenze di quante MaxDifferences ne consenta, una pagina la cui struttura (o, in cmPageText, il cui testo) non poteva essere letta, e un passaggio sui pixel incompleto. Ognuna di queste forza anche identical a false; l'API non riporta uguaglianza da un percorso fermato presto. Una gate CI deve quindi distinguere i due tipi di fallimento:
uses
SysUtils, HPDFJobJSON;
// Restituisce True solo per un confronto concluso senza differenze;
// stampa la ragione altrimenti. La gate in sé è codice vostro
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;
Trattate «incompleto» come un esito di build a sé. Un job che lo mappa su «diverso» manda gli ingegneri a caccia di una regressione che in realtà è un input malformato o un limite impostato troppo basso, e un job che lo mappa su «uguale» lascia passare un percorso troncato fino a una release
Che cosa tiene il percorso entro i limiti su file che non avete prodotto voi?
THPDFStructuralCompareLimits.Default è dimensionato per documenti reali: 250.000 oggetti, 2.000.000 di riferimenti seguiti, 250.000 pagine, profondità di annidamento 128, 10.000 differenze elencate, 64 MB letti da ogni singolo stream e 512 MB da tutti gli stream insieme, 1 MB per valore stringa o nome, 4.096 byte per percorso, e un tetto di 16 MB sul report serializzato. Un campo zero o negativo ripiega sul proprio default, quindi un record riempito a metà non diventa mai uno illimitato. Il record porta inoltre un CancellationToken e un evento Checkpoint che il confronto controlla tra unità di lavoro, incluso mentre le pagine renderizzano
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; // tiene corta la lista; differenceCount conta comunque tutto
Limits.MaxTotalStreamBytes := 128 * 1024 * 1024;
Limits.CancellationToken := Token; // un altro thread può chiamare Token.Cancel
Options := THPDFRenderedCompareOptions.Default;
Options.DPI := 150; // il default è 72
Options.ColorSpace := rccLuminance; // confronta la luminosità, ignora gli spostamenti di sola tinta
Options.ColorTolerance := 2; // i delta di 1-2 livelli non sono contati
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 := ''; // cancellato: non c'è alcun report
end;
end;
La cancellazione solleva EHPDFOperationCancelled fuori dalla chiamata invece di restituire un report parziale. Un confronto cancellato non ha alcun report da consegnare, e l'eccezione è il modo in cui l'API lo dice. Le opzioni di render ricevono la stessa normalizzazione dei limiti. La DPI viene serrata a 2.400, ColorTolerance a 0–255, TileSize a 8–1.024, e una soglia di similarità o rapporto fuori da 0–1 (o NaN) torna in silenzio al default
Il passaggio sui pixel stima la dimensione della bitmap di ogni pagina dalle dimensioni della pagina e dalla DPI richiesta prima di renderizzare qualsiasi cosa, e ricontrolla la bitmap reale contro MaxPixelsPerPage dopo, così una pagina con geometria assurda non può scivolare oltre la stima. Il costo cresce con il quadrato della DPI. Per un documento di pagine US Letter, 612 per 792 punti, alla DPI predefinita di 72 ogni coppia di pagine costa circa 0,97 milioni di pixel, e il default MaxTotalPixels di 500 milioni copre più di 500 coppie. A 300 DPI una singola coppia è di circa 16,8 milioni di pixel, e il budget si esaurisce dopo 29 coppie. Il passaggio registra allora una voce renderBudget, marca quella pagina budgetExceeded e si ferma, lasciando renderComparisonComplete false
Quanto simile è abbastanza simile?
Con le opzioni di default il passaggio sui pixel esige una corrispondenza esatta: ColorTolerance 0, MinimumSimilarity 1.0 e MaxChangedPixelRatio 0. Restare severi per default tiene esplicita la decisione di allentare: qualcuno deve scriverla, e una pipeline dovrebbe rilassare le soglie solo dopo aver visto che aspetto ha il rumore di anti-aliasing nei propri render
Per pixel, il delta in modalità rccRGB è la differenza maggiore tra i canali rosso, verde e blu; in modalità rccLuminance è la differenza di luminanza Rec. 709. Un pixel conta come modificato quando il suo delta supera ColorTolerance. La cifra di similarità è un punteggio di similarità strutturale (SSIM) calcolato sulla luminanza dell'intera pagina in una volta. Una coppia è similar solo quando il rapporto di pixel modificati è pari o sotto MaxChangedPixelRatio e la similarità è pari o sopra MinimumSimilarity. Due filtri, perché qualche centinaio di pixel malissimi in un barcode e una tinta leggera su tutta la pagina sono fallimenti diversi, e ogni workflow li tollera diversamente. I controlli delle soglie usano valori non arrotondati; le sei posizioni decimali nel JSON tengono i report stabili da corsa a corsa
I pixel modificati vengono raggruppati in regioni su una griglia di tile fissi, 64 pixel di lato per default, unite attraverso i quattro vicini di bordo. Ogni regione in changedRegions dà la propria bounding box, il proprio conteggio di pixel modificati e il proprio delta massimo. Al massimo MaxChangedRegions (256 per default) vengono elencate; changedRegionCount riporta comunque il numero vero, e quando la lista è tagliata changedRegionsTruncated è impostato e il passaggio sui pixel conta come incompleto. Con GenerateHeatmaps attivo, ogni pagina che ha pixel modificati riceve un PNG chiamato tipo page-000003-diff.png in HeatmapDirectory: la pagina del primo file con i pixel modificati tinti dal giallo (appena sopra la tolleranza) al rosso (delta massimo), e il suo percorso appare nel report come overlayPath
I fallimenti vengono riportati, mai assorbiti. Un'eccezione del renderer, una bitmap mancante o una dimensione di pagina invalida diventa una voce renderError con il messaggio, la voce della pagina prende stato error, e renderComparisonComplete va false. Due render con dimensioni in pixel diverse prendono stato sizeMismatch e una differenza renderedImageSize che elenca entrambe le dimensioni. Una pagina che nessuno è riuscito a confrontare non viene mai contata come identica
Dove sta ogni modalità in una pipeline
Il passaggio sui pixel accoppia le pagine rigorosamente per indice, pagina i contro pagina i, fino al documento più corto. L'allineamento delle pagine gira in ogni modalità tranne cmPageCount e cmRenderedImage. Con una copertina inserita, il solo cmRenderedImage segnala ogni pagina dopo di lei, e cmFull vi dà l'allineamento della sua metà strutturale accanto a quei risultati pixel posizionali. Leggete prima il verdetto strutturale, e fidatevi dei risultati pixel solo quando le liste delle pagine si allineano
Eseguite cmStructural su ogni build. È economico, nomina il percorso, l'indice di pagina e i numeri di oggetto coinvolti, e un objectChanged inatteso punta dritto al codice che l'ha prodotto. Tenete cmFull con heatmap per le release candidate e per controllare che un passaggio di ottimizzazione sia davvero stato lossless, quando c'è qualcuno attorno che guarda le sovrapposizioni. cmPageText sta bene ai documenti dove conta solo il testo. La revisione a livello di markup è un'altra opzione: esportare le pagine PDF in SVG dà una vista testuale che i normali strumenti di diff sanno leggere, e i controlli in l'automazione dei report di preflight coprono le domande di conformità che nessuna delle due modalità di confronto cerca di rispondere
Confronto, preflight e rendering lavorano tutti sullo stesso documento THotPDF caricato, quindi un solo caricamento può servire tutti e tre. Tutto ciò che il componente copre per gli sviluppatori Delphi e C++Builder è sulla pagina del componente HotPDF Delphi PDF