AI利用と関係の開示：本稿・コード・架空PDFはCodexが生成し、変換操作とファイル検査もエージェントが実行しました。Yan Wang / LensUp向けに作成した記事です。人間のアカウント所有者が自ら実験・独立検証したという意味ではありません。

PDFのしおりを取り出してtitle → pageの辞書にすると、扱いやすそうに見えます。ただ、複数の文書に同じ「Overview」「Details」があると、結合後には片方が上書きされます。この検査では、しおりのタイトルを一意のキーとして使えません。

そこで今回は、ページ番号を見る前に、巡回順・階層の深さ・移動先ページの識別文字列を一組で残す方法を紹介します。汎用のPDF検証器ではなく、同名しおりを含む小さな架空例の診断です。

まず期待する順序を決める

入力はAlphaとBetaの2文書で、どちらも2ページです。しおりは各文書とも、親がOverview、子がDetailsです。1ページ目には、同じ文書の2ページ目への内部リンクも置きました。出力はファイル名順とは逆のBeta、Alphaの順にして、エージェントがブラウザーから実際に結合・ダウンロードしました。

出力ページに印字された識別子はBETA-1 → BETA-2 → ALPHA-1 → ALPHA-2です。下表のindexは0始まりなので、PDFリーダーでいう「1ページ目」がindex 0にあたります。

depth	title	page_index	target_token
0	Overview	0	BETA-1
1	Details	1	BETA-2
0	Overview	2	ALPHA-1
1	Details	3	ALPHA-2

期待値には同じtitleが重複して含まれます。この重複を消してしまうと、検査したい対象そのものがなくなります。

リストとして出力する短い診断コード

実行環境はmacOS、Python 3.12.14、pypdf 6.10.0、ReportLab 4.4.9です。まず専用のサンプルを生成し、それを結合します。使える仮想環境がなければ、専用の環境を作ってください。

python3.12 -m venv .venv
source .venv/bin/activate
python -m pip install pypdf==6.10.0 reportlab==4.4.9

次のコードをreproduce_source.pyとして、既存ファイルのない作業用ディレクトリに保存します。実行すると、同名のしおりとページ識別子を持つPDFが2つ書き出されます。

"""Standalone reader recipe; writes two synthetic PDFs only when run as a script."""
import io
from pathlib import Path
from reportlab.pdfgen import canvas
from reportlab.lib.pagesizes import A4

def make_source(name):
    stream = io.BytesIO()
    pdf = canvas.Canvas(stream, pagesize=A4, invariant=1, pageCompression=1)
    pdf.setTitle(f'{name.title()} fictional handbook')
    pdf.setAuthor('Synthetic fixture')
    for page in (1, 2):
        pdf.setFont('Helvetica-Bold', 22)
        pdf.drawString(50, 770, f'{name.upper()} / PAGE {page}')
        pdf.setFont('Helvetica', 12)
        pdf.drawString(50, 735, 'Fictional navigation test. Not a customer document.')
        pdf.drawString(50, 708, f'Identity token: {name.upper()}-{page}')
        if page == 1:
            pdf.bookmarkPage('overview')
            pdf.addOutlineEntry('Overview', 'overview', level=0, closed=False)
            pdf.setFillColorRGB(0, 0.2, 0.65)
            pdf.drawString(50, 660, 'Jump to this handbook\'s Details page')
            pdf.linkRect('', 'details', (48, 653, 330, 677), relative=0, thickness=1)
            pdf.setFillColorRGB(0, 0, 0)
            pdf.drawString(50, 620, 'Expected local target before merge: the second page.')
        else:
            pdf.bookmarkPage('details')
            pdf.addOutlineEntry('Details', 'details', level=1, closed=False)
            pdf.drawString(50, 660, f'This is the Details page of {name.title()}.')
        pdf.showPage()
    pdf.save()
    return stream.getvalue()

if __name__ == '__main__':
    for name in ('alpha', 'beta'):
        Path(f'{name}-handbook.pdf').write_bytes(make_source(name))

python reproduce_source.py

生成したbeta-handbook.pdfとalpha-handbook.pdfをこの順で結合ツールに入れ、結果を同じ作業ディレクトリにmerged.pdfとして保存します。ツール側でファイル順を並べ替えられる場合も、最終的にBeta、Alphaの順になっているか確認してください。エージェントが実測したのはこの結合ツールでの1回だけです。他のツールで期待値と違う結果が出ても、期待値を結果に合わせて書き換えず、まずページ順としおりが保持されているかを確認します。

次をoutline_snapshot.pyとして保存します。

"""Read-only list snapshot; this is a diagnostic dump, not a generic PDF validator."""
import json
import re
import sys
from pypdf import PdfReader

def outline_rows(reader):
    tokens = []
    for page in reader.pages:
        matches = re.findall(r'Identity token: ((?:ALPHA|BETA)-[12])\b', page.extract_text() or '')
        if len(matches) != 1:
            raise ValueError('This example requires one synthetic identity token per page')
        tokens.append(matches[0])
    rows = []
    def walk(items, depth=0):
        for item in items:
            if isinstance(item, list):
                walk(item, depth + 1)
                continue
            index = reader.get_destination_page_number(item)
            token = tokens[index] if index is not None and 0 <= index < len(tokens) else None
            rows.append({'depth': depth, 'title': item.title,
                         'page_index': index, 'target_token': token})
    walk(reader.outline)
    return rows

if __name__ == '__main__':
    rows = outline_rows(PdfReader(sys.argv[1]))
    print(json.dumps(rows, ensure_ascii=False, indent=2))
    by_title = {row['title']: row['target_token'] for row in rows}
    print(json.dumps({'outline_nodes': len(rows), 'unique_titles': len(by_title),
                      'lossy_title_dictionary': by_title}, ensure_ascii=False, indent=2))

python outline_snapshot.py merged.pdf

識別子はこの架空PDF専用です。一般の文書に使う場合は、確認したいページを特定できるテキストか、別の識別方法に置き換えてください。スキャン画像ではテキスト抽出が空になることがあるので、この方法は使えません。

pypdfの公式APIによると、outlineはしおりを含むリストとして提供され、get_destination_page_number()で移動先のページを取得できます。子リストに入るたびにdepthを増やし、全ノードを順に追加します。indexを解決できない場合はtarget_tokenをNoneにして、成功したかのような値は補いません。

このコードは診断用に情報を出力するだけです。元のアクション種別やPDFの仕様適合性を判定するものではないので、表示された行だけで「あらゆるPDFのしおりが正常」とは結論づけられません。

辞書にした場合、実際に何が消えるか

保存した実ファイルでは、outline_nodesが4、unique_titlesが2でした。辞書に残ったのは次の2項目です。

{
  "Overview": "ALPHA-1",
  "Details": "ALPHA-2"
}

消えたのはBetaの2ノードです。PDFから消えたのではなく、診断側が同じtitleをキーにして上書きしたためです。辞書の中身だけを期待値と比べると、結合に問題がなくても誤判定したり、必要なノードの欠落を見逃したりします。

比較するなら、次のコードを同じファイルの末尾に追記し、リストから必要な組を取り出します。この期待値は、この4ページの架空例にだけ当てはまります。

expected = [
    (0, "Overview", "BETA-1"),
    (1, "Details", "BETA-2"),
    (0, "Overview", "ALPHA-1"),
    (1, "Details", "ALPHA-2"),
]
actual = [(r["depth"], r["title"], r["target_token"]) for r in rows]
assert actual == expected

しおりとページ内リンクは別に確認する

同じ実ファイルに対し、別の限定的な検査で、生の/Dest配列または単純な/GoToからページ参照を読み取りました。しおりの4ノードに加えて、ページ内リンク2本もindex 0から1、index 2から3へ対応していました。上の短い診断コードはページ内リンクを調べていないので、その検査の代わりにはなりません。

反例は実ファイルをもとにメモリー上で作りました。2つ目のOverviewの移動先だけを変える、しおりは残してリンク先だけを変える、ノードやリンクを消す、ページ順を変える、といった変更で、それぞれ該当する検査が失敗しました。名前付き移動先、URIアクション、アクションチェーンは、この限定検査の対象外です。確認したのは10ケースで、ブラウザーでの実行を10回繰り返したわけではありません。

4ページの出力はPopplerで85 DPIに描画し、対応する入力ページとのRGBピクセル一致と、画像の目視も確認しました。ただし、PDFリーダー上でしおりやリンクをクリックする試験はしていません。移動先座標、ズーム、クリック範囲、フォーム、署名、アクセシビリティ構造、他のリーダーでの挙動までは保証しません。

タイトルをキーにする前に、重複があり得るかを確かめ、実際のダウンロードから順序と深さを残した行を取り出す。そのうえでページ内容・しおり・リンクの期待値を分けておけば、検査そのものが情報を落としていないかも確認できます。
英語版では、結合後のナビゲーションをページ順とは別に検査する方法を扱っています。