Filter — 詳細リファレンス

概要

このページは、NextPDF Pro の Filter モジュール（名前空間 NextPDF\Pro\Filter）のコントラクトレベルのリファレンスです。この API 面は 2 つのクラスで構成されます。DecodeParms は、PDF の /DecodeParms ディクショナリ断片を、イミュータブルで境界チェック済みの値オブジェクトへと解析します。PngPredictor は、FlateDecode 済みのストリームバイトに対して PNG プレディクターファミリー（タグ 10～15）を逆処理します。本モジュールは Pro の Diff および Classifier エクストラクターのために提供されるものであり、汎用のストリームフィルターフレームワークではありません。このページでは、公開 API、観測可能な挙動コントラクト、および型付けされた失敗モードを規定します。使用方法のガイダンスとコードサンプルは Filter ケーパビリティページ に掲載されています。

提供状況とライセンス

このケーパビリティは NextPDF Pro（nextpdf/pro）に含まれ、Pro ティアのライセンスエンベロープによって有効化されます。そのエンタイトルメントを持たないデプロイメントでは、このケーパビリティのクラスは読み込まれません。エディションを比較してライセンスを取得。

このモジュールをゲートするランタイムのケーパビリティフラグはありません。Filter のクラスは、nextpdf/pro がインストールされていれば常に利用可能です。

公開 API サーフェス

シンボル	パラメータ	既定の挙動	戻り値	スローまたは失敗	備考
DecodeParms	コンストラクター: int $predictor = 1, int $columns = 1, int $colors = 1, int $bitsPerComponent = 8	既定値は「プレディクターなし」を表す	—	—	final readonly。4 つのプロパティはすべて public かつイミュータブル
DecodeParms::fromDictionary()	string $raw — 生のディクショナリテキスト。周囲のオブジェクトボディも許容	存在しないキーは既定値を維持。マッチングは空白に寛容	self	InvalidArgumentException	解析時のチョークポイント。境界は挙動コントラクトに記載
DecodeParms::isPngPredictor()	なし	純粋な述語。I/O なし	bool — プレディクター 10～15 で true	—	逆フィルターを呼び出す前にこれで分岐
PngPredictor	—	ステートレス	—	—	final。唯一のエントリポイントは静的な inverse()
PngPredictor::inverse()	string $raw, int $columns, int $colors, int $bitsPerComponent, int $predictor	行ごとのタグに基づいて 1 行ずつ逆フィルター。空の入力は空文字列を返す	string — フィルタータグを取り除いた再構成済みペイロード	InvalidArgumentException	受け付けるのはプレディクター 10～15 のみ。TIFF プレディクターは対象外

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

public function __construct(
    public int $predictor = 1,
    public int $columns = 1,
    public int $colors = 1,
    public int $bitsPerComponent = 8,
) {}

public static function fromDictionary(string $raw): self

public function isPngPredictor(): bool

public static function inverse(
    string $raw,
    int $columns,
    int $colors,
    int $bitsPerComponent,
    int $predictor,
): string

挙動コントラクト

/DecodeParms の解析

DecodeParms::fromDictionary() は、生のディクショナリテキスト内で認識される 4 つのキーを整数としてマッチングします。すなわち /Predictor、/Columns、/Colors、/BitsPerComponent です。これらは、ISO 32000-2:2020 §7.4.4.4 が LZWDecode および FlateDecode フィルターに対して定義するプレディクターパラメータです。マッチングは空白に寛容であり、周囲の PDF トークンがあっても機能します。存在しないキーは既定値を維持します。すなわちプレディクター 1、列数 1、色数 1、コンポーネントあたりビット数 8 です。存在する値は解析時にフェイルクローズで検証され、そのジオメトリが逆フィルターの行割り当てに到達する前に処理されます。

• 認識されるいずれかのキーに存在する負の値は拒否されます。
• 1,000,000 を超える /Columns は拒否されます。
• 32 を超える /Colors は拒否されます。
• {1, 2, 4, 8, 16} の範囲外の /BitsPerComponent は拒否されます。
• 64,000,000 バイトを超える導出された行ストライドは拒否されます。

isPngPredictor() は、解析されたプレディクターが 10 から 15 の場合に true を返します。プレディクター 1（予測なし）およびプレディクター 2（TIFF グループ）は false を返します。

行のジオメトリ

PngPredictor::inverse() は、各行の先頭に 1 バイトのフィルタータグが付いた FlateDecode 済みのバイトストリームを消費します。そしてタグを取り除いた再構成済みペイロードを出力します。行ペイロードの幅は ceil(columns * colors * bitsPerComponent / 8) バイトであり、行ストライドはこれに 1 バイトのタグを加えたものです。左隣オフセット（ピクセルあたりバイト数）は max(1, floor(colors * bitsPerComponent / 8)) であるため、サブバイトのパッキングは 1 バイトに切り捨てられます。フィルタリングはビット深度にかかわらずバイト単位で行われ、PNG フィルターのセマンティクスと一致します。

行ごとの再構築

タグ	フィルター	再構成
0	None	パススルー
1	Sub	recon[x] = filt[x] + recon[x-bpp]
2	Up	recon[x] = filt[x] + prior[x]
3	Average	recon[x] = filt[x] + floor((recon[x-bpp] + prior[x]) / 2)
4	Paeth	recon[x] = filt[x] + Paeth(left, up, up-left)

すべての加算はモジュロ 256 で行われます。最初の行、および最初のピクセルより左のバイトについては、存在しない隣接バイトは W3C PNG §9.2 に従ってゼロとして読み取られます。逆操作は行ごとのタグによって完全に駆動されます。これは、固定プレディクター（10～14）と Optimum（15）の双方について ISO 32000-2:2020 §7.4.4.4 に準拠する挙動であり、ライターによるタグの差異は許容されます。

検証のレイヤー化

パラメータ検証は、設計上 2 つのレイヤーで実行されます。DecodeParms は解析時のチョークポイントであり、まず悪意ある大きさの値を拒否します。PngPredictor::inverse() は、第 2 のレイヤーとして独自のチェックを保持します。すなわち、4 つのパラメータすべてに対する範囲チェック、ストライドの積を形成する前に個々の因子を PHP_INT_MAX と比較するオーバーフローガード、同じ 64,000,000 バイトの行あたり上限、および行バッファが割り当てられる前に入力全体より大きい宣言済みストライドを拒否する入力比例の境界です。

決定性

どちらのエントリポイントも、入力の純粋な静的関数です。I/O、ロギング、グローバル状態はありません。実行時間は入力長に対して線形であり、バイトあたりの定数は小さいものです。/DecodeParms の解析は、いくつかの境界付き正規表現マッチングです。バジェットはフロントマターの performance_budget に記載されています。

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

このモジュールにおけるすべての失敗は、問題となった値をメッセージ内に明示して InvalidArgumentException を発生させます。

• fromDictionary() は、認識されるいずれかのキーに存在する負の値を拒否します。
• fromDictionary() は、1,000,000 を超える /Columns と 32 を超える /Colors を拒否します。
• fromDictionary() は、{1, 2, 4, 8, 16} の範囲外の /BitsPerComponent と、64,000,000 バイトを超える導出された行ストライドを拒否します。
• inverse() は、10～15 の範囲外のプレディクターを拒否します。TIFF プレディクター（2）はここでは決して逆フィルターされません。まず isPngPredictor() で分岐してください。
• inverse() は、1 未満の columns または colors、および正当な集合の範囲外の bitsPerComponent を拒否します。
• inverse() は、ストライドの積がプラットフォームの整数をオーバーフローするジオメトリを、割り当ての前に拒否します。
• inverse() は、実際の入力長とは無関係に、64,000,000 バイトの行あたり上限を超える行ストライドを拒否します。
• inverse() は、空の入力に対して空文字列を返します。これはエラーではありません。
• inverse() は、入力全体より大きい宣言済みの行ストライドを、オフセット 0 における切り詰められた行として失敗させます。
• inverse() は、末尾の部分的な行を、オフセットとバイト数を明示して切り詰められた行として失敗させます。
• inverse() は、不明な行ごとのフィルタータグ（0～4 以外）を、タグ値と行オフセットとともに失敗させます。
• 宣言された /DecodeParms のジオメトリと実際のストリームレイアウトとの不一致は、パラメータエラーまたは切り詰めエラーとして表面化し、暗黙のうちに破損した出力になることはありません。
• Average フィルターは整数除算を使用し、PNG 仕様の floor セマンティクスと一致します。
• このモジュールでは暗号操作は一切行われません。FIPS 制約下のデプロイメントでも挙動は同一です。

適合性

主張	標準	条項
/Predictor フィルターパラメータはプレディクターアルゴリズムを選択します。許容される値はプレディクター値テーブルに由来します。	ISO 32000-2:2020	§7.4.4.4
PDF は 2 つのプレディクターグループを定義します。TIFF グループは単一のプレディクター 2 関数であり、PNG グループはタグ 10～15 です。	ISO 32000-2:2020	§7.4.4.4
/BitsPerComponent の有効な値は 1、2、4、8、16 で既定は 8、/Colors は 1 以上で既定は 1、/Columns の既定は 1 です。	ISO 32000-2:2020	§7.4.4.4
フィルタータイプ 0～4 の再構成関数はバイト単位でモジュロ 256 で動作します。存在しない左バイトおよび前の行のバイトはゼロとして読み取られます。	W3C PNG (Third Edition)	§9.2
Paeth フィルタータイプは、左、上、左上の隣接バイトの PaethPredictor を計算し、最も近いものを選択します。	W3C PNG (Third Edition)	§9.4

すべての条項は言い換えであり、NextPDF は規範的テキストを転載しません。これらはケーパビリティの記述であって認証ではありません。NextPDF はいかなる認証も保有せず、また付与しません。再構成の計算とパラメータの既定値の適合性は、ユニットスイートによって検証されます。完全な PDF ストリームフィルターフレームワーク、および TIFF プレディクターの逆処理は、本モジュールの対象外です。

開発上の注意

• どちらのクラスも nextpdf/pro 3.0.0 以降に含まれ、3.1.0 でも最新です。
• 本モジュールは、入力がプレディクターを伴う場合に、Pro の Diff および Classifier エクストラクターによって利用されます。
• inverse() を呼び出す前に isPngPredictor() で分岐してください。プレディクター 1 と TIFF プレディクターは PNG の逆処理を必要としません。
• 本モジュールは自身の行あたりの割り当てを制限します。信頼できないストリームでプレディクターを逆処理する呼び出し側は、Pro のエクストラクターがそうしているように、上流で展開後の入力サイズを制限すべきです。
• 固定プレディクター（10～14）と Optimum（15）は 1 つのコードパスを共有します。行ごとのタグが両方の場合で再構成を駆動します。
• 内部メカニズムの詳細はソースリポジトリの内部ドキュメントに留まり、本マニュアルの対象外です。

公開の境界

このページは、外部から観測可能な挙動とサポート対象の公開 API 面のみを記載します。内部の名前空間パス、ヘルパークラス、メカニズムテーブル、Runbook のファイル名、およびチケットのプレフィックスは対象外です。

関連項目

• Filter（ケーパビリティ） — インストール、クイックスタート、および本番環境での使用サンプル。
• Diff — 詳細リファレンス — 逆フィルターの利用者。
• Classifier — 詳細リファレンス — 逆フィルターの利用者。