Geo — Tài liệu tham chiếu chuyên sâu

Tổng quan nhanh

Trang này là tài liệu tham chiếu ở cấp hợp đồng cho module Geo của NextPDF Pro. Bề mặt gồm bốn đối tượng giá trị bất biến — GeoCoordinate, GeoControlPoint, ProjectionType, và GeoRegistration — cộng với GeoPdfLayer, lớp liên kết các đăng ký với chỉ số trang và phát ra đầu ra viewport. Module tạo ra văn bản từ điển PDF: một từ điển /Measure với /Subtype /GEO, một từ điển /Viewport, và giá trị mảng /VP ở cấp trang. Việc tạo là quá trình lắp ráp chuỗi mang tính tất định: không gọi mạng, không truy cập hệ thống tệp, không có yếu tố ngẫu nhiên. Trang này nêu API công khai, hợp đồng hành vi có thể quan sát được, và các chế độ lỗi.

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

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

Không có cờ giấy phép theo từng tính năng nào kiểm soát module này. Các class Geo khả dụng bất cứ khi nào nextpdf/pro được cài đặt.

Bề mặt API công khai

Ký hiệu	Tham số	Hành vi mặc định	Trả về	Ném hoặc thất bại với	Ghi chú
GeoCoordinate	constructor: float $latitude, float $longitude, float $altitude = 0.0	Xác thực latitude trong [-90, 90] và longitude trong [-180, 180]	—	InvalidArgumentException khi một trong hai giá trị nằm ngoài khoảng	final readonly; altitude là số mét trên mực nước biển và không được kiểm tra khoảng
GeoCoordinate::toDms()	không có	Định dạng thành degrees-minutes-seconds với hậu tố N/S và E/W	string	—	Giây gần bằng không hiển thị là 00; ngược lại hai chữ số thập phân với các số 0 ở cuối được cắt bỏ
GeoCoordinate::toDecimal()	không có	Định dạng latitude và longitude tới sáu chữ số thập phân, phân tách bằng dấu phẩy	string	—	Altitude không được bao gồm
GeoCoordinate::fromDms()	string $dms	Phân tích một chuỗi DMS; giây là tùy chọn; các glyph độ và dấu nháy kiểu chữ được chuẩn hóa	self	InvalidArgumentException khi chuỗi không phân tích được, hoặc khi các giá trị phân tích không qua được kiểm tra khoảng của constructor	Static factory; các chữ cái bán cầu không phân biệt hoa thường; altitude mặc định là 0.0
GeoControlPoint	constructor: float $pdfX, float $pdfY, GeoCoordinate $geo	Ghép một điểm không gian người dùng PDF (tính bằng point) với một tọa độ địa lý	—	—	final readonly; tọa độ PDF không được xác thực
ProjectionType	enum backed bằng string, 4 case	Các case: Geographic, UTM, TransverseMercator, LambertConformal	giá trị backing GEO, UTM, TM, LCC	—	Xem bảng ánh xạ phép chiếu bên dưới
ProjectionType::epsgCode()	không có	Ánh xạ case tới một mã EPSG cố định	int	—	4326, 32601, 2154, hoặc 3347
ProjectionType::label()	không có	Tên phép chiếu dễ đọc	string	—	Ví dụ WGS 84 Geographic
GeoRegistration	constructor: array $controlPoints, ProjectionType $projection, string $datum = 'WGS84'	Giữ các điểm khống chế, phép chiếu, và datum trắc địa	—	—	final readonly; số lượng điểm khống chế không được xác thực khi khởi tạo
GeoRegistration::isValid()	không có	Yêu cầu tối thiểu hai điểm khống chế	bool	—	Hai điểm là mức tối thiểu cho một ánh xạ affine
GeoRegistration::toPdfMeasureDictionary()	không có	Phát ra một từ điển /Measure với /Subtype /GEO, /GCS, /GPTS, /LPTS, và /Bounds	string	—	Không kiểm tra isValid(); hãy bảo vệ lời gọi hoặc định tuyến qua GeoPdfLayer
GeoPdfLayer::addRegistration()	int $pageIndex, GeoRegistration $registration	Thêm một đăng ký cho một chỉ số trang bắt đầu từ 0	self	InvalidArgumentException khi $pageIndex âm	Fluent; đăng ký đầu tiên được thêm cho một trang sẽ thắng tại thời điểm tạo
GeoPdfLayer::getRegistrations()	không có	Trả về tất cả đăng ký theo thứ tự chèn	list<array{pageIndex: int, registration: GeoRegistration}>	—	Bao gồm cả các đăng ký trùng lặp và không hợp lệ đúng như khi được thêm
GeoPdfLayer::generateViewportDictionary()	int $pageIndex	Phát ra một từ điển /Viewport với /BBox, /Name, và một /Measure nội tuyến	string	—	Chuỗi rỗng khi trang không có đăng ký hoặc đăng ký không hợp lệ
GeoPdfLayer::generateViewportArray()	int $pageIndex	Bọc từ điển viewport trong dấu ngoặc vuông thành literal mảng /VP	string	—	Chuỗi rỗng khi vắng mặt; khi đó caller bỏ qua /VP cho trang đó
GeoPdfLayer::writeToPdfWriter()	BinaryBuffer $buffer, int $pageIndex	Ghi /VP cùng literal mảng và một ký tự xuống dòng vào buffer	bool	—	true khi một mục đã được ghi; không làm gì và false trong trường hợp khác

Chữ ký điểm vào

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

Hợp đồng hành vi

Xác thực và định dạng tọa độ

GeoCoordinate xác thực khi khởi tạo và không bao giờ biến đổi. Latitude ngoài [-90, 90] hoặc longitude ngoài [-180, 180] sẽ ném InvalidArgumentException nêu tên giá trị vi phạm. toDms() hiển thị cả hai trục dưới dạng độ, phút có đệm số 0, giây, và một hậu tố bán cầu. toDecimal() hiển thị latitude, longitude với sáu chữ số thập phân. fromDms() chấp nhận đầu vào DMS có giây tùy chọn, chuẩn hóa các glyph prime, double-prime, dấu độ, và dấu nháy thông minh, chuyển đổi thành độ thập phân có dấu, và khởi tạo một instance mới. Vĩ độ nam và kinh độ tây trở thành giá trị âm.

Ánh xạ phép chiếu

Mỗi case ProjectionType mang một mã EPSG và nhãn cố định. Ánh xạ này là một bảng đóng, không phải một registry hệ tham chiếu tọa độ.

Case	Giá trị 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

Case UTM phát ra mã zone 1. Các dự án cần một UTM zone khác, hoặc bất kỳ mã EPSG nào ngoài bảng này, nên mang mô tả CRS có thẩm quyền trong chuỗi datum dưới dạng Well Known Text.

Phát ra từ điển measure

GeoRegistration::toPdfMeasureDictionary() phát ra một từ điển nhiều dòng: /Type /Measure, /Subtype /GEO, một từ điển hệ tọa độ /GCS, /GPTS, /LPTS, và /Bounds, theo ISO 32000-2:2020 §12.10 (Table 269). Hành vi cụ thể:

• /GCS được phát ra dưới dạng << /Type /PROJCS /EPSG <code> /WKT (<datum>) >>. Mã EPSG đến từ case phép chiếu. Giá trị /WKT là chuỗi datum đúng như được cung cấp; mặc định là WGS84.
• /GPTS liệt kê các cặp latitude-longitude với sáu chữ số thập phân, theo thứ tự điểm khống chế.
• /LPTS liệt kê các cặp pdfX/pdfY với sáu chữ số thập phân, đúng như được cung cấp. ISO 32000-2:2020 Table 269 định nghĩa các điểm LPTS trong một hình vuông đơn vị 2D; việc cung cấp các giá trị đã chuẩn hóa theo hình vuông đơn vị là trách nhiệm của caller.
• /Bounds được cố định ở [0 0 0 1 1 1 1 0], hình vuông đơn vị đầy đủ.
• Chuỗi datum được escape trước khi nội suy vào literal string: dấu gạch chéo ngược, dấu ngoặc đơn, và các ký tự điều khiển thông dụng trở thành các escape gạch chéo ngược tương ứng theo ISO 32000-2:2020 §7.3.4.2. Một datum chịu ảnh hưởng của caller không thể kết thúc literal string hoặc chèn các token PDF thô.

Phát ra viewport và trang

GeoPdfLayer giữ các đăng ký theo thứ tự chèn, đánh khóa bằng chỉ số trang bắt đầu từ 0. generateViewportDictionary() phân giải đăng ký đầu tiên cho trang được yêu cầu và trả về chuỗi rỗng khi không tồn tại đăng ký nào hoặc khi isValid() là false. Một từ điển được tạo ra mang /Type /Viewport, một /BBox được tính từ tọa độ PDF nhỏ nhất và lớn nhất của các điểm khống chế, một /Name theo dạng GeoViewport_Page<n>, và từ điển /Measure nội tuyến. Mục /Measure của viewport tuân theo ISO 32000-2:2020 §12.9. generateViewportArray() bọc từ điển trong dấu ngoặc vuông, tạo ra giá trị /VP của trang: một mảng các từ điển viewport theo ISO 32000-2:2020 §7.7.3.3 (Table 31). writeToPdfWriter() ghi /VP cùng literal mảng vào một BinaryBuffer của Core và báo cáo liệu có gì đã được ghi hay không, để việc tuần tự hóa trang có thể bỏ qua khóa một cách gọn gàng.

Trường hợp ngoại lệ & chế độ lỗi

• Latitude hoặc longitude ngoài khoảng sẽ ném InvalidArgumentException khi khởi tạo; không tồn tại tọa độ hợp lệ một phần.
• fromDms() ném khi đầu vào không phân tích được. Các giá trị đã phân tích đi qua constructor, nên một chuỗi hợp lệ về cú pháp nhưng có giá trị ngoài khoảng cũng sẽ ném.
• Ký hiệu DMS không mang altitude; fromDms() luôn cho altitude 0.0.
• Một GeoRegistration với ít hơn hai điểm khống chế báo cáo isValid() là false, nhưng toPdfMeasureDictionary() vẫn phát ra một từ điển với các mảng điểm ngắn. Hãy bảo vệ các lời gọi trực tiếp bằng isValid(), hoặc định tuyến việc phát ra qua GeoPdfLayer, lớp sẽ chặn các đăng ký không hợp lệ.
• Các đăng ký trùng lặp cho một chỉ số trang đều được getRegistrations() giữ lại; việc tạo viewport dùng đăng ký được thêm đầu tiên.
• Một chỉ số trang âm sẽ ném InvalidArgumentException; chỉ số trang bắt đầu từ 0.
• Các điểm khống chế chia sẻ chung một giá trị X hoặc Y sẽ tạo ra một /BBox suy biến có chiều rộng bằng không hoặc chiều cao bằng không. Hãy cung cấp các điểm trải trên cả hai trục.
• Toàn bộ đầu ra là văn bản được tạo ra. Không có gì được ghi vào đĩa hoặc mạng, và đầu vào giống nhau tạo ra đầu ra giống nhau.
• Không có thao tác mã hóa nào xảy ra trong module này, nên không có hành vi đặc thù cho chế độ FIPS.

Tính phù hợp

Tuyên bố	Tiêu chuẩn	Điều khoản
Từ điển measure được phát ra với subtype GEO, cùng các cặp latitude-longitude GPTS và các giá trị LPTS được ghép cặp.	ISO 32000-2:2020	§12.10
Từ điển viewport mang các mục BBox, Name, và Measure.	ISO 32000-2:2020	§12.9
Giá trị VP của trang được phát ra dưới dạng một mảng các từ điển viewport.	ISO 32000-2:2020	§7.7.3.3
Việc nội suy datum escape các siêu ký tự literal-string.	ISO 32000-2:2020	§7.3.4.2

Mọi điều khoản đều được diễn giải lại; NextPDF không tái tạo văn bản quy phạm. Đây là các tuyên bố về năng lực, không phải chứng nhận. NextPDF không nắm giữ chứng nhận nào và không cấp chứng nhận nào. Các mã EPSG là những giá trị đại diện cố định theo từng case phép chiếu, và mục /WKT mang chuỗi datum được cung cấp thay vì một mô tả Well Known Text được tạo ra; cả hai tuyên bố đều dựa trên sản phẩm. Hãy xác thực đầu ra GeoPDF được phát ra trong các bộ xử lý PDF tương tác mục tiêu trước khi dựa vào phép đo phía trình xem.

Ghi chú phát triển

• Khả dụng từ nextpdf/pro 1.9.0; hiện tại ở nextpdf/pro 3.1.0.
• Kiểm tra isValid() trước khi gọi trực tiếp toPdfMeasureDictionary(); GeoPdfLayer thực hiện kiểm tra này giúp bạn.
• Khi các consumer phía sau phân tích /WKT, hãy truyền một mô tả Well Known Text đầy đủ làm datum; mặc định WGS84 chỉ là một nhãn datum.
• Chuẩn hóa các đầu vào LPTS về hình vuông đơn vị trước khi khởi tạo các điểm khống chế khi các bound viewport khác với các giá trị không gian PDF của bạn.
• Chi phí phát ra tuyến tính theo số lượng điểm khống chế; việc tra cứu trong GeoPdfLayer tuyến tính theo số lượng đăng ký.
• writeToPdfWriter() tích hợp với việc tuần tự hóa trang thông qua NextPDF\Support\BinaryBuffer từ Core.

Ranh giới xuất bản

Trang này chỉ ghi lại 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ộ, class 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 (năng lực) — cài đặt, tổng quan khái niệm, và các mẫu quick-start.
• Document — Tài liệu tham chiếu chuyên sâu — bề mặt soạn thảo document và page.