Geo — Diepe referentie

In het kort

Deze pagina is de referentie op contractniveau voor de NextPDF Pro Geo-module. Het oppervlak bestaat uit vier onveranderlijke waardeobjecten — GeoCoordinate, GeoControlPoint, ProjectionType en GeoRegistration — plus GeoPdfLayer, die registraties koppelt aan pagina-indexen en viewport-uitvoer genereert. De module produceert tekst voor PDF-dictionaries: een /Measure-dictionary met /Subtype /GEO, een /Viewport-dictionary en de /VP-arraywaarde op paginaniveau. De generatie is deterministische string-assemblage: geen netwerkaanroep, geen toegang tot het bestandssysteem, geen willekeur. Deze pagina beschrijft de publieke API, het waarneembare gedragscontract en de faalmodi.

Beschikbaarheid en licentie

Deze functionaliteit wordt geleverd in NextPDF Pro (nextpdf/pro) en wordt geactiveerd met een licentie-envelop op Pro-niveau. Een deployment zonder dat recht laadt de klassen van de functionaliteit niet. Vergelijk edities en verkrijg een licentie.

Geen licentievlag per functie gate’t deze module. De Geo-klassen zijn beschikbaar zodra nextpdf/pro is geïnstalleerd.

Publiek API-oppervlak

Symbool	Parameters	Standaardgedrag	Retourneert	Genereert of faalt met	Opmerkingen
GeoCoordinate	constructor: float $latitude, float $longitude, float $altitude = 0.0	Valideert breedtegraad binnen [-90, 90] en lengtegraad binnen [-180, 180]	—	InvalidArgumentException wanneer een van beide waarden buiten bereik ligt	final readonly; altitude is meters boven zeeniveau en wordt niet op bereik gecontroleerd
GeoCoordinate::toDms()	geen	Formatteert als graden-minuten-seconden met de achtervoegsels N/S en E/W	string	—	Seconden nabij nul worden als 00 weergegeven; anders twee decimalen met afgekapte nullen aan het eind
GeoCoordinate::toDecimal()	geen	Formatteert breedte- en lengtegraad op zes decimalen, gescheiden door komma’s	string	—	Altitude wordt niet opgenomen
GeoCoordinate::fromDms()	string $dms	Parseert een DMS-string; seconden zijn optioneel; typografische graad- en aanhalingstekens worden genormaliseerd	self	InvalidArgumentException wanneer de string niet parseert, of wanneer geparseerde waarden de bereikcontroles van de constructor niet doorstaan	Statische factory; letters voor het halfrond zijn hoofdletterongevoelig; altitude is standaard 0.0
GeoControlPoint	constructor: float $pdfX, float $pdfY, GeoCoordinate $geo	Koppelt een punt in PDF-gebruikersruimte (punten) aan een geografische coördinaat	—	—	final readonly; PDF-coördinaten worden niet gevalideerd
ProjectionType	op string gebaseerde enum, 4 cases	Cases: Geographic, UTM, TransverseMercator, LambertConformal	backing-waarden GEO, UTM, TM, LCC	—	Zie de projectie-mappingtabel hieronder
ProjectionType::epsgCode()	geen	Mapt de case naar één vaste EPSG-code	int	—	4326, 32601, 2154 of 3347
ProjectionType::label()	geen	Leesbare projectienaam	string	—	Bijvoorbeeld WGS 84 Geographic
GeoRegistration	constructor: array $controlPoints, ProjectionType $projection, string $datum = 'WGS84'	Bevat controlepunten, projectie en geodetisch datum	—	—	final readonly; het aantal controlepunten wordt bij constructie niet gevalideerd
GeoRegistration::isValid()	geen	Vereist minstens twee controlepunten	bool	—	Twee punten is het minimum voor een affiene mapping
GeoRegistration::toPdfMeasureDictionary()	geen	Genereert een /Measure-dictionary met /Subtype /GEO, /GCS, /GPTS, /LPTS en /Bounds	string	—	Controleert isValid() niet; bescherm de aanroep of route via GeoPdfLayer
GeoPdfLayer::addRegistration()	int $pageIndex, GeoRegistration $registration	Voegt een registratie toe voor een nulgebaseerde pagina-index	self	InvalidArgumentException wanneer $pageIndex negatief is	Fluent; de eerste registratie die voor een pagina is toegevoegd wint bij generatie
GeoPdfLayer::getRegistrations()	geen	Retourneert alle registraties in invoegvolgorde	list<array{pageIndex: int, registration: GeoRegistration}>	—	Bevat duplicaten en ongeldige registraties zoals toegevoegd
GeoPdfLayer::generateViewportDictionary()	int $pageIndex	Genereert een /Viewport-dictionary met /BBox, /Name en een inline /Measure	string	—	Lege string wanneer de pagina geen registratie heeft of de registratie ongeldig is
GeoPdfLayer::generateViewportArray()	int $pageIndex	Verpakt de viewport-dictionary tussen haken als de /VP-arrayliteral	string	—	Lege string wanneer afwezig; aanroepers laten /VP dan weg voor die pagina
GeoPdfLayer::writeToPdfWriter()	BinaryBuffer $buffer, int $pageIndex	Schrijft /VP plus de arrayliteral en een newline naar de buffer	bool	—	true wanneer een entry is geschreven; anders een no-op en false

Signaturen van de entrypoints

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

Gedragscontract

Coördinaatvalidatie en -formattering

GeoCoordinate valideert bij constructie en muteert nooit. Een breedtegraad buiten [-90, 90] of een lengtegraad buiten [-180, 180] genereert InvalidArgumentException met vermelding van de ongeldige waarde. toDms() geeft beide assen weer als graden, met nullen aangevulde minuten, seconden en een halfrond-achtervoegsel. toDecimal() geeft latitude, longitude op zes decimalen weer. fromDms() accepteert DMS-invoer met optionele seconden, normaliseert prime-, dubbele-prime-, graadteken- en smart-quote-glyphs, converteert naar decimale graden met teken en construeert een nieuwe instantie. Zuidelijke breedtegraden en westelijke lengtegraden worden negatieve waarden.

Projectie-mapping

Elke ProjectionType-case draagt één vaste EPSG-code en label. De mapping is een gesloten tabel, geen register van coördinaatreferentiesystemen.

Case	Backing-waarde	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

De UTM-case emitteert de code voor zone 1. Projecten die een andere UTM-zone nodig hebben, of een EPSG-code buiten deze tabel, moeten de gezaghebbende CRS-beschrijving in de datum-string opnemen als Well Known Text.

Emissie van de measure-dictionary

GeoRegistration::toPdfMeasureDictionary() emitteert een dictionary over meerdere regels: /Type /Measure, /Subtype /GEO, een /GCS-coördinatensysteemdictionary, /GPTS, /LPTS en /Bounds, conform ISO 32000-2:2020 §12.10 (Table 269). Concreet gedrag:

• /GCS wordt geëmitteerd als << /Type /PROJCS /EPSG <code> /WKT (<datum>) >>. De EPSG-code komt uit de projectie-case. De /WKT-waarde is de datum-string precies zoals aangeleverd; de standaard is WGS84.
• /GPTS somt paren van breedte- en lengtegraad op met zes decimalen, in de volgorde van de controlepunten.
• /LPTS somt pdfX/pdfY-paren op met zes decimalen, precies zoals aangeleverd. ISO 32000-2:2020 Table 269 definieert LPTS-punten in een 2D-eenheidsvierkant; het aanleveren van naar het eenheidsvierkant genormaliseerde waarden is de verantwoordelijkheid van de aanroeper.
• /Bounds staat vast op [0 0 0 1 1 1 1 0], het volledige eenheidsvierkant.
• De datum-string wordt geëscaped voordat deze in de literal string wordt geïnterpoleerd: backslash, haakjes en gangbare stuurtekens worden hun backslash-escapes conform ISO 32000-2:2020 §7.3.4.2. Een door de aanroeper beïnvloed datum kan de literal string niet beëindigen of ruwe PDF-tokens injecteren.

Viewport- en pagina-emissie

GeoPdfLayer bewaart registraties in invoegvolgorde, gekoppeld aan een nulgebaseerde pagina-index. generateViewportDictionary() zoekt de eerste registratie voor de gevraagde pagina en retourneert een lege string wanneer er geen bestaat of wanneer isValid() false is. Een geproduceerde dictionary bevat /Type /Viewport, een /BBox berekend uit de minimale en maximale PDF-coördinaten van de controlepunten, een /Name in de vorm GeoViewport_Page<n> en de inline /Measure-dictionary. De /Measure-entry van de viewport volgt ISO 32000-2:2020 §12.9. generateViewportArray() verpakt de dictionary tussen haken en produceert de /VP-waarde van de pagina: een array van viewport-dictionaries conform ISO 32000-2:2020 §7.7.3.3 (Table 31). writeToPdfWriter() schrijft /VP plus de arrayliteral naar een Core-BinaryBuffer en rapporteert of er iets is geschreven, zodat de pagina-serialisatie de sleutel netjes kan weglaten.

Randgevallen en faalmodi

• Een breedte- of lengtegraad buiten bereik genereert InvalidArgumentException bij constructie; er bestaat geen gedeeltelijk geldige coördinaat.
• fromDms() genereert een exception bij niet-parseerbare invoer. Geparseerde waarden gaan door de constructor, dus een syntactisch geldige string met waarden buiten bereik genereert ook een exception.
• DMS-notatie bevat geen altitude; fromDms() levert altijd altitude 0.0 op.
• Een GeoRegistration met minder dan twee controlepunten rapporteert isValid() false, maar toPdfMeasureDictionary() emitteert alsnog een dictionary met korte puntarrays. Bescherm directe aanroepen met isValid(), of route de emissie via GeoPdfLayer, die ongeldige registraties onderdrukt.
• Dubbele registraties voor één pagina-index worden allemaal bewaard door getRegistrations(); de viewport-generatie gebruikt de eerst toegevoegde.
• Een negatieve pagina-index genereert InvalidArgumentException; pagina-indexen zijn nulgebaseerd.
• Controlepunten die een X- of Y-waarde delen, produceren een gedegenereerde /BBox met breedte of hoogte nul. Lever punten aan die beide assen overspannen.
• Alle uitvoer is gegenereerde tekst. Er wordt niets naar schijf of netwerk geschreven, en identieke invoer levert identieke uitvoer op.
• Er vindt geen cryptografische bewerking plaats in deze module, dus er is geen FIPS-modusspecifiek gedrag.

Conformiteit

Bewering	Standaard	Clausule
De measure-dictionary wordt geëmitteerd met subtype GEO, met GPTS-paren van breedte- en lengtegraad en gepaarde LPTS-waarden.	ISO 32000-2:2020	§12.10
De viewport-dictionary bevat de entries BBox, Name en Measure.	ISO 32000-2:2020	§12.9
De VP-waarde van de pagina wordt geëmitteerd als een array van viewport-dictionaries.	ISO 32000-2:2020	§7.7.3.3
Datum-interpolatie escapet metatekens van literal strings.	ISO 32000-2:2020	§7.3.4.2

Alle clausules zijn geparafraseerd; NextPDF reproduceert geen normatieve tekst. Dit zijn functionaliteitsverklaringen, geen certificeringen. NextPDF bezit geen certificering en verleent er geen. EPSG-codes zijn vaste representatieve waarden per projectie-case, en de /WKT-entry bevat de aangeleverde datum-string in plaats van een gegenereerde Well Known Text-beschrijving; beide beweringen zijn productgefundeerd. Valideer geëmitteerde GeoPDF-uitvoer in de beoogde interactieve PDF-processors voordat je vertrouwt op meting aan de viewerzijde.

Ontwikkelnotities

• Beschikbaar sinds nextpdf/pro 1.9.0; actueel in nextpdf/pro 3.1.0.
• Controleer isValid() voordat je toPdfMeasureDictionary() rechtstreeks aanroept; GeoPdfLayer voert deze controle voor je uit.
• Wanneer downstream-consumenten /WKT parseren, geef dan een volledige Well Known Text-beschrijving door als datum; de standaard WGS84 is alleen een datum-label.
• Normaliseer LPTS-invoer naar het eenheidsvierkant voordat je controlepunten construeert wanneer de viewport-grenzen afwijken van je waarden in PDF-ruimte.
• De emissiekosten zijn lineair in het aantal controlepunten; het opzoeken in GeoPdfLayer is lineair in het aantal registraties.
• writeToPdfWriter() integreert met pagina-serialisatie via NextPDF\Support\BinaryBuffer uit Core.

Publicatiegrens

Deze pagina documenteert alleen extern waarneembaar gedrag en het ondersteunde publieke API-oppervlak. Interne namespace-paden, helperklassen, mechanismetabellen, runbook-bestandsnamen en ticketprefixen vallen buiten de scope.

Zie ook

• Geo (capability) — installatie, conceptueel overzicht en quickstart-voorbeelden.
• Document — Diepe referentie — het oppervlak voor document- en paginacompositie.