Geo

Auf einen Blick

NextPDF Pro bildet PDF-Seitenkoordinaten auf geografische Koordinaten ab und generiert ein PDF-Measure-Dictionary mit dem GEO-Subtyp, sodass ein Viewer aus einem Punkt auf der Seite die reale Position melden kann.

Verfügbarkeit & Lizenzierung

Diese Fähigkeit wird in NextPDF Pro (nextpdf/pro) ausgeliefert und wird mit einem Lizenzumschlag der Pro-Stufe aktiviert. Eine Bereitstellung ohne diese Berechtigung lädt die Klassen der Fähigkeit nicht. Editionen vergleichen und Lizenz erwerben.

Geo hat kein separates Feature-bezogenes Lizenz-Flag; der Umschlag der Pro-Stufe aktiviert es direkt.

Installation

composer require nextpdf/pro:^3

Konzeptioneller Überblick

Ein geografisches PDF trägt ein Measure-Dictionary, beschrieben in ISO 32000-2 §12.8.2, das Geräteraum-Punkte mit einem geografischen Koordinatenreferenzsystem verbindet. NextPDF Pro baut diese Daten aus unveränderlichen Wertobjekten:

• GeoCoordinate — ein Tripel aus Breitengrad/Längengrad/Höhe. Die Konstruktion validiert den Breitengrad innerhalb [-90, 90] und den Längengrad innerhalb [-180, 180] und bietet eine Formatierung als Grad-Minuten-Sekunden und als Dezimal-String.
• GeoControlPoint — eine Paarung eines PDF-Raum-Punkts mit einer GeoCoordinate.
• ProjectionType — ein Enum gängiger Projektionen (geografisch, UTM, transversale Mercator, Lambert-Schnittkegelprojektion), jeweils einem EPSG-Code zugeordnet.
• GeoRegistration — die Kontrollpunkte plus Projektion und geodätisches Datum (Standard WGS84). isValid() erfordert mindestens zwei Kontrollpunkte für eine minimale affine Transformation; toPdfMeasureDictionary() gibt das /Measure-Dictionary mit /Subtype /GEO und den Kontrollpunkt-Arrays aus.

Warum es so funktioniert

NextPDF baut das Measure-Dictionary aus validierten, unveränderlichen Wertobjekten, nicht aus einem rohen Dictionary, das der Aufrufer liefert. GeoCoordinate weist einen Breiten- oder Längengrad außerhalb des Bereichs bereits bei der Konstruktion ab. GeoRegistration::isValid() verweigert weniger als zwei Kontrollpunkte, sodass eine fehlerhafte Registrierung schnell scheitert, statt ein verschlechtertes /GEO-Dictionary auszugeben. Projektionen lösen sich über ProjectionType in standardisierte EPSG-Codes auf, was das Koordinatenreferenzsystem explizit statt geraten hält. Das Datum steht standardmäßig auf WGS84, bleibt aber ein benanntes Feld, sodass ein abweichendes Referenzsystem eine bewusste Entscheidung ist. Diese Fail-Closed-Haltung ist wichtig, weil eine falsche Georeferenz schlimmer ist als keine; ein Viewer würde selbstbewusst eine falsche reale Position melden. Design-Hintergrund: Eine API, die sich weigert zu raten.

API-Oberfläche

Class	Responsibility
GeoCoordinate	Validierte Breite/Länge/Höhe mit Formatierung.
GeoControlPoint	PDF-Punkt ↔ geografischer Punkt-Paarung.
ProjectionType	Projektions-Enum mit EPSG-Codes.
GeoRegistration	Das /Measure /GEO-Dictionary bauen.

Codebeispiel — Schnellstart

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

Codebeispiel — Produktion

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

Randfälle & Fallstricke

• Die Konstruktion von GeoCoordinate weist einen Breiten- oder Längengrad außerhalb des Bereichs ab.
• Weniger als zwei Kontrollpunkte erzeugen eine ungültige Registrierung.
• Das Standard-Datum ist WGS84; setzen Sie es für andere Referenzsysteme explizit.

Performance

Die Dictionary-Generierung ist linear in der Anzahl der Kontrollpunkte.

Sicherheitshinweise

Die Geo-Eingabe sind numerische Koordinatendaten. Validieren Sie aus nicht vertrauenswürdigen Eingaben bezogene Kontrollpunkte vor der Registrierung.

Konformität

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

Verhaltensvertrag

• GeoCoordinate validiert den Breitengrad innerhalb [-90, 90] und den Längengrad innerhalb [-180, 180] bei der Konstruktion und bietet eine Formatierung als DMS und als Dezimal-String.
• GeoControlPoint paart einen PDF-Raum-Punkt mit einer GeoCoordinate.
• GeoRegistration trägt Kontrollpunkte plus einen ProjectionType (einem EPSG-Code zugeordnet) und ein geodätisches Datum, das standardmäßig auf WGS84 steht. isValid() erfordert mindestens zwei Kontrollpunkte; toPdfMeasureDictionary() gibt ein /Measure-Dictionary mit /Subtype /GEO und den Kontrollpunkt-Arrays aus.
• Koordinaten außerhalb des Bereichs oder weniger als zwei Kontrollpunkte erzeugen eine ungültige Registrierung statt stillschweigend verschlechterter Ausgabe.

Hinweis zur Enterprise-Abgrenzung

Enterprise ändert das Geo-Verhalten nicht. Enterprise ergänzt Funktionen höherer Stufe, die separat dokumentiert sind; sie sind zur Generierung eines GeoPDF-Measure-Dictionary nicht erforderlich.

Core-Rückfalloption / Alternative

Für die GeoPDF-Measure-Dictionary-Generierung gibt es kein Core-Äquivalent. Dies ist eine Pro-Ergänzung.

Veröffentlichungsgrenze

Diese Seite dokumentiert ausschließlich extern beobachtbares Verhalten und die unterstützte öffentliche API-Oberfläche. Interne Namespace-Pfade, Helferklassen, Mechanismustabellen, Runbook-Dateinamen und Ticket-Präfixe sind nicht Gegenstand dieser Seite.

Siehe auch

• Geo — Deep Reference — vollständige Klassen- und Methodenreferenz.
• Document — Seiten- und Dokumentzusammenstellung.
• Core annotations.