Filter — глубокий справочник

Краткий обзор

Эта страница — справочник уровня контракта для модуля Filter в NextPDF Pro, пространство имён NextPDF\Pro\Filter. Поверхность состоит из двух классов. DecodeParms разбирает фрагмент словаря PDF /DecodeParms в неизменяемый объект-значение с проверкой границ. PngPredictor выполняет обратное преобразование семейства PNG-предикторов (теги 10-15) над байтами потока после FlateDecode. Модуль обслуживает экстракторы Pro Diff и Classifier. Это не универсальный каркас потоковых фильтров. Эта страница описывает публичный API, контракт наблюдаемого поведения и типизированные режимы отказа. Руководство по использованию и примеры кода — на странице возможности Filter.

Доступность и лицензирование

Эта возможность поставляется в NextPDF Pro (nextpdf/pro) и активируется лицензионным конвертом уровня Pro. Развёртывание без этого права доступа не загружает классы возможности. Сравнить редакции и получить лицензию.

Никакой флаг возможностей времени выполнения не закрывает этот модуль. Классы Filter доступны всегда, когда установлен nextpdf/pro.

Публичная поверхность API

Символ	Параметры	Поведение по умолчанию	Возвращает	Бросает или завершается с	Примечания
DecodeParms	конструктор: int $predictor = 1, int $columns = 1, int $colors = 1, int $bitsPerComponent = 8	Значения по умолчанию кодируют “без предиктора”	—	—	final readonly; все четыре свойства публичны и неизменяемы
DecodeParms::fromDictionary()	string $raw — сырой текст словаря, окружающее тело объекта допускается	Отсутствующие ключи сохраняют значения по умолчанию; сопоставление устойчиво к пробелам	self	InvalidArgumentException	Узкое место на этапе разбора; границы перечислены в контракте поведения
DecodeParms::isPngPredictor()	нет	Чистый предикат; без ввода-вывода	bool — true для предикторов 10-15	—	Разветвляйтесь по нему перед вызовом обратного фильтра
PngPredictor	—	Без состояния	—	—	final; единственная точка входа — статический inverse()
PngPredictor::inverse()	string $raw, int $columns, int $colors, int $bitsPerComponent, int $predictor	Выполняет обратную фильтрацию построчно по тегу строки; пустой ввод возвращает пустую строку	string — реконструированная полезная нагрузка со снятыми тегами фильтра	InvalidArgumentException	Принимает только предикторы 10-15; TIFF-предиктор вне области действия

Сигнатуры точек входа

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

Контракт поведения

Разбор /DecodeParms

DecodeParms::fromDictionary() сопоставляет четыре распознаваемых ключа как целые числа в сыром тексте словаря: /Predictor, /Columns, /Colors и /BitsPerComponent. Это параметры предиктора, которые ISO 32000-2:2020 §7.4.4.4 определяет для фильтров LZWDecode и FlateDecode. Сопоставление устойчиво к пробелам и переживает окружающие токены PDF. Отсутствующие ключи сохраняют значения по умолчанию: предиктор 1, columns 1, colors 1, bits-per-component 8. Присутствующие значения проверяются по принципу fail-closed на этапе разбора, прежде чем какая-либо геометрия достигнет выделения строк обратного фильтра:

• Присутствующее отрицательное значение любого распознаваемого ключа отклоняется.
• /Columns больше 1,000,000 отклоняется.
• /Colors больше 32 отклоняется.
• /BitsPerComponent вне {1, 2, 4, 8, 16} отклоняется.
• Производный шаг строки больше 64,000,000 байт отклоняется.

isPngPredictor() возвращает true, когда разобранный предиктор — от 10 до 15. Предиктор 1 (без предсказания) и предиктор 2 (группа TIFF) возвращают false.

Геометрия строки

PngPredictor::inverse() потребляет байтовый поток после FlateDecode, в котором каждой строке предшествует однобайтовый тег фильтра. Он выдаёт реконструированную полезную нагрузку со снятыми тегами. Ширина полезной нагрузки строки — ceil(columns * colors * bitsPerComponent / 8) байт; шаг строки добавляет один байт тега. Смещение левого соседа (байт на пиксель) — max(1, floor(colors * bitsPerComponent / 8)), поэтому упаковки менее байта округляются вниз до одного байта. Фильтрация работает над целыми байтами независимо от битовой глубины, что соответствует семантике PNG-фильтров.

Построчная реконструкция

Тег	Фильтр	Реконструкция
0	None	сквозная передача
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)

Все суммы берутся по модулю 256. Для первой строки и для байтов слева от первого пикселя отсутствующий сосед читается как ноль, согласно W3C PNG §9.2. Обратная операция полностью управляется тегом строки. Это соответствующее поведение как для фиксированных предикторов (10-14), так и для Optimum (15) по ISO 32000-2:2020 §7.4.4.4, поэтому вариативность тегов у записывающей стороны допускается.

Уровни проверки

Проверка параметров по замыслу выполняется в два уровня. DecodeParms — узкое место на этапе разбора, отклоняющее враждебные величины первым. PngPredictor::inverse() сохраняет собственные проверки как второй уровень: проверки диапазона всех четырёх параметров, защита от переполнения, сравнивающая отдельные множители с PHP_INT_MAX до формирования произведения для шага, тот же потолок 64,000,000 байт на строку и пропорциональная вводу граница, отклоняющая объявленный шаг больше всего ввода до выделения любого буфера строки.

Детерминированность

Обе точки входа — чистые статические функции своих входов. Нет ввода-вывода, нет логирования и нет глобального состояния. Время работы линейно по длине ввода с малой константой на байт. Разбор /DecodeParms — несколько ограниченных сопоставлений регулярных выражений. Бюджеты указаны в поле performance_budget фронтматтера.

Граничные случаи и режимы отказа

Любой отказ в этом модуле возбуждает InvalidArgumentException с указанием проблемного значения в сообщении.

• fromDictionary() отклоняет присутствующее отрицательное значение любого распознаваемого ключа.
• fromDictionary() отклоняет /Columns больше 1,000,000 и /Colors больше 32.
• fromDictionary() отклоняет /BitsPerComponent вне {1, 2, 4, 8, 16} и производный шаг строки больше 64,000,000 байт.
• inverse() отклоняет предиктор вне 10-15. TIFF-предиктор (2) здесь никогда не обрабатывается обратным фильтром; сначала разветвляйтесь по isPngPredictor().
• inverse() отклоняет columns или colors меньше 1 и bitsPerComponent вне допустимого набора.
• inverse() отклоняет геометрию, произведение шага которой переполнило бы целое число платформы, до любого выделения памяти.
• inverse() отклоняет шаг строки выше потолка 64,000,000 байт на строку, независимо от фактической длины ввода.
• inverse() возвращает пустую строку для пустого ввода; это не ошибка.
• inverse() завершается ошибкой при объявленном шаге строки больше всего ввода как усечённая строка со смещением 0.
• inverse() завершается ошибкой при завершающей неполной строке как усечённая строка, указывая смещение и количество байт.
• inverse() завершается ошибкой при неизвестном теге фильтра строки (не 0-4) с указанием значения тега и смещения строки.
• Несоответствие между объявленной геометрией /DecodeParms и фактической компоновкой потока проявляется как ошибка параметра или усечения, но никогда как молча повреждённый вывод.
• Фильтр Average использует целочисленное деление, что соответствует семантике floor спецификации PNG.
• В этом модуле не выполняется никакой криптографической операции. Поведение идентично в развёртываниях с ограничениями FIPS.

Соответствие

Утверждение	Стандарт	Пункт
Параметр фильтра /Predictor выбирает алгоритм предиктора; допустимые значения берутся из таблицы значений предиктора.	ISO 32000-2:2020	§7.4.4.4
PDF определяет две группы предикторов: группа TIFF — единственная функция Predictor 2; группа PNG — теги 10-15.	ISO 32000-2:2020	§7.4.4.4
Допустимые значения /BitsPerComponent — 1, 2, 4, 8 и 16 при значении по умолчанию 8; /Colors — 1 или больше при значении по умолчанию 1; /Columns по умолчанию 1.	ISO 32000-2:2020	§7.4.4.4
Функции реконструкции для типов фильтров 0-4 работают побайтово по модулю 256; отсутствующие байты слева и предыдущей строки читаются как ноль.	W3C PNG (Third Edition)	§9.2
Тип фильтра Paeth вычисляет PaethPredictor от левого, верхнего и верхнего-левого соседей и выбирает ближайший.	W3C PNG (Third Edition)	§9.4

Все пункты пересказаны; NextPDF не воспроизводит нормативный текст. Это заявления о возможностях, а не сертификации; NextPDF не имеет сертификации и не предоставляет её. Соответствие математики реконструкции и значений параметров по умолчанию проверяется модульным набором тестов. Полный каркас потоковых фильтров PDF и обратное преобразование TIFF-предиктора вне области действия этого модуля.

Замечания по разработке

• Оба класса поставляются начиная с nextpdf/pro 3.0.0 и актуальны в 3.1.0.
• Модуль используется экстракторами Pro Diff и Classifier, когда их входные данные несут предиктор.
• Разветвляйтесь по isPngPredictor() перед вызовом inverse(); предиктор 1 и TIFF-предиктор не требуют обратного преобразования PNG.
• Модуль ограничивает собственное выделение памяти на строку. Вызывающему коду, обращающему предикторы на недоверенных потоках, всё равно следует ограничивать размер распакованного ввода выше по потоку, как это делают экстракторы Pro.
• Фиксированные предикторы (10-14) и Optimum (15) используют один путь кода; тег строки управляет реконструкцией в обоих случаях.
• Детали внутреннего механизма остаются во внутренней документации исходного репозитория и вне области действия этого руководства.

Граница публикации

Эта страница документирует только внешне наблюдаемое поведение и поддерживаемую публичную поверхность API. Внутренние пути пространств имён, вспомогательные классы, таблицы механизмов, имена файлов runbook и префиксы тикетов вне области действия.

См. также

• Filter (возможность) — установка, быстрый старт и примеры промышленного использования.
• Diff — глубокий справочник — потребитель обратного фильтра.
• Classifier — глубокий справочник — потребитель обратного фильтра.