Geo — Referência Profunda

Visão geral

Esta página é a referência em nível de contrato do módulo Geo do NextPDF Pro. A superfície consiste em quatro objetos de valor imutáveis — GeoCoordinate, GeoControlPoint, ProjectionType e GeoRegistration — além de GeoPdfLayer, que associa registros a índices de página e emite a saída de viewport. O módulo produz texto de dicionário PDF: um dicionário /Measure com /Subtype /GEO, um dicionário /Viewport e o valor do array /VP em nível de página. A geração é uma montagem de strings determinística: sem chamada de rede, sem acesso ao sistema de arquivos, sem aleatoriedade. Esta página apresenta a API pública, o contrato de comportamento observável e os modos de falha.

Disponibilidade e licenciamento

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

Nenhum sinalizador de licença por recurso restringe este módulo. As classes Geo estão disponíveis sempre que nextpdf/pro estiver instalado.

Superfície da API pública

Símbolo	Parâmetros	Comportamento padrão	Retorna	Lança ou falha com	Notas
GeoCoordinate	construtor: float $latitude, float $longitude, float $altitude = 0.0	Valida a latitude dentro de [-90, 90] e a longitude dentro de [-180, 180]	—	InvalidArgumentException quando qualquer valor está fora do intervalo	final readonly; a altitude é em metros acima do nível do mar e não passa por verificação de intervalo
GeoCoordinate::toDms()	nenhum	Formata como graus-minutos-segundos com sufixos N/S e E/W	string	—	Segundos próximos de zero renderizam como 00; caso contrário, duas casas decimais com zeros à direita removidos
GeoCoordinate::toDecimal()	nenhum	Formata latitude e longitude com seis casas decimais, separadas por vírgula	string	—	A altitude não é incluída
GeoCoordinate::fromDms()	string $dms	Analisa uma string DMS; os segundos são opcionais; glifos tipográficos de grau e aspas são normalizados	self	InvalidArgumentException quando a string não é analisável, ou quando os valores analisados falham nas verificações de intervalo do construtor	Fábrica estática; as letras de hemisfério são insensíveis a maiúsculas; a altitude assume o padrão 0.0
GeoControlPoint	construtor: float $pdfX, float $pdfY, GeoCoordinate $geo	Emparelha um ponto do espaço de usuário do PDF (em pontos) com uma coordenada geográfica	—	—	final readonly; as coordenadas PDF não são validadas
ProjectionType	enum baseado em string, 4 casos	Casos: Geographic, UTM, TransverseMercator, LambertConformal	valores de apoio GEO, UTM, TM, LCC	—	Veja a tabela de mapeamento de projeção abaixo
ProjectionType::epsgCode()	nenhum	Mapeia o caso para um código EPSG fixo	int	—	4326, 32601, 2154 ou 3347
ProjectionType::label()	nenhum	Nome de projeção legível por humanos	string	—	Por exemplo WGS 84 Geographic
GeoRegistration	construtor: array $controlPoints, ProjectionType $projection, string $datum = 'WGS84'	Mantém os pontos de controle, a projeção e o datum geodésico	—	—	final readonly; a contagem de pontos de controle não é validada na construção
GeoRegistration::isValid()	nenhum	Exige pelo menos dois pontos de controle	bool	—	Dois pontos é o mínimo para um mapeamento afim
GeoRegistration::toPdfMeasureDictionary()	nenhum	Emite um dicionário /Measure com /Subtype /GEO, /GCS, /GPTS, /LPTS e /Bounds	string	—	Não verifica isValid(); proteja a chamada ou encaminhe por GeoPdfLayer
GeoPdfLayer::addRegistration()	int $pageIndex, GeoRegistration $registration	Anexa um registro para um índice de página baseado em zero	self	InvalidArgumentException quando $pageIndex é negativo	Fluente; o primeiro registro adicionado para uma página prevalece no momento da geração
GeoPdfLayer::getRegistrations()	nenhum	Retorna todos os registros na ordem de inserção	list<array{pageIndex: int, registration: GeoRegistration}>	—	Inclui duplicatas e registros inválidos conforme adicionados
GeoPdfLayer::generateViewportDictionary()	int $pageIndex	Emite um dicionário /Viewport com /BBox, /Name e um /Measure inline	string	—	String vazia quando a página não tem registro ou o registro é inválido
GeoPdfLayer::generateViewportArray()	int $pageIndex	Envolve o dicionário de viewport em colchetes como o literal do array /VP	string	—	String vazia quando ausente; os chamadores então omitem /VP para essa página
GeoPdfLayer::writeToPdfWriter()	BinaryBuffer $buffer, int $pageIndex	Escreve /VP mais o literal do array e uma quebra de linha no buffer	bool	—	true quando uma entrada foi escrita; nenhuma operação e false caso contrário

Assinaturas de ponto de entrada

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

Contrato de comportamento

Validação e formatação de coordenadas

GeoCoordinate valida na construção e nunca sofre mutação. Latitude fora de [-90, 90] ou longitude fora de [-180, 180] lança InvalidArgumentException nomeando o valor infrator. toDms() renderiza ambos os eixos como graus, minutos preenchidos com zero, segundos e um sufixo de hemisfério. toDecimal() renderiza latitude, longitude com seis casas decimais. fromDms() aceita entrada DMS com segundos opcionais, normaliza os glifos de linha (prime), linha dupla (double-prime), sinal de grau e aspas tipográficas, converte para graus decimais com sinal e constrói uma nova instância. Latitudes ao sul e longitudes a oeste tornam-se valores negativos.

Mapeamento de projeção

Cada caso de ProjectionType carrega um código EPSG fixo e um rótulo. O mapeamento é uma tabela fechada, não um registro de sistemas de referência de coordenadas.

Caso	Valor de apoio	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

O caso UTM emite o código da zona 1. Projetos que precisam de uma zona UTM diferente, ou de qualquer código EPSG fora desta tabela, devem carregar a descrição autoritativa do CRS na string datum como Well Known Text.

Emissão do dicionário de medida

GeoRegistration::toPdfMeasureDictionary() emite um dicionário de várias linhas: /Type /Measure, /Subtype /GEO, um dicionário de sistema de coordenadas /GCS, /GPTS, /LPTS e /Bounds, conforme ISO 32000-2:2020 §12.10 (Tabela 269). Comportamento concreto:

• /GCS é emitido como << /Type /PROJCS /EPSG <code> /WKT (<datum>) >>. O código EPSG vem do caso de projeção. O valor /WKT é a string datum exatamente como fornecida; o padrão é WGS84.
• /GPTS lista pares de latitude-longitude com seis casas decimais, na ordem dos pontos de controle.
• /LPTS lista pares pdfX/pdfY com seis casas decimais, exatamente como fornecidos. A Tabela 269 da ISO 32000-2:2020 define os pontos LPTS em um quadrado unitário 2D; fornecer valores normalizados ao quadrado unitário é responsabilidade do chamador.
• /Bounds é fixo em [0 0 0 1 1 1 1 0], o quadrado unitário completo.
• A string datum é escapada antes da interpolação na string literal: barra invertida, parênteses e caracteres de controle comuns tornam-se seus escapes com barra invertida conforme ISO 32000-2:2020 §7.3.4.2. Um datum influenciado pelo chamador não pode encerrar a string literal nem injetar tokens PDF brutos.

Emissão de viewport e de página

GeoPdfLayer mantém os registros na ordem de inserção, indexados por índice de página baseado em zero. generateViewportDictionary() resolve o primeiro registro da página solicitada e retorna uma string vazia quando nenhum existe ou quando isValid() é falso. Um dicionário produzido carrega /Type /Viewport, um /BBox calculado a partir das coordenadas PDF mínima e máxima dos pontos de controle, um /Name na forma GeoViewport_Page<n> e o dicionário /Measure inline. A entrada /Measure do viewport segue a ISO 32000-2:2020 §12.9. generateViewportArray() envolve o dicionário em colchetes, produzindo o valor /VP da página: um array de dicionários de viewport conforme ISO 32000-2:2020 §7.7.3.3 (Tabela 31). writeToPdfWriter() escreve /VP mais o literal do array em um BinaryBuffer do Core e informa se algo foi escrito, para que a serialização da página possa omitir a chave de forma limpa.

Casos extremos e modos de falha

• Latitude ou longitude fora do intervalo lança InvalidArgumentException na construção; nenhuma coordenada parcialmente válida existe.
• fromDms() lança em entrada não analisável. Os valores analisados passam pelo construtor, então uma string sintaticamente válida com valores fora do intervalo também lança.
• A notação DMS não carrega altitude; fromDms() sempre produz altitude 0.0.
• Uma GeoRegistration com menos de dois pontos de controle reporta isValid() falso, mas toPdfMeasureDictionary() ainda emite um dicionário com arrays de pontos curtos. Proteja as chamadas diretas com isValid(), ou encaminhe a emissão por GeoPdfLayer, que suprime registros inválidos.
• Registros duplicados para um índice de página são todos retidos por getRegistrations(); a geração de viewport usa o primeiro adicionado.
• Um índice de página negativo lança InvalidArgumentException; os índices de página são baseados em zero.
• Pontos de controle que compartilham um valor de X ou Y produzem um /BBox degenerado de largura zero ou altura zero. Forneça pontos que abranjam ambos os eixos.
• Toda a saída é texto gerado. Nada é escrito em disco ou rede, e uma entrada idêntica produz uma saída idêntica.
• Nenhuma operação criptográfica ocorre neste módulo, portanto não há comportamento específico do modo FIPS.

Conformidade

Afirmação	Norma	Cláusula
O dicionário de medida é emitido com subtipo GEO, com pares de latitude-longitude GPTS e valores LPTS pareados.	ISO 32000-2:2020	§12.10
O dicionário de viewport carrega as entradas BBox, Name e Measure.	ISO 32000-2:2020	§12.9
O valor VP da página é emitido como um array de dicionários de viewport.	ISO 32000-2:2020	§7.7.3.3
A interpolação do datum escapa os metacaracteres de string literal.	ISO 32000-2:2020	§7.3.4.2

Todas as cláusulas são parafraseadas; o NextPDF não reproduz texto normativo. Estas são declarações de capacidade, não certificações. O NextPDF não detém nenhuma certificação e não concede nenhuma. Os códigos EPSG são valores representativos fixos por caso de projeção, e a entrada /WKT carrega a string de datum fornecida em vez de uma descrição Well Known Text gerada; ambas as afirmações são fundamentadas no produto. Valide a saída GeoPDF emitida nos processadores de PDF interativos de destino antes de confiar na medição do lado do visualizador.

Notas de desenvolvimento

• Disponível desde nextpdf/pro 1.9.0; atual em nextpdf/pro 3.1.0.
• Verifique isValid() antes de chamar toPdfMeasureDictionary() diretamente; GeoPdfLayer realiza essa verificação por você.
• Quando consumidores downstream analisam /WKT, passe uma descrição Well Known Text completa como datum; o padrão WGS84 é apenas um rótulo de datum.
• Normalize as entradas LPTS para o quadrado unitário antes de construir os pontos de controle quando os limites do viewport diferirem dos seus valores de espaço PDF.
• O custo de emissão é linear na contagem de pontos de controle; a busca em GeoPdfLayer é linear na contagem de registros.
• writeToPdfWriter() integra-se com a serialização de página por meio de NextPDF\Support\BinaryBuffer do Core.

Limite de publicação

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

Veja também

• Geo (capacidade) — instalação, visão conceitual e amostras de início rápido.
• Document — Referência Profunda — a superfície de composição de documento e página.