Geo — szczegółowa dokumentacja referencyjna

W skrócie

Ta strona stanowi kontraktową dokumentację referencyjną modułu Geo w NextPDF Pro. Powierzchnia obejmuje cztery niemutowalne obiekty wartości — GeoCoordinate, GeoControlPoint, ProjectionType oraz GeoRegistration — a także GeoPdfLayer, który wiąże rejestracje z indeksami stron i emituje dane viewportu. Moduł generuje tekst słownika PDF: słownik /Measure z /Subtype /GEO, słownik /Viewport oraz wartość tablicy /VP na poziomie strony. Generowanie to deterministyczne składanie łańcuchów znaków: brak wywołań sieciowych, brak dostępu do systemu plików, brak losowości. Ta strona opisuje publiczne API, kontrakt obserwowalnego zachowania oraz tryby awarii.

Dostępność i licencjonowanie

Ta funkcja jest dostarczana w NextPDF Pro (nextpdf/pro) i aktywuje się wraz z kopertą licencyjną poziomu Pro. Wdrożenie bez tego uprawnienia nie ładuje klas tej funkcji. Porównaj edycje i uzyskaj licencję.

Żadna flaga licencji dla pojedynczej funkcji nie bramkuje tego modułu. Klasy Geo są dostępne zawsze, gdy zainstalowano nextpdf/pro.

Powierzchnia publicznego API

Symbol	Parametry	Zachowanie domyślne	Zwraca	Zgłasza lub kończy się błędem	Uwagi
GeoCoordinate	konstruktor: float $latitude, float $longitude, float $altitude = 0.0	Waliduje szerokość w zakresie [-90, 90] i długość w zakresie [-180, 180]	—	InvalidArgumentException, gdy któraś z wartości jest poza zakresem	final readonly; wysokość jest podana w metrach nad poziomem morza i nie podlega kontroli zakresu
GeoCoordinate::toDms()	brak	Formatuje jako stopnie-minuty-sekundy z sufiksami N/S oraz E/W	string	—	Sekundy bliskie zeru są renderowane jako 00; w przeciwnym razie dwie cyfry dziesiętne z obciętymi końcowymi zerami
GeoCoordinate::toDecimal()	brak	Formatuje szerokość i długość do sześciu miejsc dziesiętnych, oddzielone przecinkiem	string	—	Wysokość nie jest uwzględniana
GeoCoordinate::fromDms()	string $dms	Parsuje łańcuch DMS; sekundy są opcjonalne; typograficzne glify stopnia i cudzysłowu są normalizowane	self	InvalidArgumentException, gdy łańcuch nie daje się sparsować lub gdy sparsowane wartości nie przechodzą kontroli zakresu w konstruktorze	Statyczna fabryka; litery półkul są niewrażliwe na wielkość znaków; wysokość domyślnie 0.0
GeoControlPoint	konstruktor: float $pdfX, float $pdfY, GeoCoordinate $geo	Paruje punkt w przestrzeni użytkownika PDF (w punktach) ze współrzędną geograficzną	—	—	final readonly; współrzędne PDF nie są walidowane
ProjectionType	enum oparty na łańcuchach, 4 przypadki	Przypadki: Geographic, UTM, TransverseMercator, LambertConformal	wartości bazowe GEO, UTM, TM, LCC	—	Zobacz tabelę mapowania projekcji poniżej
ProjectionType::epsgCode()	brak	Mapuje przypadek na jeden stały kod EPSG	int	—	4326, 32601, 2154 lub 3347
ProjectionType::label()	brak	Czytelna dla człowieka nazwa projekcji	string	—	Na przykład WGS 84 Geographic
GeoRegistration	konstruktor: array $controlPoints, ProjectionType $projection, string $datum = 'WGS84'	Przechowuje punkty kontrolne, projekcję oraz układ odniesienia geodezyjnego	—	—	final readonly; liczba punktów kontrolnych nie jest walidowana podczas konstrukcji
GeoRegistration::isValid()	brak	Wymaga co najmniej dwóch punktów kontrolnych	bool	—	Dwa punkty to minimum dla mapowania afinicznego
GeoRegistration::toPdfMeasureDictionary()	brak	Emituje słownik /Measure z /Subtype /GEO, /GCS, /GPTS, /LPTS oraz /Bounds	string	—	Nie sprawdza isValid(); zabezpiecz wywołanie lub kieruj je przez GeoPdfLayer
GeoPdfLayer::addRegistration()	int $pageIndex, GeoRegistration $registration	Dodaje rejestrację dla indeksu strony liczonego od zera	self	InvalidArgumentException, gdy $pageIndex jest ujemny	Płynny (fluent); pierwsza dodana rejestracja dla strony wygrywa w czasie generowania
GeoPdfLayer::getRegistrations()	brak	Zwraca wszystkie rejestracje w kolejności wstawiania	list<array{pageIndex: int, registration: GeoRegistration}>	—	Uwzględnia duplikaty i nieprawidłowe rejestracje w postaci dodanej
GeoPdfLayer::generateViewportDictionary()	int $pageIndex	Emituje słownik /Viewport z /BBox, /Name oraz wbudowanym /Measure	string	—	Pusty łańcuch, gdy strona nie ma rejestracji lub rejestracja jest nieprawidłowa
GeoPdfLayer::generateViewportArray()	int $pageIndex	Owija słownik viewportu w nawiasy jako literał tablicy /VP	string	—	Pusty łańcuch, gdy brak; wywołujący pomijają wtedy /VP dla tej strony
GeoPdfLayer::writeToPdfWriter()	BinaryBuffer $buffer, int $pageIndex	Zapisuje /VP oraz literał tablicy i znak nowej linii do bufora	bool	—	true, gdy wpis został zapisany; brak operacji i false w przeciwnym razie

Sygnatury punktów wejścia

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

Kontrakt zachowania

Walidacja i formatowanie współrzędnych

GeoCoordinate waliduje podczas konstrukcji i nigdy nie ulega mutacji. Szerokość poza [-90, 90] lub długość poza [-180, 180] zgłasza InvalidArgumentException z podaniem wadliwej wartości. toDms() renderuje obie osie jako stopnie, minuty uzupełnione zerami, sekundy oraz sufiks półkuli. toDecimal() renderuje latitude, longitude do sześciu miejsc dziesiętnych. fromDms() przyjmuje dane DMS z opcjonalnymi sekundami, normalizuje glify prima, podwójnego prima, znaku stopnia oraz cudzysłowów typograficznych, konwertuje na dziesiętne stopnie ze znakiem i tworzy nową instancję. Szerokości południowe i długości zachodnie stają się wartościami ujemnymi.

Mapowanie projekcji

Każdy przypadek ProjectionType niesie jeden stały kod EPSG i etykietę. Mapowanie to zamknięta tabela, a nie rejestr układów odniesienia współrzędnych.

Przypadek	Wartość bazowa	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

Przypadek UTM emituje kod strefy 1. Projekty wymagające innej strefy UTM lub dowolnego kodu EPSG spoza tej tabeli powinny umieścić autorytatywny opis CRS w łańcuchu datum jako Well Known Text.

Emisja słownika miary

GeoRegistration::toPdfMeasureDictionary() emituje wielowierszowy słownik: /Type /Measure, /Subtype /GEO, słownik układu współrzędnych /GCS, /GPTS, /LPTS oraz /Bounds, zgodnie z ISO 32000-2:2020 §12.10 (Tabela 269). Konkretne zachowanie:

• /GCS jest emitowany jako << /Type /PROJCS /EPSG <code> /WKT (<datum>) >>. Kod EPSG pochodzi z przypadku projekcji. Wartość /WKT to łańcuch datum dokładnie w postaci przekazanej; domyślnie WGS84.
• /GPTS wymienia pary szerokość-długość z sześcioma miejscami dziesiętnymi, w kolejności punktów kontrolnych.
• /LPTS wymienia pary pdfX/pdfY z sześcioma miejscami dziesiętnymi, dokładnie w postaci przekazanej. ISO 32000-2:2020 Tabela 269 definiuje punkty LPTS w dwuwymiarowym kwadracie jednostkowym; przekazanie wartości znormalizowanych do kwadratu jednostkowego jest obowiązkiem wywołującego.
• /Bounds jest ustalony na [0 0 0 1 1 1 1 0], pełny kwadrat jednostkowy.
• Łańcuch datum jest poddawany escape’owaniu przed interpolacją do łańcucha literalnego: ukośnik wsteczny, nawiasy oraz typowe znaki sterujące stają się swoimi sekwencjami ucieczki z ukośnikiem wstecznym, zgodnie z ISO 32000-2:2020 §7.3.4.2. Wpływany przez wywołującego datum nie może zakończyć łańcucha literalnego ani wstrzyknąć surowych tokenów PDF.

Emisja viewportu i strony

GeoPdfLayer przechowuje rejestracje w kolejności wstawiania, kluczowane indeksem strony liczonym od zera. generateViewportDictionary() rozwiązuje pierwszą rejestrację dla żądanej strony i zwraca pusty łańcuch, gdy żadna nie istnieje lub gdy isValid() jest fałszem. Wygenerowany słownik niesie /Type /Viewport, /BBox obliczony z minimalnych i maksymalnych współrzędnych PDF punktów kontrolnych, /Name w postaci GeoViewport_Page<n> oraz wbudowany słownik /Measure. Wpis /Measure viewportu jest zgodny z ISO 32000-2:2020 §12.9. generateViewportArray() owija słownik w nawiasy, tworząc wartość /VP strony: tablicę słowników viewportu zgodnie z ISO 32000-2:2020 §7.7.3.3 (Tabela 31). writeToPdfWriter() zapisuje /VP oraz literał tablicy do BinaryBuffer z Core i raportuje, czy cokolwiek zostało zapisane, dzięki czemu serializacja strony może czysto pominąć ten klucz.

Przypadki brzegowe i tryby awarii

• Szerokość lub długość poza zakresem zgłasza InvalidArgumentException podczas konstrukcji; nie istnieje częściowo prawidłowa współrzędna.
• fromDms() zgłasza wyjątek przy danych, których nie da się sparsować. Sparsowane wartości przechodzą przez konstruktor, więc składniowo poprawny łańcuch z wartościami poza zakresem również zgłasza wyjątek.
• Notacja DMS nie niesie wysokości; fromDms() zawsze daje wysokość 0.0.
• GeoRegistration z mniej niż dwoma punktami kontrolnymi raportuje isValid() jako fałsz, jednak toPdfMeasureDictionary() i tak emituje słownik z krótkimi tablicami punktów. Zabezpiecz bezpośrednie wywołania za pomocą isValid() lub kieruj emisję przez GeoPdfLayer, który wygasza nieprawidłowe rejestracje.
• Zduplikowane rejestracje dla jednego indeksu strony są w całości zachowywane przez getRegistrations(); generowanie viewportu używa pierwszej dodanej.
• Ujemny indeks strony zgłasza InvalidArgumentException; indeksy stron są liczone od zera.
• Punkty kontrolne o wspólnej wartości X lub Y dają zdegenerowany /BBox o zerowej szerokości lub zerowej wysokości. Podawaj punkty rozciągające się na obie osie.
• Całe wyjście to generowany tekst. Nic nie jest zapisywane na dysk ani do sieci, a identyczne dane wejściowe dają identyczne wyjście.
• W tym module nie zachodzi żadna operacja kryptograficzna, więc nie istnieje zachowanie specyficzne dla trybu FIPS.

Zgodność

Twierdzenie	Standard	Klauzula
Słownik miary jest emitowany z podtypem GEO, z parami szerokość-długość GPTS oraz sparowanymi wartościami LPTS.	ISO 32000-2:2020	§12.10
Słownik viewportu niesie wpisy BBox, Name oraz Measure.	ISO 32000-2:2020	§12.9
Wartość VP strony jest emitowana jako tablica słowników viewportu.	ISO 32000-2:2020	§7.7.3.3
Interpolacja datum poddaje escape’owaniu metaznaki łańcucha literalnego.	ISO 32000-2:2020	§7.3.4.2

Wszystkie klauzule są parafrazowane; NextPDF nie reprodukuje tekstu normatywnego. Są to twierdzenia o możliwościach, nie certyfikaty. NextPDF nie posiada żadnego certyfikatu i żadnego nie udziela. Kody EPSG to stałe wartości reprezentatywne dla każdego przypadku projekcji, a wpis /WKT niesie przekazany łańcuch datum, a nie wygenerowany opis Well Known Text; oba stwierdzenia są ugruntowane w produkcie. Zwaliduj wygenerowane wyjście GeoPDF w docelowych interaktywnych procesorach PDF, zanim zaczniesz polegać na pomiarach po stronie przeglądarki.

Uwagi programistyczne

• Dostępne od nextpdf/pro 1.9.0; aktualne w nextpdf/pro 3.1.0.
• Sprawdź isValid() przed bezpośrednim wywołaniem toPdfMeasureDictionary(); GeoPdfLayer wykonuje tę kontrolę za Ciebie.
• Gdy konsumenci w dalszej części potoku parsują /WKT, przekaż pełny opis Well Known Text jako datum; domyślne WGS84 to jedynie etykieta datum.
• Znormalizuj dane wejściowe LPTS do kwadratu jednostkowego przed konstruowaniem punktów kontrolnych, gdy granice viewportu różnią się od Twoich wartości w przestrzeni PDF.
• Koszt emisji jest liniowy względem liczby punktów kontrolnych; wyszukiwanie w GeoPdfLayer jest liniowe względem liczby rejestracji.
• writeToPdfWriter() integruje się z serializacją strony poprzez NextPDF\Support\BinaryBuffer z Core.

Granica publikacji

Ta strona dokumentuje wyłącznie zachowanie obserwowalne z zewnątrz oraz wspieraną powierzchnię publicznego API. Wewnętrzne ścieżki przestrzeni nazw, klasy pomocnicze, tabele mechanizmów, nazwy plików runbooków oraz prefiksy zgłoszeń są poza zakresem.

Zobacz także

• Geo (funkcja) — instalacja, przegląd koncepcyjny i przykłady szybkiego startu.
• Document — szczegółowa dokumentacja referencyjna — powierzchnia kompozycji dokumentu i strony.