Geo — 深度参考

概览

本页是 NextPDF Pro Geo 模块的契约级参考。其接口面是四个不可变值对象——GeoCoordinate、GeoControlPoint、ProjectionType 与 GeoRegistration——以及 GeoPdfLayer，后者将注册项关联到页索引并输出视口。该模块生成 PDF 字典文本：一个带 /Subtype /GEO 的 /Measure 字典、一个 /Viewport 字典，以及页级 /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 个枚举值	枚举值：Geographic、UTM、TransverseMercator、LambertConformal	背衬值 GEO、UTM、TM、LCC	—	参见下方的投影映射表
ProjectionType::epsgCode()	无	将枚举值映射到一个固定的 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 字典	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；否则为空操作并返回 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 枚举值携带一个固定的 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 枚举值输出 zone 1 的代码。需要不同 UTM 分带、或此表以外任何 EPSG 代码的项目，应将权威的 CRS 描述以 Well Known Text 形式携带在 datum 字符串中。

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 按控制点顺序列出纬度-经度对，保留六位小数。
• /LPTS 列出 pdfX/pdfY 对，保留六位小数，与提供的完全一致。ISO 32000-2:2020 Table 269 将 LPTS 点定义在一个二维单位正方形内；提供单位正方形归一化后的值是调用方的责任。
• /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。
• 控制点少于两个的 GeoRegistration 报告 isValid() 为 false，但 toPdfMeasureDictionary() 仍会输出一个带短点数组的字典。请用 isValid() 守护直接调用，或经由 GeoPdfLayer 路由输出，后者会抑制无效注册项。
• 同一页索引的重复注册项都会被 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 条目携带提供的 datum 字符串，而非生成的 Well Known Text 描述；两项陈述均以产品为依据。在依赖查看器端测量之前，请在目标交互式 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 — 深度参考 — 文档与页面组合接口面。