PHP: полный мануал с примерами, функциями и ООП

От крапинок к первому видимому результату

На каталожном макете появились отдельные крапинки и зернистость. Их хочется ослабить, сохранив ярлык и тонкую служебную маркировку. Фильтр не знает, какая точка — дефект, а какая — нужный штрих. Начнём с видимого результата и маленького окна соседей, затем сравним три разных правила.

В модели «окно 3×3» — 3 столбца по 3 пикселя, всего 9 значений. В центре контрольной точки (32,260) находится 255, вокруг восемь 128. Медиана сортирует их и выбирает пятое 128; среднее складывает и делит на 9: 1279/9≈142.111. Это модель statisticImage, не полный алгоритм despeckle или enhance. Координата x растёт вправо, y вниз; отсчёт начинается с 0.

У первого despeckle собственное правило: фиксированный проход небольшими парными повышениями тёмных и понижениями светлых относительно соседей. Он ослабляет локальные выбросы постепенно; показанная сортировка медианы описывает другой метод и не заменяет этот механизм.

Самая маленькая запись

В $image уже загружена отдельная копия. Стрелка -> вызывает метод; () содержит аргументы, ; завершает команду. У despeckleImage нет аргументов: нельзя добавить выдуманную силу, sigma или канал.

$image->despeckleImage();

Метод меняет текущий объект. Сначала $image = clone $source; создаёт независимую копию; простое = объект не копирует. В полной программе ! проверяет false, if выбирает отказ, throw new RuntimeException прекращает неудачную цепочку. Clear освобождает native-ресурсы после записи. Подготовка: объект и метод, clone, исключения.

Распакуйте весь архив примера: example.php — программа, localstats-fixture.php — показанный ниже помощник, source.png.b64 — текстовое Base64-представление точного PNG. Require подключает файл относительно __DIR__, папки программы. LoadLocalStatsSource возвращает объект Imagick: декодирует данные, проверяет SHA256 и записывает source.png. Фильтры работают с clone; SaveLocalStatsComparison собирает панели в новом PNG и печатает имя файла. Его нужно открыть просмотрщиком: stdout содержит имя, не саму картинку.

Виртуальные пиксели задают данные за рамкой: EDGE продолжает край для enhance/statistic. У CPU-despeckle собственный буфер с нулевой рамкой; нельзя обещать одинаковое влияние настройки для трёх методов. Константа Imagick::VIRTUALPIXELMETHOD_EDGE — имя правила, :: здесь читает константу.

<?php
declare(strict_types=1);

require __DIR__ . '/localstats-fixture.php';
$source = loadLocalStatsSource();
$source->setImageVirtualPixelMethod(Imagick::VIRTUALPIXELMETHOD_EDGE);
$image = clone $source;
if (!$image->despeckleImage()) {
    throw new RuntimeException('Не удалось применить despeckleImage');
}
saveLocalStatsComparison([$source, $image], 'localstats-first.png');
$source->clear();
$image->clear();

localstats-first.png

<?php
declare(strict_types=1);

function loadLocalStatsSource(): Imagick
{
    $encoded = file_get_contents(__DIR__ . '/source.png.b64');
    if ($encoded === false) {
        throw new RuntimeException('Не найден source.png.b64: распакуйте весь архив');
    }
    $bytes = base64_decode($encoded, true);
    if ($bytes === false || hash('sha256', $bytes) !== '73657c239600755e483369848a41d9f21495cb286490504659151b49aa8bebef') {
        throw new RuntimeException('Повреждён исходный PNG');
    }
    $path = __DIR__ . '/source.png';
    if (file_put_contents($path, $bytes) !== strlen($bytes)) {
        throw new RuntimeException('Не удалось восстановить source.png');
    }
    return new Imagick($path);
}

function saveLocalStatsComparison(array $panels, string $filename): void
{
    if ($panels === []) {
        throw new InvalidArgumentException('Нужна хотя бы одна панель');
    }
    $output = new Imagick();
    $output->newImage(400 * count($panels), 320, 'white');
    $output->setImageFormat('png');
    foreach ($panels as $index => $panel) {
        if (!$panel instanceof Imagick || $panel->getImageWidth() !== 400 || $panel->getImageHeight() !== 320) {
            throw new InvalidArgumentException('Панель должна быть Imagick 400 на 320 пикселей');
        }
        if (!$output->compositeImage($panel, Imagick::COMPOSITE_OVER, 400 * $index, 0)) {
            throw new RuntimeException('Не удалось собрать сравнение');
        }
    }
    $output->setImageDepth(8);
    $output->setOption('png:color-type', '2');
    if (!$output->writeImage(__DIR__ . '/' . $filename)) {
        throw new RuntimeException('Не удалось записать результат');
    }
    $output->clear();
    echo $filename, "\n";
}

В помощнике function объявляет операции; тип после : описывает результат, Imagick — объект изображения, void — отсутствие возвращаемого значения. Array $panels — список объектов; foreach перебирает его с индексом, count считает панели. Проверки чтения/декодирования/хеша/размера останавливают повреждённый вход. Composite размещает панели без масштабирования; depth 8 и RGB PNG фиксируют формат. Это инфраструктура примеров, не скрытая часть алгоритмов. Подробнее: функции, массивы, foreach, чтение и запись.

Три правила локальной обработки

Despeckle использует complementary Hull: по четырём направлениям выполняет парные повышения тёмных и понижения светлых относительно соседей. В точном CPU C шаг равен одному 8-битному уровню, поэтому один проход не обязан удалить сильную 0/255 точку. Это не сортировка медианы.

Enhance использует фиксированную окрестность 5×5 и заданные веса: сосед включается при достаточно малом цветовом расстоянии до центра. В точном Core distance_squared<0.069 учитывает компоненты цвета и alpha. Это не автоматическая яркость, резкость или ползунок «качества»; очень отличающийся импульс может остаться.

StatisticImage применяет статистику отдельно к обновляемым каналам каждого пикселя. Окно включает центр и перемещается по растру; результатом остаётся изображение. Медианы R,G,B выбираются отдельно: итоговый RGB не обязательно совпадает с цветом одного соседнего пикселя. Это отличается от selectiveBlur, сравнивающего интенсивности для допуска соседей.

Перед полной программой: $image, $enhanced, $median — отдельные clone из $source. Первые два вызова без аргументов; у третьего константа выбирает медиану, 3 и 3 задают окно, channel остаётся default. Скобки вызывают метод, запятые разделяют аргументы, :: без скобок читает константу.

$image->despeckleImage();
$enhanced->enhanceImage();
$median->statisticImage(Imagick::STATISTIC_MEDIAN, 3, 3);

<?php
declare(strict_types=1);

require __DIR__ . '/localstats-fixture.php';
$source = loadLocalStatsSource();
$source->setImageVirtualPixelMethod(Imagick::VIRTUALPIXELMETHOD_EDGE);
$image = clone $source;
if (!$image->despeckleImage()) {
    throw new RuntimeException('Не удалось применить despeckleImage');
}
$enhanced = clone $source;
if (!$enhanced->enhanceImage()) {
    throw new RuntimeException('Не удалось применить enhanceImage');
}
$median = clone $source;
if (!$median->statisticImage(Imagick::STATISTIC_MEDIAN, 3, 3)) {
    throw new RuntimeException('Не удалось применить statisticImage');
}
saveLocalStatsComparison([$source, $image, $enhanced, $median], 'localstats-controls.png');
$source->clear();
$image->clear();
$enhanced->clear();
$median->clear();

localstats-controls.png

Выбрать статистику, окно и единицы

Тип статистики — выбор числа из соседних значений. Width/height — размеры окна в пикселях; 3×3 не означает радиус 3. Здесь размеры не доли диапазона и не числа отброшенных пикселей. PNG8 отображается как 0..255; внутри проверенной Q16-сборки Q означает QuantumRange, максимум 65535. В дальнейшей схеме ярлыка 0.68×Q — порог 44563.8 native-единицы, не доля числа пикселей. Сохранение в PNG8 квантует вычисление.

Все 10 имён доступны в проверенной сборке. Не переносите это автоматически на старый сервер. Для пользовательского выбора заведите whitelist, для окна — положительные нечётные ограниченные размеры. Чётные окна C допускает, но центр смещён: ширина 2 использует x−1 и x. Большое окно может уничтожить букву и требует ресурсов; сравнительную скорость без измерений не обещаем.

Окно 3×3 связано с масштабом этого входа. При удвоении разрешения фиксированное окно не действует автоматически на тот же физический размер детали. Цветовая маска канала и прямоугольная область — разные способы ограничения.

Разделить дефекты товара, маркировку и бумагу

Координаты известны из макета. Despeckle применяется к x=24..243,y=36..219; SKU находится справа вне области. Ярлык занимает x=72..227,y=140..189. Возвращая непрозрачную вырезку на clone, можно проверить каждый внешний пиксель. Это жёсткая граница ROI, не автоматическое выделение предмета или мягкая маска смешивания.

В пустой части ярлыка x=80..219,y=177..185 нет букв: чёрный после threshold там можно считать ложным дефектом по устройству входа. Это не OCR и не доказательство сохранения каждого штриха. Зерно измеряется отдельно в x=148..247,y=290..303 стандартным отклонением R — разбросом вокруг среднего; меньшее число на участке не доказывает лучшее качество всей картинки.

В сохранённых PNG8 сильные одиночные точки 255/0 после despeckle стали 239/16, после enhance остались 255/0, после медианы 3×3 стали 128. Разброс R на зернистом контрольном участке: исходник 7.21, despeckle 1.92, enhance 3.22, median 3.74, mean 2.48. У despeckle изменилось и среднее участка: 127.91→129.36. Эти числа описывают данный образец, а не рейтинг фильтров.

После одного порога в пустом участке ярлыка было 307 чёрных пикселей, после enhance и того же порога — 26. Отдельный исходник и промежуточный вариант позволяют увидеть, что именно помогло задаче; наличие оставшихся 26 точек не скрывается.

Увидеть цену медианы и расширения маски

Белый в маске означает выбранную область. MAXIMUM расширяет выбранное, MINIMUM сужает; при обратной полярности смысл изменится. Малую дырку окно заполнит, большая останется: метод не определяет, окружён ли чёрный участок белым на расстоянии десятков пикселей. Для заполнения по связности нужен другой алгоритм.

На входе есть одиночные дырки, дырки 5×5 и 9×9 и двухпиксельный зазор между белыми прямоугольниками. Даже когда дырка исчезает, граница растёт и соседние фигуры могут соединиться. Сравнивайте площадь и связность, а не только число дыр. Настоящий штрих не отличается от «шума» лишь тем, что нужен человеку.

Сохранённый центр (32,260): median 128, mean 142. Точка тонкой линии (74,258) была 255, после median стала 128, после mean — 170. В маске белая площадь выросла с 3896 до 4312 пикселей при 3×3 и до 4630 при 5×5. Одиночная дырка заполнена и двухпиксельный зазор закрыт уже при 3×3; центр большой дырки остался чёрным в обоих вариантах.

Проверить эффект, ограничения и отказ

Определите критерий до фильтра: ослабить известные точки, уменьшить зерно бумаги, сохранить SKU побайтно или заполнить малую дырку при допустимом росте области. Сохраняйте оригинал и промежуточный результат; варианты начинайте с оригинала. True означает успех операции, не пригодность для публикации.

Проверяйте формат, площадь, кадры, доступность методов/констант и права записи. Ограничьте пользовательский type whitelist-списком, окно — положительными нечётными размерами в разумном пределе. Неподходящий type или размеры не обязаны вызвать аккуратную PHP-ошибку. Окно, разрешение и копии влияют на native-память; время измеряйте в своей среде.

Восемь программ проверены на PHP 8.5.11, Imagick 3.8.1, ImageMagick 7.1.1-46 Q16. PNG8 непрозрачный RGB; при сохранении значения квантуются. Малый опыт охватывает 10 статистик, 0/1/even/прямоугольное окно, unknown-тип и alpha-шахматку; отрицательные и огромные размеры не запускались. Контрольные свойства не являются полной независимой реализацией алгоритмов.

Выбрать правило и сделать свой вариант

• Изолированная точка: сравните median 3×3 и despeckle, отдельно проверьте нужную линию.
• Зернистая бумага: сравните enhance и исходник; затем одинаковый порог.
• Белая маска с малой дыркой: MAXIMUM, если допустим рост границ; связностный залив — отдельная задача.
• Нужно сохранить маркировку: обработайте известную ROI и проверьте все внешние пиксели.

Упражнение: исправить только плашку маски, сохранив товар, подписи и SKU. Решение: clone; cropImage(116,64,268,246); setImagePage(0,0,0,0); statisticImage(MAXIMUM,3,3); compositeImage обратно в (268,246). Полная программа с вариантом 5×5 — в карточке statisticImage. Объясните, почему исчезнувшая дырка при выросшей белой площади не означает восстановленную истинную маску.

Дальше: похожие соседи и карта границ, пороговая маска, распределение яркостей, производный файл. Не переносите сильный фильтр на весь каталог без просмотра разных входов.