Geo — 深入參考

概觀

本頁是 NextPDF Pro Geo 模組的合約層級參考。其介面是四個不可變的值物件——GeoCoordinate、GeoControlPoint、ProjectionType 與 GeoRegistration——外加 GeoPdfLayer，後者將註冊與頁面索引關聯起來並發出 viewport 輸出。此模組產生 PDF dictionary 文字：一個帶有 /Subtype /GEO 的 /Measure dictionary、一個 /Viewport dictionary，以及頁面層級的 /VP 陣列值。產生過程是確定性的字串組裝：沒有網路呼叫、沒有檔案系統存取、沒有隨機性。本頁陳述公開 API、可觀察的行為合約，以及失敗模式。

供應與授權

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

沒有任何單功能授權旗標閘控此模組。只要安裝了 nextpdf/pro，Geo 類別即可使用。

公開 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；否則為兩位小數並去除尾隨零
GeoCoordinate::toDecimal()	無	將緯度與經度格式化為六位小數，以逗號分隔	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 個 case	case：Geographic、UTM、TransverseMercator、LambertConformal	底值 GEO、UTM、TM、LCC	—	見下方投影映射表
ProjectionType::epsgCode()	無	將 case 映射到一個固定的 EPSG 碼	int	—	4326、32601、2154 或 3347
ProjectionType::label()	無	人類可讀的投影名稱	string	—	例如 WGS 84 Geographic
GeoRegistration	建構子：array $controlPoints、ProjectionType $projection、string $datum = 'WGS84'	持有控制點、投影與大地基準面	—	—	final readonly；建構時不驗證控制點數量
GeoRegistration::isValid()	無	要求至少兩個控制點	bool	—	兩個點是仿射映射的最小值
GeoRegistration::toPdfMeasureDictionary()	無	發出帶有 /Subtype /GEO、/GCS、/GPTS、/LPTS 與 /Bounds 的 /Measure dictionary	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 dictionary	string	—	該頁無註冊或註冊無效時回傳空字串
GeoPdfLayer::generateViewportArray()	int $pageIndex	將 viewport dictionary 以中括號包裹為 /VP 陣列字面值	string	—	不存在時回傳空字串；呼叫方隨即為該頁省略 /VP
GeoPdfLayer::writeToPdfWriter()	BinaryBuffer $buffer、int $pageIndex	將 /VP 加上陣列字面值與一個換行寫入緩衝區	bool	—	有寫入項目時為 true；否則為無操作並回傳 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。fromDms() 接受秒為選用的 DMS 輸入，正規化撇號、雙撇號、度符號與智慧引號字符，轉換為帶號的十進位度，並建構一個新實例。南緯與西經會成為負值。

投影映射

每個 ProjectionType case 帶有一個固定的 EPSG 碼與標籤。此映射是一張封閉的表，而非座標參考系統登錄檔。

Case	底值	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 case 發出 zone 1 的碼。需要不同 UTM zone、或此表以外任何 EPSG 碼的專案，應以 Well Known Text 形式將權威的 CRS 描述帶入 datum 字串中。

Measure dictionary 發出

GeoRegistration::toPdfMeasureDictionary() 發出一個多行 dictionary：/Type /Measure、/Subtype /GEO、一個 /GCS 座標系統 dictionary、/GPTS、/LPTS 與 /Bounds，依 ISO 32000-2:2020 §12.10（Table 269）。具體行為：

• /GCS 發出為 << /Type /PROJCS /EPSG <code> /WKT (<datum>) >>。EPSG 碼來自投影 case。/WKT 值即為原樣提供的 datum 字串；預設為 WGS84。
• /GPTS 以控制點順序列出六位小數的緯度—經度配對。
• /LPTS 原樣列出六位小數的 pdfX/pdfY 配對。ISO 32000-2:2020 Table 269 將 LPTS 點定義於一個 2D 單位正方形內；提供以單位正方形正規化的值是呼叫方的責任。
• /Bounds 固定為 [0 0 0 1 1 1 1 0]，即完整的單位正方形。
• datum 字串在插入字面字串之前會先跳脫：反斜線、括號與常見控制字元會依 ISO 32000-2:2020 §7.3.4.2 成為其反斜線跳脫。受呼叫方影響的 datum 無法終止字面字串或注入原始 PDF token。

Viewport 與頁面發出

GeoPdfLayer 以插入順序保存註冊，並以零為基底的頁面索引作鍵。generateViewportDictionary() 解析所請求頁面的第一筆註冊，當無此註冊或 isValid() 為 false 時回傳空字串。產生的 dictionary 帶有 /Type /Viewport、一個由控制點 PDF 座標的最小與最大值算出的 /BBox、一個形如 GeoViewport_Page<n> 的 /Name，以及內嵌的 /Measure dictionary。viewport 的 /Measure 項目遵循 ISO 32000-2:2020 §12.9。generateViewportArray() 將 dictionary 以中括號包裹，產生頁面 /VP 值：一個依 ISO 32000-2:2020 §7.7.3.3（Table 31）的 viewport dictionary 陣列。writeToPdfWriter() 將 /VP 加上陣列字面值寫入 Core 的 BinaryBuffer，並回報是否有寫入內容，讓頁面序列化能俐落地省略該鍵。

邊界案例與失敗模式

• 超出範圍的緯度或經度在建構時擲出 InvalidArgumentException；不存在部分有效的座標。
• fromDms() 對無法解析的輸入擲出例外。解析出的值會通過建構子，因此語法有效但值超出範圍的字串同樣會擲出。
• DMS 記法不帶 altitude；fromDms() 一律產生 altitude 0.0。
• 控制點少於兩個的 GeoRegistration 其 isValid() 回報 false，但 toPdfMeasureDictionary() 仍會發出一個帶有短點陣列的 dictionary。請以 isValid() 防護直接呼叫，或透過會抑制無效註冊的 GeoPdfLayer 繞送發出。
• 某頁面索引的重複註冊全數被 getRegistrations() 保留；viewport 產生使用最先加入的那筆。
• 負的頁面索引擲出 InvalidArgumentException；頁面索引以零為基底。
• 共用同一 X 或 Y 值的控制點會產生退化的零寬或零高 /BBox。請提供橫跨兩軸的點。
• 所有輸出皆為產生的文字。不會寫入磁碟或網路，且相同輸入產生相同輸出。
• 此模組不發生任何密碼學運算，因此沒有 FIPS 模式特定的行為。

一致性

主張	標準	條款
measure dictionary 以 subtype GEO 發出，帶有 GPTS 緯度—經度配對與成對的 LPTS 值。	ISO 32000-2:2020	§12.10
viewport dictionary 帶有 BBox、Name 與 Measure 項目。	ISO 32000-2:2020	§12.9
頁面 VP 值以 viewport dictionary 陣列形式發出。	ISO 32000-2:2020	§7.7.3.3
datum 插值會跳脫字面字串的元字元。	ISO 32000-2:2020	§7.3.4.2

所有條款皆為改寫；NextPDF 不重製規範性文字。這些是能力陳述，而非認證。NextPDF 未持有任何認證，亦不授予任何認證。EPSG 碼為每個投影 case 的固定代表值，而 /WKT 項目帶有所提供的 datum 字串，而非產生的 Well Known Text 描述；兩項陳述皆以產品為依據。在仰賴 viewer 端量測之前，請先於目標互動式 PDF 處理器中驗證發出的 GeoPDF 輸出。

開發備註

• 自 nextpdf/pro 1.9.0 起提供；於 nextpdf/pro 3.1.0 為現行版本。
• 直接呼叫 toPdfMeasureDictionary() 之前請先檢查 isValid()；GeoPdfLayer 會替你執行此檢查。
• 當下游消費者解析 /WKT 時，請將完整的 Well Known Text 描述作為 datum 傳入；預設的 WGS84 僅為 datum 標籤。
• 當 viewport 邊界與你的 PDF 空間值不同時，請在建構控制點之前將 LPTS 輸入正規化到單位正方形。
• 發出成本與控制點數量呈線性；GeoPdfLayer 中的查找與註冊數量呈線性。
• writeToPdfWriter() 透過來自 Core 的 NextPDF\Support\BinaryBuffer 與頁面序列化整合。

出版邊界

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

另請參閱

• Geo（能力）——安裝、概念概觀與快速上手範例。
• Document — 深入參考——文件與頁面組合介面。