コンテンツにスキップ
NextPDF
getnextpdf.com

Pro エディション

Converter — 詳細リファレンス

概要

「概要」という見出しのセクション

NextPDF\Pro\Converter は、既存の PDF を位置情報付きの HTML、簡略化された SVG、またはプレーンテキストにエクスポートし、ドキュメントのコンテンツを型付きの構造領域へセグメント化します。この詳細リファレンスでは、公開 API サーフェス、演算子カバレッジマトリクス、挙動の契約、および失敗モードを列挙します。これはコンテンツ抽出エクスポーターであり、ピクセル単位で正確なレンダラーではありません。

提供状況とライセンス

「提供状況とライセンス」という見出しのセクション

この機能は NextPDF Pro（nextpdf/pro）で提供され、Pro ティアのライセンスエンベロープで有効化されます。そのエンタイトルメントを持たないデプロイメントでは、この機能のクラスは読み込まれません。エディションを比較してライセンスを入手。

このモジュールをゲートするランタイムのケーパビリティフラグはありません。Pro パッケージがインストールされライセンスされていれば、いつでも Converter クラスは解決されます。

公開 API サーフェス

「公開 API サーフェス」という見出しのセクション
シンボルパラメーターデフォルトの挙動戻り値スロー/失敗条件備考
PdfToHtmlConverter::convert()string $pdfData, ?ConversionConfig $config = nullテキストを含む全ページを 1 つの自己完結型 HTML5 ドキュメントへエクスポートConversionResult（ターゲット Html5）$pdfData が空の場合に InvalidArgumentExceptionnull 設定時は ConversionTarget::Html5 がデフォルト
PdfToSvgConverter::convert()string $pdfData, int $pageIndex = 0, ?ConversionConfig $config = null1 ページをスタンドアロンの SVG ドキュメントへエクスポートConversionResult（ターゲット Svg。pageCount は常に 1）$pdfData が空の場合に InvalidArgumentException範囲外の $pageIndex は背景のみの SVG を生成
PdfToTextConverter::convert()string $pdfData全ページからデコード済みテキストを抽出し、改ページマーカーで区切りConversionResult（ターゲット PlainText）$pdfData が空の場合に InvalidArgumentExceptionリテラル文字列エスケープをデコードするのはこのターゲットのみ
PdfToTextConverter::extractPage()string $pdfData, int $pageIndex0 始まりの 1 ページ分のデコード済みテキストを抽出stringスローしない。存在しないページや空入力には '' を返すconvert() と異なり、空入力ガードなし
DocumentSegmentationEngine::segment()string $pdfData空間的およびフォントのヒューリスティックを用いてページコンテンツを型付き構造セグメントへ分類NextPDF\Pro\Interop\V1\Segment\DocumentSegmentation入力が空、または PDF 構造を解析できない場合に InvalidArgumentExceptionルールベース。AI 推論は行わない
ConversionConfig::__construct()ConversionTarget $target, bool $embedFonts = false, bool $embedImages = true, float $scaleFactor = 1.0, string $cssClass = 'pdf-page'イミュータブルな変換設定ConversionConfig—embedFonts と embedImages は受け付けられるが 3.1.0 では未使用
ConversionResult::size()—生成された出力のバイト長int—公開の readonly フィールド：output、target、pageCount、processingTimeMs
ConversionResult::isValid()—出力が空でないかどうかを報告bool—HTML と SVG のドキュメントシェルは決して空にならないため、代わりに pageCount を確認
ConversionTarget文字列バックの列挙ケース Html5、Svg、PlainTextエクスポートターゲットを選択mimeType(): string、fileExtension(): string—fileExtension() は html、svg、txt にマッピング

エントリーポイントのシグネチャ：

public function convert(string $pdfData, ?ConversionConfig $config = null): ConversionResult
public function convert(
    string $pdfData,
    int $pageIndex = 0,
    ?ConversionConfig $config = null,
): ConversionResult
public function convert(string $pdfData): ConversionResult
public function extractPage(string $pdfData, int $pageIndex): string
public function segment(string $pdfData): DocumentSegmentation

挙動の契約

「挙動の契約」という見出しのセクション

入力は生の PDF バイト列で、出力は ConversionResult 値オブジェクトです。3 つのエクスポートコンバーターは同じスキャン方式を共有します。stream/endstream の境界を特定し、BT/ET のテキストブロックを切り出し、テキスト表示演算子を解析します。これらはクロスリファレンステーブルを解析せず、圧縮ストリームを展開しません。DocumentSegmentationEngine はこれと異なり、トレーラー、カタログ、ページツリーを解決し、分類の前に FlateDecode のページコンテンツを展開します。

演算子のカバレッジ：

PDF operatorHTMLSVGText
Tj（文字列表示）はいはいはい
TJ（配列表示）はいはいはい
'（移動＋表示）いいえいいえはい
Td / Tm（位置指定）はいはい該当なし
Tf（フォントサイズ）はいはい該当なし
re（矩形）いいえはいいいえ
m / l（線）いいえはいいいえ
RG（RGB ストローク）いいえはい（矩形/線のストロークに適用）いいえ
曲線、シェーディング、クリッピング、画像いいえいいえいいえ
  • 位置指定。 各 BT/ET ブロックは、最初にマッチした Td または Tm から 1 つの位置を解決します。両方が現れる場合は Tm が優先されます。Y 軸は PDF ユーザー空間から左上原点の出力空間へ反転されます。Tf が存在しない場合、フォントサイズはデフォルトで 12 pt になります。
  • ページジオメトリ。 HTML と SVG は、scaleFactor を乗じた A4 のページボックス（595 x 842 pt）を前提とします。SVG ルートは、白い背景矩形の上に、対応する viewBox、幅、高さの属性を保持します。
  • ストロークカラー。 RG 演算子は位置ベースで解決されるため、ストロークカラーを複数回変更するストリームでは、各矩形と線は直前に現れた演算子で着色されます。各成分は 16 進変換の前に 0..1 の範囲にクランプされます。矩形の塗りは常に黒で、rg 塗り演算子は評価されません。
  • 文字列デコード。 テキストターゲットは、ISO 32000-2:2020 §7.3.4.2 に従ってリテラル文字列エスケープをデコードします。名前付きエスケープ、1 バイトにマスクされる 8 進 \ddd コード、バックスラッシュによる行継続、および単独バックスラッシュの除去です。HTML と SVG のターゲットは、HTML または XML エスケープを施したうえで括弧内の生バイトを出力し、エスケープはデコードしません。
  • 出力の組み立て。 テキストターゲットは、ブロックのテキストをスペースで連結し、ページを空行で囲んだ --- Page Break --- で連結します。HTML ターゲットは、設定された CSS クラスと data-page 属性を持つページごとのコンテナ内に、テキストブロックごとに 1 つの絶対配置された <div> を出力します。
  • 決定性。 同一の入力と設定に対して、生成される HTML、SVG、テキストのバイト列は安定しています。processingTimeMs は実時間の計測値であり、決定的なサーフェスからは除外されます。

エッジケースと失敗モード

「エッジケースと失敗モード」という見出しのセクション
  • 空の入力：すべての convert() と segment() エントリーポイントは InvalidArgumentException（“PDF data must not be empty”）を発生させます。部分的な出力は生成されません。例外は extractPage() で、スローせずに '' を返します。
  • BT/ET を含まないストリームは、HTML およびテキストのコンバーターによってスキップされます。そのようなストリームのみを含む PDF は、pageCount がゼロとなり、空のテキスト出力またはページのない HTML シェルになります。
  • isValid() は出力が空でないことのみを確認します。HTML と SVG のコンバーターは常にドキュメントシェルを出力するため、テキストが見つからなくても isValid() は true のままです。空の抽出を検出するには pageCount（HTML、テキスト）を使用してください。
  • FlateDecode のコンテンツは、3 つのエクスポートコンバーターでは展開されません。圧縮のみの PDF は、これらを通してもコンテンツがほとんど、あるいはまったくエクスポートされません。segment() は FlateDecode のページストリームを展開します。
  • segment() は、ストリームごとのサイズ、圧縮率、および累積的な予算によって展開を制限します。上限を超えるストリームは、メモリを枯渇させる代わりに空のページコンテンツに縮退し、スローはしません。
  • segment() は、トレーラー、クロスリファレンスオフセット、ドキュメントカタログ、またはページツリーを解決できない場合に InvalidArgumentException を発生させます。
  • ページのインデックス付けはコンバーターごとに異なります。HTML とテキストのコンバーターはテキストを含むストリームのみを数えますが、SVG コンバーターは認識対象のグラフィックスまたはテキスト演算子を含むストリームを数えます。したがって、同じ $pageIndex でも異なるストリームを指すことがあります。
  • TJ の数値カーニング調整は破棄され、配列の文字列はグリフ間のスペースなしで連結されます。
  • グリフから Unicode へのマッピングは適用されません。カスタムエンコーディングのフォントで組まれたテキストは、生のバイト列としてエクスポートされます。
  • 回転したテキスト、テキスト以外の変換、および段組みのフローは、最初にマッチした位置による近似で扱われ、元のレイアウトを再現しない場合があります。
  • このモジュールでは暗号操作は一切行われないため、FIPS モードにモジュール固有の挙動はありません。

準拠性

「準拠性」という見出しのセクション

NextPDF は、引用された条項に対して機能を文書化しています。サポートに関する記述は実装された挙動を説明するものであり、準拠性テストの結果でも認証でもなく、NextPDF はいかなる認証も保有していません。

主張仕様条項ステータス
Tj テキスト表示演算子の解析ISO 32000-2:2020 §9.4検証済み（ユニットスイート）
TJ 配列テキスト表示演算子の解析ISO 32000-2:2020 §9.4検証済み（ユニットスイート）
' 移動＋表示演算子の解析（テキストターゲットのみ）ISO 32000-2:2020 §9.4検証済み（ユニットスイート）
リテラル文字列エスケープのデコード（テキストターゲットのみ）ISO 32000-2:2020 §7.3.4.2実装済み。バイトはそのまま返され、文字セットの解釈は下流で実施
re、m、l パス構築の認識（SVG ターゲット）ISO 32000-2:2020 §8.5.2部分的：曲線、パスの閉じ、塗りモードの評価を伴わないサブセット
完全なテキストステートマシンおよびページレンダリング—非対応（対象外）

Converter はテキスト表示演算子を解析してコンテンツを復元しますが、完全なテキストステートマシンは実装していないため、グリフの配置は仕様どおりに厳密ではなく近似的です。

開発メモ

「開発メモ」という見出しのセクション
  • 解析は PDF のバイト長に対して線形です。メモリ使用量は、入力と生成される出力文字列に比例します。フロントマターの performance_budget は、一般的なオフィス文書に対する呼び出しごとの基準値です。
  • コンバーターは、境界付きの strpos/substr スキャンで信頼できない PDF バイト列を解析します。埋め込まれた JavaScript は実行せず、外部参照も辿りません。エクスポートされた HTML は信頼できないコンテンツとして扱い、送信先に応じてエスケープしてください。
  • HTML 出力は htmlspecialchars（ENT_QUOTES、HTML5）でエスケープされ、SVG テキストは XML エスケープされます。設定された cssClass は出力前にエスケープされます。
  • 設定の消費：scaleFactor は HTML と SVG のターゲットに適用され、cssClass は HTML のみに適用されます。embedFonts と embedImages は予約済みで現在は未使用です。target フィールドは、コンバーター自身の出力フォーマットを上書きしません。
  • エクスポートコンバーターは 1.9.0 から提供され、DocumentSegmentationEngine は 2.1.0 から提供され、Pro MCP の segment_document ツールと Interop のセグメンテーション契約を支えています。
  • 同じ名前空間の PdfPageExtractor と PdfPageData はセグメンテーションエンジンの内部実装であり、公開 API ではありません。

公開範囲の境界

「公開範囲の境界」という見出しのセクション

このページは、外部から観測可能な挙動とサポート対象の公開 API サーフェスのみを文書化しています。内部の名前空間パス、ヘルパークラス、メカニズムの表、ランブックのファイル名、およびチケットの接頭辞は対象外です。

関連項目

「関連項目」という見出しのセクション