Filter — Detailreferenz

Auf einen Blick

Diese Seite ist die Referenz auf Vertragsebene für das NextPDF-Pro-Filtermodul, Namespace NextPDF\Pro\Filter. Die Oberfläche besteht aus zwei Klassen. DecodeParms parst ein PDF-/DecodeParms-Dictionary-Fragment zu einem unveränderlichen, bereichsgeprüften Wertobjekt. PngPredictor kehrt die PNG-Prädiktorfamilie (Tags 10-15) auf FlateDecoded-Stream-Bytes um. Das Modul bedient die Pro-Diff- und Classifier-Extraktoren. Es ist kein allgemeines Stream-Filter-Framework. Diese Seite legt die öffentliche API, den beobachtbaren Verhaltensvertrag und die typisierten Fehlermodi fest. Anwendungshinweise und Codebeispiele finden Sie auf der Filter-Funktionsseite.

Verfügbarkeit und Lizenzierung

Diese Funktion ist in NextPDF Pro (nextpdf/pro) enthalten und wird mit einem Lizenz-Envelope der Pro-Stufe aktiviert. Eine Bereitstellung ohne diese Berechtigung lädt die Klassen der Funktion nicht. Editionen vergleichen und eine Lizenz erwerben.

Kein Laufzeit-Funktionsflag schützt dieses Modul. Die Filter-Klassen sind immer verfügbar, sobald nextpdf/pro installiert ist.

Öffentliche API-Oberfläche

Symbol	Parameter	Standardverhalten	Rückgabe	Wirft oder scheitert mit	Hinweise
DecodeParms	Konstruktor: int $predictor = 1, int $columns = 1, int $colors = 1, int $bitsPerComponent = 8	Standardwerte kodieren „kein Prädiktor”	—	—	final readonly; alle vier Eigenschaften sind öffentlich und unveränderlich
DecodeParms::fromDictionary()	string $raw — roher Dictionary-Text, umgebender Objektkörper wird toleriert	Fehlende Schlüssel behalten ihre Standardwerte; die Zuordnung ist leerraumtolerant	self	InvalidArgumentException	Engstelle zur Parse-Zeit; Grenzen sind im Verhaltensvertrag aufgeführt
DecodeParms::isPngPredictor()	keine	Reines Prädikat; kein I/O	bool — true für Prädiktor 10-15	—	Verzweigen Sie hierauf, bevor Sie den Umkehrfilter aufrufen
PngPredictor	—	Zustandslos	—	—	final; der einzige Einstiegspunkt ist das statische inverse()
PngPredictor::inverse()	string $raw, int $columns, int $colors, int $bitsPerComponent, int $predictor	Kehrt Zeile für Zeile anhand des Zeilen-Tags um; leere Eingabe gibt eine leere Zeichenkette zurück	string — rekonstruierte Nutzlast mit entfernten Filter-Tags	InvalidArgumentException	Akzeptiert nur Prädiktor 10-15; der TIFF-Prädiktor liegt außerhalb des Geltungsbereichs

Einstiegspunkt-Signaturen

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

Verhaltensvertrag

/DecodeParms-Parsing

DecodeParms::fromDictionary() erkennt vier bekannte Schlüssel als Ganzzahlen im rohen Dictionary-Text: /Predictor, /Columns, /Colors und /BitsPerComponent. Dies sind die Prädiktorparameter, die ISO 32000-2:2020 §7.4.4.4 für die Filter LZWDecode und FlateDecode definiert. Die Zuordnung ist leerraumtolerant und übersteht umgebende PDF-Token. Fehlende Schlüssel behalten ihre Standardwerte: Prädiktor 1, Columns 1, Colors 1, Bits-pro-Komponente 8. Vorhandene Werte werden zur Parse-Zeit fail-closed validiert, bevor irgendeine Geometrie die Zeilenzuordnung des Umkehrfilters erreichen kann:

• Ein vorhandener negativer Wert für einen der bekannten Schlüssel wird abgelehnt.
• /Columns über 1.000.000 wird abgelehnt.
• /Colors über 32 wird abgelehnt.
• /BitsPerComponent außerhalb von {1, 2, 4, 8, 16} wird abgelehnt.
• Ein abgeleiteter Zeilen-Stride über 64.000.000 Bytes wird abgelehnt.

isPngPredictor() gibt true zurück, wenn der geparste Prädiktor 10 bis 15 ist. Prädiktor 1 (keine Vorhersage) und Prädiktor 2 (die TIFF-Gruppe) geben false zurück.

Zeilengeometrie

PngPredictor::inverse() verbraucht einen FlateDecoded-Byte-Stream, in dem jeder Zeile ein Ein-Byte-Filter-Tag vorangestellt ist. Er gibt die rekonstruierte Nutzlast mit entfernten Tags aus. Die Nutzlastbreite einer Zeile beträgt ceil(columns * colors * bitsPerComponent / 8) Bytes; der Zeilen-Stride fügt ein Tag-Byte hinzu. Der Offset des linken Nachbarn (Bytes pro Pixel) beträgt max(1, floor(colors * bitsPerComponent / 8)), sodass Sub-Byte-Packungen auf ein Byte abgerundet werden. Die Filterung arbeitet unabhängig von der Bittiefe auf ganzen Bytes, entsprechend der PNG-Filtersemantik.

Zeilenweise Rekonstruktion

Tag	Filter	Rekonstruktion
0	None	Durchleitung
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)

Alle Summen werden modulo 256 gebildet. Für die erste Zeile und für Bytes links vom ersten Pixel wird der fehlende Nachbar als Null gelesen, gemäß W3C PNG §9.2. Die Umkehroperation wird vollständig durch das Zeilen-Tag gesteuert. Das ist das konforme Verhalten sowohl für feste Prädiktoren (10-14) als auch für Optimum (15) gemäß ISO 32000-2:2020 §7.4.4.4, sodass Tag-Varianz seitens des Schreibers toleriert wird.

Validierungsschichten

Die Parametervalidierung läuft konzeptbedingt in zwei Schichten. DecodeParms ist die Engstelle zur Parse-Zeit und lehnt feindliche Größenordnungen zuerst ab. PngPredictor::inverse() behält seine eigenen Prüfungen als zweite Schicht: Bereichsprüfungen aller vier Parameter, Überlaufschutz, der einzelne Faktoren gegen PHP_INT_MAX vergleicht, bevor das Stride-Produkt gebildet wird, dieselbe Obergrenze von 64.000.000 Bytes pro Zeile sowie eine eingabeproportionale Schranke, die einen deklarierten Stride, der größer als die gesamte Eingabe ist, ablehnt, bevor irgendein Zeilenpuffer zugewiesen wird.

Determinismus

Beide Einstiegspunkte sind reine statische Funktionen ihrer Eingaben. Es gibt kein I/O, kein Logging und keinen globalen Zustand. Die Laufzeit ist linear in der Eingabelänge mit einer kleinen Konstante pro Byte. Das /DecodeParms-Parsing besteht aus wenigen begrenzten Regulärausdruck-Übereinstimmungen. Die Budgets sind im Frontmatter-performance_budget angegeben.

Grenzfälle und Fehlermodi

Jeder Fehler in diesem Modul löst eine InvalidArgumentException aus, wobei der beanstandete Wert in der Meldung benannt wird.

• fromDictionary() lehnt einen vorhandenen negativen Wert für einen der bekannten Schlüssel ab.
• fromDictionary() lehnt /Columns über 1.000.000 und /Colors über 32 ab.
• fromDictionary() lehnt /BitsPerComponent außerhalb von {1, 2, 4, 8, 16} und einen abgeleiteten Zeilen-Stride über 64.000.000 Bytes ab.
• inverse() lehnt einen Prädiktor außerhalb von 10-15 ab. Der TIFF-Prädiktor (2) wird hier niemals umgekehrt gefiltert; verzweigen Sie zuerst auf isPngPredictor().
• inverse() lehnt columns oder colors unter 1 und bitsPerComponent außerhalb der zulässigen Menge ab.
• inverse() lehnt eine Geometrie ab, deren Stride-Produkt die Plattform-Ganzzahl überlaufen würde, vor jeder Zuweisung.
• inverse() lehnt einen Zeilen-Stride über der Obergrenze von 64.000.000 Bytes pro Zeile ab, unabhängig von der tatsächlichen Eingabelänge.
• inverse() gibt für eine leere Eingabe eine leere Zeichenkette zurück; das ist kein Fehler.
• inverse() scheitert bei einem deklarierten Zeilen-Stride, der größer als die gesamte Eingabe ist, als abgeschnittene Zeile bei Offset 0.
• inverse() scheitert bei einer abschließenden Teilzeile als abgeschnittene Zeile und benennt den Offset und die Byte-Anzahlen.
• inverse() scheitert bei einem unbekannten Zeilen-Filter-Tag (nicht 0-4) mit dem Tag-Wert und dem Zeilen-Offset.
• Eine Diskrepanz zwischen der deklarierten /DecodeParms-Geometrie und dem tatsächlichen Stream-Layout äußert sich als Parameter- oder Abschneidefehler, niemals als stillschweigend beschädigte Ausgabe.
• Der Average-Filter verwendet Ganzzahldivision, entsprechend der Floor-Semantik der PNG-Spezifikation.
• In diesem Modul findet keine kryptografische Operation statt. Das Verhalten ist in FIPS-beschränkten Bereitstellungen identisch.

Konformität

Aussage	Standard	Klausel
Der Filterparameter /Predictor wählt den Prädiktoralgorithmus; zulässige Werte stammen aus der Prädiktorwerte-Tabelle.	ISO 32000-2:2020	§7.4.4.4
PDF definiert zwei Prädiktorgruppen: Die TIFF-Gruppe ist die einzelne Funktion Prädiktor 2; die PNG-Gruppe umfasst die Tags 10-15.	ISO 32000-2:2020	§7.4.4.4
Gültige Werte für /BitsPerComponent sind 1, 2, 4, 8 und 16 mit Standardwert 8; /Colors ist 1 oder größer mit Standardwert 1; /Columns hat Standardwert 1.	ISO 32000-2:2020	§7.4.4.4
Rekonstruktionsfunktionen für die Filtertypen 0-4 arbeiten byteweise modulo 256; fehlende linke und vorherige Zeilenbytes werden als Null gelesen.	W3C PNG (Third Edition)	§9.2
Der Paeth-Filtertyp berechnet den PaethPredictor des linken, oberen und oberen linken Nachbarn und wählt den nächstgelegenen.	W3C PNG (Third Edition)	§9.4

Alle Klauseln sind paraphrasiert; NextPDF gibt keinen normativen Text wieder. Es handelt sich um Funktionsaussagen, nicht um Zertifizierungen; NextPDF hält keine Zertifizierung und erteilt keine. Die Konformität der Rekonstruktionsmathematik und der Parameterstandardwerte wird durch die Unit-Suite geprüft. Ein vollständiges PDF-Stream-Filter-Framework und die Umkehrung des TIFF-Prädiktors liegen außerhalb des Geltungsbereichs dieses Moduls.

Entwicklungshinweise

• Beide Klassen sind seit nextpdf/pro 3.0.0 enthalten und in 3.1.0 aktuell.
• Das Modul wird von den Pro-Diff- und Classifier-Extraktoren genutzt, wenn ihre Eingaben einen Prädiktor tragen.
• Verzweigen Sie auf isPngPredictor(), bevor Sie inverse() aufrufen; Prädiktor 1 und der TIFF-Prädiktor benötigen keine PNG-Umkehrung.
• Das Modul begrenzt seine eigene Zuweisung pro Zeile. Aufrufer, die Prädiktoren auf nicht vertrauenswürdigen Streams umkehren, sollten die Größe der dekomprimierten Eingabe dennoch vorgelagert begrenzen, wie es die Pro-Extraktoren tun.
• Feste Prädiktoren (10-14) und Optimum (15) teilen sich einen Codepfad; das Zeilen-Tag steuert die Rekonstruktion in beiden Fällen.
• Interne Mechanismusdetails verbleiben in der internen Dokumentation des Quell-Repositorys und liegen außerhalb des Geltungsbereichs dieses Handbuchs.

Veröffentlichungsgrenze

Diese Seite dokumentiert ausschließlich das extern beobachtbare Verhalten und die unterstützte öffentliche API-Oberfläche. Interne Namespace-Pfade, Hilfsklassen, Mechanismustabellen, Runbook-Dateinamen und Ticket-Präfixe liegen außerhalb des Geltungsbereichs.

Siehe auch

• Filter (Funktion) — Installation, Schnellstart und Beispiele für den Produktivbetrieb.
• Diff — Detailreferenz — ein Konsument des Umkehrfilters.
• Classifier — Detailreferenz — ein Konsument des Umkehrfilters.