Применяет фильтр к изображению

# imagefilter

(PHP 5, PHP 7, PHP 8)

imagefilter — Применяет фильтр к изображению

### Описание

function imagefilter(GdImage `$image`, int `$filter`, array|int|float|bool `...$args`): bool

Функция imagefilter() применяет фильтр `filter` к изображению `image`.

### Список параметров

`image`
  Объект GdImage, который вернула функция imagecreatetruecolor() или другая функция генерации изображений.
`filter`

  Параметр `filter` принимает следующие значения:

  - `IMG_FILTER_NEGATE`: Инвертирует все цвета изображения.
  - `IMG_FILTER_GRAYSCALE`: Преобразует цвета изображения в градации серого путём преобразования компонент красного, зелёного и синего в их сумму с учётом весов, таких же как при вычислении яркости (Y') по рекомендации REC.601. Альфа-канал сохраняется. Для изображений с палитрой результат иногда отличается из-за ограничений, которые накладывает палитра.
  - `IMG_FILTER_BRIGHTNESS`: Изменяет яркость изображения. Уровень яркость устанавливают через параметр `args`. Диапазон яркости принимает значения от -255 до 255.
  - `IMG_FILTER_CONTRAST`: Изменяет контрастность изображения. Уровень контрастности устанавливают через параметр `args`.
  - `IMG_FILTER_COLORIZE`: То же, что и `IMG_FILTER_GRAYSCALE`, за исключением того, что разрешается указать цвет. Аргументы `args`, `arg2` и `arg3` устанавливают каналы `red`, `green`, `blue`, а аргумент `arg4` устанавливает канал `alpha`. Диапазон каждого канала принимает значения от 0 до 255.
  - `IMG_FILTER_EDGEDETECT`: Использует определение границ для их подсветки.
  - `IMG_FILTER_EMBOSS`: Добавляет рельеф.
  - `IMG_FILTER_GAUSSIAN_BLUR`: Размывает изображение методом Гаусса.
  - `IMG_FILTER_SELECTIVE_BLUR`: Размывает изображение.
  - `IMG_FILTER_MEAN_REMOVAL`: Использует усреднение для достижения эффекта «эскиза».
  - `IMG_FILTER_SMOOTH`: Делает границы более плавными, а изображение менее чётким. Уровень гладкости устанавливают через параметр `args`.
  - `IMG_FILTER_PIXELATE`: Применяет эффект пикселирования. Размер блока устанавливают через параметр `args`, а режим эффекта пикселизации через параметр `arg2`.
  - `IMG_FILTER_SCATTER`: Применяет эффект рассеивания к изображению. Силу эффекта определяют параметрами `args` и `arg2`, а аргумент `arg3` передают дополнительно, чтобы применить эффект только к конкретным цветам пикселей.
`args`

  - `IMG_FILTER_BRIGHTNESS`: Уровень яркости.
  - `IMG_FILTER_CONTRAST`: Уровень контрастности.
  - `IMG_FILTER_COLORIZE`: Значение красного компонента цвета.
  - `IMG_FILTER_SMOOTH`: Уровень сглаживания.
  - `IMG_FILTER_PIXELATE`: Размер блока в пикселях.
  - `IMG_FILTER_SCATTER`: Уровень уменьшения эффекта. Значению нельзя быть больше или равным уровню добавления эффекта, который установили в параметре `arg2`.
`arg2`

  - `IMG_FILTER_COLORIZE`: Значение зелёного компонента цвета.
  - `IMG_FILTER_PIXELATE`: Определяет, применять ли усовершенствованный эффект пикселизации. Значение по умолчанию равняется `false`.
  - `IMG_FILTER_SCATTER`: Уровень добавления эффекта.
`arg3`

  - `IMG_FILTER_COLORIZE`: Значение синего компонента цвета.
  - `IMG_FILTER_SCATTER`: Необязательный массив значений индексации цвета для применения эффекта.
`arg4`

  - `IMG_FILTER_COLORIZE`: Альфа-канал, значение между 0 и 127. Значение 0 обозначает непрозрачность, а 127 соответствует абсолютной прозрачности.

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Ошибки

Функция выбрасывает ошибку ValueError, если значение аргумента `sub` или `plus` приведёт к переполнению или недополнению со значением `IMG_FILTER_SCATTER` для параметра `filter`.

### Список изменений

Версия | Описание
--- | ---
8.4.0 | Функция теперь выбрасывает ошибку ValueError, если значение параметра `sub` или `plus` приведёт к переполнению или недополнению со значением `IMG_FILTER_SCATTER` для параметра `filter`.
8.0.0 | Параметр `image` теперь принимает объект GdImage; раньше параметр принимал корректный `gd`-ресурс (resource).
7.4.0 | Добавили поддержку рассеивания — `IMG_FILTER_SCATTER`.

### Примеры

Пример #1 Пример наложения фильтра на изображение функцией imagefilter() с фильтром grayscale

    <?php

    $im = imagecreatefrompng('dave.png');

    if ($im && imagefilter($im, IMG_FILTER_GRAYSCALE)) {
        echo 'Изображение преобразовано к градациям серого.';

        imagepng($im, 'dave.png');
    } else {
        echo 'Преобразование не удалось.';
    }

    ?>

Пример #2 Пример наложения фильтра функцией imagefilter() с фильтром яркости

    <?php
    $im = imagecreatefrompng('sean.png');

    if ($im && imagefilter($im, IMG_FILTER_BRIGHTNESS, 20)) {
        echo 'Яркость изображения изменена.';

        imagepng($im, 'sean.png');

    } else {
        echo 'Изменить яркость не удалось.';
    }

    ?>

Пример #3 Пример наложения фильтра функцией imagefilter() с фильтром colorize

    <?php

    $im = imagecreatefrompng('philip.png');

    /* R, G, B, so 0, 255, 0 is green */
    if ($im && imagefilter($im, IMG_FILTER_COLORIZE, 0, 255, 0)) {
        echo 'Изображение преобразовано к оттенкам зеленого.';

        imagepng($im, 'philip.png');
    } else {
        echo 'Преобразование не удалось.';
    }

    ?>

Пример #4 Пример наложения фильтра функцией imagefilter() с фильтром negate

    <?php

    // Определим функцию negate(), которую получится перенести в PHP
    // без функции imagefilter()
    function negate($im)
    {
        if (function_exists('imagefilter')) {
            return imagefilter($im, IMG_FILTER_NEGATE);
        }

        for ($x = 0; $x < imagesx($im); ++$x) {
            for ($y = 0; $y < imagesy($im); ++$y) {
                $index = imagecolorat($im, $x, $y);
                $rgb = imagecolorsforindex($index);
                $color = imagecolorallocate($im, 255 - $rgb['red'], 255 - $rgb['green'], 255 - $rgb['blue']);

                imagesetpixel($im, $x, $y, $color);
            }
        }

        return (true);
    }

    $im = imagecreatefromjpeg('kalle.jpg');

    if ($im && negate($im)) {
        echo 'Изображение инвертировано успешно.';

        imagejpeg($im, 'kalle.jpg', 100);
    } else {
        echo 'Инвертировать изображение не удалось.';
    }

    ?>

Пример #5 Пример наложения фильтра функцией imagefilter() с фильтром pixelate

    <?php

    // Загрузка PHP логотипа, нам нужно 2 штуки
    // для сравнения
    $logo1 = imagecreatefrompng('./php.png');
    $logo2 = imagecreatefrompng('./php.png');

    // Подопытный экземпляр
    $output = imagecreatetruecolor(imagesx($logo1) * 2, imagesy($logo1));

    // Применение пикселирования к каждому изображению с размером блока в 3 пикселя
    imagefilter($logo1, IMG_FILTER_PIXELATE, 3);
    imagefilter($logo2, IMG_FILTER_PIXELATE, 3, true);

    // Совмещение различий в выходном изображении
    imagecopy($output, $logo1, 0, 0, 0, 0, imagesx($logo1) - 1, imagesy($logo1) - 1);
    imagecopy($output, $logo2, imagesx($logo2), 0, 0, 0, imagesx($logo2) - 1, imagesy($logo2) - 1);

    // Вывод различий
    header('Content-Type: image/png');
    imagepng($output);

    ?>

Вывод приведённого примера будет похож на:

Пример #6 Пример наложения фильтра функцией imagefilter() с фильтром scatter

    <?php

    // Загрузка изображения
    $logo = imagecreatefrompng('./php.png');

    // Применение очень мягкого эффекта рассеивания к изображению
    imagefilter($logo, IMG_FILTER_SCATTER, 3, 5);

    // Вывов изображения с эффектом рассеивания
    header('Content-Type: image/png');
    imagepng($logo);

    ?>

Вывод приведённого примера будет похож на:

### Примечания

> Замечание: Результат фильтра `IMG_FILTER_SCATTER` всегда случайный.

### Смотрите также

- imageconvolution() - Наложение искривляющей матрицы 3х3, используя коэффициент и смещение

`↑` and `↓` to navigate • `Enter` to select • `Esc` to close • `/` to open