Geo — глубокий справочник

Кратко

Эта страница — справочник контрактного уровня по модулю Geo в NextPDF Pro. Поверхность составляют четыре неизменяемых объекта-значения — GeoCoordinate, GeoControlPoint, ProjectionType и GeoRegistration — плюс GeoPdfLayer, который связывает регистрации с индексами страниц и формирует вывод области просмотра. Модуль порождает текст словарей PDF: словарь /Measure с /Subtype /GEO, словарь /Viewport и значение массива /VP на уровне страницы. Генерация — детерминированная сборка строк: без сетевых вызовов, без доступа к файловой системе, без случайности. На этой странице описаны публичный API, контракт наблюдаемого поведения и режимы отказа.

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

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

Отдельный лицензионный флаг для этого модуля не используется. Классы Geo доступны всегда, когда установлен nextpdf/pro.

Публичная поверхность API

Символ	Параметры	Поведение по умолчанию	Возвращает	Возбуждает или отказывает с	Примечания
GeoCoordinate	конструктор: float $latitude, float $longitude, float $altitude = 0.0	Проверяет широту в пределах [-90, 90] и долготу в пределах [-180, 180]	—	InvalidArgumentException, когда любое из значений выходит за диапазон	final readonly; высота — метры над уровнем моря, диапазон не проверяется
GeoCoordinate::toDms()	нет	Форматирует как градусы-минуты-секунды с суффиксами N/S и E/W	string	—	Секунды около нуля отображаются как 00; иначе два знака после запятой с обрезкой хвостовых нулей
GeoCoordinate::toDecimal()	нет	Форматирует широту и долготу до шести знаков после запятой через запятую	string	—	Высота не включается
GeoCoordinate::fromDms()	string $dms	Разбирает строку DMS; секунды необязательны; типографские глифы градуса и кавычек нормализуются	self	InvalidArgumentException, когда строка не разбирается или когда разобранные значения не проходят проверки диапазона в конструкторе	Статическая фабрика; буквы полушарий регистронезависимы; высота по умолчанию 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()	нет	Выдаёт словарь /Measure с /Subtype /GEO, /GCS, /GPTS, /LPTS и /Bounds	string	—	Не проверяет isValid(); защитите вызов или направьте его через GeoPdfLayer
GeoPdfLayer::addRegistration()	int $pageIndex, GeoRegistration $registration	Добавляет регистрацию для индекса страницы, отсчитываемого от нуля	self	InvalidArgumentException, когда $pageIndex отрицателен	Текучий интерфейс; при генерации побеждает первая добавленная для страницы регистрация
GeoPdfLayer::getRegistrations()	нет	Возвращает все регистрации в порядке вставки	list<array{pageIndex: int, registration: GeoRegistration}>	—	Включает дубликаты и недействительные регистрации в том виде, как они добавлены
GeoPdfLayer::generateViewportDictionary()	int $pageIndex	Выдаёт словарь /Viewport с /BBox, /Name и встроенным /Measure	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 выдаёт код зоны 1. Проекты, которым нужна другая зона UTM или любой код EPSG вне этой таблицы, должны нести авторитетное описание CRS в строке datum в виде Well Known Text.

Вывод словаря измерений

GeoRegistration::toPdfMeasureDictionary() выдаёт многострочный словарь: /Type /Measure, /Subtype /GEO, словарь системы координат /GCS, /GPTS, /LPTS и /Bounds, согласно ISO 32000-2:2020 §12.10 (таблица 269). Конкретное поведение:

• /GCS выводится как << /Type /PROJCS /EPSG <code> /WKT (<datum>) >>. Код EPSG берётся из случая проекции. Значение /WKT — это строка datum в точности как передана; по умолчанию WGS84.
• /GPTS перечисляет пары широта-долгота с шестью знаками после запятой в порядке контрольных точек.
• /LPTS перечисляет пары pdfX/pdfY с шестью знаками после запятой в точности как переданы. ISO 32000-2:2020, таблица 269, определяет точки LPTS в 2D-единичном квадрате; передача нормализованных к единичному квадрату значений — ответственность вызывающей стороны.
• /Bounds фиксировано как [0 0 0 1 1 1 1 0] — полный единичный квадрат.
• Строка datum экранируется перед подстановкой в литеральную строку: обратная косая черта, скобки и распространённые управляющие символы заменяются на свои escape-последовательности с обратной косой чертой согласно ISO 32000-2:2020 §7.3.4.2. Датум под влиянием вызывающей стороны не может завершить литеральную строку или внедрить сырые токены PDF.

Вывод области просмотра и страницы

GeoPdfLayer хранит регистрации в порядке вставки, с ключом по индексу страницы от нуля. generateViewportDictionary() разрешает первую регистрацию для запрошенной страницы и возвращает пустую строку, когда её нет или когда isValid() равно false. Полученный словарь несёт /Type /Viewport, /BBox, вычисленный по минимальным и максимальным координатам PDF контрольных точек, /Name вида GeoViewport_Page<n> и встроенный словарь /Measure. Запись /Measure области просмотра следует ISO 32000-2:2020 §12.9. generateViewportArray() оборачивает словарь в скобки, порождая значение страницы /VP: массив словарей области просмотра согласно ISO 32000-2:2020 §7.7.3.3 (таблица 31). writeToPdfWriter() записывает /VP плюс литерал массива в BinaryBuffer из Core и сообщает, было ли что-то записано, чтобы сериализация страницы могла аккуратно опустить ключ.

Граничные случаи и режимы отказа

• Широта или долгота вне диапазона возбуждают InvalidArgumentException при конструировании; частично действительной координаты не существует.
• fromDms() возбуждает исключение на неразбираемом вводе. Разобранные значения проходят через конструктор, поэтому синтаксически корректная строка со значениями вне диапазона также возбуждает исключение.
• Нотация DMS не несёт высоты; fromDms() всегда даёт высоту 0.0.
• GeoRegistration с менее чем двумя контрольными точками сообщает isValid() false, однако toPdfMeasureDictionary() всё равно выдаёт словарь с короткими массивами точек. Защищайте прямые вызовы через isValid() или направляйте вывод через GeoPdfLayer, который подавляет недействительные регистрации.
• Дублирующиеся регистрации для одного индекса страницы полностью сохраняются в getRegistrations(); генерация области просмотра использует первую добавленную.
• Отрицательный индекс страницы возбуждает InvalidArgumentException; индексы страниц отсчитываются от нуля.
• Контрольные точки с общим значением X или Y порождают вырожденный /BBox нулевой ширины или высоты. Передавайте точки, охватывающие обе оси.
• Весь вывод — сгенерированный текст. Ничего не пишется на диск или в сеть, и одинаковый ввод порождает одинаковый вывод.
• В этом модуле не выполняются криптографические операции, поэтому нет поведения, специфичного для режима FIPS.

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

Утверждение	Стандарт	Пункт
Словарь измерений выводится с подтипом 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
Подстановка датума экранирует метасимволы литеральной строки.	ISO 32000-2:2020	§7.3.4.2

Все пункты перефразированы; NextPDF не воспроизводит нормативный текст. Это утверждения о возможностях, а не сертификаты. NextPDF не имеет сертификации и не предоставляет её. Коды EPSG — фиксированные репрезентативные значения для каждого случая проекции, а запись /WKT несёт переданную строку датума, а не сгенерированное описание Well Known Text; оба утверждения основаны на продукте. Проверяйте выведенный вывод GeoPDF в целевых интерактивных обработчиках PDF, прежде чем полагаться на измерения на стороне просмотрщика.

Заметки по разработке

• Доступно с nextpdf/pro 1.9.0; актуально в nextpdf/pro 3.1.0.
• Проверяйте isValid() перед прямым вызовом toPdfMeasureDictionary(); GeoPdfLayer выполняет эту проверку за вас.
• Когда нижестоящие потребители разбирают /WKT, передавайте полное описание Well Known Text как datum; значение по умолчанию WGS84 — лишь метка датума.
• Нормализуйте входные данные LPTS к единичному квадрату перед конструированием контрольных точек, когда границы области просмотра отличаются от ваших значений в пространстве PDF.
• Стоимость вывода линейна по количеству контрольных точек; поиск в GeoPdfLayer линеен по количеству регистраций.
• writeToPdfWriter() интегрируется с сериализацией страницы через NextPDF\Support\BinaryBuffer из Core.

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

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

См. также

• Geo (возможность) — установка, концептуальный обзор и примеры для быстрого старта.
• Document — глубокий справочник — поверхность композиции документа и страниц.