Dos PDF producidos por el mismo generador de reportes desde los mismos datos, a una corrida de distancia, rara vez coinciden byte a byte. Un diff binario enciende la tabla de referencias cruzadas, los números de objeto y muchas veces los programas de fuentes, mientras ambos archivos imprimen exactamente las mismas páginas. Comparar píxeles renderizados parece la cura hasta que alguien agrega una carátula: desde ese momento, cada página queda una posición más tarde que su contraparte, y un chequeo de píxeles página por página reporta todo el documento como cambiado. Una comparación que vale la pena automatizar tiene que responder dos preguntas distintas, qué cambió dentro del archivo y si un lector lo vería, y tiene que saber qué página de un archivo corresponde a qué página del otro
¿Por qué pueden dos PDF ser distintos en bytes pero visualmente idénticos?
La mayor parte del churn de bytes viene de contabilidad que un lector nunca ve. Los números de objeto se reparten en el orden que al writer le toque emitir objetos. Muchos generadores construyen subsets de fuentes en el orden en que los glifos se usan por primera vez, así que un recorrido levemente distinto produce códigos de glifo distintos, y por lo tanto bytes de content stream distintos, para el mismo texto visible. Los offsets de la tabla de referencias cruzadas se mueven cada vez que algo anterior en el archivo cambia de largo, que es casi siempre
Así que los números de objeto son inútiles como identidad entre dos archivos. THPDFDocComparison en HotPDF nombra cada objeto por la ruta que lo alcanza primero en un recorrido breadth-first desde el catálogo del documento. Las claves de diccionario se visitan en orden de bytes y los elementos de array por índice, lo que hace determinista el recorrido: un recurso de fuente de la primera página típicamente termina como algo como $Catalog/Pages/Kids[0]/Resources/Font/F1 en ambos archivos, sin importar qué número de objeto le dio cada generador. Los bytes inusuales en una clave se escapan como #xx, y una ruta más larga que MaxPathBytes se corta y se termina con un hash de la ruta completa, así que dos rutas largas que comparten prefijo siguen siendo distintas
Cada objeto recibe después una firma SHA-256 sobre su propio contenido. Una referencia indirecta aporta solo el hecho de que ahí hay una referencia, nunca el número de objeto al que apunta, y el destino se pone en cola para firmarse por su cuenta. Renumerar todos los objetos de un archivo no produce entonces ninguna diferencia. Y cuando un diccionario de fuente cambia, el reporte nombra la ruta de esa fuente como objectChanged en lugar de marcar la página, el diccionario de recursos y el árbol de páginas de arriba. Un objeto cuya firma coincide pero cuya ruta se movió (una página corrida a otra rama del árbol de páginas, digamos) aparece como objectMoved; el resto son objectInserted o objectDeleted
Los objetos que ninguna ruta desde el catálogo alcanza igual se firman, bajo una ruta sintética como $Unreachable[42:0] que lleva el número de objeto y de generación. El contenido huérfano es una diferencia real entre dos archivos aunque ningún visor lo vaya a mostrar nunca. La data de streams se hashea en chunks de 64 KB directo del stream, y la posición del stream se devuelve después, así que comparar dos archivos grandes no significa sostener una copia de cada stream en memoria
Alinear páginas cuando un documento gana una portada
Emparejar la página 1 con la página 1 y la página 2 con la página 2 es correcto solo hasta que algo se inserta. Con una portada nueva al frente, el emparejamiento posicional reporta cada página como cambiada, lo que es técnicamente cierto y no le dice nada al revisor
Todo modo que inspecciona páginas las alinea primero. Cada página recibe una firma desde su texto extraído; las páginas sin texto extraíble recurren a una firma del diccionario de página más su content stream. Las páginas cuyas firmas coinciden exactamente se emparejan, y la comparación toma entonces la subsecuencia creciente más larga de esos pares, ordenados por su posición en el segundo archivo. Los pares dentro de esa subsecuencia solo se corrieron junto con una inserción o borrado. Los pares fuera de ella realmente se reordenaron y se reportan como pageMoved. Lo que no coincidió para nada se empareja en orden como pageChanged, y cualquier sobrante se vuelve pageInserted o pageDeleted. Para un manual de 400 páginas con una carátula nueva, las entradas a nivel de página quedan en un solo pageInserted donde el emparejamiento posicional habría producido 400 cambios. La pasada de objetos trabaja por ruta, así que los objetos de página corridos típicamente aparecen ahí igual como objectMoved, y filtrar por el campo type los separa de las ediciones reales
Los pares alineados reciben un chequeo más en los modos estructurales. El diccionario de página se firma una segunda vez sin /Contents, /Resources ni /Parent, y si esa firma difiere el par se reporta como pageChanged con el detalle page metadata changed. Eso caza una página cuyo texto es idéntico pero cuyo /MediaBox o /Rotate se movió, un cambio que la alineación por texto sola emparejaría y dejaría pasar
Correr una comparación estructural y leer el veredicto
Una comparación toma dos instancias de THotPDF cargadas y un modo, y devuelve un reporte JSON como AnsiString. cmStructural corre el recorrido de objetos y páginas, cmRenderedImage corre la pasada de píxeles, cmFull corre ambas, y cmPageCount, cmPageText y cmObjectCount son chequeos más livianos para tests de humo. Compare usa los límites y opciones por defecto; CompareWithLimits y CompareWithOptions toman los suyos
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;
El reporte carga tres hechos de primer nivel que un solo booleano mezclaría. identical es verdadero solo cuando no se registró ninguna diferencia y la comparación terminó. comparisonComplete dice si terminó. differencesTruncated dice si el listado se cortó, mientras que differenceCount conserva el total verdadero y reportedDifferenceCount la cantidad realmente listada. Cuando un recorrido pega con un límite, una entrada comparisonBudget en el array differences dice si se truncó el recorrido de páginas o el de objetos
Varias cosas ponen comparisonComplete en falso: un recorrido de páginas u objetos truncado, una referencia indirecta que no se resuelve en uno de los archivos, más diferencias de las que MaxDifferences permite, una página cuya estructura (o, en cmPageText, cuyo texto) no se pudo leer, y una pasada de píxeles incompleta. Todas fuerzan también identical a falso; la API no reporta igualdad desde un recorrido que se detuvo temprano. Un gate de CI tiene entonces que distinguir los dos tipos de fallo:
uses
SysUtils, HPDFJobJSON;
// Devuelve True solo para una comparación terminada sin diferencias;
// imprime la razón en otro caso. El gate mismo es código suyo
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;
Trate «incompleto» como un desenlace de build propio. Un job que lo mapea a «distinto» manda a los ingenieros a cazar una regresión que en realidad es una entrada malformada o un límite puesto muy bajo, y un job que lo mapea a «igual» deja que un recorrido truncado pase un release
¿Qué mantiene acotado el recorrido con archivos que usted no produjo?
THPDFStructuralCompareLimits.Default está dimensionado para documentos del mundo real: 250,000 objetos, 2,000,000 de referencias seguidas, 250,000 páginas, profundidad de anidamiento 128, 10,000 diferencias listadas, 64 MB leídos de cualquier stream individual y 512 MB de todos los streams juntos, 1 MB por valor de string o name, 4,096 bytes por ruta, y un techo de 16 MB para el reporte serializado. Un campo en cero o negativo cae a su default, así que un record lleno a medias nunca se vuelve uno sin límites. El record además lleva un CancellationToken y un evento Checkpoint que la comparación chequea entre unidades de trabajo, incluso mientras las páginas renderizan
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; // mantiene el listado corto; differenceCount igual cuenta todos
Limits.MaxTotalStreamBytes := 128 * 1024 * 1024;
Limits.CancellationToken := Token; // otro hilo puede llamar Token.Cancel
Options := THPDFRenderedCompareOptions.Default;
Options.DPI := 150; // el default es 72
Options.ColorSpace := rccLuminance; // compare brillo, ignore cambios de solo tinte
Options.ColorTolerance := 2; // los deltas de 1-2 niveles no se cuentan
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 := ''; // cancelado: no hay reporte
end;
end;
La cancelación lanza un EHPDFOperationCancelled fuera de la llamada en lugar de devolver un reporte parcial. Una comparación cancelada no tiene reporte que entregar, y la excepción es como la API lo dice. Las opciones de render reciben la misma normalización que los límites. El DPI se recorta a 2,400, ColorTolerance a 0–255, TileSize a 8–1,024, y un umbral de similitud o proporción fuera de 0–1 (o NaN) revierte en silencio al default
La pasada de píxeles estima el tamaño del bitmap de cada página desde sus dimensiones y el DPI pedido antes de renderizar nada, y chequea el bitmap real contra MaxPixelsPerPage otra vez después, así que una página con geometría bogusa no puede colarse pasado la estimación. El costo crece con el cuadrado del DPI. Para un documento de páginas US Letter, 612 por 792 puntos, al 72 DPI por defecto cada par de páginas cuesta unos 0.97 millones de píxeles, y el MaxTotalPixels por defecto de 500 millones cubre más de 500 pares. A 300 DPI un solo par son unos 16.8 millones de píxeles, y el presupuesto se agota después de 29 pares. La pasada registra entonces una entrada renderBudget, marca esa página budgetExceeded y se detiene, dejando renderComparisonComplete en falso
¿Qué tan similar es lo bastante similar?
Con las opciones por defecto la pasada de píxeles exige una coincidencia exacta: ColorTolerance 0, MinimumSimilarity 1.0 y MaxChangedPixelRatio 0. Mantenerse estricto por defecto mantiene explícita la decisión de aflojar: alguien tiene que escribirla, y un pipeline debería relajar los umbrales solo después de haber visto cómo se ve el ruido de anti-aliasing en sus propios renders
Por píxel, el delta en modo rccRGB es la mayor diferencia entre los canales rojo, verde y azul; en modo rccLuminance es la diferencia de luminancia Rec. 709. Un píxel cuenta como cambiado cuando su delta excede ColorTolerance. La cifra de similitud es un puntaje de similitud estructural (SSIM) calculado sobre la luminancia de la página entera de una vez. Un par es similar solo cuando la proporción de píxeles cambiados está en o por debajo de MaxChangedPixelRatio y la similitud está en o por encima de MinimumSimilarity. Dos gateos, porque unos pocos cientos de píxeles muy equivocados en un barcode y un tinte leve a lo largo de la página entera son fallos distintos, y cada flujo de trabajo los tolera distinto. Los chequeos de umbral usan valores sin redondear; los seis decimales del JSON mantienen los reportes estables de corrida a corrida
Los píxeles cambiados se agrupan en regiones sobre una grilla de tiles de tamaño fijo, de 64 píxeles por lado por defecto, unidos por sus cuatro vecinos de borde. Cada región en changedRegions da su bounding box, su conteo de píxeles cambiados y su delta mayor. A lo sumo se listan MaxChangedRegions (256 por defecto); changedRegionCount igual reporta el número verdadero, y cuando el listado se corta se activa changedRegionsTruncated y la pasada de píxeles cuenta como incompleta. Con GenerateHeatmaps activado, cada página con píxeles cambiados recibe un PNG nombrado como page-000003-diff.png en HeatmapDirectory: la página del primer archivo con los píxeles cambiados teñidos de amarillo (apenas sobre la tolerancia) a rojo (delta máximo), y su ruta aparece en el reporte como overlayPath
Los fallos se reportan, nunca se absorben. Una excepción de renderer, un bitmap ausente o un tamaño de página inválido se vuelve una entrada renderError con el mensaje, la entrada de página toma estado error, y renderComparisonComplete pasa a falso. Dos renders con dimensiones de píxeles distintas toman estado sizeMismatch y una diferencia renderedImageSize que lista ambos tamaños. Una página que nadie logró comparar nunca cuenta como idéntica
Dónde encaja cada modo en una canalización
La pasada de píxeles empareja páginas estrictamente por índice, página i contra página i, hasta el documento más corto. La alineación de páginas corre en todos los modos salvo cmPageCount y cmRenderedImage. Con una portada insertada, cmRenderedImage solo marca cada página posterior a ella, y cmFull le da la alineación de su mitad estructural junto a esos resultados posicionales de píxeles. Lea primero el veredicto estructural, y confíe en los resultados de píxeles solo cuando las listas de páginas se alinean
Corra cmStructural en cada build. Es barato, nombra la ruta, el índice de página y los números de objeto involucrados, y un objectChanged inesperado apunta derecho al código que lo produjo. Conserve cmFull con heatmaps para candidatos a release y para chequear que una pasada de optimización realmente fue sin pérdida, cuando hay alguien cerca para mirar los overlays. cmPageText le queda a los documentos donde solo importa la redacción. La revisión a nivel de markup es otra opción: exportar páginas PDF a SVG da una vista de texto que las herramientas de diff corrientes pueden leer, y los chequeos de automatización de informes de preflight cubren preguntas de conformidad que ninguno de los dos modos de comparación intenta responder
La comparación, el preflight y el renderizado trabajan todos sobre el mismo documento THotPDF cargado, así que una sola carga puede servir a los tres. Todo lo que el componente cubre para desarrolladores de Delphi y C++Builder está en la página del componente PDF de HotPDF para Delphi