Geo — Riferimento approfondito

In sintesi

Questa pagina è il riferimento a livello di contratto per il modulo Geo di NextPDF Pro. La superficie è costituita da quattro value object immutabili — GeoCoordinate, GeoControlPoint, ProjectionType e GeoRegistration — più GeoPdfLayer, che associa le registrazioni agli indici di pagina ed emette l’output del viewport. Il modulo produce testo di dizionari PDF: un dizionario /Measure con /Subtype /GEO, un dizionario /Viewport e il valore dell’array /VP a livello di pagina. La generazione è un assemblaggio deterministico di stringhe: nessuna chiamata di rete, nessun accesso al filesystem, nessuna casualità. Questa pagina enuncia l’API pubblica, il contratto di comportamento osservabile e le modalità di errore.

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.

Nessun flag di licenza per singola funzionalità applica il gate a questo modulo. Le classi Geo sono disponibili ogni volta che nextpdf/pro è installato.

Superficie API pubblica

Simbolo	Parametri	Comportamento predefinito	Restituisce	Solleva o fallisce con	Note
GeoCoordinate	costruttore: float $latitude, float $longitude, float $altitude = 0.0	Convalida la latitudine entro [-90, 90] e la longitudine entro [-180, 180]	—	InvalidArgumentException quando uno dei valori è fuori intervallo	final readonly; l’altitudine è in metri sul livello del mare e non è sottoposta a controllo di intervallo
GeoCoordinate::toDms()	nessuno	Formatta in gradi-minuti-secondi con suffissi N/S ed E/W	string	—	I secondi prossimi allo zero rendono 00; altrimenti due decimali con gli zeri finali eliminati
GeoCoordinate::toDecimal()	nessuno	Formatta latitudine e longitudine con sei decimali, separate da virgola	string	—	L’altitudine non è inclusa
GeoCoordinate::fromDms()	string $dms	Analizza una stringa DMS; i secondi sono facoltativi; i glifi tipografici di grado e apice vengono normalizzati	self	InvalidArgumentException quando la stringa non viene analizzata, o quando i valori analizzati non superano i controlli di intervallo del costruttore	Factory statico; le lettere dell’emisfero sono insensibili alle maiuscole; l’altitudine assume come predefinito 0.0
GeoControlPoint	costruttore: float $pdfX, float $pdfY, GeoCoordinate $geo	Accoppia un punto nello spazio utente PDF (in punti) con una coordinata geografica	—	—	final readonly; le coordinate PDF non vengono convalidate
ProjectionType	enum con backing di tipo string, 4 casi	Casi: Geographic, UTM, TransverseMercator, LambertConformal	valori di backing GEO, UTM, TM, LCC	—	Vedere la tabella di mappatura delle proiezioni più sotto
ProjectionType::epsgCode()	nessuno	Mappa il caso su un codice EPSG fisso	int	—	4326, 32601, 2154 o 3347
ProjectionType::label()	nessuno	Nome leggibile della proiezione	string	—	Per esempio WGS 84 Geographic
GeoRegistration	costruttore: array $controlPoints, ProjectionType $projection, string $datum = 'WGS84'	Contiene i punti di controllo, la proiezione e il datum geodetico	—	—	final readonly; il numero di punti di controllo non viene convalidato in fase di costruzione
GeoRegistration::isValid()	nessuno	Richiede almeno due punti di controllo	bool	—	Due punti è il minimo per una mappatura affine
GeoRegistration::toPdfMeasureDictionary()	nessuno	Emette un dizionario /Measure con /Subtype /GEO, /GCS, /GPTS, /LPTS e /Bounds	string	—	Non verifica isValid(); proteggere la chiamata o instradarla tramite GeoPdfLayer
GeoPdfLayer::addRegistration()	int $pageIndex, GeoRegistration $registration	Aggiunge una registrazione per un indice di pagina in base zero	self	InvalidArgumentException quando $pageIndex è negativo	Fluente; la prima registrazione aggiunta per una pagina prevale in fase di generazione
GeoPdfLayer::getRegistrations()	nessuno	Restituisce tutte le registrazioni nell’ordine di inserimento	list<array{pageIndex: int, registration: GeoRegistration}>	—	Include i duplicati e le registrazioni non valide così come aggiunti
GeoPdfLayer::generateViewportDictionary()	int $pageIndex	Emette un dizionario /Viewport con /BBox, /Name e un /Measure inline	string	—	Stringa vuota quando la pagina non ha registrazione o la registrazione non è valida
GeoPdfLayer::generateViewportArray()	int $pageIndex	Racchiude il dizionario del viewport tra parentesi come literal dell’array /VP	string	—	Stringa vuota quando assente; i chiamanti omettono quindi /VP per quella pagina
GeoPdfLayer::writeToPdfWriter()	BinaryBuffer $buffer, int $pageIndex	Scrive /VP più il literal dell’array e un a capo sul buffer	bool	—	true quando è stata scritta una voce; no-op e false in caso contrario

Firme dei punti di ingresso

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

Contratto di comportamento

Convalida e formattazione delle coordinate

GeoCoordinate convalida in fase di costruzione e non muta mai. Una latitudine fuori da [-90, 90] o una longitudine fuori da [-180, 180] solleva InvalidArgumentException indicando il valore incriminato. toDms() rende entrambi gli assi come gradi, minuti con zero iniziale, secondi e un suffisso di emisfero. toDecimal() rende latitude, longitude con sei decimali. fromDms() accetta input DMS con secondi facoltativi, normalizza i glifi di apice, doppio apice, segno di grado e virgolette tipografiche, converte in gradi decimali con segno e costruisce una nuova istanza. Le latitudini meridionali e le longitudini occidentali diventano valori negativi.

Mappatura delle proiezioni

Ciascun caso di ProjectionType porta un codice EPSG fisso e un’etichetta. La mappatura è una tabella chiusa, non un registro di sistemi di riferimento delle coordinate.

Caso	Valore di backing	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

Il caso UTM emette il codice della zona 1. I progetti che necessitano di una zona UTM diversa, o di qualsiasi codice EPSG al di fuori di questa tabella, dovrebbero riportare la descrizione CRS autorevole nella stringa datum come Well Known Text.

Emissione del dizionario measure

GeoRegistration::toPdfMeasureDictionary() emette un dizionario multiriga: /Type /Measure, /Subtype /GEO, un dizionario di sistema di coordinate /GCS, /GPTS, /LPTS e /Bounds, secondo ISO 32000-2:2020 §12.10 (Table 269). Comportamento concreto:

• /GCS viene emesso come << /Type /PROJCS /EPSG <code> /WKT (<datum>) >>. Il codice EPSG proviene dal caso di proiezione. Il valore /WKT è la stringa datum esattamente come fornita; il valore predefinito è WGS84.
• /GPTS elenca coppie latitudine-longitudine con sei decimali, nell’ordine dei punti di controllo.
• /LPTS elenca coppie pdfX/pdfY con sei decimali, esattamente come fornite. ISO 32000-2:2020 Table 269 definisce i punti LPTS in un quadrato unitario 2D; fornire valori normalizzati sul quadrato unitario è responsabilità del chiamante.
• /Bounds è fisso a [0 0 0 1 1 1 1 0], l’intero quadrato unitario.
• La stringa datum viene sottoposta a escape prima dell’interpolazione nella stringa literal: barra rovesciata, parentesi e i comuni caratteri di controllo diventano i rispettivi escape con barra rovesciata secondo ISO 32000-2:2020 §7.3.4.2. Un datum influenzato dal chiamante non può terminare la stringa literal né iniettare token PDF grezzi.

Emissione del viewport e della pagina

GeoPdfLayer mantiene le registrazioni nell’ordine di inserimento, indicizzate per indice di pagina in base zero. generateViewportDictionary() risolve la prima registrazione per la pagina richiesta e restituisce una stringa vuota quando nessuna esiste o quando isValid() è false. Un dizionario prodotto porta /Type /Viewport, un /BBox calcolato dalle coordinate PDF minime e massime dei punti di controllo, un /Name nella forma GeoViewport_Page<n> e il dizionario /Measure inline. La voce /Measure del viewport segue ISO 32000-2:2020 §12.9. generateViewportArray() racchiude il dizionario tra parentesi, producendo il valore /VP della pagina: un array di dizionari viewport secondo ISO 32000-2:2020 §7.7.3.3 (Table 31). writeToPdfWriter() scrive /VP più il literal dell’array su un BinaryBuffer di Core e riporta se è stato scritto qualcosa, così che la serializzazione della pagina possa omettere la chiave in modo pulito.

Casi limite e modalità di errore

• Una latitudine o longitudine fuori intervallo solleva InvalidArgumentException in fase di costruzione; non esiste alcuna coordinata parzialmente valida.
• fromDms() solleva un’eccezione su input non analizzabile. I valori analizzati passano attraverso il costruttore, quindi anche una stringa sintatticamente valida con valori fuori intervallo solleva un’eccezione.
• La notazione DMS non porta altitudine; fromDms() produce sempre altitudine 0.0.
• Una GeoRegistration con meno di due punti di controllo riporta isValid() false, eppure toPdfMeasureDictionary() emette comunque un dizionario con array di punti corti. Proteggere le chiamate dirette con isValid(), oppure instradare l’emissione tramite GeoPdfLayer, che sopprime le registrazioni non valide.
• Le registrazioni duplicate per un unico indice di pagina vengono tutte conservate da getRegistrations(); la generazione del viewport usa la prima aggiunta.
• Un indice di pagina negativo solleva InvalidArgumentException; gli indici di pagina sono in base zero.
• Punti di controllo che condividono un valore X o Y producono un /BBox degenere di larghezza o altezza zero. Fornire punti che coprano entrambi gli assi.
• Tutto l’output è testo generato. Nulla viene scritto su disco o rete, e input identico produce output identico.
• In questo modulo non avviene alcuna operazione crittografica, quindi non esiste alcun comportamento specifico della modalità FIPS.

Conformità

Affermazione	Standard	Clausola
Il dizionario measure viene emesso con sottotipo GEO, con coppie latitudine-longitudine GPTS e valori LPTS accoppiati.	ISO 32000-2:2020	§12.10
Il dizionario del viewport porta le voci BBox, Name e Measure.	ISO 32000-2:2020	§12.9
Il valore VP della pagina viene emesso come array di dizionari viewport.	ISO 32000-2:2020	§7.7.3.3
L’interpolazione del datum applica l’escape ai metacaratteri della stringa literal.	ISO 32000-2:2020	§7.3.4.2

Tutte le clausole sono parafrasate; NextPDF non riproduce testo normativo. Si tratta di dichiarazioni di capacità, non di certificazioni. NextPDF non detiene alcuna certificazione e non ne concede alcuna. I codici EPSG sono valori rappresentativi fissi per caso di proiezione, e la voce /WKT riporta la stringa datum fornita anziché una descrizione Well Known Text generata; entrambe le affermazioni sono fondate sul prodotto. Convalidare l’output GeoPDF emesso nei processori PDF interattivi di destinazione prima di fare affidamento sulla misurazione lato viewer.

Note di sviluppo

• Disponibile da nextpdf/pro 1.9.0; attuale in nextpdf/pro 3.1.0.
• Verificare isValid() prima di chiamare direttamente toPdfMeasureDictionary(); GeoPdfLayer esegue questo controllo automaticamente.
• Quando i consumatori a valle analizzano /WKT, passare una descrizione Well Known Text completa come datum; il valore predefinito WGS84 è solo un’etichetta di datum.
• Normalizzare gli input LPTS al quadrato unitario prima di costruire i punti di controllo quando i limiti del viewport differiscono dai valori nello spazio PDF.
• Il costo di emissione è lineare nel numero di punti di controllo; la ricerca in GeoPdfLayer è lineare nel numero di registrazioni.
• writeToPdfWriter() si integra con la serializzazione della pagina tramite NextPDF\Support\BinaryBuffer di Core.

Confine di pubblicazione

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

Vedere anche

• Geo (funzionalità) — installazione, panoramica concettuale e campioni di avvio rapido.
• Document — Riferimento approfondito — la superficie di composizione del documento e della pagina.