Geo

De un vistazo

NextPDF Pro asigna las coordenadas de página PDF a coordenadas geográficas y genera un diccionario de medida PDF con el subtipo GEO, de modo que un visor pueda informar de la posición en el mundo real a partir de un punto de la página.

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. Compare ediciones y obtenga una licencia.

Geo no tiene un indicador de licencia separado por función; el sobre de nivel Pro lo habilita directamente.

Instalación

composer require nextpdf/pro:^3

Descripción conceptual

Un PDF geoespacial transporta un diccionario de medida, descrito en ISO 32000-2 §12.8.2, que vincula los puntos del espacio de dispositivo a un sistema de referencia de coordenadas geográficas. NextPDF Pro construye esos datos a partir de objetos de valor inmutables:

• GeoCoordinate — una terna de latitud/longitud/altitud. La construcción valida la latitud dentro de [-90, 90] y la longitud dentro de [-180, 180], y ofrece formato de grados-minutos-segundos y de cadena decimal.
• GeoControlPoint — un emparejamiento de un punto del espacio PDF con una GeoCoordinate.
• ProjectionType — un enum de proyecciones habituales (geográfica, UTM, Mercator transversa, cónica conforme de Lambert), cada una asignada a un código EPSG.
• GeoRegistration — los puntos de control más la proyección y el dato geodésico (predeterminado WGS84). isValid() requiere al menos dos puntos de control para una transformación afín mínima; toPdfMeasureDictionary() emite el diccionario /Measure con /Subtype /GEO y los arrays de puntos de control.

Por qué funciona así

NextPDF construye el diccionario de medida a partir de objetos de valor validados e inmutables, no a partir de un diccionario en bruto suministrado por el llamador. GeoCoordinate rechaza una latitud o longitud fuera de rango en la construcción. GeoRegistration::isValid() rechaza menos de dos puntos de control, de modo que un registro mal formado falla rápido en lugar de emitir un diccionario /GEO degradado. Las proyecciones se resuelven a códigos EPSG estándar mediante ProjectionType, lo que mantiene explícito el sistema de referencia de coordenadas en lugar de adivinado. El dato toma por defecto WGS84 pero permanece como un campo con nombre, de modo que un sistema de referencia no predeterminado es una elección deliberada. Esta postura de cierre seguro importa porque una georreferencia errónea es peor que ninguna; un visor informaría con confianza de una posición falsa en el mundo real. Contexto de diseño: Una API que se niega a adivinar.

Superficie de la API

Clase	Responsabilidad
GeoCoordinate	Lat/lon/altitud validadas con formato.
GeoControlPoint	Emparejamiento de punto PDF ↔ punto geográfico.
ProjectionType	Enum de proyección con códigos EPSG.
GeoRegistration	Construir el diccionario /Measure /GEO.

Ejemplo de código — Inicio 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();

Ejemplo de código — Producción

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 límite y trampas

• La construcción de GeoCoordinate rechaza una latitud o longitud fuera de rango.
• Menos de dos puntos de control producen un registro inválido.
• El dato predeterminado es WGS84; establézcalo explícitamente para otros sistemas de referencia.

Rendimiento

La generación del diccionario es lineal respecto al número de puntos de control.

Notas de seguridad

La entrada de Geo son datos de coordenadas numéricas. Valide los puntos de control procedentes de entradas no confiables antes del registro.

Conformidad

Comportamiento	Referencia	Estado
Diccionario de medida geoespacial (subtipo GEO)	ISO 32000-2 §12.8.2	Alineado (parafraseado)

Contrato de comportamiento

• GeoCoordinate valida la latitud dentro de [-90, 90] y la longitud dentro de [-180, 180] en la construcción y ofrece formato de cadena DMS y decimal.
• GeoControlPoint empareja un punto del espacio PDF con una GeoCoordinate.
• GeoRegistration transporta los puntos de control más un ProjectionType (asignado a un código EPSG) y un dato geodésico que toma por defecto WGS84. isValid() requiere al menos dos puntos de control; toPdfMeasureDictionary() emite un diccionario /Measure con /Subtype /GEO y los arrays de puntos de control.
• Las coordenadas fuera de rango o menos de dos puntos de control producen un registro inválido en lugar de una salida degradada de forma silenciosa.

Nota sobre el límite de Enterprise

Enterprise no cambia el comportamiento de Geo. Enterprise añade funciones de nivel superior documentadas por separado; no son necesarias para generar un diccionario de medida GeoPDF.

Reserva / alternativa de Core

No existe ningún equivalente en Core para la generación de diccionarios de medida GeoPDF. Es una adición de Pro.

Límite de publicación

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

Véase también

• Geo — Referencia profunda — referencia completa de clases y métodos.
• Document — ensamblado de páginas y documentos.
• Anotaciones de Core.