Geo

速覽

NextPDF Pro 會將 PDF 頁面座標對應到地理座標，並產生一個帶有 GEO 子型別的 PDF measure 字典，讓檢視器能從頁面上的某個點回報真實世界的位置。

可用性與授權

此能力隨附於 NextPDF Pro（nextpdf/pro），並以 Pro 等級的授權封套啟用。缺少該權利的部署不會載入此能力的類別。比較各版本並取得授權。

Geo 沒有獨立的逐功能授權旗標；Pro 等級的封套會直接啟用它。

安裝

composer require nextpdf/pro:^3

概念總覽

一份地理空間 PDF 會承載一個 measure 字典（描述於 ISO 32000-2 §12.8.2），它將裝置空間點繫結到一個地理座標參考系統。NextPDF Pro 會從不可變的值物件建構該資料：

• GeoCoordinate —— 一個緯度/經度/高度三元組。建構時會驗證緯度位於 [-90, 90]、經度位於 [-180, 180]，並提供度分秒與十進位字串格式化。
• GeoControlPoint —— 一個 PDF 空間點與一個 GeoCoordinate 的配對。
• ProjectionType —— 一個常見投影的列舉（geographic、UTM、transverse Mercator、Lambert conformal conic），各自對應到一個 EPSG 代碼。
• GeoRegistration —— 控制點加上投影與大地基準（預設 WGS84）。isValid() 要求至少兩個控制點以建構一個最小化的仿射變換；toPdfMeasureDictionary() 會發出帶有 /Subtype /GEO 與控制點陣列的 /Measure 字典。

為何如此設計

NextPDF 是從已驗證、不可變的值物件建構 measure 字典，而非從呼叫端提供的原始字典。GeoCoordinate 會在建構時拒絕超出範圍的緯度或經度。GeoRegistration::isValid() 會拒絕少於兩個控制點，因此格式錯誤的配準會快速失敗，而非發出一個劣化的 /GEO 字典。投影會透過 ProjectionType 解析為標準 EPSG 代碼，讓座標參考系統保持明確而非用猜的。基準預設為 WGS84，但仍是一個具名欄位，因此採用非預設的參考系統是一項刻意的選擇。這種故障關閉（fail-closed）的姿態之所以重要，是因為錯誤的地理配準比沒有更糟；檢視器會自信地回報一個錯誤的真實世界位置。 設計背景：一個拒絕猜測的 API。

API 介面

類別	職責
GeoCoordinate	帶格式化的、已驗證的緯/經/高度。
GeoControlPoint	PDF 點 ↔ 地理點配對。
ProjectionType	帶 EPSG 代碼的投影列舉。
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 建構時會拒絕超出範圍的緯度或經度。
• 少於兩個控制點會產生一個無效的配準。
• 預設基準為 WGS84；對於其他參考系統，請明確設定它。

效能

字典產生與控制點數量呈線性關係。

安全注意事項

Geo 的輸入是數值座標資料。請在配準之前，先驗證來自不受信任輸入的控制點。

一致性

行為	參照	狀態
地理空間 measure 字典（GEO 子型別）	ISO 32000-2 §12.8.2	已對齊（改寫）

行為合約

• GeoCoordinate 在建構時會驗證緯度位於 [-90, 90]、經度位於 [-180, 180]，並提供 DMS 與十進位字串格式化。
• GeoControlPoint 會將一個 PDF 空間點與一個 GeoCoordinate 配對。
• GeoRegistration 承載控制點加上一個 ProjectionType（對應到一個 EPSG 代碼）與一個預設為 WGS84 的大地基準。isValid() 要求至少兩個控制點；toPdfMeasureDictionary() 會發出一個帶有 /Subtype /GEO 與控制點陣列的 /Measure 字典。
• 超出範圍的座標或少於兩個控制點，會產生一個無效的配準，而非默默降級的輸出。

Enterprise 邊界註記

Enterprise 不會改變 Geo 的行為。Enterprise 新增更高等級的功能，另行記載；它們對於產生 GeoPDF measure 字典並非必要。

Core 回退/替代方案

GeoPDF measure 字典產生沒有任何 Core 對應方案。這是一項 Pro 的新增功能。

出版邊界

本頁僅記載外部可觀察的行為，以及受支援的公開 API 介面。內部命名空間路徑、輔助類別、機制表格、runbook 檔名與工單前綴皆不在範圍內。

另請參閱

• Geo —— 深入參考 —— 完整的類別與方法參考。
• Document —— 頁面與文件組裝。
• Core 註解。