Qual a diferença entre pdfl compare e pdfl pixelcompare?

Dois comandos recebem dois PDFs e dizem o que mudou. Parece duplicação até a primeira vez em que eles discordam — e aí você descobre que nunca estiveram respondendo à mesma pergunta.

O pdfl compare pergunta o que o documento diz. O pdfl pixelcompare pergunta com o que o documento se parece.

Um arquivo pode passar em um e falhar no outro, nas duas direções.

pdfl compare: o que o documento diz

Ele lê o texto, a estrutura e os metadados:

pdfl compare aprovado_v1.pdf novo_v2.pdf

A parte que vale conhecer é como ele alinha as páginas. O alinhamento é por conteúdo, não por número. Insira uma página no meio de um contrato e uma comparação ingênua reporta todas as páginas seguintes como alteradas; esta percebe a inserção e continua comparando semelhante com semelhante. Isso se sustenta em documentos de mais de mil páginas.

Cada par alinhado recebe uma nota de similaridade e uma amostra das linhas que se moveram, - para removidas e + para adicionadas:

page 4 → 4: similarity 97.8% | -original title | +revised title

Metadado alterado é aviso. Texto alterado é erro quando cai abaixo do limite que você definiu, e aviso quando fica acima.

# Ignora caixa, espaçamento e datas — útil quando a data de emissão é
# regerada a cada exportação e não é o que está em revisão
pdfl compare aprovado_v1.pdf novo_v2.pdf --normalize --ignore-dates

# Aceita até 1% de diferença, e produz algo que uma pessoa consegue ler
pdfl compare v1.pdf v2.pdf --similarity-threshold 99 \
  --output html --output-file diff.html

pdfl pixelcompare: com o que o documento se parece

Ele renderiza os dois arquivos e compara as páginas como imagens:

pdfl pixelcompare aprovado.pdf reimpressao.pdf

Uma ocorrência por página que mudou, com quanto dela difere e em quantos lugares separados:

page 7: 0.51% of the pixels differ, in 29 area(s)

Ele compensa primeiro um deslocamento global, porque um arquivo exportado de novo a partir da mesma origem costuma cair um ou dois pixels fora, e sem isso a borda de cada letra contaria como diferença:

page 3: 2.10% of the pixels differ, in 44 area(s) (aligned by 2, -1 px)

E ele pode gravar um lugar para olhar:

pdfl pixelcompare aprovado.pdf reimpressao.pdf --viewer diff/

Essa pasta guarda as páginas, as diferenças e um index.html — sem servidor, sem nada para instalar. Vermelho é tinta que sumiu, verde é tinta nova, azul é o mesmo peso numa cor diferente.

Onde eles discordam

O texto é idêntico e o arquivo está errado. Um logotipo deslocado dois milímetros. Um fio de cabelo que sumiu. Uma cor especial trocada por uma composição em CMYK. O compare reporta correspondência perfeita nos três, porque nenhum caractere se moveu. O pixelcompare pega os três.

O arquivo parece idêntico e o texto está errado. O título nos metadados foi substituído, ou um campo de autor foi reescrito. Nada na página muda um pixel, então o pixelcompare vê dois documentos idênticos. O compare reporta a mudança.

Nenhum dos dois contém o outro. É esse o ponto.

Quatro situações, e o que rodar

Um contrato voltou do jurídico. Você precisa saber o que a redação diz agora em relação ao que dizia antes. O layout vai ter refluído e isso não importa.

pdfl compare contrato_v3.pdf contrato_v4.pdf --ignore-dates \
  --output html --output-file revisao.html

Chegou uma reimpressão do fornecedor. Nada pode parecer diferente da prova que foi aprovada. Se o texto é idêntico byte a byte é irrelevante — a pergunta é o que vai para o papel.

pdfl pixelcompare aprovado.pdf reimpressao.pdf --viewer diff/

O mesmo documento, exportado por outra ferramenta. Um fornecedor trocou de software. As palavras precisam sobreviver intactas, e a aparência provavelmente vai variar um pouco. Isso pede os dois, e eles conferem promessas diferentes:

pdfl compare export_antigo.pdf export_novo.pdf --normalize
pdfl pixelcompare export_antigo.pdf export_novo.pdf --max-diff 0.1 --viewer diff/

Uma bula ou rótulo regulado. O texto de advertência é exigido por lei e o layout foi aprovado por alguém que assinou. Os dois obrigam, então os dois são conferidos — e a pasta do visualizador é o que você anexa à aprovação.

pdfl compare aprovado.pdf arquivo_maquina.pdf
pdfl pixelcompare aprovado.pdf arquivo_maquina.pdf --viewer evidencia/

Os dois de uma vez, como portão

Cada comando sai com um código, então um script decide sem ler nada. O pixelcompare usa 0 quando nenhuma página passou da tolerância, 2 quando alguma passou e 10 quando um arquivo não pôde ser lido; o compare segue a convenção de todo comando de validação — 0 passou, 1 avisos, 2 erros, 10 ilegível.

#!/bin/sh
# As duas promessas, um portão só: as palavras e a aparência.
set -e

pdfl compare aprovado.pdf candidato.pdf --output-file texto-diff.json || {
  echo "a redação mudou — veja texto-diff.json"
  exit 1
}

pdfl pixelcompare aprovado.pdf candidato.pdf --max-diff 0.05 --viewer diff/ || {
  echo "não está com a mesma aparência — abra diff/index.html"
  exit 1
}

echo "mesmas palavras, mesma aparência"

Qual usar, em uma linha

A pergunta que você está fazendo	O comando
A redação mudou?	pdfl compare
Os metadados mudaram?	pdfl compare
Alguma página foi inserida ou removida?	pdfl compare
Alguma coisa moveu, sumiu ou mudou de cor?	pdfl pixelcompare
Continua imprimindo igual?	pdfl pixelcompare
Este é o arquivo que foi aprovado?	os dois

Onde olhar depois

O capítulo do CLI documenta todas as opções dos dois, e as receitas colocam ambos dentro de fluxos completos. Tem também aqui um artigo sobre a comparação pixel a pixel e o que um arquivo errado custa depois de entrar na máquina.