Geo — Ausführliche Referenz

Auf einen Blick

Diese Seite ist die Referenz auf Vertragsebene für das NextPDF Pro Geo-Modul. Die Oberfläche besteht aus vier unveränderlichen Wertobjekten — GeoCoordinate, GeoControlPoint, ProjectionType und GeoRegistration — sowie GeoPdfLayer, das Registrierungen mit Seitenindizes verknüpft und Viewport-Ausgaben erzeugt. Das Modul erzeugt PDF-Wörterbuchtext: ein /Measure-Wörterbuch mit /Subtype /GEO, ein /Viewport-Wörterbuch und den /VP-Array-Wert auf Seitenebene. Die Erzeugung ist deterministische Zeichenkettenmontage: kein Netzwerkaufruf, kein Dateisystemzugriff, keine Zufälligkeit. Diese Seite beschreibt die öffentliche API, den beobachtbaren Verhaltensvertrag und die Fehlermodi.

Verfügbarkeit & Lizenzierung

Diese Funktion ist Bestandteil von NextPDF Pro (nextpdf/pro) und wird mit einem Lizenz-Envelope der Pro-Stufe aktiviert. Eine Bereitstellung ohne diese Berechtigung lädt die Klassen der Funktion nicht. Editionen vergleichen und Lizenz erwerben.

Kein funktionsspezifisches Lizenzflag schränkt dieses Modul ein. Die Geo-Klassen sind verfügbar, sobald nextpdf/pro installiert ist.

Öffentliche API-Oberfläche

Symbol	Parameter	Standardverhalten	Rückgabe	Wirft oder scheitert mit	Hinweise
GeoCoordinate	Konstruktor: float $latitude, float $longitude, float $altitude = 0.0	Prüft, ob die Breite in [-90, 90] und die Länge in [-180, 180] liegt	—	InvalidArgumentException, wenn einer der Werte außerhalb des Bereichs liegt	final readonly; die Höhe ist in Metern über dem Meeresspiegel und wird nicht auf den Bereich geprüft
GeoCoordinate::toDms()	keine	Formatiert als Grad-Minuten-Sekunden mit den Suffixen N/S und E/W	string	—	Sekunden nahe null werden als 00 dargestellt; andernfalls zwei Nachkommastellen mit entfernten nachgestellten Nullen
GeoCoordinate::toDecimal()	keine	Formatiert Breite und Länge auf sechs Nachkommastellen, kommagetrennt	string	—	Die Höhe wird nicht einbezogen
GeoCoordinate::fromDms()	string $dms	Parst eine DMS-Zeichenkette; Sekunden sind optional; typografische Grad- und Anführungszeichen-Glyphen werden normalisiert	self	InvalidArgumentException, wenn die Zeichenkette nicht geparst werden kann oder wenn geparste Werte die Bereichsprüfungen des Konstruktors nicht bestehen	Statische Factory; Hemisphärenbuchstaben sind case-insensitiv; die Höhe ist standardmäßig 0.0
GeoControlPoint	Konstruktor: float $pdfX, float $pdfY, GeoCoordinate $geo	Paart einen PDF-Benutzerraumpunkt (Points) mit einer geografischen Koordinate	—	—	final readonly; PDF-Koordinaten werden nicht validiert
ProjectionType	string-basierte Enum, 4 Fälle	Fälle: Geographic, UTM, TransverseMercator, LambertConformal	Backing-Werte GEO, UTM, TM, LCC	—	Siehe die Projektionszuordnungstabelle unten
ProjectionType::epsgCode()	keine	Ordnet dem Fall einen festen EPSG-Code zu	int	—	4326, 32601, 2154 oder 3347
ProjectionType::label()	keine	Menschenlesbarer Projektionsname	string	—	Zum Beispiel WGS 84 Geographic
GeoRegistration	Konstruktor: array $controlPoints, ProjectionType $projection, string $datum = 'WGS84'	Hält Kontrollpunkte, Projektion und geodätisches Datum	—	—	final readonly; die Anzahl der Kontrollpunkte wird bei der Konstruktion nicht validiert
GeoRegistration::isValid()	keine	Erfordert mindestens zwei Kontrollpunkte	bool	—	Zwei Punkte sind das Minimum für eine affine Abbildung
GeoRegistration::toPdfMeasureDictionary()	keine	Erzeugt ein /Measure-Wörterbuch mit /Subtype /GEO, /GCS, /GPTS, /LPTS und /Bounds	string	—	Prüft isValid() nicht; sichern Sie den Aufruf ab oder leiten Sie ihn über GeoPdfLayer
GeoPdfLayer::addRegistration()	int $pageIndex, GeoRegistration $registration	Hängt eine Registrierung für einen nullbasierten Seitenindex an	self	InvalidArgumentException, wenn $pageIndex negativ ist	Fluent; die zuerst für eine Seite hinzugefügte Registrierung gewinnt zur Erzeugungszeit
GeoPdfLayer::getRegistrations()	keine	Gibt alle Registrierungen in Einfügereihenfolge zurück	list<array{pageIndex: int, registration: GeoRegistration}>	—	Enthält Duplikate und ungültige Registrierungen wie hinzugefügt
GeoPdfLayer::generateViewportDictionary()	int $pageIndex	Erzeugt ein /Viewport-Wörterbuch mit /BBox, /Name und einem inline /Measure	string	—	Leere Zeichenkette, wenn die Seite keine Registrierung hat oder die Registrierung ungültig ist
GeoPdfLayer::generateViewportArray()	int $pageIndex	Umschließt das Viewport-Wörterbuch mit Klammern als /VP-Array-Literal	string	—	Leere Zeichenkette, wenn nicht vorhanden; Aufrufer lassen /VP für diese Seite dann weg
GeoPdfLayer::writeToPdfWriter()	BinaryBuffer $buffer, int $pageIndex	Schreibt /VP plus das Array-Literal und einen Zeilenumbruch in den Puffer	bool	—	true, wenn ein Eintrag geschrieben wurde; andernfalls no-op und false

Signaturen der Einstiegspunkte

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

Verhaltensvertrag

Koordinatenvalidierung und -formatierung

GeoCoordinate validiert bei der Konstruktion und verändert sich nie. Eine Breite außerhalb von [-90, 90] oder eine Länge außerhalb von [-180, 180] wirft InvalidArgumentException unter Nennung des beanstandeten Werts. toDms() stellt beide Achsen als Grad, nullaufgefüllte Minuten, Sekunden und ein Hemisphärensuffix dar. toDecimal() gibt latitude, longitude mit sechs Nachkommastellen aus. fromDms() akzeptiert DMS-Eingaben mit optionalen Sekunden, normalisiert Prime-, Double-Prime-, Gradzeichen- und typografische Anführungszeichen-Glyphen, wandelt in vorzeichenbehaftete Dezimalgrad um und konstruiert eine neue Instanz. Südliche Breiten und westliche Längen werden zu negativen Werten.

Projektionszuordnung

Jeder ProjectionType-Fall trägt einen festen EPSG-Code und eine Beschriftung. Die Zuordnung ist eine geschlossene Tabelle, keine Registry für Koordinatenreferenzsysteme.

Fall	Backing-Wert	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

Der UTM-Fall gibt den Code für Zone 1 aus. Projekte, die eine andere UTM-Zone oder einen EPSG-Code außerhalb dieser Tabelle benötigen, sollten die maßgebliche CRS-Beschreibung in der datum-Zeichenkette als Well Known Text mitführen.

Emission des Measure-Wörterbuchs

GeoRegistration::toPdfMeasureDictionary() erzeugt ein mehrzeiliges Wörterbuch: /Type /Measure, /Subtype /GEO, ein /GCS-Koordinatensystem-Wörterbuch, /GPTS, /LPTS und /Bounds, gemäß ISO 32000-2:2020 §12.10 (Table 269). Konkretes Verhalten:

• /GCS wird als << /Type /PROJCS /EPSG <code> /WKT (<datum>) >> ausgegeben. Der EPSG-Code stammt aus dem Projektionsfall. Der /WKT-Wert ist die datum-Zeichenkette genau wie übergeben; der Standard ist WGS84.
• /GPTS listet Breiten-Längen-Paare mit sechs Nachkommastellen in Kontrollpunktreihenfolge auf.
• /LPTS listet pdfX/pdfY-Paare mit sechs Nachkommastellen genau wie übergeben auf. ISO 32000-2:2020 Table 269 definiert LPTS-Punkte in einem 2D-Einheitsquadrat; die Übergabe von auf das Einheitsquadrat normalisierten Werten liegt in der Verantwortung des Aufrufers.
• /Bounds ist fest auf [0 0 0 1 1 1 1 0] gesetzt, das vollständige Einheitsquadrat.
• Die datum-Zeichenkette wird vor der Interpolation in die literale Zeichenkette escaped: Backslash, Klammern und gängige Steuerzeichen werden gemäß ISO 32000-2:2020 §7.3.4.2 zu ihren Backslash-Escapes. Ein vom Aufrufer beeinflusstes Datum kann die literale Zeichenkette nicht beenden oder rohe PDF-Token einschleusen.

Viewport- und Seitenemission

GeoPdfLayer hält Registrierungen in Einfügereihenfolge, mit dem nullbasierten Seitenindex als Schlüssel. generateViewportDictionary() löst die erste Registrierung für die angeforderte Seite auf und gibt eine leere Zeichenkette zurück, wenn keine existiert oder wenn isValid() false ist. Ein erzeugtes Wörterbuch trägt /Type /Viewport, ein aus den minimalen und maximalen PDF-Koordinaten der Kontrollpunkte berechnetes /BBox, ein /Name der Form GeoViewport_Page<n> und das inline /Measure-Wörterbuch. Der /Measure-Eintrag des Viewports folgt ISO 32000-2:2020 §12.9. generateViewportArray() umschließt das Wörterbuch mit Klammern und erzeugt den /VP-Wert der Seite: ein Array von Viewport-Wörterbüchern gemäß ISO 32000-2:2020 §7.7.3.3 (Table 31). writeToPdfWriter() schreibt /VP plus das Array-Literal in einen Core-BinaryBuffer und meldet, ob etwas geschrieben wurde, sodass die Seitenserialisierung den Schlüssel sauber weglassen kann.

Grenzfälle & Fehlermodi

• Eine Breite oder Länge außerhalb des Bereichs wirft InvalidArgumentException bei der Konstruktion; es existiert keine teilweise gültige Koordinate.
• fromDms() wirft bei nicht parsbarer Eingabe. Geparste Werte durchlaufen den Konstruktor, sodass eine syntaktisch gültige Zeichenkette mit Werten außerhalb des Bereichs ebenfalls wirft.
• Die DMS-Notation führt keine Höhe mit; fromDms() liefert immer die Höhe 0.0.
• Eine GeoRegistration mit weniger als zwei Kontrollpunkten meldet isValid() false, dennoch erzeugt toPdfMeasureDictionary() weiterhin ein Wörterbuch mit kurzen Punktarrays. Sichern Sie direkte Aufrufe mit isValid() ab oder leiten Sie die Emission über GeoPdfLayer, das ungültige Registrierungen unterdrückt.
• Doppelte Registrierungen für einen Seitenindex werden alle von getRegistrations() beibehalten; die Viewport-Erzeugung verwendet die zuerst hinzugefügte.
• Ein negativer Seitenindex wirft InvalidArgumentException; Seitenindizes sind nullbasiert.
• Kontrollpunkte, die sich einen X- oder Y-Wert teilen, erzeugen ein degeneriertes /BBox mit Breite oder Höhe null. Übergeben Sie Punkte, die beide Achsen aufspannen.
• Die gesamte Ausgabe ist generierter Text. Es wird nichts auf Datenträger oder Netzwerk geschrieben, und identische Eingabe erzeugt identische Ausgabe.
• In diesem Modul findet keine kryptografische Operation statt, daher gibt es kein FIPS-Modus-spezifisches Verhalten.

Konformität

Aussage	Standard	Klausel
Das Measure-Wörterbuch wird mit Subtype GEO, mit GPTS-Breiten-Längen-Paaren und gepaarten LPTS-Werten ausgegeben.	ISO 32000-2:2020	§12.10
Das Viewport-Wörterbuch trägt BBox-, Name- und Measure-Einträge.	ISO 32000-2:2020	§12.9
Der VP-Wert der Seite wird als Array von Viewport-Wörterbüchern ausgegeben.	ISO 32000-2:2020	§7.7.3.3
Die Datum-Interpolation escaped Metazeichen literaler Zeichenketten.	ISO 32000-2:2020	§7.3.4.2

Alle Klauseln sind paraphrasiert; NextPDF gibt keinen normativen Text wieder. Dies sind Fähigkeitsaussagen, keine Zertifizierungen. NextPDF besitzt keine Zertifizierung und erteilt keine. EPSG-Codes sind feste repräsentative Werte pro Projektionsfall, und der /WKT-Eintrag trägt die übergebene Datum-Zeichenkette statt einer generierten Well-Known-Text-Beschreibung; beide Aussagen sind produktbezogen begründet. Validieren Sie die erzeugte GeoPDF-Ausgabe in den interaktiven Ziel-PDF-Prozessoren, bevor Sie sich auf betrachterseitige Messungen verlassen.

Entwicklungshinweise

• Verfügbar seit nextpdf/pro 1.9.0; aktuell in nextpdf/pro 3.1.0.
• Prüfen Sie isValid(), bevor Sie toPdfMeasureDictionary() direkt aufrufen; GeoPdfLayer führt diese Prüfung für Sie durch.
• Wenn nachgelagerte Konsumenten /WKT parsen, übergeben Sie eine vollständige Well-Known-Text-Beschreibung als datum; der Standard WGS84 ist nur eine Datumsbeschriftung.
• Normalisieren Sie LPTS-Eingaben auf das Einheitsquadrat, bevor Sie Kontrollpunkte konstruieren, wenn die Viewport-Grenzen von Ihren PDF-Raum-Werten abweichen.
• Die Emissionskosten sind linear zur Anzahl der Kontrollpunkte; die Suche in GeoPdfLayer ist linear zur Anzahl der Registrierungen.
• writeToPdfWriter() integriert sich über NextPDF\Support\BinaryBuffer aus Core in die Seitenserialisierung.

Veröffentlichungsgrenze

Diese Seite dokumentiert ausschließlich extern beobachtbares Verhalten und die unterstützte öffentliche API-Oberfläche. Interne Namespace-Pfade, Hilfsklassen, Mechanismustabellen, Runbook-Dateinamen und Ticket-Präfixe liegen außerhalb des Geltungsbereichs.

Siehe auch

• Geo (Funktion) — Installation, konzeptioneller Überblick und Schnellstart-Beispiele.
• Document — Ausführliche Referenz — die Oberfläche für Dokument- und Seitenkomposition.