Filter — Referensi Mendalam

Sekilas

Halaman ini adalah referensi tingkat kontrak untuk modul Filter NextPDF Pro, namespace NextPDF\Pro\Filter. Permukaannya terdiri dari dua kelas. DecodeParms mem-parsing fragmen kamus PDF /DecodeParms menjadi value object yang immutable dan terperiksa batasnya. PngPredictor membalikkan keluarga predictor PNG (tag 10-15) pada byte stream yang telah di-FlateDecode. Modul ini melayani extractor Diff dan Classifier Pro. Ini bukan kerangka kerja stream-filter umum. Halaman ini menyatakan API publik, kontrak perilaku yang teramati, dan mode kegagalan bertipe. Panduan penggunaan dan contoh kode berada di halaman kapabilitas Filter.

Ketersediaan & lisensi

Kapabilitas ini disertakan dalam NextPDF Pro (nextpdf/pro) dan aktif dengan envelope lisensi tier Pro. Deployment tanpa entitlement tersebut tidak memuat kelas-kelas kapabilitas ini. Bandingkan edisi dan dapatkan lisensi.

Tidak ada flag kapabilitas runtime yang menggerbangi modul ini. Kelas-kelas Filter tersedia setiap kali nextpdf/pro terpasang.

Permukaan API publik

Simbol	Parameter	Perilaku default	Mengembalikan	Melempar atau gagal dengan	Catatan
DecodeParms	constructor: int $predictor = 1, int $columns = 1, int $colors = 1, int $bitsPerComponent = 8	Default menyandikan “tanpa predictor”	—	—	final readonly; keempat properti bersifat publik dan immutable
DecodeParms::fromDictionary()	string $raw — teks kamus mentah, body objek di sekitarnya ditoleransi	Kunci yang tidak ada mempertahankan default-nya; pencocokan toleran terhadap whitespace	self	InvalidArgumentException	Titik cekik saat parse; batasan tercantum dalam kontrak perilaku
DecodeParms::isPngPredictor()	tidak ada	Predikat murni; tanpa I/O	bool — true untuk predictor 10-15	—	Bercabang atas ini sebelum memanggil reverse filter
PngPredictor	—	Stateless	—	—	final; satu-satunya titik masuk adalah static inverse()
PngPredictor::inverse()	string $raw, int $columns, int $colors, int $bitsPerComponent, int $predictor	Melakukan reverse-filter baris demi baris berdasarkan tag per-baris; input kosong mengembalikan string kosong	string — payload yang direkonstruksi dengan tag filter dilucuti	InvalidArgumentException	Hanya menerima predictor 10-15; predictor TIFF di luar cakupan

Tanda tangan titik masuk

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

Kontrak perilaku

Parsing /DecodeParms

DecodeParms::fromDictionary() mencocokkan empat kunci yang dikenali sebagai integer dalam teks kamus mentah: /Predictor, /Columns, /Colors, dan /BitsPerComponent. Ini adalah parameter predictor yang didefinisikan ISO 32000-2:2020 §7.4.4.4 untuk filter LZWDecode dan FlateDecode. Pencocokan toleran terhadap whitespace dan bertahan terhadap token PDF di sekitarnya. Kunci yang tidak ada mempertahankan default-nya: predictor 1, columns 1, colors 1, bits-per-component 8. Nilai yang ada divalidasi secara fail-closed saat parse, sebelum geometri apa pun dapat mencapai alokasi baris pada reverse filter:

• Nilai negatif yang ada untuk kunci yang dikenali mana pun ditolak.
• /Columns di atas 1.000.000 ditolak.
• /Colors di atas 32 ditolak.
• /BitsPerComponent di luar {1, 2, 4, 8, 16} ditolak.
• Stride baris turunan di atas 64.000.000 byte ditolak.

isPngPredictor() mengembalikan true ketika predictor yang di-parse adalah 10 hingga 15. Predictor 1 (tanpa prediksi) dan predictor 2 (grup TIFF) mengembalikan false.

Geometri baris

PngPredictor::inverse() mengonsumsi byte stream yang telah di-FlateDecode di mana setiap baris didahului oleh satu byte filter tag. Ia mengemisi payload yang direkonstruksi dengan tag dilucuti. Lebar payload baris adalah ceil(columns * colors * bitsPerComponent / 8) byte; stride baris menambahkan satu byte tag. Offset tetangga-kiri (byte per piksel) adalah max(1, floor(colors * bitsPerComponent / 8)), sehingga pengemasan sub-byte membulat ke bawah menjadi satu byte. Filtering beroperasi pada byte utuh terlepas dari kedalaman bit, sesuai semantik filter PNG.

Rekonstruksi per-baris

Tag	Filter	Rekonstruksi
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)

Semua penjumlahan diambil modulo 256. Untuk baris pertama, dan untuk byte di sebelah kiri piksel pertama, tetangga yang hilang dibaca sebagai nol, sesuai W3C PNG §9.2. Operasi pembalikan digerakkan sepenuhnya oleh tag per-baris. Itu adalah perilaku yang sesuai untuk baik predictor tetap (10-14) maupun Optimum (15) di bawah ISO 32000-2:2020 §7.4.4.4, sehingga varians tag writer ditoleransi.

Pelapisan validasi

Validasi parameter berjalan dalam dua lapisan secara desain. DecodeParms adalah titik cekik saat parse dan menolak magnitudo bermusuhan lebih dulu. PngPredictor::inverse() mempertahankan pemeriksaannya sendiri sebagai lapisan kedua: pemeriksaan rentang pada keempat parameter, penjaga overflow yang membandingkan faktor tunggal terhadap PHP_INT_MAX sebelum membentuk produk stride, batas atas per-baris 64.000.000 byte yang sama, dan batas proporsional-input yang menolak stride terdeklarasi yang lebih besar dari seluruh input sebelum buffer baris apa pun dialokasikan.

Determinisme

Kedua titik masuk adalah fungsi static murni dari input-nya. Tidak ada I/O, tidak ada logging, dan tidak ada state global. Waktu jalan linear terhadap panjang input dengan konstanta per-byte kecil. Parsing /DecodeParms adalah beberapa pencocokan regular-expression yang terbatas. Anggaran dinyatakan dalam frontmatter performance_budget.

Kasus tepi & mode kegagalan

Setiap kegagalan dalam modul ini menaikkan InvalidArgumentException dengan nilai yang melanggar dinamai dalam pesan.

• fromDictionary() menolak nilai negatif yang ada untuk kunci yang dikenali mana pun.
• fromDictionary() menolak /Columns di atas 1.000.000 dan /Colors di atas 32.
• fromDictionary() menolak /BitsPerComponent di luar {1, 2, 4, 8, 16} dan stride baris turunan di atas 64.000.000 byte.
• inverse() menolak predictor di luar 10-15. Predictor TIFF (2) tidak pernah di-reverse-filter di sini; bercabang atas isPngPredictor() lebih dulu.
• inverse() menolak columns atau colors di bawah 1 dan bitsPerComponent di luar himpunan yang sah.
• inverse() menolak geometri yang produk stride-nya akan overflow integer platform, sebelum alokasi apa pun.
• inverse() menolak stride baris di atas batas atas per-baris 64.000.000 byte, terlepas dari panjang input aktual.
• inverse() mengembalikan string kosong untuk input kosong; itu bukan error.
• inverse() menggagalkan stride baris terdeklarasi yang lebih besar dari keseluruhan input sebagai baris terpotong pada offset 0.
• inverse() menggagalkan baris parsial di akhir sebagai baris terpotong, menamai offset dan jumlah byte.
• inverse() menggagalkan tag filter per-baris yang tidak dikenal (bukan 0-4) dengan nilai tag dan offset baris.
• Ketidakcocokan antara geometri /DecodeParms yang terdeklarasi dan tata letak stream aktual muncul sebagai error parameter atau truncation, tidak pernah sebagai output yang rusak secara diam-diam.
• Filter Average menggunakan pembagian integer, sesuai semantik floor spesifikasi PNG.
• Tidak ada operasi kriptografis yang terjadi dalam modul ini. Perilaku identik pada deployment yang dibatasi FIPS.

Konformansi

Klaim	Standar	Klausa
Parameter filter /Predictor memilih algoritma predictor; nilai yang diizinkan berasal dari tabel predictor-values.	ISO 32000-2:2020	§7.4.4.4
PDF mendefinisikan dua grup predictor: grup TIFF adalah fungsi Predictor 2 tunggal; grup PNG adalah tag 10-15.	ISO 32000-2:2020	§7.4.4.4
Nilai valid /BitsPerComponent adalah 1, 2, 4, 8, dan 16 dengan default 8; /Colors adalah 1 atau lebih dengan default 1; /Columns default ke 1.	ISO 32000-2:2020	§7.4.4.4
Fungsi rekonstruksi untuk tipe filter 0-4 beroperasi byte-wise modulo 256; byte tetangga-kiri dan baris-sebelumnya yang tidak ada dibaca sebagai nol.	W3C PNG (Third Edition)	§9.2
Tipe filter Paeth menghitung PaethPredictor dari tetangga kiri, atas, dan kiri-atas serta memilih yang terdekat.	W3C PNG (Third Edition)	§9.4

Semua klausa diparafrasekan; NextPDF tidak mereproduksi teks normatif. Ini adalah pernyataan kapabilitas, bukan sertifikasi; NextPDF tidak memegang sertifikasi dan tidak memberikan sertifikasi apa pun. Konformansi matematika rekonstruksi dan default parameter diuji oleh suite unit. Kerangka kerja stream-filter PDF penuh, dan pembalikan predictor TIFF, di luar cakupan modul ini.

Catatan pengembangan

• Kedua kelas disertakan sejak nextpdf/pro 3.0.0 dan aktif di 3.1.0.
• Modul ini dikonsumsi oleh extractor Diff dan Classifier Pro ketika input mereka membawa predictor.
• Bercabang atas isPngPredictor() sebelum memanggil inverse(); predictor 1 dan predictor TIFF tidak memerlukan pembalikan PNG.
• Modul membatasi alokasi per-baris-nya sendiri. Pemanggil yang membalikkan predictor pada stream tidak tepercaya tetap harus membatasi ukuran input terdekompresi di hulu, sebagaimana yang dilakukan extractor Pro.
• Predictor tetap (10-14) dan Optimum (15) berbagi satu jalur kode; tag per-baris menggerakkan rekonstruksi dalam kedua kasus.
• Detail mekanisme internal tetap berada di dokumentasi internal repositori sumber dan di luar cakupan manual ini.

Batas publikasi

Halaman ini mendokumentasikan perilaku yang teramati secara eksternal dan permukaan API publik yang didukung saja. Path namespace internal, kelas helper, tabel mekanisme, nama file runbook, dan prefiks tiket di luar cakupan.

Lihat juga

• Filter (kapabilitas) — instalasi, mulai cepat, dan contoh penggunaan produksi.
• Diff — Referensi Mendalam — konsumen dari reverse filter.
• Classifier — Referensi Mendalam — konsumen dari reverse filter.