「どこが直ったか」を確認するのに毎回疲れていた
資料や論文の改訂版が届くたびに、旧版と新版のPDFを並べて目視で見比べる作業をしていませんか。
共著者(上司や教授たち)からの修正、査読対応からの戻し原稿——「結局どこが変わったの?」を確かめるためだけに、何十ページものPDFを1ページずつ突き合わせるのは地味に時間を食います。
Wordなら変更履歴がありますが、PDFにはそれがありません。しかも日本語の文書では、改行位置がずれただけで別の行として扱われたり、段組みやスライド形式のレイアウトで文章の抽出順がめちゃくちゃになったり、CJK特有の面倒がいろいろあります。
そこで、この課題を解決するために kogo(校合) というOSSツールを作りました。
- リポジトリ: https://github.com/ta-061/kogo
- サイト: https://kogo.tatu-sec.dev/
- ドキュメント(日本語対応): https://kogo.tatu-sec.dev/manual/ja/
- デモ(ブラウザですぐ試せます): https://kogo-demo.tatu-sec.dev/
- PyPI:
pip install kogo
「校合(こうごう)」は、改訂版を原本と照合するという意味の日本の出版用語です。
名前の通り、2つのPDFを比較して、追加・削除された文字、図、数式、注釈をハイライトします。
何ができるか
- 単語単位(CJKは文字単位)のテキスト差分 — CJK拡張漢字B〜J領域のまれな漢字も含めて対応
- 段組み・スライド形式のレイアウトも正しい読み順で比較(空白領域からレイアウトを分析)
- ページの挿入・削除があってもズレない対応付け(テキスト類似度+視覚的類似度)
- 図・数式・レイアウトの視覚差分(テキスト領域はマスクして除外、スキャンのズレも補正)
- ハイライト・コメント・手書き注釈の追加/削除検出
- 太字・斜体・文字サイズだけの変更をアンバー色で別途検出
- マーカーはPDFのページ内容に直接焼き込まれるため、注釈を非表示にするビューアでも見える
- すべての処理はローカルで完結——PDFの中身がどこにも送信されません
まず動かしてみる
インストールなしで試したい場合は、ブラウザから直接使えるデモがあります。
CLIやライブラリとして使う場合:
pip install kogo
kogo diff old.pdf new.pdf -o out/
import kogo
result = kogo.compare_pdfs("old.pdf", "new.pdf", "out/")
print(result["summary"])
# out/ に old-highlighted.pdf, new-highlighted.pdf, side-by-side.pdf,
# result.json、ページプレビューが生成されます
Webアプリとしても使えます。
pip install "kogo[serve]"
kogo fetch-viewer
kogo serve
中身の仕組み
kogoのエンジン(src/kogo/engine/)は、関心ごとにモジュールが分かれています。全体の流れは次のようになっています。
1. 単語抽出と読み順の再構築
PDF内部の生のコンテンツストリーム順(描画命令が書かれた順序)をそのまま信用すると、段組みのページやスライド形式のテキストボックスで、無関係な列の文章が1つの文脈に混ざってしまいます。kogoは空白領域を手がかりに再帰的にページを分割し、人間が読む順序を再構築してから比較します。テキストは単語単位、CJKは文字単位で抽出します。
2. ページ対応付け
「旧ファイルのページNは新ファイルのページNに対応する」という前提を置きません。ページの挿入・削除があると、この前提はすぐに崩れます。kogoは動的計画法による編集距離を使い、2つの指標を組み合わせた類似度でページ同士を対応付けます。
- テキストシグネチャの類似度——単語トークンの重なり具合(CJKは3文字シングル)
-
視覚シグネチャの類似度——縮小したグレースケール画像のコサイン類似度
(画像中心のページやスキャンページなど、テキストが少ない場合に活用)
3. テキスト差分は3段階
文書全体をいきなり1回の difflib.SequenceMatcher にかけるのではなく、3段階で差分を検出します。
Stage 1で完全一致行を先に固定することで、変更されていない列やテーブルのセルが、単に抽出順が変わっただけで「削除+追加」として誤検出されるのを防いでいます。また、非常に大きく内容がほぼ無関係な文書では SequenceMatcher(autojunk=False)が最悪計算量で2乗のオーダーになるため、ページごとの比較にフォールバックする安全装置も入れています。
太字・斜体・文字サイズだけが変わった(文字自体は同じ)ケースも、Stage 1の完全一致行マッチング中に検出し、追加・削除とは別に報告します。
4. 視覚差分と注釈差分
図や数式などテキスト以外のレイアウトは、対応付けたページペアを画像として描画し、テキスト差分で検出済みの領域をマスクしたうえで画素差分を取ります。スキャンや書き出しによる数ピクセルのズレは、画素差分の前に位置合わせして補正します。
既存のPDF注釈(ハイライト・コメント・手書き)は、種類・位置・色・不透明度・内容からフィンガープリント化し、テキスト・視覚差分とは独立に集合差分で比較します。
LaTeXの論文レビューをCIで自動化する
個人的に一番気に入っている使い方が、GitHub Actions上でLaTeX論文をPRごとにビルドして、変更点をPRコメントとして自動投稿するワークフローです。
import kogo
result = kogo.compare_pdfs(
"old/paper/paper.pdf",
"new/paper/paper.pdf",
"out/",
artifacts=False, # 要約だけでよいのでマーカー付きPDFは生成しない
)
summary = result["summary"]
print(
f"{summary['changed_pages']} of {summary['compared_rows']} pages changed "
f"(+{summary['added_words']} / -{summary['deleted_words']} words, "
f"{summary['visual_regions']} visual regions)"
)
これを gh pr comment と組み合わせるだけで、レビュアーはPDFを開く前に「どのくらい・どこが変わったか」を把握できます。ワークフロー全体はドキュメントのLaTeXのPRレビューレシピにそのまま使える形で載せています。
今後・コントリビュート募集
まだ足りない機能もいくつかあります(ROADMAPに一覧)。
- 移動した段落を「削除+追加」ではなく「移動」として検出
- 縦書き(縦組み)対応
- 表(テーブル)を意識した差分
- テキストレイヤーのないスキャンPDF向けのOCR組み込み
Issue・PRお待ちしています。ドキュメントは英語・日本語に対応していますが、他言語への翻訳も歓迎です(docs-src/*.<言語コード>.md を追加するだけです。
詳しくはCONTRIBUTINGを参照)。
AGPL-3.0で公開しています。試してみて気になった点があれば、IssuesやDiscussionsで教えてください。
