Geo — Derinlemesine başvuru

Genel bakış

Bu sayfa, NextPDF Pro Geo modülünün sözleşme düzeyindeki başvurusudur. Yüzey, dört değişmez değer nesnesinden — GeoCoordinate, GeoControlPoint, ProjectionType ve GeoRegistration — ve kayıtları sayfa dizinleriyle ilişkilendirip görünüm alanı çıktısı yayan GeoPdfLayer’dan oluşur. Modül, PDF sözlük metni üretir: /Subtype /GEO içeren bir /Measure sözlüğü, bir /Viewport sözlüğü ve sayfa düzeyindeki /VP dizi değeri. Oluşturma, deterministik dize birleştirmedir: ağ çağrısı yok, dosya sistemi erişimi yok, rastgelelik yok. Bu sayfa, herkese açık API’yi, gözlemlenebilir davranış sözleşmesini ve başarısızlık modlarını belirtir.

Kullanılabilirlik ve lisanslama

Bu yetenek NextPDF Pro (nextpdf/pro) ile gelir ve Pro katmanı lisans zarfıyla etkinleşir. Bu yetkilendirmeye sahip olmayan bir dağıtım, yeteneğin sınıflarını yüklemez. Sürümleri karşılaştırın ve lisans edinin.

Bu modülü özellik başına bir lisans bayrağı kapılamaz. Geo sınıfları, nextpdf/pro yüklü olduğunda kullanılabilir.

Genel API yüzeyi

Sembol	Parametreler	Varsayılan davranış	Döndürür	Şununla fırlatır veya başarısız olur	Notlar
GeoCoordinate	yapıcı: float $latitude, float $longitude, float $altitude = 0.0	Enlemi [-90, 90] ve boylamı [-180, 180] aralığında doğrular	—	Her iki değer de aralık dışındayken InvalidArgumentException	final readonly; rakım deniz seviyesinden metre cinsindedir ve aralık denetimi yapılmaz
GeoCoordinate::toDms()	yok	N/S ve E/W sonekleriyle derece-dakika-saniye olarak biçimlendirir	string	—	Sıfıra yakın saniyeler 00 olarak işlenir; aksi hâlde sondaki sıfırları kırpılmış iki ondalık
GeoCoordinate::toDecimal()	yok	Enlem ve boylamı altı ondalığa, virgülle ayrılmış biçimlendirir	string	—	Rakım dâhil edilmez
GeoCoordinate::fromDms()	string $dms	Bir DMS dizesini ayrıştırır; saniyeler isteğe bağlıdır; tipografik derece ve tırnak glifleri normalleştirilir	self	Dize ayrıştırılamadığında veya ayrıştırılan değerler yapıcı aralık denetimlerinden geçemediğinde InvalidArgumentException	Statik fabrika; yarımküre harfleri büyük/küçük harf duyarsızdır; rakım varsayılan olarak 0.0
GeoControlPoint	yapıcı: float $pdfX, float $pdfY, GeoCoordinate $geo	Bir PDF kullanıcı uzayı noktasını (punto) bir coğrafi koordinatla eşleştirir	—	—	final readonly; PDF koordinatları doğrulanmaz
ProjectionType	dize destekli enum, 4 durum	Durumlar: Geographic, UTM, TransverseMercator, LambertConformal	destek değerleri GEO, UTM, TM, LCC	—	Aşağıdaki projeksiyon eşleme tablosuna bakın
ProjectionType::epsgCode()	yok	Durumu tek bir sabit EPSG koduna eşler	int	—	4326, 32601, 2154 veya 3347
ProjectionType::label()	yok	İnsan tarafından okunabilir projeksiyon adı	string	—	Örneğin WGS 84 Geographic
GeoRegistration	yapıcı: array $controlPoints, ProjectionType $projection, string $datum = 'WGS84'	Kontrol noktalarını, projeksiyonu ve jeodezik datumu tutar	—	—	final readonly; kontrol noktası sayısı yapım sırasında doğrulanmaz
GeoRegistration::isValid()	yok	En az iki kontrol noktası gerektirir	bool	—	İki nokta, bir afin eşleme için gereken en az sayıdır
GeoRegistration::toPdfMeasureDictionary()	yok	/Subtype /GEO, /GCS, /GPTS, /LPTS ve /Bounds içeren bir /Measure sözlüğü yayar	string	—	isValid() denetlemez; çağrıyı koruyun veya GeoPdfLayer üzerinden yönlendirin
GeoPdfLayer::addRegistration()	int $pageIndex, GeoRegistration $registration	Sıfır tabanlı bir sayfa dizini için bir kayıt ekler	self	$pageIndex negatif olduğunda InvalidArgumentException	Akıcı; bir sayfa için eklenen ilk kayıt, oluşturma sırasında kazanır
GeoPdfLayer::getRegistrations()	yok	Tüm kayıtları ekleme sırasına göre döndürür	list<array{pageIndex: int, registration: GeoRegistration}>	—	Yinelenen ve geçersiz kayıtları eklendiği gibi içerir
GeoPdfLayer::generateViewportDictionary()	int $pageIndex	/BBox, /Name ve satır içi bir /Measure içeren bir /Viewport sözlüğü yayar	string	—	Sayfada kayıt yoksa veya kayıt geçersizse boş dize
GeoPdfLayer::generateViewportArray()	int $pageIndex	Görünüm alanı sözlüğünü /VP dizi değişmezi olarak köşeli parantezlere sarar	string	—	Yoksa boş dize; çağıranlar o sayfa için /VP girmez
GeoPdfLayer::writeToPdfWriter()	BinaryBuffer $buffer, int $pageIndex	Arabelleğe /VP artı dizi değişmezini ve bir yeni satır yazar	bool	—	Bir girdi yazıldığında true; aksi hâlde işlemsiz ve false

Giriş noktası imzaları

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

Davranış sözleşmesi

Koordinat doğrulama ve biçimlendirme

GeoCoordinate yapım sırasında doğrular ve asla değişmez. [-90, 90] aralığı dışındaki enlem veya [-180, 180] aralığı dışındaki boylam, kusurlu değeri belirten bir InvalidArgumentException fırlatır. toDms(), her iki ekseni de derece, sıfır doldurulmuş dakika, saniye ve bir yarımküre soneki olarak işler. toDecimal(), latitude, longitude değerini altı ondalıkla işler. fromDms(), saniyeleri isteğe bağlı DMS girdisini kabul eder; asal, çift asal, derece işareti ve akıllı tırnak gliflerini normalleştirir; işaretli ondalık derecelere dönüştürür ve yeni bir örnek oluşturur. Güney enlemleri ve batı boylamları negatif değer olur.

Projeksiyon eşleme

Her ProjectionType durumu, tek bir sabit EPSG kodu ve etiket taşır. Eşleme, bir koordinat referans sistemi kaydı değil, kapalı bir tablodur.

Durum	Destek değeri	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

UTM durumu, bölge 1 kodunu yayar. Farklı bir UTM bölgesine veya bu tablonun dışındaki herhangi bir EPSG koduna ihtiyaç duyan projeler, yetkili CRS açıklamasını datum dizesinde Well Known Text olarak taşımalıdır.

Ölçü sözlüğü yayımı

GeoRegistration::toPdfMeasureDictionary(), ISO 32000-2:2020 §12.10 (Tablo 269) uyarınca çok satırlı bir sözlük yayar: /Type /Measure, /Subtype /GEO, bir /GCS koordinat sistemi sözlüğü, /GPTS, /LPTS ve /Bounds. Somut davranış:

• /GCS, << /Type /PROJCS /EPSG <code> /WKT (<datum>) >> olarak yayılır. EPSG kodu projeksiyon durumundan gelir. /WKT değeri, tam olarak sağlandığı biçimiyle datum dizesidir; varsayılan WGS84’tür.
• /GPTS, kontrol noktası sırasına göre altı ondalıkla enlem-boylam çiftlerini listeler.
• /LPTS, pdfX/pdfY çiftlerini tam olarak sağlandığı biçimiyle altı ondalıkla listeler. ISO 32000-2:2020 Tablo 269, LPTS noktalarını 2B birim karede tanımlar; birim kareye normalleştirilmiş değerler sağlamak, çağıranın sorumluluğundadır.
• /Bounds, tam birim kare olan [0 0 0 1 1 1 1 0] değerinde sabittir.
• datum dizesi, literal dizeye enterpolasyondan önce kaçışlanır: ters eğik çizgi, parantezler ve yaygın denetim karakterleri, ISO 32000-2:2020 §7.3.4.2 uyarınca ters eğik çizgi kaçışlarına dönüşür. Çağıranın etkilediği bir datum, literal dizeyi sonlandıramaz veya ham PDF belirteçleri enjekte edemez.

Görünüm alanı ve sayfa yayımı

GeoPdfLayer, kayıtları sıfır tabanlı sayfa dizinine göre anahtarlanmış olarak ekleme sırasında tutar. generateViewportDictionary(), istenen sayfa için ilk kaydı çözer ve hiçbiri yoksa veya isValid() yanlışsa boş dize döndürür. Üretilen bir sözlük şunları taşır: /Type /Viewport, en küçük ve en büyük kontrol noktası PDF koordinatlarından hesaplanan bir /BBox, GeoViewport_Page<n> biçiminde bir /Name ve satır içi /Measure sözlüğü. Görünüm alanı /Measure girdisi, ISO 32000-2:2020 §12.9’u izler. generateViewportArray(), sözlüğü köşeli parantezlere sararak sayfa /VP değerini üretir: ISO 32000-2:2020 §7.7.3.3 (Tablo 31) uyarınca bir görünüm alanı sözlükleri dizisi. writeToPdfWriter(), /VP artı dizi değişmezini bir Core BinaryBuffer’ına yazar ve herhangi bir şeyin yazılıp yazılmadığını bildirir, böylece sayfa serileştirmesi anahtarı temiz biçimde atlayabilir.

Uç durumlar ve başarısızlık modları

• Aralık dışı enlem veya boylam, yapım sırasında InvalidArgumentException fırlatır; kısmen geçerli bir koordinat yoktur.
• fromDms(), ayrıştırılamayan girdide fırlatır. Ayrıştırılan değerler yapıcıdan geçer, dolayısıyla aralık dışı değerler içeren sözdizimsel olarak geçerli bir dize de fırlatır.
• DMS gösterimi rakım taşımaz; fromDms() her zaman 0.0 rakımı verir.
• İkiden az kontrol noktasına sahip bir GeoRegistration, isValid() için yanlış bildirir, yine de toPdfMeasureDictionary() kısa nokta dizileriyle bir sözlük yayar. Doğrudan çağrıları isValid() ile koruyun veya yayımı, geçersiz kayıtları bastıran GeoPdfLayer üzerinden yönlendirin.
• Bir sayfa dizini için yinelenen kayıtların tümü getRegistrations() tarafından korunur; görünüm alanı oluşturma, eklenen ilkini kullanır.
• Negatif bir sayfa dizini InvalidArgumentException fırlatır; sayfa dizinleri sıfır tabanlıdır.
• Aynı X veya Y değerini paylaşan kontrol noktaları, dejenere bir sıfır genişlikli veya sıfır yükseklikli /BBox üretir. Her iki ekseni de kapsayan noktalar sağlayın.
• Tüm çıktı, üretilen metindir. Diske veya ağa hiçbir şey yazılmaz ve aynı girdi aynı çıktıyı üretir.
• Bu modülde hiçbir kriptografik işlem gerçekleşmez, dolayısıyla FIPS moduna özgü bir davranış yoktur.

Uygunluk

İddia	Standart	Madde
Ölçü sözlüğü, GPTS enlem-boylam çiftleri ve eşlenmiş LPTS değerleriyle GEO alt türüyle yayılır.	ISO 32000-2:2020	§12.10
Görünüm alanı sözlüğü, BBox, Name ve Measure girdilerini taşır.	ISO 32000-2:2020	§12.9
Sayfa VP değeri, bir görünüm alanı sözlükleri dizisi olarak yayılır.	ISO 32000-2:2020	§7.7.3.3
Datum enterpolasyonu, literal dize meta karakterlerini kaçışlar.	ISO 32000-2:2020	§7.3.4.2

Tüm maddeler açımlanmıştır; NextPDF, normatif metni yeniden üretmez. Bunlar sertifikalar değil, yetenek beyanlarıdır. NextPDF hiçbir sertifikaya sahip değildir ve hiçbirini vermez. EPSG kodları, projeksiyon durumu başına sabit temsili değerlerdir ve /WKT girdisi, üretilmiş bir Well Known Text açıklaması yerine sağlanan datum dizesini taşır; her iki beyan da ürün temellidir. Görüntüleyici tarafı ölçümüne güvenmeden önce, yayılan GeoPDF çıktısını hedef etkileşimli PDF işlemcilerinde doğrulayın.

Geliştirme notları

• nextpdf/pro 1.9.0’dan beri kullanılabilir; nextpdf/pro 3.1.0’da günceldir.
• toPdfMeasureDictionary() doğrudan çağırmadan önce isValid() denetleyin; GeoPdfLayer bu denetimi sizin için yapar.
• Alt akış tüketicileri /WKT ayrıştırdığında, datum olarak tam bir Well Known Text açıklaması geçirin; varsayılan WGS84 yalnızca bir datum etiketidir.
• Görünüm alanı sınırları PDF uzayı değerlerinizden farklı olduğunda, kontrol noktalarını oluşturmadan önce LPTS girdilerini birim kareye normalleştirin.
• Yayım maliyeti, kontrol noktası sayısında doğrusaldır; GeoPdfLayer içindeki arama, kayıt sayısında doğrusaldır.
• writeToPdfWriter(), Core’dan gelen NextPDF\Support\BinaryBuffer aracılığıyla sayfa serileştirmesiyle bütünleşir.

Yayımlama sınırı

Bu sayfa, yalnızca dışarıdan gözlemlenebilir davranışı ve desteklenen herkese açık API yüzeyini belgeler. Dâhili ad alanı yolları, yardımcı sınıflar, mekanizma tabloları, runbook dosya adları ve bilet önekleri kapsam dışıdır.

Ayrıca bkz.

• Geo (yetenek) — kurulum, kavramsal genel bakış ve hızlı başlangıç örnekleri.
• Document — Derinlemesine başvuru — belge ve sayfa oluşturma yüzeyi.