Geo

In één oogopslag

NextPDF Pro mapt PDF-paginacoördinaten naar geografische coördinaten en genereert een PDF-measure-dictionary met het GEO-subtype, zodat een viewer de positie in de echte wereld kan rapporteren vanaf een punt op de pagina.

Beschikbaarheid en licentie

Deze mogelijkheid wordt geleverd in NextPDF Pro (nextpdf/pro) en wordt geactiveerd met een licentie-envelop van het Pro-niveau. Een deployment zonder die entitlement laadt de klassen van de mogelijkheid niet. Vergelijk edities en vraag een licentie aan.

Geo heeft geen aparte licentievlag per functie; de envelop van het Pro-niveau schakelt het rechtstreeks in.

Installatie

composer require nextpdf/pro:^3

Conceptueel overzicht

Een geospatiale PDF draagt een measure-dictionary, beschreven in ISO 32000-2 §12.8.2, die device-space-punten koppelt aan een geografisch coördinaatreferentiesysteem. NextPDF Pro bouwt die data uit immutable waarde-objecten:

• GeoCoordinate — een triple van breedtegraad/lengtegraad/hoogte. De constructie valideert de breedtegraad binnen [-90, 90] en de lengtegraad binnen [-180, 180], en biedt opmaak in graden-minuten-seconden en als decimale string.
• GeoControlPoint — een koppeling van een PDF-space-punt met een GeoCoordinate.
• ProjectionType — een enum van veelvoorkomende projecties (geografisch, UTM, transversale Mercator, Lambert-conforme kegel), elk gemapt naar een EPSG-code.
• GeoRegistration — de controlepunten plus projectie en geodetisch datum (standaard WGS84). isValid() vereist ten minste twee controlepunten voor een minimale affiene transformatie; toPdfMeasureDictionary() zendt de /Measure-dictionary uit met /Subtype /GEO en de controlepunt-arrays.

Waarom het zo werkt

NextPDF bouwt de measure-dictionary uit gevalideerde, immutable waarde-objecten, niet uit een ruwe dictionary die door de aanroeper wordt aangeleverd. GeoCoordinate wijst bij constructie een breedtegraad of lengtegraad buiten bereik af. GeoRegistration::isValid() weigert minder dan twee controlepunten, zodat een misvormde registratie snel faalt in plaats van een gedegradeerde /GEO-dictionary uit te zenden. Projecties resolven via ProjectionType naar standaard EPSG-codes, wat het coördinaatreferentiesysteem expliciet houdt in plaats van gegokt. Het datum is standaard WGS84, maar blijft een benoemd veld, zodat een niet-standaard referentiesysteem een bewuste keuze is. Deze fail-closed houding is belangrijk omdat een verkeerde georeferentie erger is dan geen; een viewer zou vol vertrouwen een onjuiste positie in de echte wereld rapporteren. Ontwerpachtergrond: Een API die weigert te gokken.

API-oppervlak

Klasse	Verantwoordelijkheid
GeoCoordinate	Gevalideerde lat/lon/hoogte met opmaak.
GeoControlPoint	Koppeling PDF-punt ↔ geografisch punt.
ProjectionType	Projectie-enum met EPSG-codes.
GeoRegistration	De /Measure /GEO-dictionary bouwen.

Codevoorbeeld — Snelstart

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

Codevoorbeeld — Productie

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

Randgevallen en valkuilen

• De constructie van GeoCoordinate wijst een breedtegraad of lengtegraad buiten bereik af.
• Minder dan twee controlepunten levert een ongeldige registratie op.
• Het standaard datum is WGS84; stel het expliciet in voor andere referentiesystemen.

Prestaties

Dictionarygeneratie is lineair in het aantal controlepunten.

Beveiligingsnotities

Geo-invoer bestaat uit numerieke coördinaatdata. Valideer controlepunten afkomstig van niet-vertrouwde invoer voordat je registreert.

Conformiteit

Gedrag	Referentie	Status
Geospatiale measure-dictionary (GEO-subtype)	ISO 32000-2 §12.8.2	Afgestemd (geparafraseerd)

Gedragscontract

• GeoCoordinate valideert bij constructie de breedtegraad binnen [-90, 90] en de lengtegraad binnen [-180, 180] en biedt opmaak als DMS en als decimale string.
• GeoControlPoint koppelt een PDF-space-punt aan een GeoCoordinate.
• GeoRegistration draagt controlepunten plus een ProjectionType (gemapt naar een EPSG-code) en een geodetisch datum dat standaard WGS84 is. isValid() vereist ten minste twee controlepunten; toPdfMeasureDictionary() zendt een /Measure-dictionary uit met /Subtype /GEO en de controlepunt-arrays.
• Coördinaten buiten bereik of minder dan twee controlepunten leveren een ongeldige registratie op in plaats van stilzwijgend gedegradeerde uitvoer.

Enterprise-grensnotitie

Enterprise verandert het Geo-gedrag niet. Enterprise voegt hoger-niveau functies toe die apart worden gedocumenteerd; ze zijn niet vereist om een GeoPDF-measure-dictionary te genereren.

Core-fallback / alternatief

Er is geen Core-equivalent voor GeoPDF-measure-dictionarygeneratie. Dit is een Pro-toevoeging.

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 — Deep Reference — volledige klasse- en methodereferentie.
• Document — pagina- en documentsamenstelling.
• Core annotations.