Geo — 詳細リファレンス

概要

本ページは NextPDF Pro Geo モジュールのコントラクトレベルのリファレンスです。公開面は 4 つの不変値オブジェクト — GeoCoordinate、GeoControlPoint、ProjectionType、GeoRegistration — に加え、登録をページインデックスに関連付けてビューポート出力を発行する GeoPdfLayer です。このモジュールは PDF ディクショナリのテキストを生成します。/Subtype /GEO を持つ /Measure ディクショナリ、/Viewport ディクショナリ、そしてページレベルの /VP 配列値です。生成は決定論的な文字列組み立てであり、ネットワーク呼び出しも、ファイルシステムアクセスも、乱数もありません。本ページでは公開 API、観測可能な挙動コントラクト、そして失敗モードを示します。

提供とライセンス

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

このモジュールをゲートする機能ごとのライセンスフラグはありません。Geo クラスは nextpdf/pro がインストールされていれば常に利用可能です。

公開 API 面

シンボル	パラメータ	既定の挙動	戻り値	スローまたは失敗	備考
GeoCoordinate	コンストラクタ：float $latitude、float $longitude、float $altitude = 0.0	緯度を [-90, 90]、経度を [-180, 180] の範囲で検証	—	いずれかの値が範囲外のとき InvalidArgumentException	final readonly；altitude は海抜メートルで範囲チェックなし
GeoCoordinate::toDms()	なし	N/S および E/W サフィックス付きの度分秒として整形	string	—	秒がほぼゼロなら 00；それ以外は末尾ゼロを除去した小数 2 桁
GeoCoordinate::toDecimal()	なし	緯度と経度を小数 6 桁、カンマ区切りで整形	string	—	altitude は含まれない
GeoCoordinate::fromDms()	string $dms	DMS 文字列をパース；秒は任意；活字的な度記号と引用符グリフを正規化	self	文字列がパースできないとき、またはパース値がコンストラクタの範囲チェックに失敗したとき InvalidArgumentException	静的ファクトリ；半球文字は大文字小文字を区別しない；altitude は 0.0 を既定値とする
GeoControlPoint	コンストラクタ：float $pdfX、float $pdfY、GeoCoordinate $geo	PDF ユーザー空間の点（ポイント）を地理座標と組にする	—	—	final readonly；PDF 座標は検証されない
ProjectionType	文字列バックの列挙型、4 ケース	ケース：Geographic、UTM、TransverseMercator、LambertConformal	バッキング値 GEO、UTM、TM、LCC	—	下記の投影マッピング表を参照
ProjectionType::epsgCode()	なし	ケースを 1 つの固定 EPSG コードにマップ	int	—	4326、32601、2154、または 3347
ProjectionType::label()	なし	人間可読な投影名	string	—	例：WGS 84 Geographic
GeoRegistration	コンストラクタ：array $controlPoints、ProjectionType $projection、string $datum = 'WGS84'	制御点、投影法、測地系を保持	—	—	final readonly；制御点数は構築時に検証されない
GeoRegistration::isValid()	なし	制御点が少なくとも 2 つ必要	bool	—	2 点はアフィンマッピングの最小数
GeoRegistration::toPdfMeasureDictionary()	なし	/Subtype /GEO、/GCS、/GPTS、/LPTS、/Bounds を持つ /Measure ディクショナリを出力	string	—	isValid() はチェックしない；呼び出しをガードするか GeoPdfLayer を経由
GeoPdfLayer::addRegistration()	int $pageIndex、GeoRegistration $registration	ゼロ始まりのページインデックスに登録を追加	self	$pageIndex が負のとき InvalidArgumentException	フルーエント；あるページで最初に追加された登録が生成時に採用される
GeoPdfLayer::getRegistrations()	なし	すべての登録を挿入順で返す	list<array{pageIndex: int, registration: GeoRegistration}>	—	重複や無効な登録も追加されたまま含む
GeoPdfLayer::generateViewportDictionary()	int $pageIndex	/BBox、/Name、インライン /Measure を持つ /Viewport ディクショナリを出力	string	—	ページに登録がない、または登録が無効なとき空文字列
GeoPdfLayer::generateViewportArray()	int $pageIndex	ビューポートディクショナリを角括弧で包み /VP 配列リテラルとする	string	—	存在しないとき空文字列；呼び出し側はそのページの /VP を省略
GeoPdfLayer::writeToPdfWriter()	BinaryBuffer $buffer、int $pageIndex	/VP と配列リテラルおよび改行をバッファに書き込む	bool	—	エントリを書き込んだとき true；それ以外は no-op で false

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

public function __construct(
    public float $latitude,
    public float $longitude,
    public float $altitude = 0.0,
)

public function toDms(): string

public function toDecimal(): string

public static function fromDms(string $dms): self

public function __construct(
    public float $pdfX,
    public float $pdfY,
    public GeoCoordinate $geo,
)

public function __construct(
    public array $controlPoints,
    public ProjectionType $projection,
    public string $datum = 'WGS84',
)

public function isValid(): bool

public function toPdfMeasureDictionary(): string

public function addRegistration(int $pageIndex, GeoRegistration $registration): self

public function getRegistrations(): array

public function generateViewportDictionary(int $pageIndex): string

public function generateViewportArray(int $pageIndex): string

public function writeToPdfWriter(BinaryBuffer $buffer, int $pageIndex): bool

挙動コントラクト

座標の検証と整形

GeoCoordinate は構築時に検証し、決してミューテートしません。緯度が [-90, 90] の範囲外、または経度が [-180, 180] の範囲外だと、問題の値を明示した InvalidArgumentException をスローします。toDms() は両軸を度、ゼロ埋めの分、秒、半球サフィックスとしてレンダリングします。toDecimal() は latitude, longitude を小数 6 桁でレンダリングします。fromDms() は秒を任意とする DMS 入力を受け付け、プライム、ダブルプライム、度記号、スマートクォートのグリフを正規化し、符号付き 10 進度に変換して新しいインスタンスを構築します。南緯と西経は負の値になります。

投影マッピング

各 ProjectionType ケースは 1 つの固定 EPSG コードとラベルを持ちます。このマッピングは閉じた表であり、座標参照系のレジストリではありません。

ケース	バッキング値	epsgCode()	label()
Geographic	GEO	4326	WGS 84 Geographic
UTM	UTM	32601	Universal Transverse Mercator
TransverseMercator	TM	2154	Transverse Mercator
LambertConformal	LCC	3347	Lambert Conformal Conic

UTM ケースはゾーン 1 のコードを出力します。異なる UTM ゾーン、またはこの表にない EPSG コードが必要なプロジェクトは、正式な CRS 記述を datum 文字列に Well Known Text として保持してください。

Measure ディクショナリの出力

GeoRegistration::toPdfMeasureDictionary() は複数行のディクショナリを出力します。/Type /Measure、/Subtype /GEO、/GCS 座標系ディクショナリ、/GPTS、/LPTS、/Bounds を、ISO 32000-2:2020 §12.10（Table 269）に従って出力します。具体的な挙動：

• /GCS は << /Type /PROJCS /EPSG <code> /WKT (<datum>) >> として出力されます。EPSG コードは投影ケースに由来します。/WKT 値は供給された datum 文字列そのままで、既定は WGS84 です。
• /GPTS は緯度・経度のペアを小数 6 桁で、制御点順に列挙します。
• /LPTS は pdfX/pdfY のペアを小数 6 桁で、供給されたとおりに列挙します。ISO 32000-2:2020 Table 269 は LPTS の点を 2 次元の単位正方形内で定義しており、単位正方形に正規化した値を供給するのは呼び出し側の責任です。
• /Bounds は完全な単位正方形である [0 0 0 1 1 1 1 0] に固定されています。
• datum 文字列はリテラル文字列への補間前にエスケープされます。バックスラッシュ、丸括弧、および一般的な制御文字は、ISO 32000-2:2020 §7.3.4.2 に従ってバックスラッシュエスケープになります。呼び出し側の影響を受けた datum がリテラル文字列を終端させたり、生の PDF トークンを注入したりすることはできません。

ビューポートとページの出力

GeoPdfLayer は登録を挿入順で、ゼロ始まりのページインデックスをキーとして保持します。generateViewportDictionary() は要求されたページの最初の登録を解決し、登録がない場合、または isValid() が false の場合は空文字列を返します。生成されるディクショナリは /Type /Viewport、制御点の PDF 座標の最小値と最大値から算出される /BBox、GeoViewport_Page<n> 形式の /Name、およびインライン /Measure ディクショナリを持ちます。ビューポートの /Measure エントリは ISO 32000-2:2020 §12.9 に従います。generateViewportArray() はディクショナリを角括弧で包み、ページの /VP 値を生成します。これは ISO 32000-2:2020 §7.7.3.3（Table 31）に従うビューポートディクショナリの配列です。writeToPdfWriter() は /VP と配列リテラルを Core の BinaryBuffer に書き込み、何かが書き込まれたかどうかを報告するため、ページのシリアライズはキーをきれいに省略できます。

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

• 範囲外の緯度または経度は構築時に InvalidArgumentException をスローします。部分的に有効な座標は存在しません。
• fromDms() はパース不能な入力でスローします。パース値はコンストラクタを通過するため、構文的に有効でも範囲外の値を持つ文字列も同様にスローします。
• DMS 記法は altitude を持たないため、fromDms() は常に altitude 0.0 を返します。
• 制御点が 2 つ未満の GeoRegistration は isValid() が false を報告しますが、toPdfMeasureDictionary() は依然として短い点配列を持つディクショナリを出力します。直接呼び出しは isValid() でガードするか、無効な登録を抑制する GeoPdfLayer を経由して出力してください。
• 1 つのページインデックスに対する重複登録は getRegistrations() にすべて保持されますが、ビューポート生成は最初に追加されたものを使用します。
• 負のページインデックスは InvalidArgumentException をスローします。ページインデックスはゼロ始まりです。
• X または Y の値を共有する制御点は、幅ゼロまたは高さゼロの退化した /BBox を生成します。両軸にまたがる点を供給してください。
• すべての出力は生成テキストです。ディスクにもネットワークにも何も書き込まれず、同一の入力は同一の出力を生成します。
• このモジュールでは暗号操作が発生しないため、FIPS モード固有の挙動はありません。

適合性

主張	標準	節
measure ディクショナリはサブタイプ GEO で、GPTS の緯度・経度ペアと対をなす LPTS 値とともに出力される。	ISO 32000-2:2020	§12.10
ビューポートディクショナリは BBox、Name、Measure エントリを持つ。	ISO 32000-2:2020	§12.9
ページの VP 値はビューポートディクショナリの配列として出力される。	ISO 32000-2:2020	§7.7.3.3
datum の補間はリテラル文字列のメタ文字をエスケープする。	ISO 32000-2:2020	§7.3.4.2

すべての節は言い換えであり、NextPDF は規範テキストを再現しません。これらは能力に関する記述であり、認証ではありません。NextPDF はいかなる認証も保有せず、付与もしません。EPSG コードは投影ケースごとの固定された代表値であり、/WKT エントリは生成された Well Known Text 記述ではなく供給された datum 文字列を保持します。いずれの記述も製品に基づくものです。ビューア側の測定に頼る前に、対象のインタラクティブ PDF プロセッサで出力された GeoPDF を検証してください。

開発上の注意

• nextpdf/pro 1.9.0 以降で利用可能；nextpdf/pro 3.1.0 で現行。
• toPdfMeasureDictionary() を直接呼び出す前に isValid() をチェックしてください；GeoPdfLayer はこのチェックを代行します。
• 下流のコンシューマが /WKT をパースする場合は、完全な Well Known Text 記述を datum として渡してください。既定の WGS84 は datum ラベルにすぎません。
• ビューポート境界が PDF 空間の値と異なる場合は、制御点を構築する前に LPTS 入力を単位正方形に正規化してください。
• 出力コストは制御点数に比例して線形；GeoPdfLayer 内のルックアップは登録数に比例して線形です。
• writeToPdfWriter() は Core の NextPDF\Support\BinaryBuffer を通じてページシリアライズと統合されます。

公開範囲

本ページは外部から観測可能な挙動とサポート対象の公開 API 面のみを記載します。内部の名前空間パス、ヘルパークラス、機構表、ランブックのファイル名、チケットのプレフィックスは対象外です。

関連項目

• Geo（機能） — インストール、概念的な概要、クイックスタートのサンプル。
• Document — 詳細リファレンス — ドキュメントとページ構成の面。