Geo

Tổng quan nhanh

NextPDF Pro ánh xạ các tọa độ trang PDF sang tọa độ địa lý và tạo ra một PDF measure dictionary với subtype GEO, để một trình xem có thể báo cáo vị trí thực tế từ một điểm trên trang.

Tính khả dụng & cấp phép

Khả năng này có trong NextPDF Pro (nextpdf/pro) và được kích hoạt bằng một envelope giấy phép bậc Pro. Một triển khai không có quyền đó sẽ không nạp các lớp của khả năng này. So sánh các phiên bản và nhận giấy phép.

Geo không có cờ giấy phép riêng theo từng tính năng; envelope bậc Pro kích hoạt nó trực tiếp.

Cài đặt

composer require nextpdf/pro:^3

Tổng quan khái niệm

Một PDF không gian địa lý mang một measure dictionary, được mô tả trong ISO 32000-2 §12.8.2, gắn các điểm device-space với một hệ tham chiếu tọa độ địa lý. NextPDF Pro dựng dữ liệu đó từ các đối tượng giá trị bất biến:

• GeoCoordinate — một bộ ba vĩ độ/kinh độ/độ cao. Việc khởi tạo kiểm định vĩ độ trong [-90, 90] và kinh độ trong [-180, 180], và cung cấp định dạng chuỗi độ-phút-giây cùng thập phân.
• GeoControlPoint — một sự ghép cặp giữa một điểm PDF-space với một GeoCoordinate.
• ProjectionType — một enum các phép chiếu thông dụng (geographic, UTM, transverse Mercator, Lambert conformal conic), mỗi phép được ánh xạ tới một mã EPSG.
• GeoRegistration — các điểm kiểm soát cộng với phép chiếu và geodetic datum (mặc định WGS84). isValid() yêu cầu ít nhất hai điểm kiểm soát cho một phép biến đổi affine tối thiểu; toPdfMeasureDictionary() phát ra dictionary /Measure với /Subtype /GEO và các mảng điểm kiểm soát.

Vì sao nó hoạt động theo cách này

NextPDF dựng measure dictionary từ các đối tượng giá trị bất biến đã được kiểm định, chứ không phải từ một dictionary thô do bên gọi cung cấp. GeoCoordinate từ chối một vĩ độ hoặc kinh độ ngoài phạm vi ngay khi khởi tạo. GeoRegistration::isValid() từ chối ít hơn hai điểm kiểm soát, nên một đăng ký sai định dạng sẽ thất bại sớm thay vì phát ra một dictionary /GEO suy giảm. Các phép chiếu phân giải thành các mã EPSG chuẩn thông qua ProjectionType, giữ cho hệ tham chiếu tọa độ được tường minh thay vì phỏng đoán. Datum mặc định là WGS84 nhưng vẫn là một trường có tên, nên một hệ tham chiếu khác mặc định là một lựa chọn có chủ đích. Tư thế fail-closed này quan trọng vì một tham chiếu địa lý sai còn tệ hơn không có; một trình xem sẽ tự tin báo cáo một vị trí thực tế sai lệch. Bối cảnh thiết kế: Một API từ chối phỏng đoán.

Bề mặt API

Lớp	Trách nhiệm
GeoCoordinate	Vĩ độ/kinh độ/độ cao đã kiểm định với định dạng.
GeoControlPoint	Sự ghép cặp điểm PDF ↔ điểm địa lý.
ProjectionType	Enum phép chiếu với các mã EPSG.
GeoRegistration	Dựng dictionary /Measure /GEO.

Mẫu mã — Khởi đầu nhanh

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

Mẫu mã — Production

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

Trường hợp biên & lưu ý

• Việc khởi tạo GeoCoordinate từ chối một vĩ độ hoặc kinh độ ngoài phạm vi.
• Ít hơn hai điểm kiểm soát tạo ra một đăng ký không hợp lệ.
• Datum mặc định là WGS84; hãy đặt nó tường minh cho các hệ tham chiếu khác.

Hiệu năng

Việc tạo dictionary là tuyến tính theo số lượng điểm kiểm soát.

Ghi chú về bảo mật

Đầu vào của Geo là dữ liệu tọa độ số. Hãy kiểm định các điểm kiểm soát có nguồn từ đầu vào không tin cậy trước khi đăng ký.

Sự phù hợp tiêu chuẩn

Hành vi	Tham chiếu	Trạng thái
Measure dictionary không gian địa lý (subtype GEO)	ISO 32000-2 §12.8.2	Đồng bộ (diễn đạt lại)

Hợp đồng hành vi

• GeoCoordinate kiểm định vĩ độ trong [-90, 90] và kinh độ trong [-180, 180] tại thời điểm khởi tạo và cung cấp định dạng chuỗi DMS và thập phân.
• GeoControlPoint ghép cặp một điểm PDF-space với một GeoCoordinate.
• GeoRegistration mang các điểm kiểm soát cộng với một ProjectionType (được ánh xạ tới một mã EPSG) và một geodetic datum mặc định là WGS84. isValid() yêu cầu ít nhất hai điểm kiểm soát; toPdfMeasureDictionary() phát ra một dictionary /Measure với /Subtype /GEO và các mảng điểm kiểm soát.
• Các tọa độ ngoài phạm vi hoặc ít hơn hai điểm kiểm soát tạo ra một đăng ký không hợp lệ thay vì đầu ra suy giảm âm thầm.

Ghi chú ranh giới Enterprise

Enterprise không thay đổi hành vi của Geo. Enterprise bổ sung các tính năng bậc cao hơn được ghi tài liệu riêng; chúng không bắt buộc để tạo một measure dictionary GeoPDF.

Phương án dự phòng / thay thế trong Core

Không có tương đương trong Core cho việc tạo measure-dictionary GeoPDF. Đây là một bổ sung của Pro.

Ranh giới công bố

Trang này chỉ ghi tài liệu về hành vi có thể quan sát từ bên ngoài và bề mặt API công khai được hỗ trợ. Các đường dẫn namespace nội bộ, lớp trợ giúp, bảng cơ chế, tên tệp runbook và tiền tố ticket nằm ngoài phạm vi.

Xem thêm

• Geo — Tham chiếu sâu — tham chiếu đầy đủ về lớp và phương thức.
• Document — lắp ráp trang và tài liệu.
• Chú thích của Core.