Artigo Técnico

Comparar dois arquivos PDF no Delphi: estrutura e pixels

Dois PDFs produzidos pelo mesmo gerador de relatórios a partir dos mesmos dados, uma execução de distância, raramente batem byte a byte. Um diff binário acende a tabela de referências cruzadas, os números de objeto e muitas vezes os programas de fonte, enquanto os dois arquivos imprimem exatamente as mesmas páginas. Comparar pixels renderizados parece a cura até alguém acrescentar uma capa: a partir daí, toda página fica uma posição depois da sua correspondente, e uma checagem de pixels página a página reporta o documento inteiro como mudado. Uma comparação que vale automatizar precisa responder duas perguntas diferentes, o que mudou dentro do arquivo e se um leitor veria, e precisa saber qual página num arquivo corresponde a qual página no outro

Por que dois PDFs de aparência idêntica diferem byte a byte?

A maior parte do retrabalho de bytes vem de contabilidade que um leitor nunca vê. Números de objeto são distribuídos na ordem em que o escritor por acaso emite objetos. Muitos geradores constroem subconjuntos de fontes na ordem em que os glifos são usados pela primeira vez, então uma travessia ligeiramente diferente produz códigos de glifo diferentes, e portanto bytes de fluxo de conteúdo diferentes, para o mesmo texto visível. Offsets de referências cruzadas se movem sempre que qualquer coisa antes no arquivo muda de comprimento, o que é quase sempre

Diagrama do HotPDF rodando uma passada de grafo de objetos estrutural e uma passada de pixels renderizados sobre dois arquivos PDF num único relatório de comparação JSON
As duas passadas ficam dentro de limites explícitos, e o relatório JSON casa identical com comparisonComplete e comparisonBudget para que a automação nunca confunda uma travessia truncada com uma diferença real

Logo, números de objeto são inúteis como identidade entre dois arquivos. O THPDFDocComparison no HotPDF nomeia todo objeto pelo caminho que o alcança primeiro numa caminhada em largura a partir do catálogo do documento. Chaves de dicionário são visitadas em ordem de bytes e elementos de array por índice, o que torna a caminhada determinística: um recurso de fonte na primeira página normalmente acaba como algo como $Catalog/Pages/Kids[0]/Resources/Font/F1 nos dois arquivos, não importa que número de objeto cada gerador lhe deu. Bytes incomuns numa chave recebem escape como #xx, e um caminho mais longo que MaxPathBytes é cortado e finalizado com um hash do caminho completo, então dois caminhos longos que dividem um prefixo continuam distintos

Cada objeto então ganha uma assinatura SHA-256 sobre o conteúdo próprio dele. Uma referência indireta contribui apenas com o fato de que uma referência está ali, nunca com o número de objeto para o qual aponta, e o alvo entra na fila para ser assinado por conta própria. Renumera todo objeto de um arquivo portanto não produz diferença nenhuma. E quando um dicionário de fonte muda, o relatório nomeia o caminho dessa fonte como objectChanged em vez de marcar a página, o dicionário de recursos e a árvore de páginas acima dela. Um objeto cuja assinatura bate mas cujo caminho se moveu (uma página deslocada para outro ramo da árvore de páginas, digamos) aparece como objectMoved; o resto é objectInserted ou objectDeleted

Objetos que nenhum caminho a partir do catálogo alcança continuam sendo assinados, sob um caminho sintético como $Unreachable[42:0] que carrega o número de objeto e de geração. Conteúdo órfão é uma diferença real entre dois arquivos mesmo que nenhum visualizador o exiba um dia. Dados de stream são hasheados em chunks de 64 KB direto do stream, e a posição do stream é devolvida depois, então comparar dois arquivos grandes não significa segurar uma cópia de todo stream em memória

Alinhando páginas quando um documento ganha uma capa

Combinar a página 1 com a página 1 e a página 2 com a página 2 está correto só até alguém inserir algo. Com uma capa nova na frente, o pareamento posicional reporta toda página como mudada, o que é tecnicamente verdade e não diz nada a quem revisa

Todo modo que inspeciona páginas as alinha primeiro. Cada página ganha uma assinatura a partir do texto extraído dela; páginas sem texto extraível caem para uma assinatura do dicionário de página mais o fluxo de conteúdo. Páginas cujas assinaturas batem exatamente são pareadas, e a comparação então toma a maior subsequência crescente desses pares, ordenada pela posição deles no segundo arquivo. Pares dentro dessa subsequência apenas se deslocaram junto com uma inserção ou exclusão. Pares fora dela realmente foram reordenados e são reportados como pageMoved. O que não bateu de forma alguma é pareado em ordem como pageChanged, e qualquer excedente vira pageInserted ou pageDeleted. Para um manual de 400 páginas com uma capa nova, as entradas de nível de página se resumem a um único pageInserted, onde o pareamento posicional teria produzido 400 mudanças. A passada de objetos trabalha por caminho, então os objetos de página deslocados tipicamente ainda aparecem lá como objectMoved, e filtrar pelo campo type os separa de edições reais

Diagrama comparando o pareamento de páginas PDF posição por posição ingênuo com o alinhamento por assinatura do HotPDF usando uma maior subsequência crescente
O alinhamento por assinatura casa as páginas originais deslocadas e isola a capa inserida, transformando centenas de falsos positivos numa única linha legível

Pares alinhados ganham mais uma checagem nos modos estruturais. O dicionário de página é assinado uma segunda vez sem /Contents, /Resources e /Parent, e se essa assinatura difere o par é reportado como pageChanged com o detalhe page metadata changed. Isso pega uma página cujo texto é idêntico mas cuja /MediaBox ou /Rotate se moveu, uma mudança que o alinhamento só de texto parearia e deixaria passar

Rodando uma comparação estrutural e lendo o veredito

Uma comparação recebe duas instâncias carregadas de THotPDF e um modo, e retorna um relatório JSON como AnsiString. O cmStructural roda a caminhada de objetos e páginas, o cmRenderedImage roda a passada de pixels, o cmFull roda as duas, e cmPageCount, cmPageText e cmObjectCount são checagens mais leves para smoke tests. O Compare usa os limites e opções padrão; o CompareWithLimits e o CompareWithOptions aceitam os seus

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;

O relatório carrega três fatos de topo que um booleano único embaralharia. O identical só é verdadeiro quando nenhuma diferença foi registrada e a comparação terminou. O comparisonComplete diz se ela terminou. O differencesTruncated diz se a lista foi cortada, enquanto o differenceCount guarda o total verdadeiro e o reportedDifferenceCount o número de fato listado. Quando uma travessia atinge um limite, uma entrada comparisonBudget no array differences diz se a caminhada de páginas ou a de objetos foi truncada

Várias coisas definem comparisonComplete como falso: uma travessia de páginas ou objetos truncada, uma referência indireta que não resolve num dos arquivos, mais diferenças do que o MaxDifferences permite, uma página cuja estrutura (ou, no cmPageText, cujo texto) não pôde ser lida, e uma passada de pixels incompleta. Cada uma delas também força identical para falso; a API não reporta igualdade vinda de uma caminhada que parou cedo. Um gate de CI portanto precisa separar os dois tipos de falha:

uses
  SysUtils, HPDFJobJSON;

// Retorna True só para uma comparação concluída sem diferenças;
// imprime o motivo caso contrário. O gate em si é código seu
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 um desfecho de build próprio. Um job que o mapeia para "diferente" manda engenheiros caçar uma regressão que na verdade é uma entrada malformada ou um limite baixo demais, e um job que o mapeia para "igual" deixa uma travessia truncada passar uma release

O que mantém a caminhada contida em arquivos que você não produziu?

O THPDFStructuralCompareLimits.Default é dimensionado para documentos reais: 250.000 objetos, 2.000.000 de referências seguidas, 250.000 páginas, profundidade de aninhamento 128, 10.000 diferenças listadas, 64 MB lidos de qualquer stream individual e 512 MB de todos os streams juntos, 1 MB por valor de string ou nome, 4.096 bytes por caminho, e um teto de 16 MB no relatório serializado. Um campo zero ou negativo volta para o padrão dele, então um record parcialmente preenchido nunca vira um ilimitado. O record também carrega um CancellationToken e um evento Checkpoint que a comparação checa entre unidades de trabalho, inclusive enquanto páginas renderizam

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;              // mantém a listagem curta; o differenceCount ainda conta tudo
  Limits.MaxTotalStreamBytes := 128 * 1024 * 1024;
  Limits.CancellationToken := Token;         // outra thread pode chamar Token.Cancel

  Options := THPDFRenderedCompareOptions.Default;
  Options.DPI := 150;                        // o padrão é 72
  Options.ColorSpace := rccLuminance;        // compara brilho, ignora mudanças só de matiz
  Options.ColorTolerance := 2;               // deltas de 1-2 níveis não são contados
  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: não há relatório
  end;
end;

O cancelamento levanta EHPDFOperationCancelled para fora da chamada em vez de retornar um relatório parcial. Uma comparação cancelada não tem relatório nenhum para devolver, e a exceção é como a API diz isso. As opções de render recebem a mesma normalização que os limites. O DPI é limitado a 2.400, o ColorTolerance a 0–255, o TileSize a 8–1.024, e um limiar de similaridade ou proporção fora de 0–1 (ou NaN) volta silenciosamente ao padrão

A passada de pixels estima o tamanho do bitmap de cada página a partir das dimensões da página e do DPI pedido antes de renderizar qualquer coisa, e confere o bitmap real contra o MaxPixelsPerPage de novo depois, então uma página com geometria maluca não escapa da estimativa. O custo cresce com o quadrado do DPI. Para um documento de páginas US Letter, 612 por 792 pontos, no 72 DPI padrão cada par de páginas custa uns 0,97 milhão de pixels, e o MaxTotalPixels padrão de 500 milhões cobre mais de 500 pares. A 300 DPI um único par dá uns 16,8 milhões de pixels, e o orçamento se esgota depois de 29 pares. A passada então registra uma entrada renderBudget, marca aquela página como budgetExceeded e para, deixando o renderComparisonComplete falso

Quão semelhante é semelhante o suficiente?

Com as opções padrão a passada de pixels exige uma batida exata: ColorTolerance 0, MinimumSimilarity 1.0 e MaxChangedPixelRatio 0. Ficar estrito por padrão mantém a decisão de afrouxar explícita: alguém precisa escrever isso, e um pipeline só deve relaxar os limiares depois de ter visto como o ruído de anti-aliasing fica nos renders dele

Por pixel, o delta no modo rccRGB é a maior diferença entre os canais vermelho, verde e azul; no modo rccLuminance é a diferença de luminância Rec. 709. Um pixel conta como mudado quando o delta dele excede o ColorTolerance. O número de similaridade é um escore de similaridade estrutural (SSIM) calculado sobre a luminância da página inteira de uma vez. Um par é similar só quando a proporção de pixels mudados está em ou abaixo do MaxChangedPixelRatio e a similaridade em ou acima do MinimumSimilarity. Dois portões, porque algumas centenas de pixels muito errados num código de barras e uma tonalidade leve pela página inteira são falhas diferentes, e cada fluxo de trabalho as tolera de um jeito. As checagens de limiar usam valores sem arredondamento; as seis casas decimais no JSON mantêm os relatórios estáveis de execução para execução

Diagrama dos dois limiares de similaridade na comparação renderizada do HotPDF com tolerância de cor, proporção de pixels mudados e similaridade mínima
Um par só é similar quando a proporção de pixels mudados e a similaridade passam pelos dois limiares juntos, e um render que falha é registrado em vez de silenciosamente chamado de idêntico

Pixels mudados são agrupados em regiões numa grade de tiles de tamanho fixo, 64 pixels de lado por padrão, unidos pelos quatro vizinhos de borda. Cada região em changedRegions dá o bounding box dela, a contagem de pixels mudados e o maior delta. No máximo MaxChangedRegions (256 por padrão) são listadas; o changedRegionCount ainda reporta o número verdadeiro, e quando a lista é cortada o changedRegionsTruncated é definido e a passada de pixels conta como incompleta. Com o GenerateHeatmaps ligado, toda página com pixels mudados ganha um PNG nomeado como page-000003-diff.png no HeatmapDirectory: a página do primeiro arquivo com os pixels mudados tingidos de amarelo (mal acima da tolerância) a vermelho (delta máximo), e o caminho dela aparece no relatório como overlayPath

Falhas são reportadas, nunca absorvidas. Uma exceção do renderer, um bitmap ausente ou um tamanho de página inválido vira uma entrada renderError com a mensagem, a entrada da página recebe status error, e o renderComparisonComplete vai para falso. Dois renders com dimensões de pixel diferentes recebem status sizeMismatch e uma diferença renderedImageSize listando os dois tamanhos. Uma página que ninguém conseguiu comparar nunca é contada como idêntica

Onde cada modo pertence num pipeline

A passada de pixels pareia páginas estritamente por índice, página i contra página i, até o documento mais curto. O alinhamento de páginas roda em todo modo exceto cmPageCount e cmRenderedImage. Com uma capa inserida, o cmRenderedImage sozinho marca toda página depois dela, e o cmFull te dá o alinhamento da metade estrutural dele junto com esses resultados posicionais de pixels. Leia o veredito estrutural primeiro, e confie nos resultados de pixels só quando as listas de páginas se alinham

Rode o cmStructural em toda build. Ele é barato, nomeia o caminho, o índice de página e os números de objeto envolvidos, e um objectChanged inesperado aponta direto para o código que o produziu. Guarde o cmFull com heatmaps para candidatos a release e para conferir que uma passada de otimização realmente foi sem perdas, quando tiver alguém por perto para olhar os overlays. O cmPageText serve para documentos em que só a redação importa. Revisão em nível de markup é outra opção: exportar páginas PDF para SVG dá uma visão em texto que ferramentas de diff comuns conseguem ler, e as checagens em automação de relatórios de preflight cobrem perguntas de conformidade que nenhum dos dois modos de comparação tenta responder

Comparação, preflight e renderização trabalham todos sobre o mesmo documento THotPDF carregado, então um load pode servir aos três. Tudo o que o componente cobre para desenvolvedores Delphi e C++Builder está na página do componente HotPDF Delphi PDF