Geo — Referencia detallada

De un vistazo

Esta página es la referencia a nivel de contrato del módulo Geo de NextPDF Pro. La superficie consta de cuatro objetos de valor inmutables — GeoCoordinate, GeoControlPoint, ProjectionType y GeoRegistration — más GeoPdfLayer, que asocia registros con índices de página y emite la salida del viewport. El módulo produce texto de diccionario PDF: un diccionario /Measure con /Subtype /GEO, un diccionario /Viewport y el valor del array /VP a nivel de página. La generación es un ensamblado determinista de cadenas: sin llamada de red, sin acceso al sistema de archivos, sin aleatoriedad. Esta página expone la API pública, el contrato de comportamiento observable y los modos de fallo.

Disponibilidad y licencias

Esta capacidad se distribuye en NextPDF Pro (nextpdf/pro) y se activa con un sobre de licencia de nivel Pro. Un despliegue sin ese derecho no carga las clases de la capacidad. Comparar ediciones y obtener una licencia.

Ningún indicador de licencia por característica restringe este módulo. Las clases de Geo están disponibles siempre que nextpdf/pro esté instalado.

Superficie de la API pública

Símbolo	Parámetros	Comportamiento predeterminado	Devuelve	Lanza o falla con	Notas
GeoCoordinate	constructor: float $latitude, float $longitude, float $altitude = 0.0	Valida la latitud dentro de [-90, 90] y la longitud dentro de [-180, 180]	—	InvalidArgumentException cuando cualquiera de los valores está fuera de rango	final readonly; la altitud son metros sobre el nivel del mar y no se comprueba el rango
GeoCoordinate::toDms()	ninguno	Formatea como grados-minutos-segundos con sufijos N/S y E/W	string	—	Los segundos cercanos a cero se representan como 00; en caso contrario, dos decimales con los ceros finales recortados
GeoCoordinate::toDecimal()	ninguno	Formatea la latitud y la longitud a seis decimales, separadas por comas	string	—	La altitud no se incluye
GeoCoordinate::fromDms()	string $dms	Analiza una cadena DMS; los segundos son opcionales; los glifos tipográficos de grado y de comillas se normalizan	self	InvalidArgumentException cuando la cadena no se analiza, o cuando los valores analizados no superan las comprobaciones de rango del constructor	Factoría estática; las letras de hemisferio no distinguen mayúsculas y minúsculas; la altitud es 0.0 de forma predeterminada
GeoControlPoint	constructor: float $pdfX, float $pdfY, GeoCoordinate $geo	Empareja un punto del espacio de usuario PDF (en puntos) con una coordenada geográfica	—	—	final readonly; las coordenadas PDF no se validan
ProjectionType	enum respaldado por cadena, 4 casos	Casos: Geographic, UTM, TransverseMercator, LambertConformal	valores de respaldo GEO, UTM, TM, LCC	—	Consulte la tabla de mapeo de proyecciones más abajo
ProjectionType::epsgCode()	ninguno	Asigna al caso un único código EPSG fijo	int	—	4326, 32601, 2154 o 3347
ProjectionType::label()	ninguno	Nombre de proyección legible por humanos	string	—	Por ejemplo WGS 84 Geographic
GeoRegistration	constructor: array $controlPoints, ProjectionType $projection, string $datum = 'WGS84'	Contiene los puntos de control, la proyección y el datum geodésico	—	—	final readonly; el número de puntos de control no se valida en la construcción
GeoRegistration::isValid()	ninguno	Requiere al menos dos puntos de control	bool	—	Dos puntos es el mínimo para un mapeo afín
GeoRegistration::toPdfMeasureDictionary()	ninguno	Emite un diccionario /Measure con /Subtype /GEO, /GCS, /GPTS, /LPTS y /Bounds	string	—	No comprueba isValid(); proteja la llamada o encáucela a través de GeoPdfLayer
GeoPdfLayer::addRegistration()	int $pageIndex, GeoRegistration $registration	Añade un registro para un índice de página basado en cero	self	InvalidArgumentException cuando $pageIndex es negativo	Fluida; el primer registro añadido para una página prevalece en el momento de la generación
GeoPdfLayer::getRegistrations()	ninguno	Devuelve todos los registros en orden de inserción	list<array{pageIndex: int, registration: GeoRegistration}>	—	Incluye duplicados y registros no válidos tal como se añadieron
GeoPdfLayer::generateViewportDictionary()	int $pageIndex	Emite un diccionario /Viewport con /BBox, /Name y un /Measure en línea	string	—	Cadena vacía cuando la página no tiene registro o el registro no es válido
GeoPdfLayer::generateViewportArray()	int $pageIndex	Envuelve el diccionario de viewport entre corchetes como el literal de array /VP	string	—	Cadena vacía cuando está ausente; quienes llaman omiten entonces /VP para esa página
GeoPdfLayer::writeToPdfWriter()	BinaryBuffer $buffer, int $pageIndex	Escribe /VP más el literal de array y un salto de línea en el búfer	bool	—	true cuando se escribió una entrada; sin efecto y false en caso contrario

Firmas de los puntos 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 comportamiento

Validación y formateo de coordenadas

GeoCoordinate valida en la construcción y nunca muta. Una latitud fuera de [-90, 90] o una longitud fuera de [-180, 180] lanza InvalidArgumentException indicando el valor infractor. toDms() representa ambos ejes como grados, minutos rellenados con ceros, segundos y un sufijo de hemisferio. toDecimal() representa latitude, longitude con seis decimales. fromDms() acepta una entrada DMS con segundos opcionales, normaliza los glifos de prima, doble prima, signo de grado y comillas tipográficas, convierte a grados decimales con signo y construye una nueva instancia. Las latitudes del sur y las longitudes del oeste pasan a ser valores negativos.

Mapeo de proyecciones

Cada caso de ProjectionType lleva un único código EPSG y una etiqueta fijos. El mapeo es una tabla cerrada, no un registro de sistemas de referencia de coordenadas.

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

El caso UTM emite el código de la zona 1. Los proyectos que necesiten una zona UTM distinta, o cualquier código EPSG fuera de esta tabla, deberían llevar la descripción autorizada del CRS en la cadena datum como Well Known Text.

Emisión del diccionario de medida

GeoRegistration::toPdfMeasureDictionary() emite un diccionario multilínea: /Type /Measure, /Subtype /GEO, un diccionario de sistema de coordenadas /GCS, /GPTS, /LPTS y /Bounds, según ISO 32000-2:2020 §12.10 (Tabla 269). Comportamiento concreto:

• /GCS se emite como << /Type /PROJCS /EPSG <code> /WKT (<datum>) >>. El código EPSG procede del caso de proyección. El valor de /WKT es la cadena datum exactamente tal como se suministró; el valor predeterminado es WGS84.
• /GPTS enumera pares de latitud-longitud con seis decimales, en orden de puntos de control.
• /LPTS enumera pares pdfX/pdfY con seis decimales, exactamente tal como se suministraron. ISO 32000-2:2020 Tabla 269 define los puntos LPTS en un cuadrado unitario 2D; suministrar valores normalizados al cuadrado unitario es responsabilidad de quien llama.
• /Bounds es fijo en [0 0 0 1 1 1 1 0], el cuadrado unitario completo.
• La cadena datum se escapa antes de interpolarla en la cadena literal: la barra invertida, los paréntesis y los caracteres de control comunes pasan a sus escapes con barra invertida según ISO 32000-2:2020 §7.3.4.2. Un datum influido por quien llama no puede terminar la cadena literal ni inyectar tokens PDF en bruto.

Emisión de viewport y de página

GeoPdfLayer mantiene los registros en orden de inserción, indexados por índice de página basado en cero. generateViewportDictionary() resuelve el primer registro de la página solicitada y devuelve una cadena vacía cuando no existe ninguno o cuando isValid() es falso. Un diccionario producido lleva /Type /Viewport, un /BBox calculado a partir de las coordenadas PDF mínima y máxima de los puntos de control, un /Name con la forma GeoViewport_Page<n> y el diccionario /Measure en línea. La entrada /Measure del viewport sigue ISO 32000-2:2020 §12.9. generateViewportArray() envuelve el diccionario entre corchetes, produciendo el valor /VP de la página: un array de diccionarios de viewport según ISO 32000-2:2020 §7.7.3.3 (Tabla 31). writeToPdfWriter() escribe /VP más el literal de array en un BinaryBuffer de Core e informa de si se escribió algo, de modo que la serialización de página pueda omitir la clave de forma limpia.

Casos límite y modos de fallo

• Una latitud o longitud fuera de rango lanza InvalidArgumentException en la construcción; no existe ninguna coordenada parcialmente válida.
• fromDms() lanza ante una entrada no analizable. Los valores analizados pasan por el constructor, de modo que una cadena sintácticamente válida con valores fuera de rango también lanza.
• La notación DMS no lleva altitud; fromDms() siempre produce una altitud 0.0.
• Una GeoRegistration con menos de dos puntos de control informa isValid() falso, pero toPdfMeasureDictionary() emite igualmente un diccionario con arrays de puntos cortos. Proteja las llamadas directas con isValid(), o encauce la emisión a través de GeoPdfLayer, que suprime los registros no válidos.
• Los registros duplicados para un mismo índice de página se conservan todos en getRegistrations(); la generación del viewport usa el primero que se añadió.
• Un índice de página negativo lanza InvalidArgumentException; los índices de página se basan en cero.
• Los puntos de control que comparten un valor X o Y producen un /BBox degenerado de ancho cero o alto cero. Suministre puntos que abarquen ambos ejes.
• Toda la salida es texto generado. No se escribe nada en disco ni en red, y una entrada idéntica produce una salida idéntica.
• En este módulo no se produce ninguna operación criptográfica, por lo que no hay comportamiento específico del modo FIPS.

Conformidad

Afirmación	Estándar	Cláusula
El diccionario de medida se emite con subtipo GEO, con pares de latitud-longitud GPTS y valores LPTS emparejados.	ISO 32000-2:2020	§12.10
El diccionario de viewport lleva las entradas BBox, Name y Measure.	ISO 32000-2:2020	§12.9
El valor VP de la página se emite como un array de diccionarios de viewport.	ISO 32000-2:2020	§7.7.3.3
La interpolación del datum escapa los metacaracteres de la cadena literal.	ISO 32000-2:2020	§7.3.4.2

Todas las cláusulas están parafraseadas; NextPDF no reproduce texto normativo. Se trata de declaraciones de capacidad, no de certificaciones. NextPDF no posee ninguna certificación ni concede ninguna. Los códigos EPSG son valores representativos fijos por caso de proyección, y la entrada /WKT lleva la cadena de datum suministrada en lugar de una descripción Well Known Text generada; ambas afirmaciones se fundamentan en el producto. Valide la salida GeoPDF emitida en los procesadores interactivos de PDF de destino antes de confiar en la medición del lado del visor.

Notas de desarrollo

• Disponible desde nextpdf/pro 1.9.0; vigente en nextpdf/pro 3.1.0.
• Compruebe isValid() antes de llamar directamente a toPdfMeasureDictionary(); GeoPdfLayer realiza esta comprobación por usted.
• Cuando los consumidores posteriores analizan /WKT, pase una descripción Well Known Text completa como datum; el valor predeterminado WGS84 es solo una etiqueta de datum.
• Normalice las entradas LPTS al cuadrado unitario antes de construir los puntos de control cuando los límites del viewport difieran de sus valores del espacio PDF.
• El coste de emisión es lineal respecto al número de puntos de control; la búsqueda en GeoPdfLayer es lineal respecto al número de registros.
• writeToPdfWriter() se integra con la serialización de página a través de NextPDF\Support\BinaryBuffer de Core.

Límite de publicación

Esta página documenta únicamente el comportamiento observable externamente y la superficie pública de la API compatible. Las rutas de espacios de nombres internas, las clases auxiliares, las tablas de mecanismos, los nombres de archivo de los runbooks y los prefijos de tickets quedan fuera del alcance.

Consulte también

• Geo (capacidad) — instalación, visión conceptual y ejemplos de inicio rápido.
• Document — Referencia detallada — la superficie de composición de documento y página.