技術記事

Delphiで2つのPDFファイルを比較する:構造とピクセル

同じレポート生成器が同じデータから1回違いで作った2つのPDFは、バイト単位で一致することはめったにありません。バイナリdiffは相互参照テーブル、オブジェクト番号、たいていはフォントプログラムを光らせますが、両方のファイルはまったく同じページを印刷します。レンダリングしたピクセルの比較が救いに見えますが、誰かが表紙を1枚足した途端に、すべてのページが対応ページより1つ後ろにずれ、ページごとのピクセル検査はドキュメント全体が変わったと報告します。自動化する価値のある比較は、ファイルの内側で何が変わったかという問いと、読み手がそれに気づくかという問いの、2つの異なる問いに答えなければならず、一方のファイルのどのページが他方のどのページに対応するかも知っていなければなりません

なぜ2つの同じ見た目のPDFはバイト単位で異なるのか

バイトの攪乱の大半は、読み手が目にしない帳簿作業から来ます。オブジェクト番号は、ライターがオブジェクトを吐いたたまたまの順序で割り振られます。多くの生成器はグリフが最初に使われた順にフォントサブセットを組むため、わずかに違うたどり順は同じ見た目のテキストに対して異なるグリフコードを生み、ひいては異なるコンテンツストリームのバイトを生みます。相互参照オフセットは、ファイルの手前にある何かが長さを変えるたびに動きます。それはほぼ常に起きています

HotPDF が 2 つの PDF ファイルに構造オブジェクトグラフパスと描画ピクセルパスを実行し、1 つの JSON 比較レポートにまとめる図
両方のパスは明示的な制限内に収まり、JSON レポートは identical を comparisonComplete や comparisonBudget と組み合わせるため、オートメーションが打ち切られた走査を本当の差異と取り違えることはありません

だからオブジェクト番号は、2つのファイルにまたがる同一性としては役に立ちません。HotPDFのTHPDFDocComparisonは、ドキュメントカタログからの幅優先たどりで最初にオブジェクトへ届く経路で、すべてのオブジェクトを名付けます。辞書のキーはバイト順で訪ねられ、配列の要素はインデックス順なので、たどりは決定論的です。最初のページのフォントリソースは、各生成器がどんなオブジェクト番号を振ろうが、たいてい両方のファイルで$Catalog/Pages/Kids[0]/Resources/Font/F1のような経路に収まります。キーの異常なバイトは#xxでエスケープされ、MaxPathBytesを超える経路は切り詰められてフルパスのハッシュで締められるため、接頭辞を共有する2つの長い経路も区別され続けます

さらに各オブジェクトは、自分のコンテンツの上にSHA-256署名を受け取ります。間接参照が寄与するのは、参照がそこに座っているという事実だけで、それが指すオブジェクト番号は決して入らず、ターゲットは自分自身の署名のためにキューに入ります。したがってファイル内の全オブジェクトの番号の付け替えは、差分を1つも生みません。そして1つのフォント辞書が変わったとき、レポートはそのフォントの経路をobjectChangedとして名指しし、その上のページ、リソース辞書、ページツリーにフラグを立てたりしません。署名は一致するのに経路が動いたオブジェクト(ページがページツリーの別の枝へ移された、など)はobjectMovedとして現れ、残りはobjectInsertedかobjectDeletedです

カタログからのどの経路も届かないオブジェクトも、オブジェクト番号と世代番号を運ぶ$Unreachable[42:0]のような合成経路の下で、やはり署名されます。孤立したコンテンツは、どのビューアーも表示しないとしても、2つのファイルの間の実在の差分です。ストリームデータは64 KBのチャンクでストリームから直接ハッシュされ、その後ストリーム位置は戻されるため、大きなファイル2つの比較が、すべてのストリームのコピーをメモリに抱えることを意味しません

表紙が1枚加わったときのページ整合

ページ1をページ1と、ページ2をページ2と組み合わせるやり方が正しいのは、何かが挿入されるまでです。先頭に新しい表紙が付くと、位置による組み合わせはすべてのページを変更済みと報告します。技術的には正しく、レビュアーには何も教えません

ページを検査するすべてのモードは、まずページを整列させます。各ページは抽出したテキストから署名を受け取り、抽出可能なテキストを持たないページはページ辞書とコンテンツストリームの署名へフォールバックします。署名が正確に一致したページは組み合わされ、比較はそれらのペアのうち、2つ目のファイルでの位置順に並べた最長増加部分列を取ります。その部分列の内側のペアは、挿入や削除に伴ってずれただけです。外側のペアは本当に並べ替えられたもので、pageMovedとして報告されます。まったく一致しなかったものは順にpageChangedとして組み合わされ、余りはpageInsertedかpageDeletedになります。表紙が1枚足されただけの400ページのマニュアルでは、ページレベルのエントリーは1つのpageInsertedに収まります。位置による組み合わせなら400の変更になっていたところです。オブジェクトパスは経路で働くため、動いたページオブジェクトはたいていそちらにもobjectMovedとして現れ、typeフィールドでの絞り込みが本物の編集と切り分けます

素朴な位置ごとの PDF ページ対合と、最長増加部分列を使う HotPDF 署名整合の比較図
シグネチャベースの整列がずれた元ページを一致させ、挿入された表紙を切り離すことで、数百の偽陽性が 1 行の読める報告に変わります

整列したペアは、構造モードではもう1つの検査を受けます。ページ辞書は/Contents、/Resources、/Parentを抜いて2度目の署名を受け、その署名が異なればペアはpageChanged、詳細はpage metadata changedとして報告されます。これは、テキストは同一なのに/MediaBoxや/Rotateが動いたページを捕まえます。テキストベースの整列だけでは、組み合わされて素通りする変更です

構造比較の実行と判定の読み方

比較は、ロード済みのTHotPDFインスタンス2つとモードを受け取り、JSONレポートをAnsiStringとして返します。cmStructuralはオブジェクトとページのたどりを走らせ、cmRenderedImageはピクセルパスを、cmFullは両方を走らせます。cmPageCount、cmPageText、cmObjectCountはスモークテスト向けの軽い検査です。Compareはデフォルトの上限とオプションを使い、CompareWithLimitsとCompareWithOptionsは自分のものを受け取ります

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;

レポートは、単一の真偽値では混ぜ合わされてしまう3つのトップレベルの事実を運びます。identicalは、差分が記録されず、比較が完走したときにだけtrueです。comparisonCompleteは完走したかどうかを言います。differencesTruncatedはリストが切り詰められたかどうかを言い、differenceCountは本当の合計を、reportedDifferenceCountは実際に列挙された数を保持します。たどりが上限に当たると、differences配列のcomparisonBudgetエントリーが、ページたどりとオブジェクトたどりのどちらが切り詰められたかを言います

comparisonCompleteをfalseにするものはいくつもあります。切り詰められたページやオブジェクトのたどり、どちらかのファイルで解決しない間接参照、MaxDifferencesの許す数を超えた差分、構造が読めなかったページ(cmPageTextではテキストが読めなかったページ)、そして不完全なピクセルパスです。そのどれもがidenticalもfalseに強制します。APIは、途中で止まったたどりから等しさを報告しません。したがってCIゲートは、2種類の失敗を区別しなければなりません:

uses
  SysUtils, HPDFJobJSON;

// 完走した比較で差分がないときだけTrueを返す。
// それ以外は理由を出力する。ゲート本体はあなたのコード
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;

「不完全」は独自のビルド結果として扱ってください。それを「異なる」に対応付けるジョブは、実は不正な入力か低すぎる上限である回帰を追いかけるために技術者を送り出し、「同じ」に対応付けるジョブは、切り詰められたたどりをリリースに通します

自分で作っていないファイルで走査を有界に保つもの

THPDFStructuralCompareLimits.Defaultは実世界のドキュメントを想定した寸法です。オブジェクト25万、追跡参照200万、ページ25万、ネスト深さ128、列挙差分1万、単一ストリームから64 MB、全ストリーム合計で512 MB、文字列や名前の値ごとに1 MB、経路ごとに4,096バイト、そして直列化レポートの上限16 MBです。ゼロや負のフィールドはデフォルトへフォールバックするため、一部だけ埋めたレコードが無制限のレコードに化けることはありません。レコードはさらにCancellationTokenと、比較が仕事の単位の間に検査するCheckpointイベントを運びます。ページがレンダリングされている間も含みます

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;              // 一覧を短く保つ。differenceCountは全件を数え続ける
  Limits.MaxTotalStreamBytes := 128 * 1024 * 1024;
  Limits.CancellationToken := Token;         // 別スレッドがToken.Cancelを呼んでもよい

  Options := THPDFRenderedCompareOptions.Default;
  Options.DPI := 150;                        // デフォルトは72
  Options.ColorSpace := rccLuminance;        // 明るさを比較し、色相だけのずれを無視する
  Options.ColorTolerance := 2;               // 1〜2レベルの差は数えない
  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 := '';                          // キャンセルされた:報告書はない
  end;
end;

キャンセルは、部分的なレポートを返す代わりに、呼び出しからEHPDFOperationCancelledを上げます。キャンセルされた比較には引き渡すレポートがなく、その例外がそれを伝えるAPIの言葉です。レンダーオプションは上限と同じ正規化を受けます。DPIは2,400に、ColorToleranceは0〜255に、TileSizeは8〜1,024にクランプされ、0〜1の外(またはNaN)の類似度や比率のしきい値は黙ってデフォルトへ戻ります

ピクセルパスは、何かをレンダリングする前に、ページ寸法と要求DPIから各ページのビットマップサイズを見積もり、その後に実際のビットマップをMaxPixelsPerPageに対して再検査します。いい加減なジオメトリのページが見積もりをすり抜けることはできません。コストはDPIの2乗で育ちます。US Letter(612 × 792ポイント)のドキュメントでは、デフォルトの72 DPIで各ページペアはおよそ97万ピクセルで、デフォルトのMaxTotalPixels 5億は500組超を覆います。300 DPIでは1組がおよそ1,680万ピクセルで、予算は29組で尽きます。パスはその後renderBudgetエントリーを記録し、そのページをbudgetExceededとマークして止まり、renderComparisonCompleteはfalseのままになります

どの程度似ていれば「十分に似ている」と言えるのか?

デフォルトオプションでは、ピクセルパスは正確な一致を要求します。ColorTolerance 0、MinimumSimilarity 1.0、MaxChangedPixelRatio 0です。デフォルトで厳格に保つことで、緩める決断は明示になります。誰かがそれを書き留めなければならず、パイプラインは、アンチエイリアスのノイズが自分のレンダーでどんな姿かを見てからでないと、しきい値を緩めるべきではありません

ピクセルごとの差分は、rccRGBモードでは赤、緑、青のチャンネルの中で最大の差です。rccLuminanceモードではRec. 709輝度の差です。差分がColorToleranceを超えるピクセルが変更ピクセルとして数えられます。類似度の数字は、ページ全体の輝度に対して一括で計算される構造類似度(SSIM)スコアです。ペアがsimilarになるのは、変更ピクセル比率がMaxChangedPixelRatio以下で、類似度がMinimumSimilarity以上のときだけです。門が2つあるのは、バーコードの中の数百のひどく間違ったピクセルと、ページ全体にかかる淡い色かぶりとでは失敗の種類が違い、ワークフローごとに許容の仕方が違うからです。しきい値の検査には丸めない値を使い、JSONの小数6桁は実行から実行へのレポートの安定のためのものです

HotPDF 描画比較における 2 つの類似度しきい値の図。色許容、変更ピクセル率、最小類似度
ペアが類似と判定されるのは、変更ピクセル比率と類似度が両方のしきい値を同時に超えたときだけです。描画失敗は記録され、黙って同一と呼ばれることはありません

変更ピクセルは、固定タイル、デフォルトで64ピクセル四方の格子の上で領域にまとめられ、4つの辺の隣を通じて連結されます。changedRegionsの各領域は、外接箱、変更ピクセル数、最大差分を与えます。列挙されるのは最大でMaxChangedRegions(デフォルト256)です。changedRegionCountはそれでも本当の数を報告し、リストが切り詰められたときはchangedRegionsTruncatedが立ち、ピクセルパスは不完全として数えられます。GenerateHeatmapsが有効だと、変更ピクセルを持つすべてのページが、HeatmapDirectoryにpage-000003-diff.pngのような名前のPNGを受け取ります。1つ目のファイルのページに、黄(許容をかすかに超える)から赤(最大差分)への色付けが乗ったもので、その経路はレポートにoverlayPathとして現れます

失敗は報告され、決して吸収されません。レンダラーの例外、欠落したビットマップ、無効なページサイズは、メッセージ付きのrenderErrorエントリーになり、ページエントリーはステータスerrorを受け取り、renderComparisonCompleteはfalseへ落ちます。ピクセル寸法の違う2つのレンダーはステータスsizeMismatchと、両方のサイズを列挙するrenderedImageSize差分を受け取ります。誰にも比較できなかったページが同一と数えられることはありません

各モードはパイプラインのどこに位置づけられるのか

ピクセルパスはページをインデックスで厳密に組み合わせます。ページi対ページiで、短い方のドキュメントまでです。ページ整列は、cmPageCountとcmRenderedImageを除くすべてのモードで走ります。挿入された表紙があるとき、cmRenderedImage単体はその後のすべてのページにフラグを立てますが、cmFullは構造の半分から整列を与え、それに位置によるピクセル結果を並べてくれます。最初に構造の判定を読み、ページのリストが揃っているときだけピクセルの結果を信じてください

すべてのビルドでcmStructuralを走らせてください。安く、関わる経路とページインデックスとオブジェクト番号を名指しし、予期しないobjectChangedはそれを作ったコードへまっすぐ指します。ヒートマップ付きのcmFullは、リリース候補と、最適化パスが本当に無損失だったかの確認に取っておきます。誰かがオーバーレイを見に来られるときにです。cmPageTextは、文言だけが大事なドキュメントに合います。マークアップレベルのレビューも選択肢です。PDFページのSVGエクスポートは、普通のdiffツールが読めるテキストビューを与え、プリフライトレポートの自動化の検査は、どちらの比較モードも答えようとしない適合性の問いを覆います

比較、プリフライト、レンダリングはすべて同じロード済みTHotPDFドキュメントの上で動くため、1回のロードが3つすべてに仕えます。DelphiとC++Builderの開発者向けにコンポーネントが覆うすべては、HotPDF Delphi PDFコンポーネントページにあります