Geo

In sintesi

NextPDF Pro mappa le coordinate di pagina del PDF a coordinate geografiche e genera un dizionario di misura PDF con il sottotipo GEO, così che un visualizzatore possa riportare la posizione reale a partire da un punto sulla pagina.

Disponibilità e licenza

Questa funzionalità è inclusa in NextPDF Pro (nextpdf/pro) e si attiva con un envelope di licenza di livello Pro. Un deployment privo di tale entitlement non carica le classi della funzionalità. Confronta le edizioni e ottieni una licenza.

Geo non ha un flag di licenza separato per funzionalità; l’envelope di livello Pro la abilita direttamente.

Installazione

composer require nextpdf/pro:^3

Panoramica concettuale

Un PDF geospaziale porta un dizionario di misura, descritto in ISO 32000-2 §12.8.2, che lega i punti dello spazio dispositivo a un sistema di riferimento di coordinate geografiche. NextPDF Pro costruisce tali dati a partire da value object immutabili:

• GeoCoordinate — una tripletta latitudine/longitudine/altitudine. La costruzione convalida la latitudine entro [-90, 90] e la longitudine entro [-180, 180], e offre la formattazione in gradi-minuti-secondi e in stringa decimale.
• GeoControlPoint — l’accoppiamento di un punto dello spazio PDF con una GeoCoordinate.
• ProjectionType — un’enumerazione di proiezioni comuni (geografica, UTM, Mercatore trasversa, conica conforme di Lambert), ciascuna mappata a un codice EPSG.
• GeoRegistration — i punti di controllo più la proiezione e il datum geodetico (default WGS84). isValid() richiede almeno due punti di controllo per una trasformazione affine minimale; toPdfMeasureDictionary() emette il dizionario /Measure con /Subtype /GEO e gli array dei punti di controllo.

Perché funziona così

NextPDF costruisce il dizionario di misura a partire da value object convalidati e immutabili, non da un dizionario grezzo fornito dal chiamante. GeoCoordinate rifiuta una latitudine o una longitudine fuori intervallo in fase di costruzione. GeoRegistration::isValid() rifiuta meno di due punti di controllo, così che una registrazione malformata fallisca subito anziché emettere un dizionario /GEO degradato. Le proiezioni si risolvono in codici EPSG standard tramite ProjectionType, che mantiene esplicito il sistema di riferimento delle coordinate invece di indovinarlo. Il datum è per default WGS84 ma resta un campo con nome, così che un sistema di riferimento non predefinito sia una scelta deliberata. Questa postura fail-closed è importante perché una georeferenziazione sbagliata è peggiore di nessuna; un visualizzatore riporterebbe con sicurezza una posizione reale falsa. Approfondimento di progettazione: Un’API che si rifiuta di indovinare.

Superficie API

Class	Responsibility
GeoCoordinate	Lat/lon/altitudine convalidate con formattazione.
GeoControlPoint	Accoppiamento punto PDF ↔ punto geografico.
ProjectionType	Enumerazione delle proiezioni con codici EPSG.
GeoRegistration	Costruire il dizionario /Measure /GEO.

Esempio di codice — Avvio rapido

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

Esempio di codice — Produzione

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

Casi limite e insidie

• La costruzione di GeoCoordinate rifiuta una latitudine o una longitudine fuori intervallo.
• Meno di due punti di controllo producono una registrazione non valida.
• Il datum predefinito è WGS84; impostarlo esplicitamente per altri sistemi di riferimento.

Prestazioni

La generazione del dizionario è lineare rispetto al numero di punti di controllo.

Note sulla sicurezza

L’input di Geo è costituito da dati di coordinate numeriche. Convalidare i punti di controllo provenienti da input non attendibile prima della registrazione.

Conformità

Behavior	Reference	Status
Geospatial measure dictionary (GEO subtype)	ISO 32000-2 §12.8.2	Aligned (paraphrased)

Contratto di comportamento

• GeoCoordinate convalida la latitudine entro [-90, 90] e la longitudine entro [-180, 180] in fase di costruzione e offre la formattazione in stringa DMS e decimale.
• GeoControlPoint accoppia un punto dello spazio PDF con una GeoCoordinate.
• GeoRegistration porta i punti di controllo più un ProjectionType (mappato a un codice EPSG) e un datum geodetico con default WGS84. isValid() richiede almeno due punti di controllo; toPdfMeasureDictionary() emette un dizionario /Measure con /Subtype /GEO e gli array dei punti di controllo.
• Coordinate fuori intervallo o meno di due punti di controllo producono una registrazione non valida anziché un output silenziosamente degradato.

Nota sul confine Enterprise

Enterprise non modifica il comportamento di Geo. Enterprise aggiunge funzionalità di fascia superiore documentate separatamente; non sono richieste per generare un dizionario di misura GeoPDF.

Core fallback / alternativa

Non esiste alcun equivalente Core per la generazione del dizionario di misura GeoPDF. Questa è un’aggiunta di Pro.

Confine di pubblicazione

Questa pagina documenta solo il comportamento osservabile dall’esterno e la superficie pubblica supportata dell’API. Percorsi di namespace interni, classi helper, tabelle di meccanismi, nomi di file di runbook e prefissi di ticket sono fuori ambito.

Vedere anche

• Geo — Deep Reference — riferimento completo di classi e metodi.
• Document — assemblaggio di pagine e documenti.
• Core annotations.