Enterprise phiên bản

Common — 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 chuyên sâu cho namespace NextPDF\Enterprise\Common. Namespace này cung cấp một ký hiệu công khai duy nhất: value object BoundingBox. Đó là một hình chữ nhật bất biến, đã chuẩn hóa, dùng cho việc định vị không gian độc lập với độ phân giải trên một trang. Các bề mặt Enterprise Intelligence và Privacy tiêu thụ nó cho hình học ô bảng, vị trí thực thể, và vùng biên tập. Module này không thực hiện I/O, không nắm giữ nội dung tài liệu, và không đụng đến mật mã. Để có hướng dẫn quy trình làm việc, hãy đọc trang khả năng Common trước.

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

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

Bản thân primitive này không thực hiện kiểm soát cấp phép nào; việc kiểm soát diễn ra trên các bề mặt Enterprise tiêu thụ nó. Không có thành phần tương đương ở bậc Core hay bậc Pro của lớp này. Nó chỉ đi kèm trong gói nextpdf/enterprise và không nhân bản hay thay thế các kiểu hình học của Core.

Bề mặt Public API

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ú
`BoundingBox::__construct`	`float $x`, `float $y`, `float $width`, `float $height`	Xác thực mỗi giá trị theo `[0.0, 1.0]`, rồi xác thực cả hai tổng cạnh	`BoundingBox`	`InvalidArgumentException` khi một giá trị nằm ngoài khoảng hoặc một tổng cạnh vượt quá `1.0 + 1e-9`	Cả bốn giá trị trở thành thuộc tính `public readonly`
`BoundingBox::area`	không có	Nhân `width` với `height`	`float`	Không khai báo gì	Trả về `0.0` cho các hộp suy biến
`BoundingBox::contains`	`self $other`	Kiểm tra xem `$other` có nằm hoàn toàn bên trong hộp này không	`bool`	Không khai báo gì	Cạnh phải và cạnh dưới dung nạp `+1e-9`; cạnh trái và cạnh trên so sánh chính xác
`BoundingBox::overlaps`	`self $other`	Kiểm tra giao nhau hình chữ nhật chặt	`bool`	Không khai báo gì	Một toán hạng diện tích bằng không ở bất kỳ bên nào trả về `false`

Chữ ký điểm vào

final readonly class BoundingBox
{
    public function __construct(
        public float $x,
        public float $y,
        public float $width,
        public float $height,
    )

    public function area(): float

    public function contains(self $other): bool

    public function overlaps(self $other): bool
}

Hợp đồng hành vi

Mô hình tọa độ

Cả bốn giá trị là các phân số của kích thước trang, được chuẩn hóa về khoảng [0.0, 1.0].
x xác định cạnh trái và y xác định cạnh trên của hộp. x + width và y + height giới hạn cạnh phải và cạnh dưới.
Việc chuẩn hóa làm cho mọi thao tác độc lập với độ phân giải. Cùng một hộp định địa chỉ cùng một vùng trang ở bất kỳ kích thước render hay DPI nào.

Khởi tạo

Constructor là điểm xác thực duy nhất. Một tọa độ nằm ngoài [0.0, 1.0] phát sinh InvalidArgumentException; thông điệp nêu tên thành phần vi phạm và giá trị nhận được.
Một tổng cạnh vượt quá 1.0 + 1e-9 phát sinh InvalidArgumentException; thông điệp báo cáo cả hai toán hạng và tổng của chúng. Dung sai 1e-9 hấp thụ việc làm tròn dấu phẩy động từ số học chuẩn hóa ở phía thượng nguồn.
Một instance đã khởi tạo là bất biến. Lớp này là final readonly, nên việc ghi thuộc tính sẽ thất bại với một Error của PHP và lớp không thể được kế thừa.

Vị từ

area() trả về width * height. Đó là một phép tính thuần túy không có tác dụng phụ.
contains() trả về true khi hộp kia nằm hoàn toàn bên trong hộp này. Các so sánh cạnh phải và cạnh dưới mang dung sai +1e-9; các so sánh cạnh trái và cạnh trên là chính xác. Mọi hộp đều chứa chính nó, và một hộp diện tích bằng không có thể được chứa.
overlaps() trả về true khi có giao nhau hình chữ nhật chặt. Cả bốn so sánh cạnh đều chặt, không có dung sai. Nếu một trong hai toán hạng có diện tích bằng không, kết quả là false.
Do đó việc chứa không hàm ý chồng lấn: một hộp suy biến bên trong một hộp khác thì được chứa nhưng không bao giờ chồng lấn.
Không phương thức nào thực hiện I/O, lưu trữ bền, truy cập mạng, hay ghi log, và không phương thức nào nắm giữ nội dung tài liệu hay dữ liệu cá nhân. Không có tài nguyên do người vận hành sở hữu cho bề mặt này.

Bên tiêu thụ

Các module Enterprise dùng chung primitive này thay vì định nghĩa hình học riêng cho từng module. Trong Intelligence, đầu ra của TableExtractor mang nó trên các giá trị TableCell và KeyValuePair. Trong Privacy, PiiEntity, RedactionFinding, và ZoneRedaction định vị nội dung bằng nó, và RedactionEngine tiêu thụ các vị trí đó. Các hợp đồng của những bề mặt đó được tài liệu hóa trên các trang tham chiếu riêng của chúng.

Trường hợp biên và chế độ thất bại

Thành phần ngoài khoảng. Bất kỳ giá trị nào trong bốn giá trị nhỏ hơn 0.0 hoặc lớn hơn 1.0 đều phát sinh InvalidArgumentException khi khởi tạo. INF và -INF bị từ chối bởi cùng bộ bảo vệ đó.
Tràn tổng cạnh. x + width hoặc y + height vượt quá 1.0 + 1e-9 phát sinh InvalidArgumentException. Một tổng nằm trong dung sai 1e-9 sẽ khởi tạo thành công.
Đầu vào NAN. Bộ bảo vệ khoảng dùng các so sánh có thứ tự, và mọi so sánh có thứ tự với NAN đều là false, nên một thành phần NAN không bị từ chối. Một instance như vậy báo cáo một area NAN và trả về false từ cả hai vị từ. Hãy làm sạch các nguồn số thực ở thượng nguồn trước khi khởi tạo.
Hộp diện tích bằng không. Một hộp có chiều rộng bằng không hoặc chiều cao bằng không không bao giờ chồng lấn bất cứ thứ gì, kể cả chính nó. Nó vẫn có thể được chứa bởi một hộp không suy biến. Hãy tính đến sự bất đối xứng này trong logic giao nhau.
Hộp chạm cạnh. Hai hộp chỉ chia sẻ một cạnh hoặc một góc thì không chồng lấn; phép kiểm tra giao nhau là chặt.
Bất đối xứng dung sai của việc chứa. Một hộp bên trong có cạnh trái hoặc cạnh trên nằm ngoài hộp bên ngoài dù chỉ một lượng bất kỳ đều thất bại phép chứa; chỉ cạnh phải và cạnh dưới nhận được khoản dung sai 1e-9.
Chế độ FIPS. Module này không thực hiện thao tác mật mã nào; chế độ FIPS không làm thay đổi hành vi của nó.

Phù hợp tiêu chuẩn

Module này không hiện thực tiêu chuẩn quy phạm nào và không đưa ra tuyên bố phù hợp tiêu chuẩn nào. Nó là một primitive hình học đã được xác thực. Ngữ nghĩa không gian tọa độ PDF cho các tính năng tiêu thụ nó được tài liệu hóa trên các trang của những tính năng đó. NextPDF không nắm giữ chứng nhận nào và không cấp chứng nhận nào; hỗ trợ không phải là phù hợp tiêu chuẩn, và phù hợp tiêu chuẩn không phải là chứng nhận. Không có hạn chế kiểm soát xuất khẩu nào áp dụng cho bề mặt này, và tài liệu tham chiếu này không phải là một ý kiến pháp lý.

Ghi chú phát triển

Lớp này có sẵn từ nextpdf/enterprise 2.2.0; bề mặt công khai của nó không thay đổi ở 3.1.0.
Hãy chuyển đổi tọa độ không gian trang tuyệt đối sang các phân số tương đối với trang trước khi khởi tạo. Lớp này xác thực khoảng, không phải ngữ nghĩa; nó không thể phát hiện một vùng hợp lý-nhưng-sai.
Các instance là value object thuần túy và rẻ để khởi tạo. Đừng gộp bể hay cache chúng.
Hai instance với tọa độ giống hệt nhau so sánh bằng nhau dưới đẳng thức lỏng (==); đồng nhất chặt (===) phân biệt chúng. Hãy ưu tiên so sánh tọa độ trong kiểm thử.
Đối với hình học ngoài các vị từ boolean, hãy suy ra các cạnh từ các thuộc tính công khai: cạnh phải x + width, cạnh dưới y + height.
Khi kiểm thử các ranh giới dung sai, hãy dò cả hai phía của 1e-9 trên bộ bảo vệ tổng cạnh và trên các so sánh phải/dưới của việc chứa.

Ranh giới xuất bản

Trang này chỉ tài liệu hóa hành vi quan sát được từ bên ngoài và bề mặt public API đượ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 đều nằm ngoài phạm vi.