Geo

概要

NextPDF Pro は、PDF ページ座標を地理座標にマッピングし、GEO サブタイプを持つ PDF measure 辞書を生成します。これにより、ビューアーがページ上の点から実世界の位置をレポートできるようになります。

提供状況とライセンス

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

Geo には機能ごとの個別ライセンスフラグはありません。Pro ティアのエンベロープが直接これを有効化します。

インストール

composer require nextpdf/pro:^3

概念の概要

地理空間 PDF は、ISO 32000-2 §12.8.2 で記述されている measure 辞書を保持します。これは、デバイス空間の点を地理座標参照系に結び付けます。NextPDF Pro は、そのデータを不変の値オブジェクトから構築します。

• GeoCoordinate — 緯度/経度/高度の三つ組です。構築時に緯度を [-90, 90]、経度を [-180, 180] の範囲で検証し、度分秒形式および 10 進数文字列形式での書式設定を提供します。
• GeoControlPoint — PDF 空間の点と GeoCoordinate のペアリングです。
• ProjectionType — 一般的な投影法（地理座標、UTM、横メルカトル、ランベルト正角円錐）の enum で、それぞれが EPSG コードにマッピングされます。
• GeoRegistration — コントロールポイントに加えて、投影法と測地系の基準（デフォルト WGS84）です。isValid() は、最小限のアフィン変換のために少なくとも 2 つのコントロールポイントを要求します。toPdfMeasureDictionary() は、/Subtype /GEO とコントロールポイント配列を持つ /Measure 辞書を出力します。

なぜこの仕組みなのか

NextPDF は、呼び出し元が供給した生の辞書からではなく、検証済みの不変の値オブジェクトから measure 辞書を構築します。GeoCoordinate は、構築時に範囲外の緯度または経度を拒否します。GeoRegistration::isValid() は 2 つ未満のコントロールポイントを拒否するため、不正なレジストレーションは劣化した /GEO 辞書を出力する代わりに、早期に失敗します。投影法は ProjectionType を通じて標準的な EPSG コードに解決され、座標参照系を推測せず明示的に保ちます。測地系はデフォルトで WGS84 ですが、名前付きフィールドのままであり、デフォルト以外の参照系は意図的な選択となります。このフェイルクローズドな姿勢が重要なのは、誤ったジオリファレンスは何もないよりも悪いからです。ビューアーは誤った実世界の位置を確信を持ってレポートしてしまいます。 設計の背景: 推測を拒否する API。

API サーフェス

クラス	責務
GeoCoordinate	書式設定付きの検証済み緯度/経度/高度。
GeoControlPoint	PDF 点 ↔ 地理点のペアリング。
ProjectionType	EPSG コード付きの投影法 enum。
GeoRegistration	/Measure /GEO 辞書を構築。

コードサンプル — クイックスタート

use NextPDF\Pro\Geo\{GeoRegistration, GeoControlPoint, GeoCoordinate, ProjectionType};

$reg = new GeoRegistration(
    controlPoints: [
        new GeoControlPoint(0.0, 0.0, new GeoCoordinate(40.0, -74.0, 0.0)),
        new GeoControlPoint(600.0, 800.0, new GeoCoordinate(41.0, -73.0, 0.0)),
    ],
    projection: ProjectionType::Geographic,
);
$dict = $reg->toPdfMeasureDictionary();

コードサンプル — 本番

if (! $reg->isValid()) {
    throw new RuntimeException('Geo registration needs at least two control points.');
}
$logger->info('geo.registered', [
    'projection' => $reg->projection->value,
    'datum'      => $reg->datum,
]);

エッジケースと落とし穴

• GeoCoordinate の構築は、範囲外の緯度または経度を拒否します。
• 2 つ未満のコントロールポイントは、無効なレジストレーションを生成します。
• デフォルトの測地系は WGS84 です。他の参照系の場合は明示的に設定してください。

パフォーマンス

辞書の生成は、コントロールポイントの数に対して線形です。

セキュリティに関する注意

Geo の入力は数値の座標データです。信頼できない入力に由来するコントロールポイントは、レジストレーションの前に検証してください。

適合性

振る舞い	参照	ステータス
地理空間 measure 辞書（GEO サブタイプ）	ISO 32000-2 §12.8.2	整合（言い換え）

振る舞いの契約

• GeoCoordinate は、構築時に緯度を [-90, 90]、経度を [-180, 180] の範囲で検証し、DMS および 10 進数文字列形式での書式設定を提供します。
• GeoControlPoint は、PDF 空間の点を GeoCoordinate とペアリングします。
• GeoRegistration は、コントロールポイントに加えて、（EPSG コードにマッピングされる）ProjectionType と、デフォルトで WGS84 の測地系の基準を保持します。isValid() は少なくとも 2 つのコントロールポイントを要求します。toPdfMeasureDictionary() は、/Subtype /GEO とコントロールポイント配列を持つ /Measure 辞書を出力します。
• 範囲外の座標、または 2 つ未満のコントロールポイントは、暗黙のうちに劣化した出力ではなく、無効なレジストレーションを生成します。

Enterprise の境界に関する注意

Enterprise は Geo の振る舞いを変更しません。Enterprise は別途文書化された上位ティアの機能を追加しますが、それらは GeoPDF の measure 辞書を生成するには必要ありません。

Core のフォールバック/代替手段

GeoPDF の measure 辞書生成に相当する Core の機能はありません。これは Pro の追加機能です。

公開範囲の境界

このページは、外部から観測可能な振る舞いと、サポートされる公開 API サーフェスのみを記述します。内部の名前空間パス、ヘルパークラス、メカニズムの表、ランブックのファイル名、チケットのプレフィックスは対象外です。

関連項目

• Geo — 詳細リファレンス — 完全なクラスおよびメソッドのリファレンス。
• Document — ページとドキュメントの組み立て。
• Core 注釈。