Геопривязка

Краткий обзор

NextPDF Pro сопоставляет координаты страницы PDF с географическими координатами и генерирует словарь измерений PDF с подтипом GEO, чтобы средство просмотра могло сообщать реальную позицию по точке на странице.

Доступность и лицензирование

Эта возможность поставляется в составе NextPDF Pro (nextpdf/pro) и активируется лицензионным конвертом уровня Pro. Развёртывание без этого права не загружает классы возможности. Сравнить редакции и получить лицензию.

У Geo нет отдельного флага лицензии для каждой возможности; конверт уровня Pro включает её напрямую.

Установка

composer require nextpdf/pro:^3

Концептуальный обзор

Геопространственный PDF несёт словарь измерений, описанный в ISO 32000-2 §12.8.2, который связывает точки пространства устройства с географической системой координат. NextPDF Pro строит эти данные из неизменяемых объектов-значений:

• GeoCoordinate — тройка широта/долгота/высота. Конструирование проверяет широту в диапазоне [-90, 90] и долготу в диапазоне [-180, 180] и предлагает форматирование в градусах-минутах-секундах и в виде десятичной строки.
• GeoControlPoint — пара из точки PDF-пространства и GeoCoordinate.
• ProjectionType — перечисление распространённых проекций (географическая, UTM, поперечная Меркатора, коническая равноугольная Ламберта), каждая из которых сопоставлена с кодом EPSG.
• GeoRegistration — контрольные точки плюс проекция и геодезический датум (по умолчанию WGS84). isValid() требует не менее двух контрольных точек для минимального аффинного преобразования; toPdfMeasureDictionary() выводит словарь /Measure с /Subtype /GEO и массивами контрольных точек.

Почему это работает именно так

NextPDF строит словарь измерений из проверенных, неизменяемых объектов-значений, а не из сырого словаря, переданного вызывающей стороной. GeoCoordinate отклоняет широту или долготу вне диапазона при конструировании. GeoRegistration::isValid() отказывается принимать менее двух контрольных точек, поэтому некорректная регистрация быстро завершается неудачей вместо того, чтобы выдать неполноценный словарь /GEO. Проекции разрешаются в стандартные коды EPSG через ProjectionType, что делает систему координат явной, а не угаданной. Датум по умолчанию — WGS84, но остаётся именованным полем, поэтому нестандартная система координат — это осознанный выбор. Такая позиция «отказ при ошибке» важна, потому что неверная геопривязка хуже, чем её отсутствие; средство просмотра уверенно сообщит ложную реальную позицию. Предыстория проектирования: 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 — это числовые данные координат. Проверяйте контрольные точки, полученные из недоверенного ввода, перед регистрацией.

Соответствие

Поведение	Ссылка	Статус
Геопространственный словарь измерений (подтип GEO)	ISO 32000-2 §12.8.2	Согласовано (пересказ)

Контракт поведения

• GeoCoordinate проверяет при конструировании широту в диапазоне [-90, 90] и долготу в диапазоне [-180, 180] и предлагает форматирование DMS и в виде десятичной строки.
• GeoControlPoint объединяет точку PDF-пространства с GeoCoordinate.
• GeoRegistration несёт контрольные точки плюс ProjectionType (сопоставленный с кодом EPSG) и геодезический датум со значением по умолчанию WGS84. isValid() требует не менее двух контрольных точек; toPdfMeasureDictionary() выводит словарь /Measure с /Subtype /GEO и массивами контрольных точек.
• Координаты вне диапазона или менее двух контрольных точек дают недействительную регистрацию, а не молча ухудшенный вывод.

Примечание о границе Enterprise

Enterprise не меняет поведение Geo. Enterprise добавляет возможности более высокого уровня, документированные отдельно; они не требуются для генерации словаря измерений GeoPDF.

Резервный вариант Core / альтернатива

В Core нет аналога для генерации словаря измерений GeoPDF. Это дополнение Pro.

Граница публикации

Эта страница документирует только внешне наблюдаемое поведение и поддерживаемую публичную поверхность API. Внутренние пути пространств имён, вспомогательные классы, таблицы механизмов, имена файлов runbook и префиксы тикетов выходят за рамки.

См. также

• Geo — Deep Reference — полный справочник классов и методов.
• Document — сборка страниц и документов.
• Core annotations.