Trabalhando com imagens

A classe Nette\Utils\Image simplifica a manipulação de imagens, como redimensionamento, recorte, nitidez, desenho ou combinação de várias imagens.

O PHP possui um extenso conjunto de funções para manipulação de imagens. Mas a sua API não é muito conveniente. Não seria o Nette Framework se não viesse com uma API sexy.

Instalação:

composer require nette/utils

Todos os exemplos assumem que um alias foi criado:

use Nette\Utils\Image;
use Nette\Utils\ImageColor;
use Nette\Utils\ImageType;

Criação de imagem

Criamos uma nova imagem true color, por exemplo, com dimensões 100×200:

$image = Image::fromBlank(100, 200);

Opcionalmente, pode-se especificar a cor de fundo (o padrão é preto):

$image = Image::fromBlank(100, 200, ImageColor::rgb(125, 0, 0));

Ou carregamos a imagem de um arquivo:

$image = Image::fromFile('nette.jpg');

Salvando a imagem

A imagem pode ser salva em um arquivo:

$image->save('resampled.jpg');

Podemos especificar a qualidade da compressão na faixa de 0..100 para JPEG (padrão 85), WEBP (padrão 80) e AVIF (padrão 30) e 0..9 para PNG (padrão 9):

$image->save('resampled.jpg', 80); // JPEG, qualidade 80%

Se o formato não for óbvio pela extensão do arquivo, ele pode ser especificado por uma constante:

$image->save('resampled.tmp', null, ImageType::JPEG);

A imagem pode ser escrita em uma variável em vez de no disco:

$data = $image->toString(ImageType::JPEG, 80); // JPEG, qualidade 80%

ou enviada diretamente para o navegador com o cabeçalho HTTP Content-Type apropriado:

// envia o cabeçalho Content-Type: image/png
$image->send(ImageType::PNG);

Formatos

Os formatos suportados são JPEG, PNG, GIF, WebP, AVIF e BMP, no entanto, eles também devem ser suportados pela sua versão do PHP, o que pode ser verificado com a função isTypeSupported(). Animações não são suportadas.

O formato é representado pelas constantes ImageType::JPEG, ImageType::PNG, ImageType::GIF, ImageType::WEBP, ImageType::AVIF e ImageType::BMP.

$supported = Image::isTypeSupported(ImageType::JPEG);

Precisa detectar o formato da imagem ao carregar? O método o retorna no segundo parâmetro:

$image = Image::fromFile('nette.jpg', $type);

A detecção por si só, sem carregar a imagem, é feita por Image::detectTypeFromFile().

Redimensionamento

Uma operação comum é redimensionar a imagem. As dimensões atuais são retornadas pelos métodos getWidth() e getHeight().

O método resize() é usado para a alteração. Exemplo de redimensionamento proporcional para que não exceda as dimensões de 500×300 pixels (ou a largura será exatamente 500 px ou a altura será exatamente 300 px, uma das dimensões será calculada para manter a proporção):

$image->resize(500, 300);

É possível especificar apenas uma dimensão e a outra será calculada:

$image->resize(500, null); // largura 500px, altura será calculada

$image->resize(null, 300); // largura será calculada, altura 300px

Qualquer dimensão também pode ser especificada em porcentagem:

$image->resize('75%', 300); // 75 % × 300px

O comportamento de resize pode ser influenciado pelos seguintes flags. Todos, exceto Image::Stretch, mantêm a proporção.

Os flags são especificados como o terceiro argumento da função:

$image->resize(500, 300, Image::OrBigger);

Os flags podem ser combinados:

$image->resize(500, 300, Image::ShrinkOnly | Image::Stretch);

As imagens podem ser invertidas verticalmente ou horizontalmente especificando uma das dimensões (ou ambas) como um número negativo:

$flipped = $image->resize(null, '-100%'); // inverter verticalmente

$flipped = $image->resize('-100%', '-100%'); // rotacionar 180°

$flipped = $image->resize(-125, 500); // redimensionar e inverter horizontalmente

Após reduzir a imagem, é possível melhorar sua aparência com uma leve nitidez:

$image->sharpen();

Recorte

O método crop() é usado para recortar:

$image->crop($left, $top, $width, $height);

Assim como em resize(), todos os valores podem ser especificados em porcentagens. As porcentagens para $left e $top são calculadas a partir do espaço restante, semelhante à propriedade CSS background-position:

$image->crop('100%', '50%', '80%', '80%');

A imagem também pode ser recortada automaticamente, por exemplo, recortando as bordas pretas:

$image->cropAuto(IMG_CROP_BLACK);

O método cropAuto() é um substituto orientado a objetos para a função imagecropauto(), você pode encontrar mais informações em sua documentação.

Cores

O método ImageColor::rgb() permite definir uma cor usando os valores de vermelho, verde e azul (RGB). Opcionalmente, você também pode especificar o valor de transparência na faixa de 0 (totalmente transparente) a 1 (totalmente opaco), assim como no CSS.

$color = ImageColor::rgb(255, 0, 0); // Vermelho
$transparentBlue = ImageColor::rgb(0, 0, 255, 0.5); // Azul semitransparente

O método ImageColor::hex() permite definir uma cor usando o formato hexadecimal, semelhante ao CSS. Suporta os formatos #rgb, #rrggbb, #rgba e #rrggbbaa:

$color = ImageColor::hex("#F00"); // Vermelho
$transparentGreen = ImageColor::hex("#00FF0080"); // Verde semitransparente

As cores podem ser usadas em outros métodos, como ellipse(), fill(), etc.

Desenho e edições

Você pode desenhar e escrever. Todas as funções PHP para trabalhar com imagens estão disponíveis para você, veja Přehled metod, mas em um invólucro orientado a objetos:

$image->filledEllipse($centerX, $centerY, $width, $height, ImageColor::rgb(255, 0, 0));

Como as funções PHP para desenhar retângulos são impraticáveis devido à especificação de coordenadas, a classe Image oferece substitutos na forma das funções rectangleWH() e filledRectangleWH().

Combinação de múltiplas imagens

É fácil inserir outra imagem em uma imagem:

$logo = Image::fromFile('logo.png');
$blank = Image::fromBlank(320, 240, ImageColor::rgb(52, 132, 210));

// as coordenadas podem ser especificadas novamente em porcentagens
$blank->place($logo, '80%', '80%'); // inserimos perto do canto inferior direito

Ao inserir, o canal alfa é respeitado, além disso, podemos influenciar a transparência da imagem inserida (criamos a chamada marca d'água):

$blank->place($image, '80%', '80%', 25); // a transparência é de 25%

É realmente um prazer usar essa API!

Visão geral dos métodos

static fromBlank (int $width, int $height, ?ImageColor $color=null): Image

Cria uma nova imagem true color das dimensões fornecidas. A cor padrão é preta.

static fromFile (string $file, int &$detectedFormat=null): Image

Carrega uma imagem de um arquivo e retorna seu tipo em $detectedFormat.

static fromString (string $s, int &$detectedFormat=null): Image

Carrega uma imagem de uma string e retorna seu tipo em $detectedFormat.

static rgb (int $red, int $green, int $blue, int $transparency=0): array

Esta função foi substituída pela classe ImageColor, veja cores.

static typeToExtension (int $type): string

Retorna a extensão do arquivo para o tipo fornecido.

static typeToMimeType (int $type): string

Retorna o tipo mime para o tipo fornecido.

static extensionToType (string $extension): int

Retorna o tipo da imagem com base na extensão do arquivo.

static detectTypeFromFile (string $file, int &$width=null, int &$height=null): ?int

Retorna o tipo da imagem e, nos parâmetros $width e $height, também suas dimensões.

static detectTypeFromString (string $s, int &$width=null, int &$height=null): ?int

Retorna o tipo da imagem a partir de uma string e, nos parâmetros $width e $height, também suas dimensões.

static isTypeSupported (int $type): bool

Verifica se o tipo de imagem fornecido é suportado.

static getSupportedTypes(): array

Retorna um array dos tipos de imagem suportados.

static calculateTextBox (string $text, string $fontFile, float $size, float $angle=0, array $options=[]): array

Calcula as dimensões do retângulo que envolve o texto em uma determinada fonte e tamanho. Retorna um array associativo contendo as chaves left, top, width, height. A margem esquerda pode ser negativa se o texto começar com um kerning esquerdo.

affine (array $affine, ?array $clip=null): Image

Retorna uma imagem contendo a imagem src transformada afinamente usando uma área de recorte opcional. (mais).

affineMatrixConcat (array $m1, array $m2): array

Retorna a concatenação de duas matrizes de transformação afim, o que é útil se várias transformações devem ser aplicadas à mesma imagem de uma vez. (mais)

affineMatrixGet (int $type, ?mixed $options=null): array

Retorna uma matriz de transformação afim. (mais)

alphaBlending (bool $on): void

Permite dois modos diferentes de desenho em imagens truecolor. No modo de mesclagem, o componente do canal alfa da cor usada em todas as funções de desenho, como setPixel(), determina até que ponto a cor base deve ser permitida a transparecer. Como resultado, a cor existente neste ponto é automaticamente misturada com a cor desenhada e o resultado é salvo na imagem. O pixel resultante é opaco. No modo sem mesclagem, a cor desenhada é copiada literalmente com as informações do canal alfa e substitui o pixel de destino. O modo de mesclagem não está disponível ao desenhar em imagens de paleta. (mais)

antialias (bool $on): void

Ativa o desenho de linhas e polígonos suavizados. Não suporta canais alfa. Funciona apenas com imagens truecolor.

O uso de primitivas suavizadas com uma cor de fundo transparente pode resultar em alguns resultados inesperados. O método de mesclagem usa a cor de fundo como todas as outras cores. (mais)

arc (int $centerX, int $centerY, int $width, int $height, int $startAngle, int $endAngle, ImageColor $color): void

Desenha um arco de círculo centrado nas coordenadas fornecidas. (mais)

colorAllocate (int $red, int $green, int $blue): int

Retorna um identificador de cor representando a cor composta pelos componentes RGB fornecidos. Deve ser chamado para criar cada cor a ser usada na imagem. (mais)

colorAllocateAlpha (int $red, int $green, int $blue, int $alpha): int

Comporta-se da mesma forma que colorAllocate() com a adição do parâmetro de transparência $alpha. (mais)

colorAt (int $x, int $y): int

Retorna o índice da cor do pixel na localização especificada na imagem. Se a imagem for truecolor, esta função retorna o valor RGB desse pixel como um inteiro. Use deslocamento de bits e mascaramento de bits para acessar os valores dos componentes vermelho, verde e azul separadamente: (mais)

colorClosest (int $red, int $green, int $blue): int

Retorna o índice da cor na paleta da imagem que está “mais próxima” do valor RGB especificado. A “distância” entre a cor desejada e cada cor na paleta é calculada como se os valores RGB representassem pontos em um espaço tridimensional. (mais)

colorClosestAlpha (int $red, int $green, int $blue, int $alpha): int

Retorna o índice da cor na paleta da imagem que está “mais próxima” do valor RGB especificado e do nível $alpha. (mais)

colorClosestHWB (int $red, int $green, int $blue): int

Obtém o índice da cor que tem a matiz, o branco e o preto mais próximos da cor fornecida. (mais)

colorDeallocate (int $color): void

Desaloca uma cor previamente alocada usando colorAllocate() ou colorAllocateAlpha(). (mais)

colorExact (int $red, int $green, int $blue): int

Retorna o índice da cor especificada na paleta da imagem. (mais)

colorExactAlpha (int $red, int $green, int $blue, int $alpha): int

Retorna o índice da cor especificada + alfa na paleta da imagem. (mais)

colorMatch (Image $image2): void

Corresponde as cores da paleta à segunda imagem. (mais)

colorResolve (int $red, int $green, int $blue): int

Retorna um índice de cor para a cor solicitada, seja a cor exata ou a alternativa mais próxima possível. (mais)

colorResolveAlpha (int $red, int $green, int $blue, int $alpha): int

Retorna um índice de cor para a cor solicitada, seja a cor exata ou a alternativa mais próxima possível. (mais)

colorSet (int $index, int $red, int $green, int $blue): void

Define o índice especificado na paleta para a cor especificada. (mais)

colorsForIndex (int $index): array

Obtém a cor para um índice especificado. (mais)

colorsTotal(): int

Retorna o número de cores na paleta de imagens. (mais)

colorTransparent (?int $color=null): int

Obtém ou define a cor transparente na imagem. (mais)

convolution (array $matrix, float $div, float $offset): void

Aplica uma matriz de convolução na imagem, usando o coeficiente e o deslocamento fornecidos. (mais)

Requer a presença da Extensão GD Agrupada, portanto, pode não funcionar em todos os lugares.

copy (Image $src, int $dstX, int $dstY, int $srcX, int $srcY, int $srcW, int $srcH): void

Copia parte de $src para a imagem começando nas coordenadas $srcX, $srcY com largura $srcW e altura $srcH. A parte definida será copiada para as coordenadas $dstX e $dstY. (mais)

copyMerge (Image $src, int $dstX, int $dstY, int $srcX, int $srcY, int $srcW, int $srcH, int $opacity): void

Copia parte de $src para a imagem começando nas coordenadas $srcX, $srcY com largura $srcW e altura $srcH. A parte definida será copiada para as coordenadas $dstX e $dstY. (mais)

copyMergeGray (Image $src, int $dstX, int $dstY, int $srcX, int $srcY, int $srcW, int $srcH, int $opacity): void

Copia parte de $src para a imagem começando nas coordenadas $srcX, $srcY com largura $srcW e altura $srcH. A parte definida será copiada para as coordenadas $dstX e $dstY.

Esta função é idêntica a copyMerge() com a exceção de que, ao mesclar, preserva a matiz da fonte convertendo os pixels de destino para escala de cinza antes da operação de cópia. (mais)

copyResampled (Image $src, int $dstX, int $dstY, int $srcX, int $srcY, int $dstW, int $dstH, int $srcW, int $srcH): void

Copia uma porção retangular de uma imagem para outra imagem, interpolando suavemente os valores dos pixels para que, em particular, a redução do tamanho de uma imagem ainda retenha grande clareza.

Em outras palavras, copyResampled() pega uma área retangular de $src de largura $srcW e altura $srcH na posição ($srcX, $srcY) e a coloca em uma área retangular da imagem de largura $dstW e altura $dstH na posição ($dstX, $dstY).

Se as coordenadas de origem e destino, largura e altura diferirem, um alongamento ou encolhimento apropriado do fragmento da imagem será realizado. As coordenadas referem-se ao canto superior esquerdo. Esta função pode ser usada para copiar regiões dentro da mesma imagem, mas se as regiões se sobrepuserem, os resultados serão imprevisíveis. (mais)

copyResized (Image $src, int $dstX, int $dstY, int $srcX, int $srcY, int $dstW, int $dstH, int $srcW, int $srcH): void

Copia uma porção retangular de uma imagem para outra imagem. Em outras palavras, copyResized() pega uma área retangular de $src de largura $srcW e altura $srcH na posição ($srcX, $srcY) e a coloca em uma área retangular da imagem de largura $dstW e altura $dstH na posição ($dstX, $dstY).

Se as coordenadas de origem e destino, largura e altura diferirem, um alongamento ou encolhimento apropriado do fragmento da imagem será realizado. As coordenadas referem-se ao canto superior esquerdo. Esta função pode ser usada para copiar regiões dentro da mesma imagem, mas se as regiões se sobrepuserem, os resultados serão imprevisíveis. (mais)

crop (int|string $left, int|string $top, int|string $width, int|string $height): Image

Recorta uma imagem para a área retangular fornecida. As dimensões podem ser especificadas como inteiros em pixels ou strings em porcentagens (por exemplo, '50%').

cropAuto (int $mode=-1, float $threshold=.5, ?ImageColor $color=null): Image

Recorta automaticamente uma imagem de acordo com o $mode fornecido. (mais)

ellipse (int $centerX, int $centerY, int $width, int $height, ImageColor $color): void

Desenha uma elipse centrada nas coordenadas especificadas. (mais)

fill (int $x, int $y, ImageColor $color): void

Preenche uma região começando na coordenada fornecida (canto superior esquerdo é 0, 0) com a $color fornecida. (mais)

filledArc (int $centerX, int $centerY, int $width, int $height, int $startAngle, int $endAngle, ImageColor $color, int $style): void

Desenha um arco parcial centrado nas coordenadas especificadas. (mais)

filledEllipse (int $centerX, int $centerY, int $width, int $height, ImageColor $color): void

Desenha uma elipse preenchida centrada nas coordenadas especificadas. (mais)

filledPolygon (array $points, ImageColor $color): void

Cria um polígono preenchido na imagem. (mais)

filledRectangle (int $x1, int $y1, int $x2, int $y2, ImageColor $color): void

Cria um retângulo preenchido com $color na imagem começando no ponto $x1 & $y1 e terminando no ponto $x2 & $y2. O ponto 0, 0 é o canto superior esquerdo da imagem. (mais)

filledRectangleWH (int $left, int $top, int $width, int $height, ImageColor $color): void

Cria um retângulo preenchido com $color na imagem começando no ponto $left & $top com largura $width e altura $height. O ponto 0, 0 é o canto superior esquerdo da imagem.

fillToBorder (int $x, int $y, int $border, ImageColor $color): void

Realiza um preenchimento cuja cor da borda é definida por $border. O ponto inicial para o preenchimento é $x, $y (canto superior esquerdo é 0, 0) e a região é preenchida com a cor $color. (mais)

filter (int $filtertype, int …$args): void

Aplica o filtro $filtertype fornecido à imagem. (mais)

flip (int $mode): void

Inverte a imagem usando o $mode fornecido. (mais)

ftText (float $size, float $angle, int $x, int $y, ImageColor $color, string $fontFile, string $text, array $options=[]): array

Escreve texto na imagem. (mais)

gammaCorrect (float $inputgamma, float $outputgamma): void

Aplica correção gama à imagem em relação ao gama de entrada e saída. (mais)

getClip(): array

Retorna o recorte atual, ou seja, a área além da qual nenhum pixel será desenhado. (mais)

getHeight(): int

Retorna a altura da imagem.

getImageResource(): resource|GdImage

Retorna o recurso original.

getWidth(): int

Retorna a largura da imagem.

interlace (?int $interlace=null): int

Ativa ou desativa o modo entrelaçado. Se o modo entrelaçado estiver definido e a imagem for salva como JPEG, ela será salva como JPEG progressivo. (mais)

isTrueColor(): bool

Verifica se a imagem é truecolor. (mais)

layerEffect (int $effect): void

Define o sinalizador de mesclagem alfa para usar efeitos de camadas. (mais)

line (int $x1, int $y1, int $x2, int $y2, ImageColor $color): void

Desenha uma linha entre dois pontos fornecidos. (mais)

openPolygon (array $points, ImageColor $color): void

Desenha um polígono aberto na imagem. Ao contrário de polygon(), nenhuma linha é desenhada entre o último e o primeiro ponto. (mais)

paletteCopy (Image $source): void

Copia a paleta de $source para a imagem. (mais)

paletteToTrueColor(): void

Converte uma imagem baseada em paleta em uma imagem truecolor. (mais)

place (Image $image, int|string $left=0, int|string $top=0, int $opacity=100): Image

Copia $image para a imagem nas coordenadas $left e $top. As coordenadas podem ser especificadas como inteiros em pixels ou strings em porcentagens (por exemplo, '50%').

polygon (array $points, ImageColor $color): void

Cria um polígono na imagem. (mais)

rectangle (int $x1, int $y1, int $x2, int $y2, ImageColor $color): void

Cria um retângulo nas coordenadas especificadas. (mais)

rectangleWH (int $left, int $top, int $width, int $height, ImageColor $color): void

Cria um retângulo nas coordenadas especificadas.

resize (int|string $width, int|string $height, int $flags=Image::OrSmaller): Image

Redimensiona a imagem, mais informações. As dimensões podem ser especificadas como inteiros em pixels ou strings em porcentagens (por exemplo, '50%').

resolution (?int $resX=null, ?int $resY=null): mixed

Define ou retorna a resolução da imagem em DPI (pontos por polegada). Se nenhum dos parâmetros opcionais for especificado, a resolução atual é retornada como um array indexado. Se apenas $resX for especificado, as resoluções horizontal e vertical são definidas para este valor. Se ambos os parâmetros opcionais forem especificados, as resoluções horizontal e vertical são definidas para esses valores.

A resolução é usada apenas como metainformação quando as imagens são lidas e escritas em formatos que suportam este tipo de informação (atualmente PNG e JPEG). Não afeta nenhuma operação de desenho. A resolução padrão para novas imagens é 96 DPI. (mais)

rotate (float $angle, int $backgroundColor): Image

Rotaciona a imagem usando o $angle especificado em graus. O centro de rotação é o centro da imagem e a imagem rotacionada pode ter dimensões diferentes da imagem original. (mais)

Requer a presença da Extensão GD Agrupada, portanto, pode não funcionar em todos os lugares.

save (string $file, ?int $quality=null, ?int $type=null): void

Salva a imagem em um arquivo.

A qualidade da compressão está na faixa de 0..100 para JPEG (padrão 85), WEBP (padrão 80) e AVIF (padrão 30) e 0..9 para PNG (padrão 9). Se o tipo não for óbvio pela extensão do arquivo, você pode especificá-lo usando uma das constantes ImageType.

saveAlpha (bool $saveflag): void

Define o sinalizador se deve preservar informações completas do canal alfa ao salvar imagens PNG (em oposição à transparência de cor única).

A mesclagem alfa deve ser desativada (alphaBlending(false)) para que o canal alfa seja mantido em primeiro lugar. (mais)

scale (int $newWidth, int $newHeight=-1, int $mode=IMG_BILINEAR_FIXED): Image

Escala uma imagem usando o algoritmo de interpolação fornecido. (mais)

send (int $type=ImageType::JPEG, ?int $quality=null): void

Envia a imagem para o navegador.

A qualidade da compressão está na faixa de 0..100 para JPEG (padrão 85), WEBP (padrão 80) e AVIF (padrão 30) e 0..9 para PNG (padrão 9).

setBrush (Image $brush): void

Define a imagem do pincel a ser usada em todas as funções de desenho de linha (como line() e polygon()) ao desenhar com as cores especiais IMG_COLOR_BRUSHED ou IMG_COLOR_STYLEDBRUSHED. (mais)

setClip (int $x1, int $y1, int $x2, int $y2): void

Define o recorte atual, ou seja, a área além da qual nenhum pixel será desenhado. (mais)

setInterpolation (int $method=IMG_BILINEAR_FIXED): void

Define o método de interpolação, que afeta os métodos rotate() e affine(). (mais)

setPixel (int $x, int $y, ImageColor $color): void

Desenha um pixel na coordenada especificada. (mais)

setStyle (array $style): void

Define o estilo a ser usado por todas as funções de desenho de linha (como line() e polygon()) ao desenhar com a cor especial IMG_COLOR_STYLED ou linhas de imagens com a cor IMG_COLOR_STYLEDBRUSHED. (mais)

setThickness (int $thickness): void

Define a espessura das linhas ao desenhar retângulos, polígonos, arcos, etc. para $thickness pixels. (mais)

setTile (Image $tile): void

Define a imagem do ladrilho a ser usada em todas as funções de preenchimento de região (como fill() e filledPolygon()) ao preencher com a cor especial IMG_COLOR_TILED.

Um ladrilho é uma imagem usada para preencher uma área com um padrão repetido. Qualquer imagem pode ser usada como ladrilho e, definindo o índice de cor transparente da imagem do ladrilho com colorTransparent(), pode-se criar um ladrilho onde certas partes da área subjacente transparecerão. (mais)

sharpen(): Image

Torna a imagem mais nítida.

Requer a presença da Extensão GD Agrupada, portanto, pode não funcionar em todos os lugares.

toString (int $type=ImageType::JPEG, ?int $quality=null): string

Salva a imagem em uma string.

A qualidade da compressão está na faixa de 0..100 para JPEG (padrão 85), WEBP (padrão 80) e AVIF (padrão 30) e 0..9 para PNG (padrão 9).

trueColorToPalette (bool $dither, int $ncolors): void

Converte uma imagem truecolor em uma imagem de paleta. (mais)

ttfText (float $size, float $angle, int $x, int $y, ImageColor $color, string $fontFile, string $text, array $options=[]): array

Imprime o texto fornecido na imagem. (mais)