Geo — การอ้างอิงเชิงลึก

ภาพรวมโดยสังเขป

หน้านี้เป็นการอ้างอิงระดับสัญญาของโมดูล Geo ใน NextPDF Pro พื้นผิวประกอบด้วยอ็อบเจกต์ค่าที่ไม่เปลี่ยนแปลงสี่ตัว — GeoCoordinate, GeoControlPoint, ProjectionType และ GeoRegistration — บวกกับ GeoPdfLayer ซึ่งเชื่อมโยง registration กับดัชนีหน้าและปล่อยเอาต์พุต viewport โมดูลนี้ผลิตข้อความ dictionary ของ PDF: dictionary /Measure พร้อม /Subtype /GEO, dictionary /Viewport และค่าอาร์เรย์ /VP ระดับหน้า การสร้างเป็นการประกอบสตริงแบบกำหนดได้แน่นอน: ไม่มีการเรียกเครือข่าย ไม่มีการเข้าถึงระบบไฟล์ ไม่มีการสุ่ม หน้านี้ระบุ API สาธารณะ สัญญาพฤติกรรมที่สังเกตได้ และโหมดความล้มเหลว

ความพร้อมใช้งานและการอนุญาต

ความสามารถนี้มาพร้อมกับ NextPDF Pro (nextpdf/pro) และเปิดใช้งานด้วยซองใบอนุญาตระดับ Pro การนำไปใช้งานที่ไม่มีสิทธิ์ดังกล่าวจะไม่โหลดคลาสของความสามารถนี้ เปรียบเทียบรุ่นและขอใบอนุญาต

ไม่มีแฟล็กใบอนุญาตรายฟีเจอร์ที่จำกัดโมดูลนี้ คลาส Geo พร้อมใช้งานเมื่อใดก็ตามที่ติดตั้ง nextpdf/pro

พื้นผิว API สาธารณะ

สัญลักษณ์	พารามิเตอร์	พฤติกรรมปริยาย	คืนค่า	โยนหรือล้มเหลวด้วย	หมายเหตุ
GeoCoordinate	constructor: float $latitude, float $longitude, float $altitude = 0.0	ตรวจสอบละติจูดให้อยู่ใน [-90, 90] และลองจิจูดให้อยู่ใน [-180, 180]	—	InvalidArgumentException เมื่อค่าใดค่าหนึ่งอยู่นอกช่วง	final readonly; altitude คือเมตรเหนือระดับน้ำทะเลและไม่ถูกตรวจสอบช่วง
GeoCoordinate::toDms()	ไม่มี	จัดรูปแบบเป็นองศา-ลิปดา-พิลิปดา พร้อมส่วนต่อท้าย N/S และ E/W	string	—	พิลิปดาที่ใกล้ศูนย์แสดงเป็น 00; มิฉะนั้นเป็นทศนิยมสองตำแหน่งโดยตัดเลขศูนย์ท้ายออก
GeoCoordinate::toDecimal()	ไม่มี	จัดรูปแบบละติจูดและลองจิจูดเป็นทศนิยมหกตำแหน่ง คั่นด้วยจุลภาค	string	—	ไม่รวม altitude
GeoCoordinate::fromDms()	string $dms	แจงสตริง DMS; พิลิปดาเป็นตัวเลือกได้; อักขระองศาและเครื่องหมายคำพูดเชิงพิมพ์จะถูกทำให้เป็นมาตรฐาน	self	InvalidArgumentException เมื่อแจงสตริงไม่ได้ หรือเมื่อค่าที่แจงได้ไม่ผ่านการตรวจสอบช่วงของ constructor	โรงงานสถิต; ตัวอักษรซีกโลกไม่คำนึงถึงตัวพิมพ์ใหญ่เล็ก; altitude มีค่าปริยายเป็น 0.0
GeoControlPoint	constructor: float $pdfX, float $pdfY, GeoCoordinate $geo	จับคู่จุดในพื้นที่ผู้ใช้ PDF (หน่วยพอยต์) กับพิกัดภูมิศาสตร์	—	—	final readonly; พิกัด PDF ไม่ถูกตรวจสอบ
ProjectionType	enum ที่สำรองด้วยสตริง 4 กรณี	กรณี: Geographic, UTM, TransverseMercator, LambertConformal	ค่าสำรอง GEO, UTM, TM, LCC	—	ดูตารางการแมป projection ด้านล่าง
ProjectionType::epsgCode()	ไม่มี	แมปกรณีไปยังรหัส EPSG คงที่หนึ่งค่า	int	—	4326, 32601, 2154 หรือ 3347
ProjectionType::label()	ไม่มี	ชื่อ projection ที่มนุษย์อ่านได้	string	—	ตัวอย่างเช่น WGS 84 Geographic
GeoRegistration	constructor: array $controlPoints, ProjectionType $projection, string $datum = 'WGS84'	เก็บจุดควบคุม projection และดาตัมภูมิสัณฐาน	—	—	final readonly; จำนวนจุดควบคุมไม่ถูกตรวจสอบตอนสร้าง
GeoRegistration::isValid()	ไม่มี	ต้องมีจุดควบคุมอย่างน้อยสองจุด	bool	—	สองจุดเป็นจำนวนต่ำสุดสำหรับการแมปแบบ affine
GeoRegistration::toPdfMeasureDictionary()	ไม่มี	ปล่อย dictionary /Measure พร้อม /Subtype /GEO, /GCS, /GPTS, /LPTS และ /Bounds	string	—	ไม่ตรวจสอบ isValid(); ป้องกันการเรียกหรือส่งผ่าน GeoPdfLayer
GeoPdfLayer::addRegistration()	int $pageIndex, GeoRegistration $registration	เพิ่ม registration สำหรับดัชนีหน้าแบบเริ่มที่ศูนย์	self	InvalidArgumentException เมื่อ $pageIndex เป็นค่าลบ	เรียกต่อเนื่องได้; registration แรกที่เพิ่มสำหรับหน้าหนึ่งจะถูกใช้ตอนสร้าง
GeoPdfLayer::getRegistrations()	ไม่มี	คืนค่า registration ทั้งหมดตามลำดับการเพิ่ม	list<array{pageIndex: int, registration: GeoRegistration}>	—	รวม registration ที่ซ้ำและไม่ถูกต้องตามที่เพิ่มไว้
GeoPdfLayer::generateViewportDictionary()	int $pageIndex	ปล่อย dictionary /Viewport พร้อม /BBox, /Name และ /Measure แบบอินไลน์	string	—	สตริงว่างเมื่อหน้าไม่มี registration หรือ registration ไม่ถูกต้อง
GeoPdfLayer::generateViewportArray()	int $pageIndex	ห่อ dictionary viewport ในวงเล็บเหลี่ยมเป็นค่าอาร์เรย์ /VP	string	—	สตริงว่างเมื่อไม่มี; ผู้เรียกจึงละ /VP สำหรับหน้านั้น
GeoPdfLayer::writeToPdfWriter()	BinaryBuffer $buffer, int $pageIndex	เขียน /VP พร้อมค่าอาร์เรย์และขึ้นบรรทัดใหม่ลงในบัฟเฟอร์	bool	—	true เมื่อมีการเขียนรายการ; ไม่ทำงานและ false ในกรณีอื่น

ลายเซ็นจุดเข้าใช้งาน

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

ข้อกำหนดด้านพฤติกรรม

การตรวจสอบและการจัดรูปแบบพิกัด

GeoCoordinate ตรวจสอบตอนสร้างและไม่เปลี่ยนแปลงค่า ละติจูดที่อยู่นอก [-90, 90] หรือลองจิจูดที่อยู่นอก [-180, 180] จะโยน InvalidArgumentException โดยระบุค่าที่ผิดพลาด toDms() แสดงทั้งสองแกนเป็นองศา ลิปดาที่เติมศูนย์ พิลิปดา และส่วนต่อท้ายซีกโลก toDecimal() แสดง latitude, longitude เป็นทศนิยมหกตำแหน่ง fromDms() รับอินพุต DMS ที่พิลิปดาเป็นตัวเลือกได้ ทำให้อักขระ prime, double-prime, เครื่องหมายองศา และอัญประกาศเชิงพิมพ์เป็นมาตรฐาน แปลงเป็นองศาทศนิยมแบบมีเครื่องหมาย และสร้างอินสแตนซ์ใหม่ ละติจูดใต้และลองจิจูดตะวันตกจะกลายเป็นค่าลบ

การแมป projection

แต่ละกรณีของ ProjectionType มีรหัส EPSG คงที่และป้ายกำกับหนึ่งค่า การแมปนี้เป็นตารางปิด ไม่ใช่รีจิสทรีของระบบอ้างอิงพิกัด

กรณี	ค่าสำรอง	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 ปล่อยรหัสโซน 1 โปรเจกต์ที่ต้องการโซน UTM อื่น หรือรหัส EPSG ใดๆ นอกตารางนี้ ควรใส่คำอธิบาย CRS ที่เชื่อถือได้ในสตริง datum เป็น Well Known Text

การปล่อย measure dictionary

GeoRegistration::toPdfMeasureDictionary() ปล่อย dictionary หลายบรรทัด: /Type /Measure, /Subtype /GEO, dictionary ระบบพิกัด /GCS, /GPTS, /LPTS และ /Bounds ตาม ISO 32000-2:2020 §12.10 (Table 269) พฤติกรรมที่เป็นรูปธรรม:

• /GCS ถูกปล่อยเป็น << /Type /PROJCS /EPSG <code> /WKT (<datum>) >> รหัส EPSG มาจากกรณี projection ค่า /WKT คือสตริง datum ตามที่ให้มาทุกประการ ค่าปริยายคือ WGS84
• /GPTS แสดงคู่ละติจูด-ลองจิจูดเป็นทศนิยมหกตำแหน่ง ตามลำดับจุดควบคุม
• /LPTS แสดงคู่ pdfX/pdfY เป็นทศนิยมหกตำแหน่ง ตามที่ให้มาทุกประการ ISO 32000-2:2020 Table 269 นิยามจุด LPTS ในหน่วยสี่เหลี่ยมจัตุรัส 2 มิติ การให้ค่าที่ทำให้เป็นมาตรฐานภายในหน่วยสี่เหลี่ยมจัตุรัสเป็นความรับผิดชอบของผู้เรียก
• /Bounds ถูกกำหนดตายตัวที่ [0 0 0 1 1 1 1 0] ซึ่งเป็นหน่วยสี่เหลี่ยมจัตุรัสเต็ม
• สตริง datum ถูก escape ก่อนแทรกเข้าไปในสตริงลิเทอรัล: แบ็กสแลช วงเล็บ และอักขระควบคุมทั่วไปจะกลายเป็น escape แบบแบ็กสแลชตาม ISO 32000-2:2020 §7.3.4.2 ดาตัมที่ผู้เรียกมีอิทธิพลไม่สามารถปิดสตริงลิเทอรัลหรือแทรกโทเคน PDF ดิบได้

การปล่อย viewport และหน้า

GeoPdfLayer เก็บ registration ตามลำดับการเพิ่ม โดยใช้ดัชนีหน้าแบบเริ่มที่ศูนย์เป็นคีย์ generateViewportDictionary() แก้ค่า registration แรกสำหรับหน้าที่ร้องขอ และคืนค่าสตริงว่างเมื่อไม่มี หรือเมื่อ isValid() เป็นเท็จ dictionary ที่สร้างขึ้นมี /Type /Viewport, /BBox ที่คำนวณจากพิกัด PDF ต่ำสุดและสูงสุดของจุดควบคุม, /Name ในรูปแบบ GeoViewport_Page<n> และ dictionary /Measure แบบอินไลน์ รายการ /Measure ของ viewport เป็นไปตาม ISO 32000-2:2020 §12.9 generateViewportArray() ห่อ dictionary ในวงเล็บเหลี่ยม สร้างค่า /VP ของหน้า: อาร์เรย์ของ viewport dictionary ตาม ISO 32000-2:2020 §7.7.3.3 (Table 31) writeToPdfWriter() เขียน /VP พร้อมค่าอาร์เรย์ลงใน BinaryBuffer ของ Core และรายงานว่ามีการเขียนอะไรหรือไม่ เพื่อให้การซีเรียลไลซ์หน้าละคีย์ได้อย่างสะอาด

กรณีขอบและโหมดความล้มเหลว

• ละติจูดหรือลองจิจูดที่อยู่นอกช่วงจะโยน InvalidArgumentException ตอนสร้าง; ไม่มีพิกัดที่ถูกต้องบางส่วนอยู่
• fromDms() โยนเมื่ออินพุตแจงไม่ได้ ค่าที่แจงได้จะผ่าน constructor ดังนั้นสตริงที่ถูกต้องทางไวยากรณ์แต่มีค่าที่อยู่นอกช่วงก็จะโยนเช่นกัน
• สัญกรณ์ DMS ไม่มี altitude; fromDms() ให้ altitude 0.0 เสมอ
• GeoRegistration ที่มีจุดควบคุมน้อยกว่าสองจุดจะรายงาน isValid() เป็นเท็จ แต่ toPdfMeasureDictionary() ก็ยังปล่อย dictionary พร้อมอาร์เรย์จุดที่สั้น ป้องกันการเรียกโดยตรงด้วย isValid() หรือส่งการปล่อยผ่าน GeoPdfLayer ซึ่งระงับ registration ที่ไม่ถูกต้อง
• registration ที่ซ้ำสำหรับดัชนีหน้าหนึ่งจะถูกเก็บทั้งหมดโดย getRegistrations(); การสร้าง viewport ใช้ตัวแรกที่เพิ่ม
• ดัชนีหน้าที่เป็นค่าลบจะโยน InvalidArgumentException; ดัชนีหน้าเริ่มที่ศูนย์
• จุดควบคุมที่มีค่า X หรือ Y ร่วมกันจะสร้าง /BBox ที่เสื่อมสภาพแบบกว้างศูนย์หรือสูงศูนย์ ให้จุดที่ครอบคลุมทั้งสองแกน
• เอาต์พุตทั้งหมดเป็นข้อความที่สร้างขึ้น ไม่มีการเขียนลงดิสก์หรือเครือข่าย และอินพุตที่เหมือนกันจะให้เอาต์พุตที่เหมือนกัน
• ไม่มีการดำเนินการเข้ารหัสลับเกิดขึ้นในโมดูลนี้ จึงไม่มีพฤติกรรมเฉพาะของโหมด FIPS

ความสอดคล้อง

ข้ออ้าง	มาตรฐาน	ข้อกำหนด
measure dictionary ถูกปล่อยด้วย subtype GEO พร้อมคู่ละติจูด-ลองจิจูด GPTS และค่า LPTS ที่จับคู่กัน	ISO 32000-2:2020	§12.10
viewport dictionary มีรายการ BBox, Name และ Measure	ISO 32000-2:2020	§12.9
ค่า VP ของหน้าถูกปล่อยเป็นอาร์เรย์ของ viewport dictionary	ISO 32000-2:2020	§7.7.3.3
การแทรกดาตัม escape อักขระพิเศษของสตริงลิเทอรัล	ISO 32000-2:2020	§7.3.4.2

ข้อกำหนดทั้งหมดเป็นการถอดความ; NextPDF ไม่ได้ทำซ้ำข้อความเชิงบรรทัดฐาน ข้อความเหล่านี้เป็นการระบุความสามารถ ไม่ใช่การรับรอง NextPDF ไม่ถือการรับรองใดและไม่มอบการรับรองใด รหัส EPSG เป็นค่าตัวแทนคงที่ต่อกรณี projection และรายการ /WKT มีสตริงดาตัมที่ให้มาแทนที่จะเป็นคำอธิบาย Well Known Text ที่สร้างขึ้น; ข้อความทั้งสองมีพื้นฐานจากผลิตภัณฑ์ ตรวจสอบเอาต์พุต GeoPDF ที่ปล่อยออกมาในตัวประมวลผล PDF เชิงโต้ตอบเป้าหมายก่อนพึ่งพาการวัดฝั่งโปรแกรมดู

บันทึกการพัฒนา

• มีให้ใช้ตั้งแต่ nextpdf/pro 1.9.0; ปัจจุบันอยู่ใน nextpdf/pro 3.1.0
• ตรวจสอบ isValid() ก่อนเรียก toPdfMeasureDictionary() โดยตรง; GeoPdfLayer ทำการตรวจสอบนี้ให้คุณ
• เมื่อผู้บริโภคปลายทางแจง /WKT ให้ส่งคำอธิบาย Well Known Text แบบเต็มเป็น datum; ค่าปริยาย WGS84 เป็นเพียงป้ายกำกับดาตัมเท่านั้น
• ทำให้อินพุต LPTS เป็นมาตรฐานภายในหน่วยสี่เหลี่ยมจัตุรัสก่อนสร้างจุดควบคุม เมื่อขอบเขต viewport แตกต่างจากค่าในพื้นที่ PDF ของคุณ
• ต้นทุนการปล่อยเป็นเชิงเส้นตามจำนวนจุดควบคุม; การค้นหาใน GeoPdfLayer เป็นเชิงเส้นตามจำนวน registration
• writeToPdfWriter() ผสานกับการซีเรียลไลซ์หน้าผ่าน NextPDF\Support\BinaryBuffer จาก Core

ขอบเขตการเผยแพร่

หน้านี้บันทึกเฉพาะพฤติกรรมที่สังเกตได้จากภายนอกและพื้นผิว API สาธารณะที่รองรับเท่านั้น เส้นทาง namespace ภายใน คลาสช่วยเหลือ ตารางกลไก ชื่อไฟล์ runbook และคำนำหน้าตั๋วอยู่นอกขอบเขต

ดูเพิ่มเติม

• Geo (ความสามารถ) — การติดตั้ง ภาพรวมเชิงแนวคิด และตัวอย่างเริ่มต้นอย่างรวดเร็ว
• Document — การอ้างอิงเชิงลึก — พื้นผิวการประกอบเอกสารและหน้า