Dos PDF producidos por el mismo generador de informes desde los mismos datos, a una ejecución de distancia, rara vez coinciden byte a byte. Un diff binario ilumina 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 añade una portada: desde ese momento, cada página se sienta una posición más tarde que su correspondiente, y una comprobación píxel a píxel página por página reporta el documento entero como cambiado. Una comparación que valga 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é dos PDF de aspecto idéntico difieren byte a byte?
La mayor parte del traqueteo de bytes viene de contabilidad que un lector jamás ve. Los números de objeto se reparten en el orden que al escritor le apetece emitir objetos. Muchos generadores construyen los subconjuntos de fuentes en el orden en que los glifos se usan por primera vez, así que un recorrido ligeramente distinto produce códigos de glifo distintos y, por tanto, bytes de content stream distintos, para el mismo texto visible. Los offsets de las referencias cruzadas se mueven cada vez que algo anterior en el archivo cambia de longitud, 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 el camino que lo alcanza primero en un recorrido en anchura 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 acaba siendo típicamente algo como $Catalog/Pages/Kids[0]/Resources/Font/F1 en ambos archivos, sea cual sea el número de objeto que le dio cada generador. Los bytes inusuales en una clave se escapan como #xx, y un camino más largo que MaxPathBytes se corta y se remata con un hash del camino completo, de modo que dos caminos largos que comparten prefijo siguen siendo distintos
Cada objeto recibe entonces una firma SHA-256 sobre su propio contenido. Una referencia indirecta contribuye solo el hecho de que hay una referencia ahí, nunca el número de objeto al que apunta, y el objetivo se encola para firmarse por su cuenta. Renumerar todos los objetos de un archivo no produce por tanto diferencia alguna. Y cuando un diccionario de fuentes cambia, el informe nombra el camino 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 cuyo camino se movió (una página desplazada a otra rama del árbol de páginas, digamos) aparece como objectMoved; el resto son objectInserted u objectDeleted
Los objetos que ningún camino desde el catálogo alcanza también se firman, bajo un camino sintético 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 vaya a mostrarlo jamás. Los datos de stream se hashean en chunks de 64 KB directamente desde el stream, y la posición del stream se restaura después, así que comparar dos archivos grandes no significa sostener en memoria una copia de cada stream
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
Todos los modos que inspeccionan páginas las alinean primero. Cada página recibe una firma a partir de su texto extraíble; las páginas sin texto extraíble caen 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 desplazaron junto con una inserción o un borrado. Los pares fuera de ella se reordenaron de verdad y se reportan como pageMoved. Lo que no coincidió en absoluto se empareja en orden como pageChanged, y cualquier sobrante pasa a pageInserted o pageDeleted. Para un manual de 400 páginas con una portada nueva, las entradas de nivel de página se quedan en un único pageInserted donde el emparejamiento posicional habría producido 400 cambios. La pasada de objetos trabaja por caminos, así que los objetos de página desplazados típicamente aparecen allí como objectMoved, y filtrar por el campo type los separa de las ediciones reales
Los pares alineados reciben una comprobación 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 basada solo en texto emparejaría y dejaría pasar
Ejecutar una comparación estructural y leer el veredicto
Una comparación recibe dos instancias cargadas de THotPDF y un modo, y devuelve un informe 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 comprobaciones más ligeras para smoke tests. Compare usa los límites y opciones por defecto; CompareWithLimits y CompareWithOptions reciben 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 informe lleva tres hechos de primer nivel que un único booleano mezclaría. identical es true solo cuando no se registró diferencia alguna y la comparación terminó. comparisonComplete dice si terminó. differencesTruncated dice si la lista se cortó, mientras que differenceCount conserva el total verdadero y reportedDifferenceCount el número realmente listado. 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 a false: 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. Cada una fuerza además identical a false; la API no reporta igualdad desde un recorrido que se detuvo antes de tiempo. Una puerta de CI tiene por tanto que distinguir los dos tipos de fallo:
uses
SysUtils, HPDFJobJSON;
// Devuelve True solo para una comparación terminada y sin diferencias;
// imprime la razón en otro caso. La puerta en sí 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 trabajo 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 demasiado bajo, y un trabajo que lo mapea a «igual» deja que un recorrido truncado apruebe una release
¿Qué mantiene acotado el recorrido en archivos que usted no produjo?
THPDFStructuralCompareLimits.Default viene dimensionado para documentos reales: 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 cadena o nombre, 4.096 bytes por camino, y un techo de 16 MB para el informe serializado. Un campo cero o negativo cae a su default, así que un registro lleno a medias nunca se convierte en uno sin límites. El registro lleva además un CancellationToken y un evento Checkpoint que la comparación consulta entre unidades de trabajo, incluso mientras se renderizan páginas
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 corta la lista; differenceCount sigue contando todos
Limits.MaxTotalStreamBytes := 128 * 1024 * 1024;
Limits.CancellationToken := Token; // otro hilo puede llamar a Token.Cancel
Options := THPDFRenderedCompareOptions.Default;
Options.DPI := 150; // el default es 72
Options.ColorSpace := rccLuminance; // compara brillo, ignora cambios solo de tono
Options.ColorTolerance := 2; // los deltas de 1-2 niveles no 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 informe
end;
end;
La cancelación lanza EHPDFOperationCancelled fuera de la llamada en lugar de devolver un informe parcial. Una comparación cancelada no tiene informe que entregar, y la excepción es como lo dice la API. Las opciones de render reciben la misma normalización que los límites. El DPI se acota a 2.400, ColorTolerance a 0–255, TileSize a 8–1.024, y un umbral de similitud o de proporción fuera de 0–1 (o NaN) vuelve discretamente a su default
La pasada de píxeles estima el tamaño del bitmap de cada página a partir de sus dimensiones de página y el DPI pedido antes de renderizar nada, y vuelve a comprobar el bitmap real contra MaxPixelsPerPage después, así que una página con geometría fraudulenta no se cuela por la estimación. El coste 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 ronda los 16.8 millones de píxeles, y el presupuesto se agota tras 29 pares. La pasada registra entonces una entrada renderBudget, marca esa página como budgetExceeded y se detiene, dejando renderComparisonComplete en false
¿Cuánta similitud es suficiente?
Con opciones por defecto la pasada de píxeles exige coincidencia exacta: ColorTolerance 0, MinimumSimilarity 1.0 y MaxChangedPixelRatio 0. Mantener el rigor por defecto deja 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 luce el ruido del 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 una puntuación de similitud estructural (SSIM) calculada 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 puertas, porque unos cientos de píxeles muy mal puestos en un código de barras y una tinta tenue sobre la página entera son fallos distintos, y cada workflow los tolera de otra manera. Las comprobaciones de umbral usan valores sin redondear; los seis decimales del JSON mantienen los informes estables de una ejecución a otra
Los píxeles cambiados se agrupan en regiones sobre una rejilla de teselas fijas, de 64 píxeles de lado por defecto, unidas a través de sus cuatro vecinos de borde. Cada región de changedRegions da su bounding box, su recuento de píxeles cambiados y su delta mayor. Se listan como mucho MaxChangedRegions (256 por defecto); changedRegionCount sigue reportando el número verdadero, y cuando la lista se corta se activa changedRegionsTruncated y la pasada de píxeles cuenta como incompleta. Con GenerateHeatmaps activo, cada página con píxeles cambiados recibe un PNG con nombre tipo 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 camino aparece en el informe como overlayPath
Los fallos se reportan, jamás se absorben. Una excepción del renderer, un bitmap que falta o un tamaño de página inválido se convierten en una entrada renderError con el mensaje, la entrada de página toma el estado error y renderComparisonComplete pasa a false. Dos renders con dimensiones de píxel distintas toman el estado sizeMismatch y una diferencia renderedImageSize que lista ambos tamaños. Una página que nadie logró comparar jamás 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 todas las páginas posteriores, 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 cuadren
Corra cmStructural en cada build. Es barato, nombra el camino, el índice de página y los números de objeto implicados, y un objectChanged inesperado apunta directo al código que lo produjo. Conserve cmFull con heatmaps para los candidatos a release y para comprobar que una pasada de optimización fue de verdad sin pérdidas, cuando hay alguien cerca que mire los overlays. cmPageText va bien para documentos donde solo importa la letra. La revisión a nivel de marcado es otra opción: exportar páginas PDF a SVG da una vista de texto que las herramientas de diff ordinarias pueden leer, y las comprobaciones de automatización de informes de preflight cubren preguntas de conformidad que ninguno de los dos modos de comparación intenta responder
Comparación, preflight y 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 HotPDF para Delphi