Geo

Visão geral

O NextPDF Pro mapeia coordenadas de página PDF para coordenadas geográficas e gera um dicionário de medida PDF com o subtipo GEO, para que um visualizador possa relatar a posição no mundo real a partir de um ponto na página.

Disponibilidade e licenciamento

Esta capacidade é distribuída no NextPDF Pro (nextpdf/pro) e é ativada com um envelope de licença de nível Pro. Uma implantação sem esse direito não carrega as classes da capacidade. Compare as edições e obtenha uma licença.

O Geo não tem um sinalizador de licença separado por recurso; o envelope de nível Pro o habilita diretamente.

Instalação

composer require nextpdf/pro:^3

Visão conceitual

Um PDF geoespacial carrega um dicionário de medida, descrito na ISO 32000-2 §12.8.2, que vincula pontos do espaço do dispositivo a um sistema geográfico de referência de coordenadas. O NextPDF Pro constrói esses dados a partir de objetos de valor imutáveis:

• GeoCoordinate — uma tripla latitude/longitude/altitude. A construção valida a latitude dentro de [-90, 90] e a longitude dentro de [-180, 180], e oferece formatação em graus-minutos-segundos e em string decimal.
• GeoControlPoint — um emparelhamento de um ponto do espaço PDF com uma GeoCoordinate.
• ProjectionType — um enum de projeções comuns (geográfica, UTM, Mercator transversa, cônica conforme de Lambert), cada uma mapeada para um código EPSG.
• GeoRegistration — os pontos de controle mais a projeção e o datum geodésico (padrão WGS84). isValid() requer pelo menos dois pontos de controle para uma transformação afim mínima; toPdfMeasureDictionary() emite o dicionário /Measure com /Subtype /GEO e os arrays de pontos de controle.

Por que funciona assim

O NextPDF constrói o dicionário de medida a partir de objetos de valor validados e imutáveis, não a partir de um dicionário bruto fornecido pelo chamador. GeoCoordinate rejeita uma latitude ou longitude fora do intervalo na construção. GeoRegistration::isValid() recusa menos de dois pontos de controle, de modo que um registro malformado falha rapidamente em vez de emitir um dicionário /GEO degradado. As projeções são resolvidas para códigos EPSG padrão por meio de ProjectionType, o que mantém o sistema de referência de coordenadas explícito em vez de adivinhado. O datum tem WGS84 como padrão, mas permanece um campo nomeado, de modo que um sistema de referência não padrão é uma escolha deliberada. Essa postura de falha fechada importa porque uma georreferência errada é pior do que nenhuma; um visualizador relataria com confiança uma posição falsa no mundo real. Contexto de projeto: Uma API que se recusa a adivinhar.

Superfície da API

Classe	Responsabilidade
GeoCoordinate	Lat/lon/altitude validada com formatação.
GeoControlPoint	Emparelhamento de ponto PDF ↔ ponto geográfico.
ProjectionType	Enum de projeção com códigos EPSG.
GeoRegistration	Construir o dicionário /Measure /GEO.

Exemplo de código — Início rápido

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();

Exemplo de código — Produção

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,
]);

Casos extremos e armadilhas

• A construção de GeoCoordinate rejeita uma latitude ou longitude fora do intervalo.
• Menos de dois pontos de controle produz um registro inválido.
• O datum padrão é WGS84; defina-o explicitamente para outros sistemas de referência.

Desempenho

A geração do dicionário é linear no número de pontos de controle.

Notas de segurança

A entrada do Geo são dados numéricos de coordenadas. Valide os pontos de controle provenientes de entradas não confiáveis antes do registro.

Conformidade

Comportamento	Referência	Status
Dicionário de medida geoespacial (subtipo GEO)	ISO 32000-2 §12.8.2	Alinhado (parafraseado)

Contrato de comportamento

• GeoCoordinate valida a latitude dentro de [-90, 90] e a longitude dentro de [-180, 180] na construção e oferece formatação em DMS e em string decimal.
• GeoControlPoint emparelha um ponto do espaço PDF com uma GeoCoordinate.
• GeoRegistration carrega os pontos de controle mais um ProjectionType (mapeado para um código EPSG) e um datum geodésico com padrão WGS84. isValid() requer pelo menos dois pontos de controle; toPdfMeasureDictionary() emite um dicionário /Measure com /Subtype /GEO e os arrays de pontos de controle.
• Coordenadas fora do intervalo ou menos de dois pontos de controle produzem um registro inválido, em vez de uma saída silenciosamente degradada.

Nota sobre o limite do Enterprise

O Enterprise não altera o comportamento do Geo. O Enterprise acrescenta recursos de nível superior documentados separadamente; eles não são necessários para gerar um dicionário de medida GeoPDF.

Alternativa / fallback do Core

Não há equivalente no Core para a geração de dicionário de medida GeoPDF. Este é um acréscimo do Pro.

Limite de publicação

Esta página documenta apenas o comportamento observável externamente e a superfície pública de API suportada. Caminhos de namespace internos, classes helper, tabelas de mecanismos, nomes de arquivos de runbook e prefixos de tíquetes estão fora de escopo.

Veja também

• Geo — Referência aprofundada — referência completa de classes e métodos.
• Document — montagem de páginas e documentos.
• Anotações do Core.