Filter — 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 NextPDF Pro Filter, namespace NextPDF\Pro\Filter. Bề mặt gồm hai lớp. DecodeParms phân tích một mảnh từ điển PDF /DecodeParms thành một value object bất biến, đã kiểm tra biên. PngPredictor đảo ngược họ PNG predictor (các tag 10-15) trên các byte stream đã được FlateDecode. Module này phục vụ các trình trích xuất Pro Diff và Classifier. Nó không phải là một framework lọc stream tổng quát. 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 đã định kiểu. Hướng dẫn sử dụng và ví dụ mã nằm trên trang năng lực Filter.

Khả dụng & cấp phép

Năng lực này được cung cấp trong NextPDF Pro (nextpdf/pro) và kích hoạt bằng một license envelope bậc Pro. Một triển khai không có quyền đó sẽ không nạp các lớp 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ờ năng lực lúc chạy nào kiểm soát module này. Các lớp Filter 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ú
DecodeParms	constructor: int $predictor = 1, int $columns = 1, int $colors = 1, int $bitsPerComponent = 8	Các mặc định biểu thị “không predictor”	—	—	final readonly; cả bốn thuộc tính đều public và bất biến
DecodeParms::fromDictionary()	string $raw — văn bản từ điển thô, phần thân đối tượng bao quanh được chấp nhận	Các khóa vắng mặt giữ giá trị mặc định; việc so khớp bỏ qua khoảng trắng	self	InvalidArgumentException	Điểm nghẽn lúc phân tích; các giới hạn được liệt kê trong hợp đồng hành vi
DecodeParms::isPngPredictor()	không có	Vị từ thuần túy; không I/O	bool — true cho predictor 10-15	—	Rẽ nhánh theo giá trị này trước khi gọi bộ đảo-lọc
PngPredictor	—	Không trạng thái	—	—	final; điểm vào duy nhất là hàm static inverse()
PngPredictor::inverse()	string $raw, int $columns, int $colors, int $bitsPerComponent, int $predictor	Đảo-lọc từng hàng theo tag của mỗi hàng; đầu vào rỗng trả về chuỗi rỗng	string — payload đã dựng lại với các filter tag đã loại bỏ	InvalidArgumentException	Chỉ chấp nhận predictor 10-15; TIFF predictor nằm ngoài phạm vi

Chữ ký điểm vào

public function __construct(
    public int $predictor = 1,
    public int $columns = 1,
    public int $colors = 1,
    public int $bitsPerComponent = 8,
) {}

public static function fromDictionary(string $raw): self

public function isPngPredictor(): bool

public static function inverse(
    string $raw,
    int $columns,
    int $colors,
    int $bitsPerComponent,
    int $predictor,
): string

Hợp đồng hành vi

Phân tích /DecodeParms

DecodeParms::fromDictionary() so khớp bốn khóa được nhận diện dưới dạng số nguyên trong văn bản từ điển thô: /Predictor, /Columns, /Colors, và /BitsPerComponent. Đây là các tham số predictor mà ISO 32000-2:2020 §7.4.4.4 định nghĩa cho bộ lọc LZWDecode và FlateDecode. Việc so khớp bỏ qua khoảng trắng và vẫn hoạt động dù có các token PDF bao quanh. Các khóa vắng mặt giữ giá trị mặc định: predictor 1, columns 1, colors 1, bits-per-component 8. Các giá trị hiện diện được xác thực theo kiểu fail-closed lúc phân tích, trước khi bất kỳ hình học nào có thể chạm tới việc cấp phát hàng của bộ đảo-lọc:

• Một giá trị âm hiện diện cho bất kỳ khóa được nhận diện nào đều bị từ chối.
• /Columns lớn hơn 1,000,000 bị từ chối.
• /Colors lớn hơn 32 bị từ chối.
• /BitsPerComponent nằm ngoài {1, 2, 4, 8, 16} bị từ chối.
• Một bước nhảy hàng dẫn xuất lớn hơn 64,000,000 byte bị từ chối.

isPngPredictor() trả về true khi predictor được phân tích nằm trong khoảng 10 đến 15. Predictor 1 (không dự đoán) và predictor 2 (nhóm TIFF) trả về false.

Hình học hàng

PngPredictor::inverse() tiêu thụ một byte stream đã được FlateDecode, trong đó mỗi hàng được đặt trước bởi một filter tag một byte. Nó phát ra payload đã dựng lại với các tag đã được loại bỏ. Bề rộng payload của hàng là ceil(columns * colors * bitsPerComponent / 8) byte; bước nhảy hàng thêm một byte tag. Offset của ô lân cận bên trái (byte mỗi điểm ảnh) là max(1, floor(colors * bitsPerComponent / 8)), nên các cách đóng gói dưới một byte sẽ làm tròn xuống thành một byte. Việc lọc thao tác trên các byte trọn vẹn bất kể độ sâu bit, khớp với ngữ nghĩa bộ lọc PNG.

Dựng lại theo từng hàng

Tag	Filter	Dựng lại
0	None	passthrough
1	Sub	recon[x] = filt[x] + recon[x-bpp]
2	Up	recon[x] = filt[x] + prior[x]
3	Average	recon[x] = filt[x] + floor((recon[x-bpp] + prior[x]) / 2)
4	Paeth	recon[x] = filt[x] + Paeth(left, up, up-left)

Mọi tổng đều lấy modulo 256. Đối với hàng đầu tiên, và đối với các byte nằm bên trái điểm ảnh đầu tiên, ô lân cận thiếu được đọc là zero, theo W3C PNG §9.2. Phép đảo được điều khiển hoàn toàn bởi tag theo từng hàng. Đó là hành vi phù hợp cho cả các predictor cố định (10-14) lẫn Optimum (15) theo ISO 32000-2:2020 §7.4.4.4, nên sự khác biệt tag của bên ghi được chấp nhận.

Phân lớp xác thực

Việc xác thực tham số chạy theo hai lớp có chủ đích. DecodeParms là điểm nghẽn lúc phân tích và từ chối các độ lớn thù địch trước tiên. PngPredictor::inverse() giữ lại các kiểm tra riêng của nó như một lớp thứ hai: kiểm tra khoảng cho cả bốn tham số, các bảo vệ tràn số so sánh từng thừa số với PHP_INT_MAX trước khi tạo tích bước nhảy, cùng trần 64,000,000 byte mỗi hàng, và một giới hạn tỷ lệ với đầu vào, từ chối một bước nhảy được khai báo lớn hơn toàn bộ đầu vào trước khi cấp phát bất kỳ bộ đệm hàng nào.

Tính tất định

Cả hai điểm vào đều là các hàm static thuần túy của đầu vào. Không có I/O, không ghi log, và không có trạng thái toàn cục. Thời gian chạy tuyến tính theo độ dài đầu vào với một hằng số nhỏ trên mỗi byte. Việc phân tích /DecodeParms là một vài phép so khớp biểu thức chính quy có giới hạn. Các ngân sách được nêu trong performance_budget ở frontmatter.

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

Mọi thất bại trong module này đều phát sinh InvalidArgumentException với giá trị vi phạm được nêu tên trong thông điệp.

• fromDictionary() từ chối một giá trị âm hiện diện cho bất kỳ khóa được nhận diện nào.
• fromDictionary() từ chối /Columns lớn hơn 1,000,000 và /Colors lớn hơn 32.
• fromDictionary() từ chối /BitsPerComponent nằm ngoài {1, 2, 4, 8, 16} và một bước nhảy hàng dẫn xuất lớn hơn 64,000,000 byte.
• inverse() từ chối một predictor nằm ngoài 10-15. TIFF predictor (2) không bao giờ được đảo-lọc ở đây; hãy rẽ nhánh theo isPngPredictor() trước.
• inverse() từ chối columns hoặc colors nhỏ hơn 1 và bitsPerComponent nằm ngoài tập hợp lệ.
• inverse() từ chối hình học mà tích bước nhảy sẽ tràn số nguyên của nền tảng, trước bất kỳ việc cấp phát nào.
• inverse() từ chối một bước nhảy hàng lớn hơn trần 64,000,000 byte mỗi hàng, độc lập với độ dài đầu vào thực tế.
• inverse() trả về chuỗi rỗng cho đầu vào rỗng; đó không phải là lỗi.
• inverse() báo lỗi một bước nhảy hàng được khai báo lớn hơn toàn bộ đầu vào như một hàng bị cắt cụt tại offset 0.
• inverse() báo lỗi một hàng cuối bị thiếu như một hàng bị cắt cụt, nêu tên offset và số byte.
• inverse() báo lỗi một filter tag theo hàng không xác định (không phải 0-4) kèm giá trị tag và offset của hàng.
• Một sự không khớp giữa hình học /DecodeParms được khai báo và bố cục stream thực tế hiện ra như một lỗi tham số hoặc lỗi cắt cụt, không bao giờ như đầu ra bị hỏng thầm lặng.
• Bộ lọc Average dùng phép chia số nguyên, khớp với ngữ nghĩa floor của đặc tả PNG.
• Không có thao tác mã hóa nào xảy ra trong module này. Hành vi là như nhau trong các triển khai bị ràng buộc FIPS.

Tính phù hợp

Tuyên bố	Tiêu chuẩn	Điều khoản
Tham số bộ lọc /Predictor chọn thuật toán predictor; các giá trị được phép đến từ bảng giá-trị-predictor.	ISO 32000-2:2020	§7.4.4.4
PDF định nghĩa hai nhóm predictor: nhóm TIFF là hàm Predictor 2 duy nhất; nhóm PNG là các tag 10-15.	ISO 32000-2:2020	§7.4.4.4
Các giá trị hợp lệ của /BitsPerComponent là 1, 2, 4, 8, và 16 với mặc định 8; /Colors là 1 trở lên với mặc định 1; /Columns mặc định là 1.	ISO 32000-2:2020	§7.4.4.4
Các hàm dựng lại cho loại bộ lọc 0-4 thao tác theo byte modulo 256; các byte bên trái và hàng trước vắng mặt được đọc là zero.	W3C PNG (Third Edition)	§9.2
Loại bộ lọc Paeth tính PaethPredictor của các ô lân cận bên trái, phía trên, và trên-trái rồi chọn giá trị gần nhất.	W3C PNG (Third Edition)	§9.4

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ố 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. Tính phù hợp của phép toán dựng lại và các giá trị tham số mặc định được kiểm chứng bởi bộ kiểm thử đơn vị. Một framework lọc stream PDF đầy đủ, và việc đảo ngược TIFF predictor, nằm ngoài phạm vi của module này.

Ghi chú phát triển

• Cả hai lớp được cung cấp từ nextpdf/pro 3.0.0 và là bản hiện hành trong 3.1.0.
• Module được sử dụng bởi các trình trích xuất Pro Diff và Classifier khi đầu vào của chúng mang một predictor.
• Hãy rẽ nhánh theo isPngPredictor() trước khi gọi inverse(); predictor 1 và TIFF predictor không cần đảo ngược PNG.
• Module tự giới hạn việc cấp phát trên mỗi hàng của nó. Các bên gọi đảo ngược predictor trên stream không đáng tin vẫn nên giới hạn kích thước đầu vào đã giải nén ở phía trên, như các trình trích xuất Pro làm.
• Các predictor cố định (10-14) và Optimum (15) dùng chung một đường mã; tag theo từng hàng điều khiển việc dựng lại trong cả hai trường hợp.
• Chi tiết cơ chế nội bộ nằm trong tài liệu nội bộ của kho nguồn và nằm ngoài phạm vi của sổ tay này.

Ranh giới công bố

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ộ, các lớp trợ giúp, các bảng cơ chế, tên tệp runbook, và tiền tố ticket nằm ngoài phạm vi.

Xem thêm

• Filter (năng lực) — cài đặt, khởi động nhanh, và các ví dụ sử dụng ở môi trường production.
• Diff — Tài liệu tham chiếu chuyên sâu — một bên tiêu thụ bộ đảo-lọc.
• Classifier — Tài liệu tham chiếu chuyên sâu — một bên tiêu thụ bộ đảo-lọc.