Geo

W skrócie

NextPDF Pro mapuje współrzędne strony PDF na współrzędne geograficzne i generuje słownik miary PDF z podtypem GEO, dzięki czemu przeglądarka może zaraportować rzeczywiste położenie z punktu na stronie.

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ę.

Geo nie ma osobnej flagi licencyjnej dla poszczególnych funkcji; koperta poziomu Pro włącza je bezpośrednio.

Instalacja

composer require nextpdf/pro:^3

Przegląd koncepcyjny

Geoprzestrzenny plik PDF niesie słownik miary, opisany w ISO 32000-2 §12.8.2, który wiąże punkty przestrzeni urządzenia z geograficznym układem odniesienia współrzędnych. NextPDF Pro buduje te dane z niezmienialnych obiektów wartości:

• GeoCoordinate — trójka szerokość/długość/wysokość. Konstrukcja waliduje szerokość w zakresie [-90, 90] i długość w zakresie [-180, 180] oraz oferuje formatowanie w stopniach-minutach-sekundach i jako ciąg dziesiętny.
• GeoControlPoint — sparowanie punktu przestrzeni PDF z GeoCoordinate.
• ProjectionType — enum powszechnych odwzorowań (geograficzne, UTM, transwersalne Mercatora, Lamberta konforemne stożkowe), każde zmapowane na kod EPSG.
• GeoRegistration — punkty kontrolne plus odwzorowanie i geodezyjny układ odniesienia (datum, domyślnie WGS84). isValid() wymaga co najmniej dwóch punktów kontrolnych dla minimalnego przekształcenia afinicznego; toPdfMeasureDictionary() emituje słownik /Measure z /Subtype /GEO oraz tablicami punktów kontrolnych.

Dlaczego działa to w ten sposób

NextPDF buduje słownik miary ze zwalidowanych, niezmienialnych obiektów wartości, a nie z surowego słownika dostarczonego przez wywołującego. GeoCoordinate odrzuca szerokość lub długość spoza zakresu już przy konstrukcji. GeoRegistration::isValid() odmawia mniej niż dwóch punktów kontrolnych, więc wadliwa rejestracja zawodzi szybko, zamiast emitować zdegradowany słownik /GEO. Odwzorowania rozwiązują się na standardowe kody EPSG poprzez ProjectionType, co utrzymuje układ odniesienia współrzędnych jawnym, a nie zgadywanym. Datum domyślnie przyjmuje WGS84, ale pozostaje nazwanym polem, więc niedomyślny układ odniesienia jest świadomym wyborem. Ta postawa fail-closed ma znaczenie, ponieważ błędna georeferencja jest gorsza niż jej brak; przeglądarka z przekonaniem zaraportowałaby fałszywe rzeczywiste położenie. Tło projektowe: API, które odmawia zgadywania.

Powierzchnia API

Klasa	Odpowiedzialność
GeoCoordinate	Zwalidowana szerokość/długość/wysokość z formatowaniem.
GeoControlPoint	Sparowanie punkt PDF ↔ punkt geograficzny.
ProjectionType	Enum odwzorowań z kodami EPSG.
GeoRegistration	Zbuduj słownik /Measure /GEO.

Przykład kodu — Szybki start

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

Przykład kodu — Produkcja

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

Przypadki brzegowe i pułapki

• Konstrukcja GeoCoordinate odrzuca szerokość lub długość spoza zakresu.
• Mniej niż dwa punkty kontrolne dają nieprawidłową rejestrację.
• Domyślny układ odniesienia (datum) to WGS84; ustaw go jawnie dla innych układów odniesienia.

Wydajność

Generowanie słownika jest liniowe względem liczby punktów kontrolnych.

Uwagi dotyczące bezpieczeństwa

Wejście Geo to liczbowe dane współrzędnych. Waliduj punkty kontrolne pochodzące z niezaufanego wejścia przed rejestracją.

Konformancja

Zachowanie	Odniesienie	Status
Geoprzestrzenny słownik miary (podtyp GEO)	ISO 32000-2 §12.8.2	Aligned (paraphrased)

Kontrakt zachowania

• GeoCoordinate waliduje szerokość w zakresie [-90, 90] i długość w zakresie [-180, 180] przy konstrukcji oraz oferuje formatowanie DMS i jako ciąg dziesiętny.
• GeoControlPoint paruje punkt przestrzeni PDF z GeoCoordinate.
• GeoRegistration niesie punkty kontrolne plus ProjectionType (zmapowany na kod EPSG) oraz geodezyjny układ odniesienia (datum) domyślnie WGS84. isValid() wymaga co najmniej dwóch punktów kontrolnych; toPdfMeasureDictionary() emituje słownik /Measure z /Subtype /GEO oraz tablicami punktów kontrolnych.
• Współrzędne spoza zakresu lub mniej niż dwa punkty kontrolne dają nieprawidłową rejestrację, zamiast po cichu zdegradowanego wyjścia.

Nota o granicy Enterprise

Enterprise nie zmienia zachowania Geo. Enterprise dodaje funkcje wyższego poziomu udokumentowane osobno; nie są one wymagane do wygenerowania słownika miary GeoPDF.

Rozwiązanie awaryjne / alternatywa w Core

Nie istnieje odpowiednik w Core dla generowania słownika miary GeoPDF. To dodatek Pro.

Granica publikacji

Ta strona dokumentuje wyłącznie zachowanie obserwowalne zewnętrznie oraz obsługiwaną publiczną powierzchnię 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 też

• Geo — Pełny materiał źródłowy — pełny materiał źródłowy klas i metod.
• Document — składanie stron i dokumentów.
• Core annotations.