Geo

Sekilas pandang

NextPDF Pro memetakan koordinat halaman PDF ke koordinat geografis dan menghasilkan sebuah measure dictionary PDF dengan subtype GEO, sehingga sebuah viewer dapat melaporkan posisi dunia-nyata dari sebuah titik pada halaman.

Ketersediaan & lisensi

Kapabilitas ini disertakan dalam NextPDF Pro (nextpdf/pro) dan aktif dengan sebuah envelope lisensi tier Pro. Sebuah deployment tanpa entitlement tersebut tidak memuat kelas-kelas kapabilitas ini. Bandingkan edisi dan dapatkan lisensi.

Geo tidak memiliki penanda lisensi per-fitur terpisah; envelope tier Pro mengaktifkannya secara langsung.

Pemasangan

composer require nextpdf/pro:^3

Tinjauan konseptual

Sebuah PDF geospasial membawa sebuah measure dictionary, yang dideskripsikan di ISO 32000-2 §12.8.2, yang mengikat titik device-space ke sistem referensi koordinat geografis. NextPDF Pro membangun data tersebut dari objek nilai imutabel:

• GeoCoordinate — sebuah triple lintang/bujur/altitude. Konstruksi memvalidasi lintang dalam [-90, 90] dan bujur dalam [-180, 180], serta menawarkan format derajat-menit-detik dan string desimal.
• GeoControlPoint — pemasangan sebuah titik PDF-space dengan sebuah GeoCoordinate.
• ProjectionType — sebuah enum proyeksi umum (geografis, UTM, transverse Mercator, Lambert conformal conic), masing-masing dipetakan ke kode EPSG.
• GeoRegistration — control point plus proyeksi dan datum geodetik (default WGS84). isValid() membutuhkan setidaknya dua control point untuk transformasi afin minimal; toPdfMeasureDictionary() memancarkan dictionary /Measure dengan /Subtype /GEO dan array control-point.

Mengapa ia bekerja seperti ini

NextPDF membangun measure dictionary dari objek nilai yang tervalidasi dan imutabel, bukan dari sebuah dictionary mentah yang dipasok oleh pemanggil. GeoCoordinate menolak lintang atau bujur di luar rentang pada saat konstruksi. GeoRegistration::isValid() menolak kurang dari dua control point, sehingga sebuah registrasi yang cacat gagal cepat alih-alih memancarkan sebuah dictionary /GEO yang terdegradasi. Proyeksi diselesaikan ke kode EPSG standar melalui ProjectionType, yang menjaga sistem referensi koordinat tetap eksplisit alih-alih ditebak. Datum default ke WGS84 tetapi tetap menjadi field bernama, sehingga sistem referensi non-default merupakan pilihan yang disengaja. Postur fail-closed ini penting karena georeferensi yang salah lebih buruk daripada tidak ada sama sekali; sebuah viewer akan dengan yakin melaporkan posisi dunia-nyata yang keliru. Latar belakang desain: API yang menolak menebak.

Permukaan API

Class	Responsibility
GeoCoordinate	Lat/lon/altitude tervalidasi dengan pemformatan.
GeoControlPoint	Pemasangan titik PDF ↔ titik geografis.
ProjectionType	Enum proyeksi dengan kode EPSG.
GeoRegistration	Membangun dictionary /Measure /GEO.

Contoh kode — Mulai cepat

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

Contoh kode — Produksi

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

Kasus tepi & jebakan

• Konstruksi GeoCoordinate menolak lintang atau bujur di luar rentang.
• Kurang dari dua control point menghasilkan registrasi yang tidak valid.
• Datum default adalah WGS84; setel secara eksplisit untuk sistem referensi lain.

Performa

Penghasilan dictionary bersifat linear terhadap jumlah control point.

Catatan keamanan

Input Geo adalah data koordinat numerik. Validasi control point yang bersumber dari input tidak tepercaya sebelum registrasi.

Konformansi

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

Kontrak perilaku

• GeoCoordinate memvalidasi lintang dalam [-90, 90] dan bujur dalam [-180, 180] pada saat konstruksi dan menawarkan format string DMS dan desimal.
• GeoControlPoint memasangkan sebuah titik PDF-space dengan sebuah GeoCoordinate.
• GeoRegistration membawa control point plus sebuah ProjectionType (dipetakan ke kode EPSG) dan sebuah datum geodetik yang default ke WGS84. isValid() membutuhkan setidaknya dua control point; toPdfMeasureDictionary() memancarkan dictionary /Measure dengan /Subtype /GEO dan array control-point.
• Koordinat di luar rentang atau kurang dari dua control point menghasilkan registrasi yang tidak valid alih-alih keluaran yang terdegradasi secara diam-diam.

Catatan batas Enterprise

Enterprise tidak mengubah perilaku Geo. Enterprise menambahkan fitur tingkat-lebih-tinggi yang didokumentasikan terpisah; fitur tersebut tidak diwajibkan untuk menghasilkan measure dictionary GeoPDF.

Fallback / alternatif Core

Tidak ada padanan Core untuk penghasilan measure-dictionary GeoPDF. Ini adalah tambahan Pro.

Batas publikasi

Halaman ini mendokumentasikan hanya perilaku yang dapat diamati secara eksternal dan permukaan API publik yang didukung. Jalur namespace internal, kelas helper, tabel mekanisme, nama berkas runbook, dan prefiks tiket berada di luar cakupan.

Lihat juga

• Geo — Deep Reference — referensi kelas dan metode lengkap.
• Document — penyusunan halaman dan dokumen.
• Core annotations.