pdfl compare と pdfl pixelcompare は何が違うのか

二つのコマンドが、二つの PDF を受け取って何が変わったかを教えます。重複している ように見えますが、初めて食い違ったときに分かります。両者は最初から同じ問いに答えて いなかったのだと。

pdfl compare が問うのは、文書が何を言っているか。 pdfl pixelcompare が問うのは、文書がどう見えるか。

一方を通り、もう一方で落ちるファイルが、両方向にあり得ます。

pdfl compare: 文書が何を言っているか

文字と構造とメタデータを読みます。

pdfl compare approved_v1.pdf new_v2.pdf

知っておく価値があるのは、ページの対応の取り方です。番号ではなく内容で揃えます。 契約書の途中に 1 ページ挿入すると、素朴な比較はそれ以降のすべてのページを変更あり と報告します。この比較は挿入に気づき、対応するもの同士を比べ続けます。千ページを 超える文書でも成立します。

対応づいた各ページに類似度と、動いた行の抜粋がつきます。- が削除、+ が追加です。

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

メタデータの変化は警告。文字の変化は、設定したしきい値を下回れば error、上回って いれば警告になります。

# 大文字小文字・空白・日付を無視する。発行日が書き出しのたびに
# 再生成され、それが審査対象ではないときに役立つ
pdfl compare approved_v1.pdf new_v2.pdf --normalize --ignore-dates

# 1% までの差を許し、人が読める形で出す
pdfl compare v1.pdf v2.pdf --similarity-threshold 99 \
  --output html --output-file diff.html

pdfl pixelcompare: 文書がどう見えるか

両方のファイルを描画し、ページを画像として比べます。

pdfl pixelcompare approved.pdf reprint.pdf

変化したページごとに 1 件、そのページのどれだけが異なるか、何か所に分かれているかと ともに。

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

まず全体のずれを補正します。同じ原稿から書き出し直したファイルはしばしば 1、2 ピクセルずれて着地し、補正しなければ文字の輪郭すべてが差分として数えられてしまう からです。

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

そして、目で見る場所を書き出せます。

pdfl pixelcompare approved.pdf reprint.pdf --viewer diff/

そのフォルダーにはページと差分と index.html が入っています。サーバーも、 インストールするものもありません。赤は失われたインキ、緑は新しいインキ、青は同じ 濃さで色が違うところです。

両者が食い違うところ

文字は同一なのにファイルが誤っている。 2 ミリ動いたロゴ。消えたヘアラインの罫。 CMYK の掛け合わせに置き換えられた特色。compare は三つとも完全一致と報告します。 一文字も動いていないからです。pixelcompare は三つとも捕まえます。

見た目は同一なのに文字が誤っている。 メタデータのタイトルが差し替えられた、 著者欄が書き換えられた。ページ上は 1 ピクセルも動かないので、pixelcompare には 同一の文書に見えます。compare はその変化を報告します。

どちらも他方を包含しません。 それがこの話の要点です。

四つの場面と、走らせるもの

契約書が法務から戻ってきた。 いま文言が何と言っているかを、以前と比べて知る 必要があります。レイアウトは流し直されているはずで、そこは問題ではありません。

pdfl compare contract_v3.pdf contract_v4.pdf --ignore-dates \
  --output html --output-file review.html

取引先から刷り直しが届いた。 承認された校正と見た目が違ってはなりません。文字が 1 バイトまで同じかどうかは的外れで、紙に出るものが問いです。

pdfl pixelcompare approved.pdf reprint.pdf --viewer diff/

同じ文書を、別のツールで書き出した。 取引先がソフトを変えました。言葉は無傷で 残らなければならず、見た目は少しずれる可能性が高い。ここでは両方が要り、確かめて いる約束が別々です。

pdfl compare old_export.pdf new_export.pdf --normalize
pdfl pixelcompare old_export.pdf new_export.pdf --max-diff 0.1 --viewer diff/

規制対象の表示や添付文書。 注意書きは法で義務づけられ、レイアウトは誰かが署名して 承認したもの。どちらも拘束力があるので、どちらも確認します。そしてビューアーの フォルダーが、承認に添える証跡になります。

pdfl compare approved.pdf press_file.pdf
pdfl pixelcompare approved.pdf press_file.pdf --viewer evidence/

二つを同時に、関門として

どちらのコマンドも終了コードを返すので、スクリプトは何も読まずに判断できます。 pixelcompare は、許容を超えたページがなければ 0、あれば 2、ファイルが読めな ければ 10。compare は検証系コマンド共通の規約に従います — 0 合格、1 警告、 2 エラー、10 読めない。

#!/bin/sh
# 二つの約束をひとつの関門で。言葉と、見た目と。
set -e

pdfl compare approved.pdf candidate.pdf --output-file text-diff.json || {
  echo "文言が変わりました — text-diff.json を見てください"
  exit 1
}

pdfl pixelcompare approved.pdf candidate.pdf --max-diff 0.05 --viewer diff/ || {
  echo "見た目が一致しません — diff/index.html を開いてください"
  exit 1
}

echo "同じ言葉、同じ見た目"

どちらを使うか、一行で

問い	コマンド
文言が変わったか	pdfl compare
メタデータが変わったか	pdfl compare
ページが挿入・削除されたか	pdfl compare
何かが動いた・消えた・色が変わったか	pdfl pixelcompare
いまも同じように刷れるか	pdfl pixelcompare
これは承認されたファイルか	両方

次に読むもの

CLI の章に両者のすべてのオプションがあり、実践レシピ は両方を完全な流れの中に置いています。このブログにはピクセル単位の比較 と、誤ったファイルが機械に乗ったあとの代償についての記事もあります。