Common — 詳細リファレンス

概要

このページは、NextPDF\Enterprise\Common 名前空間の詳細リファレンスです。この名前空間は 1 つのパブリックシンボル、BoundingBox 値オブジェクトを提供します。これは、ページ上での解像度非依存な空間配置のための、イミュータブルで正規化された矩形です。Enterprise の Intelligence および Privacy サーフェスは、これをテーブルセルのジオメトリ、エンティティの位置、および墨消しゾーンに利用します。このモジュールは I/O を一切行わず、ドキュメントコンテンツを保持せず、暗号処理にも関与しません。ワークフローのガイダンスについては、まず Common 機能ページ をお読みください。

提供状況とライセンス

この機能は NextPDF Enterprise（nextpdf/enterprise）に同梱されており、Enterprise ティアのライセンスエンベロープで有効化されます。その権利を持たないデプロイメントでは、この機能のクラスは読み込まれません。エディションを比較してライセンスを取得。

プリミティブ自体はライセンスゲートを行いません。ゲートは、これを利用する Enterprise サーフェスで行われます。このクラスには Core ティアや Pro ティアの同等品はありません。nextpdf/enterprise パッケージにのみ同梱されており、Core のジオメトリ型を複製または置き換えるものではありません。

パブリック API サーフェス

シンボル	パラメーター	デフォルトの挙動	戻り値	送出または失敗の条件	備考
BoundingBox::__construct	float $x、float $y、float $width、float $height	各値を [0.0, 1.0] に対して検証し、その後に両方のエッジ合計を検証	BoundingBox	値が範囲外、またはエッジ合計が 1.0 + 1e-9 を超える場合に InvalidArgumentException	4 つの値すべてが public readonly プロパティに
BoundingBox::area	なし	width に height を乗算	float	宣言なし	退化したボックスには 0.0 を返却
BoundingBox::contains	self $other	$other がこのボックスの完全に内側にあるかを判定	bool	宣言なし	右辺と下辺は +1e-9 を許容。左辺と上辺は厳密に比較
BoundingBox::overlaps	self $other	厳密な矩形の交差を判定	bool	宣言なし	いずれかの側が面積ゼロのオペランドの場合は false を返却

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

final readonly class BoundingBox
{
    public function __construct(
        public float $x,
        public float $y,
        public float $width,
        public float $height,
    )

    public function area(): float

    public function contains(self $other): bool

    public function overlaps(self $other): bool
}

挙動コントラクト

座標モデル

• 4 つの値はすべて、ページ寸法に対する割合であり、[0.0, 1.0] の範囲に正規化されています。
• x はボックスの左辺を、y は上辺を位置づけます。x + width と y + height は右辺と下辺を画定します。
• 正規化により、すべての操作が解像度に依存しなくなります。同じボックスは、あらゆるレンダリングサイズや DPI において同じページ領域を指し示します。

構築

• コンストラクターは唯一の検証ポイントです。[0.0, 1.0] の範囲外の座標は InvalidArgumentException を発生させ、メッセージには問題のあるコンポーネントと受け取った値が示されます。
• 1.0 + 1e-9 を超えるエッジ合計は InvalidArgumentException を発生させ、メッセージには両方のオペランドとその合計が報告されます。1e-9 の許容範囲は、上流の正規化演算による浮動小数点の丸めを吸収します。
• 構築されたインスタンスはイミュータブルです。このクラスは final readonly であるため、プロパティへの書き込みは PHP の Error で失敗し、クラスを拡張することはできません。

述語

• area() は width * height を返します。副作用のない純粋な計算です。
• contains() は、他方のボックスがこのボックスの完全に内側にある場合に true を返します。右辺と下辺の比較は +1e-9 の許容範囲を持ち、左辺と上辺の比較は厳密です。すべてのボックスは自身を包含し、面積ゼロのボックスも包含され得ます。
• overlaps() は、厳密な矩形の交差で true を返します。4 つのエッジ比較はすべて厳密であり、許容範囲はありません。いずれかのオペランドの面積がゼロの場合、結果は false になります。
• したがって、包含はオーバーラップを意味しません。他のボックスの内側にある退化したボックスは包含されますが、決してオーバーラップしません。
• いずれのメソッドも I/O、永続化、ネットワークアクセス、ロギングを行わず、ドキュメントコンテンツや個人データを保持しません。このサーフェスにオペレーターが所有するリソースはありません。

コンシューマー

Enterprise モジュールは、モジュールごとにジオメトリを定義するのではなく、このプリミティブを共有します。Intelligence では、TableExtractor の出力が TableCell と KeyValuePair の値にこれを持ちます。Privacy では、PiiEntity、RedactionFinding、ZoneRedaction がこれでコンテンツの位置を特定し、RedactionEngine がそれらの位置を利用します。これらのサーフェスのコントラクトは、それぞれのリファレンスページに文書化されています。

エッジケースと障害モード

• 範囲外のコンポーネント。 4 つの値のいずれかが 0.0 未満または 1.0 を超える場合、構築時に InvalidArgumentException を発生させます。INF と -INF は同じガードによって拒否されます。
• エッジ合計のオーバーフロー。 x + width または y + height が 1.0 + 1e-9 を超える場合、InvalidArgumentException を発生させます。1e-9 の許容範囲内の合計は正常に構築されます。
• NAN 入力。 範囲ガードは順序比較を使用し、NAN との順序比較はすべて false になるため、NAN コンポーネントは拒否されません。そのようなインスタンスは NAN の面積を報告し、両方の述語から false を返します。構築前に上流の浮動小数点ソースをサニタイズしてください。
• 面積ゼロのボックス。 幅または高さがゼロのボックスは、自身を含め何ともオーバーラップしません。それでも、退化していないボックスに包含されることはあります。交差ロジックではこの非対称性を考慮してください。
• エッジが接するボックス。 辺または角のみを共有する 2 つのボックスはオーバーラップしません。交差判定は厳密です。
• 包含許容範囲の非対称性。 左辺または上辺が外側のボックスからわずかでもはみ出す内側のボックスは、包含判定に失敗します。1e-9 の許容は右辺と下辺にのみ適用されます。
• FIPS モード。 このモジュールは暗号操作を一切行いません。FIPS モードはその挙動を変更しません。

適合性

このモジュールは規範的な標準を実装しておらず、適合性の主張も行いません。検証済みのジオメトリプリミティブです。これを利用する機能の PDF 座標空間セマンティクスは、それらの機能のページに文書化されています。NextPDF はいかなる認証も保有せず、付与もしません。サポートは適合性ではなく、適合性は認証ではありません。このサーフェスには輸出管理上の制限は適用されず、このリファレンスは法的意見ではありません。

開発上の注記

• このクラスは nextpdf/enterprise 2.2.0 以降で利用可能であり、そのパブリックサーフェスは 3.1.0 でも変更されていません。
• 構築前に、絶対的なページ空間座標をページ相対の割合に変換してください。このクラスは範囲を検証しますが、セマンティクスは検証しません。もっともらしいが誤った領域を検出することはできません。
• インスタンスは単なる値オブジェクトであり、構築コストは低くなっています。プールやキャッシュを行わないでください。
• 同一の座標を持つ 2 つのインスタンスは、緩い等価性（==）では等しいと比較されますが、厳密な同一性（===）では区別されます。テストでは座標の比較を優先してください。
• 真偽値の述語を超えるジオメトリについては、パブリックプロパティから辺を導出してください。右辺は x + width、下辺は y + height です。
• 許容範囲の境界をテストする際は、エッジ合計ガードと包含の右辺/下辺の比較の両方について、1e-9 の両側を検証してください。

公開範囲

このページは、外部から観測可能な挙動とサポート対象のパブリック API サーフェスのみを文書化しています。内部の名前空間パス、ヘルパークラス、メカニズムテーブル、ランブックのファイル名、チケットのプレフィックスは範囲外です。

関連項目

• Common 機能ページ
• Intelligence — 詳細リファレンス
• Privacy — 詳細リファレンス
• Validation — 詳細リファレンス
• Evidence — 詳細リファレンス