Geo

โดยสรุป

NextPDF Pro แมปพิกัดหน้า PDF ให้เป็นพิกัดภูมิศาสตร์และสร้างพจนานุกรม measure ของ PDF ที่มี subtype GEO เพื่อให้ตัวแสดงผลรายงานตำแหน่งในโลกจริงจากจุดบนหน้าได้

ความพร้อมใช้งานและการให้สิทธิ์

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

Geo ไม่มีแฟล็กใบอนุญาตแยกต่อฟีเจอร์ ซองระดับ Pro เปิดใช้งานให้โดยตรง

การติดตั้ง

composer require nextpdf/pro:^3

ภาพรวมเชิงแนวคิด

PDF เชิงภูมิสารสนเทศนำพาพจนานุกรม measure ที่อธิบายไว้ใน ISO 32000-2 §12.8.2 ซึ่งผูกจุดในพื้นที่อุปกรณ์กับระบบอ้างอิงพิกัดภูมิศาสตร์ NextPDF Pro สร้างข้อมูลนั้นจากออบเจ็กต์ค่าที่ไม่เปลี่ยนแปลง:

• GeoCoordinate ทริปเปิลละติจูด/ลองจิจูด/ระดับความสูง การสร้างตรวจสอบละติจูดภายใน [-90, 90] และลองจิจูดภายใน [-180, 180] และมีการจัดรูปแบบสตริงแบบองศา-ลิปดา-พิลิปดาและทศนิยม
• GeoControlPoint การจับคู่จุดในพื้นที่ PDF กับ GeoCoordinate
• ProjectionType enum ของการฉายที่ใช้กันทั่วไป (geographic, UTM, transverse Mercator, Lambert conformal conic) แต่ละแบบแมปกับรหัส EPSG
• GeoRegistration จุดควบคุมบวกการฉายและ datum เชิงภูมิมาตร (ค่าเริ่มต้น WGS84) isValid() ต้องการจุดควบคุมอย่างน้อยสองจุดสำหรับการแปลงแบบ affine ขั้นต่ำ toPdfMeasureDictionary() ปล่อยพจนานุกรม /Measure ที่มี /Subtype /GEO และอาร์เรย์จุดควบคุม

เหตุใดจึงทำงานเช่นนี้

NextPDF สร้างพจนานุกรม measure จากออบเจ็กต์ค่าที่ตรวจสอบแล้วและไม่เปลี่ยนแปลง ไม่ใช่จากพจนานุกรมดิบที่ผู้เรียกส่งมา GeoCoordinate ปฏิเสธละติจูดหรือลองจิจูดที่อยู่นอกช่วง ณ การสร้าง GeoRegistration::isValid() ปฏิเสธจุดควบคุมที่น้อยกว่าสองจุด ดังนั้นการลงทะเบียนที่ผิดรูปจึงล้มเหลวอย่างรวดเร็วแทนที่จะปล่อยพจนานุกรม /GEO ที่เสื่อมคุณภาพ การฉายถูกแปลงไปเป็นรหัส EPSG มาตรฐานผ่าน ProjectionType ซึ่งทำให้ระบบอ้างอิงพิกัดชัดเจนแทนที่จะเดา datum ตั้งค่าเริ่มต้นเป็น WGS84 แต่ยังคงเป็นฟิลด์ที่มีชื่อ ดังนั้นระบบอ้างอิงที่ไม่ใช่ค่าเริ่มต้นจึงเป็นทางเลือกโดยเจตนา ท่าทีแบบ fail-closed นี้สำคัญเพราะการอ้างอิงภูมิศาสตร์ที่ผิดนั้นแย่ยิ่งกว่าไม่มีเลย ตัวแสดงผลจะรายงานตำแหน่งในโลกจริงที่ผิดพลาดอย่างมั่นใจ ภูมิหลังการออกแบบ: API ที่ปฏิเสธการเดา

พื้นผิว API

Class	Responsibility
GeoCoordinate	lat/lon/altitude ที่ตรวจสอบแล้วพร้อมการจัดรูปแบบ
GeoControlPoint	การจับคู่จุด PDF ↔ จุดภูมิศาสตร์
ProjectionType	enum การฉายพร้อมรหัส EPSG
GeoRegistration	สร้างพจนานุกรม /Measure /GEO

ตัวอย่างโค้ด — เริ่มต้นอย่างรวดเร็ว

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

ตัวอย่างโค้ด — สำหรับใช้งานจริง

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

กรณีขอบและข้อควรระวัง

• การสร้าง GeoCoordinate ปฏิเสธละติจูดหรือลองจิจูดที่อยู่นอกช่วง
• จุดควบคุมน้อยกว่าสองจุดจะให้การลงทะเบียนที่ไม่ถูกต้อง
• datum เริ่มต้นคือ WGS84 ให้กำหนดอย่างชัดเจนสำหรับระบบอ้างอิงอื่น

ประสิทธิภาพ

การสร้างพจนานุกรมเป็นเชิงเส้นตามจำนวนจุดควบคุม

บันทึกด้านความปลอดภัย

อินพุต Geo เป็นข้อมูลพิกัดตัวเลข จงตรวจสอบจุดควบคุมที่มาจากอินพุตที่ไม่น่าเชื่อถือก่อนการลงทะเบียน

ความสอดคล้องกับมาตรฐาน

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

สัญญาพฤติกรรม

• GeoCoordinate ตรวจสอบละติจูดภายใน [-90, 90] และลองจิจูดภายใน [-180, 180] ณ การสร้าง และมีการจัดรูปแบบสตริงแบบ DMS และทศนิยม
• GeoControlPoint จับคู่จุดในพื้นที่ PDF กับ GeoCoordinate
• GeoRegistration นำพาจุดควบคุมบวก ProjectionType (แมปกับรหัส EPSG) และ datum เชิงภูมิมาตรที่ตั้งค่าเริ่มต้นเป็น WGS84 isValid() ต้องการจุดควบคุมอย่างน้อยสองจุด toPdfMeasureDictionary() ปล่อยพจนานุกรม /Measure ที่มี /Subtype /GEO และอาร์เรย์จุดควบคุม
• พิกัดที่อยู่นอกช่วงหรือจุดควบคุมน้อยกว่าสองจุดจะให้การลงทะเบียนที่ไม่ถูกต้องแทนที่จะเป็นเอาต์พุตที่เสื่อมคุณภาพอย่างเงียบ ๆ

บันทึกขอบเขตของ Enterprise

Enterprise ไม่เปลี่ยนพฤติกรรมของ Geo Enterprise เพิ่มฟีเจอร์ระดับสูงขึ้นที่บันทึกแยกต่างหาก โดยไม่จำเป็นสำหรับการสร้างพจนานุกรม measure ของ GeoPDF

ทางสำรอง / ทางเลือกของ Core

ไม่มีสิ่งเทียบเท่าใน Core สำหรับการสร้างพจนานุกรม measure ของ GeoPDF นี่เป็นการเพิ่มเติมของ Pro

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

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

ดูเพิ่มเติม

• Geo — Deep Reference — การอ้างอิงคลาสและเมธอดฉบับเต็ม
• Document — การประกอบหน้าและเอกสาร
• Core annotations