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] 内，并提供度分秒（DMS）和十进制字符串格式化。
• GeoControlPoint —— 一个 PDF 空间点与一个 GeoCoordinate 的配对。
• ProjectionType —— 一个常见投影的枚举（地理投影、UTM、横轴墨卡托、兰勃特等角圆锥），每一个都映射到一个 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 接口。内部命名空间路径、辅助类、机制表、运行手册文件名以及工单前缀均不在范围之内。

另请参阅

• Geo —— 深度参考 —— 完整的类与方法参考。
• Document —— 页面和文档组装。
• Core annotations。