Filter — szczegółowa dokumentacja referencyjna

W skrócie

Ta strona stanowi referencję na poziomie kontraktu dla modułu Filter w NextPDF Pro, przestrzeń nazw NextPDF\Pro\Filter. Powierzchnia składa się z dwóch klas. DecodeParms parsuje fragment słownika PDF /DecodeParms do niezmiennego, sprawdzonego pod kątem zakresów obiektu wartości. PngPredictor odwraca rodzinę predyktorów PNG (znaczniki 10-15) na bajtach strumienia po dekodowaniu FlateDecode. Moduł obsługuje ekstraktory Pro Diff i Classifier. Nie jest to ogólny framework filtrów strumieniowych. Ta strona określa publiczne API, kontrakt obserwowalnego zachowania oraz typowane tryby awarii. Wskazówki dotyczące użycia i przykłady kodu znajdują się na stronie możliwości Filter.

Dostępność i licencjonowanie

Ta funkcjonalność jest dostarczana w NextPDF Pro (nextpdf/pro) i aktywuje się wraz z kopertą licencyjną poziomu Pro. Wdrożenie bez tego uprawnienia nie ładuje klas tej funkcjonalności. Porównaj edycje i uzyskaj licencję.

Żadna flaga możliwości w czasie działania nie kontroluje dostępu do tego modułu. Klasy Filter są dostępne zawsze, gdy zainstalowano nextpdf/pro.

Powierzchnia publicznego API

Symbol	Parametry	Zachowanie domyślne	Zwraca	Zgłasza lub kończy się błędem	Uwagi
DecodeParms	konstruktor: int $predictor = 1, int $columns = 1, int $colors = 1, int $bitsPerComponent = 8	Wartości domyślne oznaczają „brak predyktora”	—	—	final readonly; wszystkie cztery właściwości są publiczne i niezmienne
DecodeParms::fromDictionary()	string $raw — surowy tekst słownika, otaczające ciało obiektu jest tolerowane	Brakujące klucze zachowują wartości domyślne; dopasowanie toleruje białe znaki	self	InvalidArgumentException	Punkt kontrolny na etapie parsowania; ograniczenia wymieniono w kontrakcie zachowania
DecodeParms::isPngPredictor()	brak	Czysty predykat; brak operacji wejścia/wyjścia	bool — true dla predyktora 10-15	—	Rozgałęź na tym przed wywołaniem filtra odwrotnego
PngPredictor	—	Bezstanowa	—	—	final; jedynym punktem wejścia jest statyczna inverse()
PngPredictor::inverse()	string $raw, int $columns, int $colors, int $bitsPerComponent, int $predictor	Odwraca filtr wiersz po wierszu na podstawie znacznika wiersza; puste wejście zwraca pusty ciąg	string — zrekonstruowany ładunek z usuniętymi znacznikami filtra	InvalidArgumentException	Akceptuje wyłącznie predyktor 10-15; predyktor TIFF jest poza zakresem

Sygnatury punktów wejścia

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

Kontrakt zachowania

Parsowanie /DecodeParms

DecodeParms::fromDictionary() dopasowuje cztery rozpoznawane klucze jako liczby całkowite w surowym tekście słownika: /Predictor, /Columns, /Colors oraz /BitsPerComponent. Są to parametry predyktora, które ISO 32000-2:2020 §7.4.4.4 definiuje dla filtrów LZWDecode i FlateDecode. Dopasowanie toleruje białe znaki i przetrwa otaczające tokeny PDF. Brakujące klucze zachowują wartości domyślne: predyktor 1, columns 1, colors 1, bits-per-component 8. Obecne wartości są walidowane fail-closed na etapie parsowania, zanim jakakolwiek geometria dotrze do alokacji wiersza filtra odwrotnego:

• Obecna wartość ujemna dla dowolnego rozpoznawanego klucza jest odrzucana.
• /Columns powyżej 1,000,000 jest odrzucane.
• /Colors powyżej 32 jest odrzucane.
• /BitsPerComponent poza zbiorem {1, 2, 4, 8, 16} jest odrzucane.
• Wyprowadzony krok wiersza (stride) powyżej 64,000,000 bajtów jest odrzucany.

isPngPredictor() zwraca true, gdy sparsowany predyktor mieści się w zakresie od 10 do 15. Predyktor 1 (brak predykcji) i predyktor 2 (grupa TIFF) zwracają false.

Geometria wiersza

PngPredictor::inverse() pobiera strumień bajtów po dekodowaniu FlateDecode, w którym każdy wiersz jest poprzedzony jednobajtowym znacznikiem filtra. Emituje zrekonstruowany ładunek z usuniętymi znacznikami. Szerokość ładunku wiersza wynosi ceil(columns * colors * bitsPerComponent / 8) bajtów; krok wiersza (stride) dodaje jeden bajt znacznika. Przesunięcie lewego sąsiada (bajty na piksel) wynosi max(1, floor(colors * bitsPerComponent / 8)), więc upakowania sub-bajtowe zaokrąglają w dół do jednego bajta. Filtrowanie działa na całych bajtach niezależnie od głębi bitowej, zgodnie z semantyką filtrów PNG.

Rekonstrukcja w obrębie wiersza

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

Wszystkie sumy są brane modulo 256. Dla pierwszego wiersza oraz dla bajtów na lewo od pierwszego piksela brakujący sąsiad odczytywany jest jako zero, zgodnie z W3C PNG §9.2. Operacja odwrotna jest sterowana w całości znacznikiem wiersza. Jest to zachowanie zgodne zarówno dla predyktorów stałych (10-14), jak i Optimum (15) zgodnie z ISO 32000-2:2020 §7.4.4.4, więc zmienność znaczników po stronie zapisującego jest tolerowana.

Warstwy walidacji

Walidacja parametrów przebiega w dwóch warstwach zgodnie z projektem. DecodeParms jest punktem kontrolnym na etapie parsowania i najpierw odrzuca wrogie wartości. PngPredictor::inverse() zachowuje własne kontrole jako drugą warstwę: kontrole zakresu wszystkich czterech parametrów, zabezpieczenia przed przepełnieniem porównujące pojedyncze czynniki z PHP_INT_MAX przed utworzeniem iloczynu kroku, ten sam pułap 64,000,000 bajtów na wiersz oraz ograniczenie proporcjonalne do wejścia, które odrzuca zadeklarowany krok większy niż całe wejście, zanim zostanie zaalokowany jakikolwiek bufor wiersza.

Determinizm

Oba punkty wejścia są czystymi funkcjami statycznymi swoich danych wejściowych. Nie ma operacji wejścia/wyjścia, rejestrowania ani stanu globalnego. Czas działania jest liniowy względem długości wejścia z niewielką stałą na bajt. Parsowanie /DecodeParms to kilka ograniczonych dopasowań wyrażeń regularnych. Budżety podano we frontmatterze performance_budget.

Przypadki brzegowe i tryby awarii

Każda awaria w tym module zgłasza InvalidArgumentException z nazwą nieprawidłowej wartości w komunikacie.

• fromDictionary() odrzuca obecną wartość ujemną dla dowolnego rozpoznawanego klucza.
• fromDictionary() odrzuca /Columns powyżej 1,000,000 oraz /Colors powyżej 32.
• fromDictionary() odrzuca /BitsPerComponent poza zbiorem {1, 2, 4, 8, 16} oraz wyprowadzony krok wiersza powyżej 64,000,000 bajtów.
• inverse() odrzuca predyktor spoza zakresu 10-15. Predyktor TIFF (2) nigdy nie jest tutaj filtrowany odwrotnie; najpierw rozgałęź na isPngPredictor().
• inverse() odrzuca columns lub colors poniżej 1 oraz bitsPerComponent poza dozwolonym zbiorem.
• inverse() odrzuca geometrię, której iloczyn kroku spowodowałby przepełnienie liczby całkowitej platformy, przed jakąkolwiek alokacją.
• inverse() odrzuca krok wiersza powyżej pułapu 64,000,000 bajtów na wiersz, niezależnie od rzeczywistej długości wejścia.
• inverse() zwraca pusty ciąg dla pustego wejścia; nie jest to błąd.
• inverse() zgłasza błąd, gdy zadeklarowany krok wiersza jest większy niż całe wejście, jako obcięty wiersz na przesunięciu 0.
• inverse() zgłasza błąd końcowego niepełnego wiersza jako obciętego wiersza, podając przesunięcie i liczby bajtów.
• inverse() zgłasza błąd nieznanego znacznika filtra w obrębie wiersza (innego niż 0-4), podając wartość znacznika i przesunięcie wiersza.
• Niezgodność między zadeklarowaną geometrią /DecodeParms a rzeczywistym układem strumienia objawia się jako błąd parametru lub obcięcia, nigdy jako cicho uszkodzone wyjście.
• Filtr Average używa dzielenia całkowitego, zgodnie z semantyką floor ze specyfikacji PNG.
• W tym module nie zachodzi żadna operacja kryptograficzna. Zachowanie jest identyczne we wdrożeniach z ograniczeniami FIPS.

Zgodność ze standardami

Twierdzenie	Standard	Klauzula
Parametr filtra /Predictor wybiera algorytm predyktora; dozwolone wartości pochodzą z tabeli wartości predyktora.	ISO 32000-2:2020	§7.4.4.4
PDF definiuje dwie grupy predyktorów: grupa TIFF to pojedyncza funkcja Predictor 2; grupa PNG to znaczniki 10-15.	ISO 32000-2:2020	§7.4.4.4
Prawidłowe wartości /BitsPerComponent to 1, 2, 4, 8 i 16, z domyślną 8; /Colors wynosi 1 lub więcej, z domyślną 1; /Columns domyślnie wynosi 1.	ISO 32000-2:2020	§7.4.4.4
Funkcje rekonstrukcji dla typów filtrów 0-4 działają bajt po bajcie modulo 256; brakujące bajty z lewej strony i z poprzedniego wiersza odczytywane są jako zero.	W3C PNG (Third Edition)	§9.2
Typ filtra Paeth oblicza PaethPredictor z sąsiadów po lewej, powyżej i po lewej u góry i wybiera najbliższy.	W3C PNG (Third Edition)	§9.4

Wszystkie klauzule są sparafrazowane; NextPDF nie odtwarza tekstu normatywnego. Są to twierdzenia o możliwościach, nie certyfikaty; NextPDF nie posiada żadnego certyfikatu i żadnego nie udziela. Zgodność matematyki rekonstrukcji i wartości domyślnych parametrów jest weryfikowana przez zestaw testów jednostkowych. Pełny framework filtrów strumieniowych PDF oraz odwracanie predyktora TIFF są poza zakresem tego modułu.

Uwagi dotyczące rozwoju

• Obie klasy są dostarczane od nextpdf/pro 3.0.0 i są aktualne w 3.1.0.
• Moduł jest wykorzystywany przez ekstraktory Pro Diff i Classifier, gdy ich dane wejściowe zawierają predyktor.
• Rozgałęź na isPngPredictor() przed wywołaniem inverse(); predyktor 1 i predyktor TIFF nie wymagają odwracania PNG.
• Moduł ogranicza własną alokację na wiersz. Wywołujący odwracający predyktory na niezaufanych strumieniach powinni nadal ograniczać rozmiar zdekompresowanego wejścia na wcześniejszym etapie, tak jak robią to ekstraktory Pro.
• Predyktory stałe (10-14) i Optimum (15) współdzielą jedną ścieżkę kodu; znacznik wiersza steruje rekonstrukcją w obu przypadkach.
• Szczegóły wewnętrznego mechanizmu pozostają w wewnętrznej dokumentacji repozytorium źródłowego i są poza zakresem tego podręcznika.

Granica publikacji

Ta strona dokumentuje wyłącznie zewnętrznie obserwowalne zachowanie i wspieraną powierzchnię publicznego API. Wewnętrzne ścieżki przestrzeni nazw, klasy pomocnicze, tabele mechanizmów, nazwy plików runbooków oraz prefiksy zgłoszeń są poza zakresem.

Zobacz także

• Filter (możliwość) — instalacja, szybki start i przykłady użycia produkcyjnego.
• Diff — szczegółowa dokumentacja referencyjna — konsument filtra odwrotnego.
• Classifier — szczegółowa dokumentacja referencyjna — konsument filtra odwrotnego.