Descrição

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

imagefilter() aplica o filtro informado em filter na imagem fornecida em image.

Parâmetros

image

Um objeto GdImage, retornado por uma das funções de criação de imagem, como imagecreatetruecolor().

filter

filter pode ser uma das seguintes constantes:

IMG_FILTER_NEGATE: Inverte todas as cores da imagem.
IMG_FILTER_GRAYSCALE: Converte a imagem em escala de cinza alterando os componentes vermelho, verde e azul para suas respectivas somas ponderadas, usando os mesmos coeficientes de cálculo de luminância (Y') da REC.601. Os componentes alfa são retidos. Para imagens de paleta, o resultado pode ser diferente devido a limitações da paleta.
IMG_FILTER_BRIGHTNESS: Altera o brilho da imagem. Use args para definir o nível de brilho. O intervalo de brilho é de -255 a 255.
IMG_FILTER_CONTRAST: Altera o contraste da imagem. Use args para definir o nível de contraste.
IMG_FILTER_COLORIZE: Parecida com IMG_FILTER_GRAYSCALE, exceto que pode-se especificar a cor. Use args, arg2 e arg3 na forma de red (vermelho), green (verde), blue (azul) e arg4 para o canal alpha (alfa). O intervalo de cada cor é de 0 a 255.
IMG_FILTER_EDGEDETECT: Usa detecção de borda para destacar as bordas da imagem.
IMG_FILTER_EMBOSS: Faz alto relevo da imagem.
IMG_FILTER_GAUSSIAN_BLUR: Desfoca a imagem usando o método gaussiano.
IMG_FILTER_SELECTIVE_BLUR: Desfoca a imagem.
IMG_FILTER_MEAN_REMOVAL: Usa a remoção de média para alcançar um efeito de "esboço".
IMG_FILTER_SMOOTH: Torna a imagem mais suave. Use args para definir o nível de suavidade.
IMG_FILTER_PIXELATE: Aplica efeito de pixelização à imagem, use args para definir o tamanho do bloco e arg2 para definir o modo do efeito de pixelização.
IMG_FILTER_SCATTER: Aplica efeito de dispersão à imagem, use args e arg2 para definir a intensidade do efeito e adicionalmente arg3 para aplicar o efeito somente em cores de pixels selecionadas.

args

IMG_FILTER_BRIGHTNESS: Nível de brilho.
IMG_FILTER_CONTRAST: Nível de contraste.
IMG_FILTER_COLORIZE: Valor do componente vermelho.
IMG_FILTER_SMOOTH: Nível de suavidade.
IMG_FILTER_PIXELATE: Tamanho do bloco em pixels.
IMG_FILTER_SCATTER: Nível de subtração de efeito. Não pode ser maior ou igual ao nível de adição de efeito definido com arg2.

arg2

IMG_FILTER_COLORIZE: Valor do componente verde.
IMG_FILTER_PIXELATE: Informa se deve ser usada efeito de pixelização avançada ou não (o padrão é false).
IMG_FILTER_SCATTER: Nível de adição de efeito.

arg3

IMG_FILTER_COLORIZE: Valor do componente azul.
IMG_FILTER_SCATTER: Array opcional indexado com valores de cores nas quais os efeitos serão aplicados.

arg4

IMG_FILTER_COLORIZE: Canal alfa, um valor entre 0 e 127. 0 indica completamente opaco e 127 indica completamente transparente.

Valor Retornado

Retorna true em caso de sucesso ou false em caso de falha.

Erros/Exceções

Lança um ValueError se sub ou plus puderem causar um estouro de limites com IMG_FILTER_SCATTER definido em filter.

Registro de Alterações

Versão Descrição

8.4.0 Agora lança um ValueError se sub ou plus puderem causar um estouro de limites com IMG_FILTER_SCATTER definido em filter.

8.0.0 O parâmetro image agora espera uma instância de GdImage; anteriormente, um resource gd válido era esperado.

7.4.0 Suporte a dispersão (IMG_FILTER_SCATTER) foi adicionado.

Versão	Descrição
8.4.0	Agora lança um ValueError se `sub` ou `plus` puderem causar um estouro de limites com `IMG_FILTER_SCATTER` definido em `filter`.
8.0.0	O parâmetro `image` agora espera uma instância de GdImage; anteriormente, um resource `gd` válido era esperado.
7.4.0	Suporte a dispersão (`IMG_FILTER_SCATTER`) foi adicionado.

Exemplos

Exemplo #1 Exemplo de escala de cinza com imagefilter()

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

if($im && imagefilter($im, IMG_FILTER_GRAYSCALE))
{
    echo 'Imagem convertida para escala de cinza.';

    imagepng($im, 'dave.png');
}
else
{
    echo 'Conversão para escala de cinza falhou.';
}
?>

Exemplo #2 Exemplo de brilho com imagefilter()

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

if($im && imagefilter($im, IMG_FILTER_BRIGHTNESS, 20))
{
    echo 'Brilho da imagem alterado.';

    imagepng($im, 'sean.png');
}
else
{
    echo 'Alteração no brilho da imagem falhou.';
}
?>

Exemplo #3 Exemplo de colorização com imagefilter()

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

/* R, G, B, portanto 0, 255, 0 é verde */
if($im && imagefilter($im, IMG_FILTER_COLORIZE, 0, 255, 0))
{
    echo 'Imagem tonalizada em verde com sucesso.';

    imagepng($im, 'philip.png');
}
else
{
    echo 'Tonalização em verde falhou.';
}
?>

Exemplo #4 Exemplo de inversão com imagefilter()

<?php
// Define a função de inversão de forma que seja portável
// para versões de php sem 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 'Imagem convertida com sucesso para cores invertidas.';

    imagejpeg($im, 'kalle.jpg', 100);
}
else
{
    echo 'Conversão para cores invertidas falhou.';
}
?>

Exemplo #5 Exemplo de pixelização com imagefilter()

<?php
// Carrega a logomarca do PHP, necessáio criar duas instâncias
// para mostrar as diferenças
$logo1 = imagecreatefrompng('./php.png');
$logo2 = imagecreatefrompng('./php.png');

// Cria a instância da imagem onde as diferenças serão
// mostradas
$output = imagecreatetruecolor(imagesx($logo1) * 2, imagesy($logo1));

// Aplica a pixelização para cada instância, com um bloco
// de tamanho 3
imagefilter($logo1, IMG_FILTER_PIXELATE, 3);
imagefilter($logo2, IMG_FILTER_PIXELATE, 3, true);

// Funde as diferenças na imagem de saída
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);

// Mostra a diferença
header('Content-Type: image/png');
imagepng($output);
?>

O exemplo acima produzirá algo semelhante a:

Exemplo #6 Exemplo de dispersão com imagefilter()

<?php
// Carrega a imagem
$logo = imagecreatefrompng('./php.png');

// Aplica um efeito bem leve de dispersão à imagem
imagefilter($logo, IMG_FILTER_SCATTER, 3, 5);

// Mostra a imagem com o efeito de dispersão
header('Content-Type: image/png');
imagepng($logo);
?>

O exemplo acima produzirá algo semelhante a:

Saída do exemplo: dispersão com imagefilter()

Notas

Nota: O resultado de IMG_FILTER_SCATTER é sempre aleatório.

Veja Também

imageconvolution() - Aplica uma matriz de convolução 3x3, usando coeficiente e deslocamento