Geo — Referensi Mendalam

Sekilas pandang

Halaman ini adalah referensi tingkat kontrak untuk modul Geo NextPDF Pro. Permukaannya adalah empat value object imutabel — GeoCoordinate, GeoControlPoint, ProjectionType, dan GeoRegistration — ditambah GeoPdfLayer, yang mengaitkan registrasi dengan indeks halaman dan mengemisi output viewport. Modul ini menghasilkan teks dictionary PDF: sebuah dictionary /Measure dengan /Subtype /GEO, sebuah dictionary /Viewport, dan nilai array /VP pada tingkat halaman. Pembuatannya adalah perakitan string yang deterministik: tanpa panggilan jaringan, tanpa akses filesystem, tanpa keacakan. Halaman ini menyatakan API publik, kontrak perilaku yang teramati, dan mode kegagalannya.

Ketersediaan & lisensi

Kemampuan ini dikirim dalam NextPDF Pro (nextpdf/pro) dan aktif dengan envelope lisensi tier Pro. Deployment tanpa entitlement tersebut tidak memuat class kemampuan ini. Bandingkan edisi dan dapatkan lisensi.

Tidak ada flag lisensi per-fitur yang menggerbang modul ini. Class Geo tersedia kapan pun nextpdf/pro terpasang.

Permukaan API publik

Symbol	Parameter	Perilaku bawaan	Mengembalikan	Melempar atau gagal dengan	Catatan
GeoCoordinate	constructor: float $latitude, float $longitude, float $altitude = 0.0	Memvalidasi lintang dalam [-90, 90] dan bujur dalam [-180, 180]	—	InvalidArgumentException ketika salah satu nilai di luar rentang	final readonly; altitude adalah meter di atas permukaan laut dan tidak diperiksa rentangnya
GeoCoordinate::toDms()	tidak ada	Memformat sebagai degrees-minutes-seconds dengan sufiks N/S dan E/W	string	—	Detik yang mendekati nol dirender sebagai 00; jika tidak, dua desimal dengan nol di belakang dipangkas
GeoCoordinate::toDecimal()	tidak ada	Memformat lintang dan bujur ke enam desimal, dipisahkan koma	string	—	Altitude tidak disertakan
GeoCoordinate::fromDms()	string $dms	Mem-parse string DMS; detik bersifat opsional; glyph degree dan quote tipografis dinormalisasi	self	InvalidArgumentException ketika string tidak dapat di-parse, atau ketika nilai hasil parse gagal pemeriksaan rentang constructor	Factory statik; huruf hemisphere tidak peka huruf besar/kecil; altitude bawaannya 0.0
GeoControlPoint	constructor: float $pdfX, float $pdfY, GeoCoordinate $geo	Memasangkan titik ruang-pengguna PDF (points) dengan sebuah koordinat geografis	—	—	final readonly; koordinat PDF tidak divalidasi
ProjectionType	enum berbasis string, 4 kasus	Kasus: Geographic, UTM, TransverseMercator, LambertConformal	nilai backing GEO, UTM, TM, LCC	—	Lihat tabel pemetaan proyeksi di bawah
ProjectionType::epsgCode()	tidak ada	Memetakan kasus ke satu kode EPSG tetap	int	—	4326, 32601, 2154, atau 3347
ProjectionType::label()	tidak ada	Nama proyeksi yang mudah dibaca manusia	string	—	Contohnya WGS 84 Geographic
GeoRegistration	constructor: array $controlPoints, ProjectionType $projection, string $datum = 'WGS84'	Menyimpan titik kontrol, proyeksi, dan datum geodetik	—	—	final readonly; jumlah titik kontrol tidak divalidasi saat konstruksi
GeoRegistration::isValid()	tidak ada	Membutuhkan setidaknya dua titik kontrol	bool	—	Dua titik adalah minimum untuk pemetaan affine
GeoRegistration::toPdfMeasureDictionary()	tidak ada	Mengemisi dictionary /Measure dengan /Subtype /GEO, /GCS, /GPTS, /LPTS, dan /Bounds	string	—	Tidak memeriksa isValid(); jaga panggilan ini atau salurkan melalui GeoPdfLayer
GeoPdfLayer::addRegistration()	int $pageIndex, GeoRegistration $registration	Menambahkan registrasi untuk indeks halaman berbasis nol	self	InvalidArgumentException ketika $pageIndex negatif	Fluent; registrasi pertama yang ditambahkan untuk sebuah halaman menang saat pembuatan
GeoPdfLayer::getRegistrations()	tidak ada	Mengembalikan semua registrasi dalam urutan penyisipan	list<array{pageIndex: int, registration: GeoRegistration}>	—	Menyertakan duplikat dan registrasi tidak valid sebagaimana ditambahkan
GeoPdfLayer::generateViewportDictionary()	int $pageIndex	Mengemisi dictionary /Viewport dengan /BBox, /Name, dan /Measure inline	string	—	String kosong ketika halaman tidak memiliki registrasi atau registrasinya tidak valid
GeoPdfLayer::generateViewportArray()	int $pageIndex	Membungkus dictionary viewport dalam kurung siku sebagai literal array /VP	string	—	String kosong ketika tidak ada; pemanggil lalu menghilangkan /VP untuk halaman tersebut
GeoPdfLayer::writeToPdfWriter()	BinaryBuffer $buffer, int $pageIndex	Menulis /VP ditambah literal array dan sebuah newline ke buffer	bool	—	true ketika sebuah entri ditulis; no-op dan false jika tidak

Signature entry-point

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

Kontrak perilaku

Validasi dan pemformatan koordinat

GeoCoordinate memvalidasi saat konstruksi dan tidak pernah bermutasi. Lintang di luar [-90, 90] atau bujur di luar [-180, 180] melempar InvalidArgumentException yang menyebutkan nilai yang bermasalah. toDms() merender kedua sumbu sebagai derajat, menit dengan padding nol, detik, dan sebuah sufiks hemisphere. toDecimal() merender latitude, longitude pada enam desimal. fromDms() menerima input DMS dengan detik opsional, menormalisasi glyph prime, double-prime, degree-sign, dan smart-quote, mengonversi ke derajat desimal bertanda, dan mengonstruksi instance baru. Lintang selatan dan bujur barat menjadi nilai negatif.

Pemetaan proyeksi

Setiap kasus ProjectionType membawa satu kode EPSG dan label yang tetap. Pemetaannya adalah tabel tertutup, bukan registry coordinate-reference-system.

Kasus	Nilai backing	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

Kasus UTM mengemisi kode zone 1. Proyek yang membutuhkan zone UTM berbeda, atau kode EPSG apa pun di luar tabel ini, sebaiknya membawa deskripsi CRS otoritatif dalam string datum sebagai Well Known Text.

Emisi measure dictionary

GeoRegistration::toPdfMeasureDictionary() mengemisi dictionary multi-baris: /Type /Measure, /Subtype /GEO, sebuah dictionary sistem koordinat /GCS, /GPTS, /LPTS, dan /Bounds, sesuai ISO 32000-2:2020 §12.10 (Table 269). Perilaku konkret:

• /GCS diemisi sebagai << /Type /PROJCS /EPSG <code> /WKT (<datum>) >>. Kode EPSG berasal dari kasus proyeksi. Nilai /WKT adalah string datum persis seperti yang diberikan; bawaannya adalah WGS84.
• /GPTS mendaftar pasangan lintang-bujur pada enam desimal, dalam urutan titik kontrol.
• /LPTS mendaftar pasangan pdfX/pdfY pada enam desimal, persis seperti yang diberikan. ISO 32000-2:2020 Table 269 mendefinisikan titik LPTS dalam unit square 2D; menyediakan nilai yang dinormalisasi ke unit-square adalah tanggung jawab pemanggil.
• /Bounds tetap pada [0 0 0 1 1 1 1 0], unit square penuh.
• String datum di-escape sebelum interpolasi ke dalam literal string: backslash, tanda kurung, dan karakter kontrol umum menjadi backslash escape-nya sesuai ISO 32000-2:2020 §7.3.4.2. Datum yang dipengaruhi pemanggil tidak dapat mengakhiri literal string atau menyuntikkan token PDF mentah.

Emisi viewport dan halaman

GeoPdfLayer menyimpan registrasi dalam urutan penyisipan, dikunci dengan indeks halaman berbasis nol. generateViewportDictionary() menyelesaikan registrasi pertama untuk halaman yang diminta dan mengembalikan string kosong ketika tidak ada atau ketika isValid() bernilai false. Dictionary yang dihasilkan membawa /Type /Viewport, sebuah /BBox yang dihitung dari koordinat PDF titik kontrol minimum dan maksimum, sebuah /Name berbentuk GeoViewport_Page<n>, dan dictionary /Measure inline. Entri /Measure viewport mengikuti ISO 32000-2:2020 §12.9. generateViewportArray() membungkus dictionary dalam kurung siku, menghasilkan nilai /VP halaman: sebuah array dictionary viewport sesuai ISO 32000-2:2020 §7.7.3.3 (Table 31). writeToPdfWriter() menulis /VP ditambah literal array ke sebuah BinaryBuffer Core dan melaporkan apakah ada yang ditulis, sehingga serialisasi halaman dapat menghilangkan key dengan bersih.

Kasus tepi & mode kegagalan

• Lintang atau bujur di luar rentang melempar InvalidArgumentException saat konstruksi; tidak ada koordinat yang valid sebagian.
• fromDms() melempar pada input yang tidak dapat di-parse. Nilai hasil parse melewati constructor, sehingga string yang secara sintaks valid dengan nilai di luar rentang juga melempar.
• Notasi DMS tidak membawa altitude; fromDms() selalu menghasilkan altitude 0.0.
• Sebuah GeoRegistration dengan kurang dari dua titik kontrol melaporkan isValid() false, namun toPdfMeasureDictionary() tetap mengemisi dictionary dengan array titik yang pendek. Jaga panggilan langsung dengan isValid(), atau salurkan emisi melalui GeoPdfLayer, yang menyembunyikan registrasi tidak valid.
• Registrasi duplikat untuk satu indeks halaman semuanya dipertahankan oleh getRegistrations(); pembuatan viewport menggunakan yang pertama ditambahkan.
• Indeks halaman negatif melempar InvalidArgumentException; indeks halaman berbasis nol.
• Titik kontrol yang berbagi nilai X atau Y menghasilkan /BBox degeneratif dengan lebar-nol atau tinggi-nol. Sediakan titik yang merentang kedua sumbu.
• Semua output adalah teks yang dihasilkan. Tidak ada yang ditulis ke disk atau jaringan, dan input identik menghasilkan output identik.
• Tidak ada operasi kriptografis yang terjadi dalam modul ini, sehingga tidak ada perilaku spesifik-mode-FIPS.

Konformansi

Klaim	Standar	Klausul
Measure dictionary diemisi dengan subtype GEO, dengan pasangan lintang-bujur GPTS dan nilai LPTS berpasangan.	ISO 32000-2:2020	§12.10
Dictionary viewport membawa entri BBox, Name, dan Measure.	ISO 32000-2:2020	§12.9
Nilai VP halaman diemisi sebagai array dictionary viewport.	ISO 32000-2:2020	§7.7.3.3
Interpolasi datum meng-escape metakarakter literal-string.	ISO 32000-2:2020	§7.3.4.2

Semua klausul diparafrasakan; NextPDF tidak mereproduksi teks normatif. Ini adalah pernyataan kemampuan, bukan sertifikasi. NextPDF tidak memegang sertifikasi dan tidak memberikannya. Kode EPSG adalah nilai representatif tetap per kasus proyeksi, dan entri /WKT membawa string datum yang diberikan alih-alih deskripsi Well Known Text yang dihasilkan; kedua pernyataan tersebut berlandaskan produk. Validasi output GeoPDF yang diemisi di processor PDF interaktif target sebelum mengandalkan pengukuran sisi-viewer.

Catatan pengembangan

• Tersedia sejak nextpdf/pro 1.9.0; terkini di nextpdf/pro 3.1.0.
• Periksa isValid() sebelum memanggil toPdfMeasureDictionary() secara langsung; GeoPdfLayer melakukan pemeriksaan ini untuk Anda.
• Ketika konsumen hilir mem-parse /WKT, berikan deskripsi Well Known Text lengkap sebagai datum; bawaan WGS84 hanyalah label datum.
• Normalisasi input LPTS ke unit square sebelum mengonstruksi titik kontrol ketika bounds viewport berbeda dari nilai ruang-PDF Anda.
• Biaya emisi linear terhadap jumlah titik kontrol; pencarian di GeoPdfLayer linear terhadap jumlah registrasi.
• writeToPdfWriter() terintegrasi dengan serialisasi halaman melalui NextPDF\Support\BinaryBuffer dari Core.

Batas publikasi

Halaman ini mendokumentasikan hanya perilaku yang teramati secara eksternal dan permukaan API publik yang didukung. Path namespace internal, class helper, tabel mekanisme, nama file runbook, dan prefiks tiket berada di luar cakupan.

Lihat juga

• Geo (kemampuan) — pemasangan, gambaran konseptual, dan sampel quick-start.
• Document — Referensi Mendalam — permukaan komposisi dokumen dan halaman.