FAQ

pdfvision は PDF-to-text ツールですか、それとも vision ツールですか？

両方ですが、中心にあるのは証拠です。pdfvision は利用できるネイティブテキストを抽出し、そのうえでレイアウト、画像/ベクターのジオメトリ、警告、レンダリング画像、OCR、検索一致、PDF 機能メタデータを公開します。エージェントは、それらを見てテキストだけで十分かどうかを判断できます。

抽出テキストが空になるのはなぜですか？

スキャン、画像中心、暗号化、独自グリフエンコーディングなどが原因です。概要フィールドと pages[].warnings を確認し、--render, --ocr, --layout を試してください。

ページに empty_but_visual_content がある場合は、レンダリングまたは OCR が必要です。グリフ関連の警告がある場合は、ネイティブテキストを信頼する前にレンダリング画像や OCR と比較してください。

--layout はいつ使いますか？

段組み、表、フォーム、脚注、繰り返しヘッダーやフッター、縦書き CJK、配置で意味が変わるページで使います。

--layout は、論文、レポート、財務諸表、フォーム、スライド書き出しのように、raw text stream が視覚順とずれる可能性がある PDF で特に有効です。

OCR はいつ使いますか？

ネイティブテキストが無い、少ない、スキャン風、またはレンダリング画像と明らかに違う場合に使います。

OCR はネイティブテキストの横に追加され、置き換えません。エージェントはネイティブテキスト、OCR テキスト、confidence、警告を比較するべきです。

ページ全体ではなく領域だけをレンダリングするのはいつですか？

検索、レイアウト、画像 bbox、ベクター bbox、visual regions で重要な領域を特定した後に --render-region を使います。1 つの条項、表のセル、グラフラベル、フォーム値、図だけを検証したい場合は、ページ全体よりクロップのほうが適しています。

visual regions とは何ですか？

visual regions は、図、グラフ、表、フォームセクション、注釈、ダイアグラム、ラスター/ベクターのまとまりを含む可能性が高い、クロップ可能なページ領域です。画像を vision model に送る前に、エージェントがどこを見るべきかを見つける助けになります。

pdfvision は PDF を検索できますか？

はい。--search は pages[].matches[] にページ、source、一致テキスト、前後文脈、利用可能な bbox を出力します。検索対象には、ネイティブテキスト、表示されるフォームフィールド値、クリック可能な link target、FreeText 注釈、OCR 有効時の OCR テキストを含められます。

座標系はどうなっていますか？

bbox は、回転前の pdf.js page view 表示ボックスを基準とする生の page-view units で、左上が原点です。表示ボックスは、適用可能な場合は CropBox ∩ MediaBox、それ以外は MediaBox です。x は右、y は下に増えます。物理サイズのポイント数は「生の値 × pages[].userUnit（省略時は 1）」、ピクセル数は「生の領域 × UserUnit × render scale」です。bbox は変更せず --render-region に渡せます。回転ページでは、pdf.js の回転 viewport transform を使います。

キャッシュはどこにありますか？

OS の一時ディレクトリ配下に保存されます。PDFVISION_CACHE_DIR には専用ディレクトリを指す絶対パスを指定してください。危険な広域パスは拒否されます。所有者確認済みの .pdfvision-cache-root マーカーが再帰削除を許可します。マーカーのないカスタムルートは削除に採用せず、override 未指定時の従来の既定ルートだけを、認識済み旧形式の権限強化前後の走査後に採用できます。POSIX では group/other が書き込めるマーカーなしルートを拒否し、祖先が読み取り・open 可能で、現在のユーザーまたは root の所有かつ書き込み不可または安全な sticky 状態であることを求めます。quarantine 後の st_dev 不一致は再帰削除を拒否しますが、元のパスは移動済みで、同一 device の bind mount は検出できません。通常の POSIX mode semantics を前提とし、ACL・ネットワークファイルシステム権限・最終確認後の root/同一 UID の置き換えは対象外です。Windows は best effort です。削除は実行中の OCR と協調しないため、中断時は再実行してください。--no-cache は抽出キャッシュとリモート PDF キャッシュを回避しますが、OCR サポートファイルは検証済みのキャッシュルートに引き続き保存されます。

PDF パスワードはどう渡すべきですか？

プロセス引数に残らないよう --password-stdin を優先してください。

printf "your-password\n" | pdfvision encrypted.pdf --password-stdin --format json

どの出力形式を使うべきですか？

素早く人間が読む確認には Markdown、ツールやエージェント制御には JSON、明示的なタグを前提にした利用側やプロンプトには XML を使います。同じスカラーフィールドを持つオブジェクト配列が多い場合は TOON を検討し、実際の文書と対象モデルのコンテキストで各形式を比較してください。