Funções de imagem

A classe Nette\Utils\Image simplifica a manipulação de imagens, tais como redimensionamento, corte, nitidez, desenho ou fusão de múltiplas imagens.

O PHP tem um extenso conjunto de funções para manipulação de imagens. Mas a API não é muito agradável. Não seria uma boa estrutura para se criar um API sexy.

Instalação:

composer require nette/utils

Os exemplos a seguir assumem que a seguinte classe está definida:

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

Criação de uma imagem

Vamos criar uma nova imagem colorida verdadeira, por exemplo, com dimensões de 100×200:

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

Opcionalmente, você pode especificar uma 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');

Salvar a imagem

A imagem pode ser salva em um arquivo:

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

Podemos especificar a qualidade de compressão na faixa 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 a partir da extensão do arquivo, ele poderá ser especificado por uma constante:

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

A imagem pode ser escrita em uma variável ao invés de em disco:

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

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

// envia cabeçalho Content-Type: imagem/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 compatíveis com sua versão do PHP, o que pode ser verificado usando a função isTypeSupported(). Não há suporte para animações.

Os formatos são representados pelas constantes ImageType::JPEG, ImageType::PNG, ImageType::GIF, ImageType::WEBP, ImageType::AVIF, e ImageType::BMP.

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

Precisa detectar o formato de uma imagem ao ser carregada? O método o retorna no segundo parâmetro:

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

A detecção real sem carregar a imagem é realizada por Image::detectTypeFromFile().

Redimensionamento de imagem

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

O método resize() é utilizado para o redimensionamento. Este é um exemplo de mudança de tamanho proporcional para que não exceda 500×300 pixels (ou a largura será exatamente 500px ou a altura será exatamente 300px, uma das dimensões é calculada para manter a relação de aspecto):

$image->resize(500, 300);

É possível definir apenas uma dimensão e a segunda será calculada:

$image->resize(500, null); // largura 500px, altura auto

$image->resize(null, 300); // largura auto, altura 300px

Qualquer dimensão pode ser especificada em porcentagens:

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

O comportamento de resize pode ser influenciado pelas seguintes bandeiras. Todos, exceto Image::Stretch, preservam a relação de aspecto.

Bandeira	Descrição
`Image::OrSmaller` (padrão)	as dimensões resultantes serão menores ou iguais, conforme especificado
`Image::OrBigger`	preenche a área de destino e possivelmente a estende em uma direção
`Image::Cover`	preenche toda a área e corta o que a excede
`Image::ShrinkOnly`	apenas balança para baixo (não estende uma pequena imagem)
`Image::Stretch`	não mantém a relação de aspecto

As bandeiras são passadas como o terceiro argumento da função:

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

As bandeiras podem ser combinadas:

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

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

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

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

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

Depois de reduzir a imagem, podemos melhorá-la através da nitidez:

$image->sharpen();

Cultivo

O método crop() é utilizado para o cultivo:

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

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 do CSS background-position:

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

A imagem também pode ser cortada automaticamente, por exemplo, bordas pretas cortadas:

$image->cropAuto(IMG_CROP_BLACK);

O método cropAuto() é um encapsulamento de objeto da função imagecropauto(), veja sua documentação para mais informações.

Cores

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

$color = ImageColor::rgb(255, 0, 0); // Red
$transparentBlue = ImageColor::rgb(0, 0, 255, 0.5); // Semi-transparent blue

O método ImageColor::hex() permite que você defina uma cor usando o formato hexadecimal, semelhante ao CSS. Ele é compatível com os formatos #rgb, #rrggbb, #rgba e #rrggbbaa:

$color = ImageColor::hex("#F00"); // Red
$transparentGreen = ImageColor::hex("#00FF0080"); // Semi-transparent green

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

Desenho e Edição

Você pode desenhar, escrever e usar todas as funções do PHP para manipulação de imagens, consulte Visão geral dos métodos, 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 seus substitutos na forma das funções rectangleWH() e filledRectangleWH().

Fundir várias imagens

Você pode facilmente colocar outra imagem dentro da imagem:

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

// as coordenadas também podem ser definidas em porcentagem
$blank->place($logo, '80%', '80%'); // perto do canto inferior direito

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

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

Tal API é realmente um prazer de usar, não é?

Visão geral dos métodos

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

Cria uma nova imagem colorida verdadeira das dimensões dadas. A cor padrão é o preto.

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

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

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

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

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

Esse recurso foi substituído pela classe ImageColor, consulte cores.

static typeToExtension (int $type): string

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

static typeToMimeType (int $type): string

Retorna o tipo de mime para o tipo fornecido.

static extensionToType (string $extension): int

Retorna o tipo de imagem de acordo com a extensão do arquivo.

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

Retorna o tipo de arquivo de 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 de imagem da string e, nos parâmetros $width e $height, também suas dimensões.

static isTypeSupported (int $type): bool

Determina se o tipo de imagem fornecido é compatível.

static getSupportedTypes(): array

Retorna uma matriz de tipos de imagens compatíveis (constantes ImageType::XXX).

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 fonte e tamanho especificados. Retorna uma matriz associativa contendo as chaves left, top, width, height. A margem esquerda pode ser negativa se o texto começar com uma saliência à esquerda.

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

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

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

Retorna a concatenação de duas matrizes de transformação afins, que é útil se múltiplas transformações devem ser aplicadas à mesma imagem de uma só vez. (mais)

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

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

alphaBlending (bool $on): void

Permite dois modos diferentes de desenhar em imagens truecolor. No modo de mistura, o componente de canal alfa da cor fornecida a todas as funções de desenho, como setPixel(), determina quanto da cor subjacente deve ser permitido brilhar. Como resultado, ele mistura automaticamente a cor existente naquele ponto com a cor do desenho, e armazena o resultado na imagem. O pixel resultante é opaco. No modo sem mistura, a cor do desenho é copiada literalmente com suas informações do canal alfa, substituindo o pixel de destino. O modo de mistura não está disponível quando se desenha em imagens de paleta. (mais)

antialias (bool $on): void

Ativar os métodos de desenho rápido antialiased para linhas e polígonos com fio. Ele não suporta componentes alfa. Funciona através de uma operação de mistura direta. Funciona apenas com imagens trégua-cores.

O uso de primitivos antialiased com cor de fundo transparente pode terminar com alguns resultados inesperados. O método de mistura utiliza a cor de fundo como qualquer outra cor. A falta de suporte de componentes alfa não permite um método antialiasing baseado em alfa. (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 dadas. (mais)

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

Retorna um identificador de cor que representa a cor composta dos componentes RGB. Ela deve ser chamada para criar cada cor a ser usada na imagem. (mais)

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

Comportamento idêntico ao de 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 no local especificado na imagem. Se a imagem for uma imagem verdadeira, esta função retorna o valor RGB daquele pixel como inteiro. Use bitshifting e mascaramento para acessar os distintos valores dos componentes vermelho, verde e azul: (mais)

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

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

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

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

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

Obtenha o índice da cor que tem a tonalidade, branco e negro mais próximo da cor dada. (mais)

colorDeallocate (int $color): void

Desaloca uma cor previamente alocada com 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+alfa especificada na paleta da imagem. (mais)

colorMatch (Image $image2): void

Faz com que as cores da versão paleta de uma imagem correspondam mais de perto à versão de cor verdadeira. (mais)

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

Retorna um índice de cor para uma 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 uma 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

Isto 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 em uma 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 sobre a imagem, usando o coeficiente dado e o offset. (mais)

Exige extensão de GD fundida, por isso não é certo que funcione em todos os lugares.

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

Copia uma parte de $src na imagem a partir das coordenadas $srcX, $srcY com uma largura de $srcW e uma altura de $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

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

Esta função é idêntica a copyMerge() exceto que ao fundir preserva a tonalidade da fonte ao converter os pixels de destino em 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 de pixels para que, em particular, a redução do tamanho de uma imagem ainda retenha uma grande quantidade de clareza.

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

Se as coordenadas de origem e destino e a largura e altura diferirem, será realizado o estiramento ou encolhimento apropriado do fragmento de imagem. As coordenadas se referem 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() tomará uma área retangular de $src de largura $srcW e altura $srcH na posição ($srcX,$srcY) e a colocará em uma área retangular de imagem de largura $dstW e altura $dstH na posição ($dstX,$dstY).

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

Cortar uma imagem para a área retangular dada. As dimensões podem ser passadas como números inteiros em pixels ou cadeias em porcentagem (ou seja, '50%').

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

Automaticamente cultiva uma imagem de acordo com o dado $mode. (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

Realiza um enchimento de inundação a partir da coordenada dada (no canto superior esquerdo é 0, 0) com o dado $color na imagem. (mais)

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

Desenha um arco parcial centrado na coordenada especificada na imagem. (mais)

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

Desenha uma elipse centrada na coordenada especificada na imagem. (mais)

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

Cria um polígono cheio na imagem de $. (mais)

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

Cria um retângulo preenchido com $color na imagem, começando em $x1 e $y1 e terminando em $x2 e $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 a partir dos pontos $left e $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 enchimento de inundação cuja cor da borda é definida por $border. O ponto de partida 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 dado $filtertype na imagem. (mais)

flip (int $mode): void

Vira a imagem usando o dado $mode. (mais)

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

Escreva o texto na figura. (mais)

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

Aplica correção gama à imagem dada uma gama de entrada e uma gama de saída. (mais)

getClip(): array

Recupera o atual retângulo de recorte, ou seja, a área além da qual nenhum pixel será desenhado. (mais)

getHeight(): int

Retorna a altura da imagem.

getImageResource(): resource|GdImage

Devolve o recurso original.

getWidth(): int

Retorna a largura da imagem.

interlace (?int $interlace=null): int

Liga ou desliga o fio entrelaçado. Se a parte entrelaçada for definida e a imagem for usada como uma imagem JPEG, a imagem é criada como um JPEG progressivo. (mais)

isTrueColor(): bool

Descobre se a imagem é uma verdadeira cor. (mais)

layerEffect (int $effect): void

Coloque a bandeira de mistura alfa para usar efeitos de camadas. (mais)

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

Traça uma linha entre os dois pontos dados. (mais)

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

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

paletteCopy (Image $source): void

Copia a paleta do site $source para a imagem. (mais)

paletteToTrueColor(): void

Converte uma imagem baseada em paleta, criada por funções como create(), para uma imagem colorida verdadeira, como createtruecolor(). (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 passadas como números inteiros em pixels ou cadeias em porcentagem (ou seja, '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 começando nas coordenadas especificadas. (mais)

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

Cria um retângulo nas coordenadas fornecidas.

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

Escala uma imagem, veja mais informações. As dimensões podem ser passadas como números inteiros em pixels ou cadeias em porcentagem (ou seja, '50%').

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

Permite definir e obter a resolução de uma imagem em DPI (dots per inch). Se nenhum dos parâmetros opcionais for dado, a resolução atual é devolvida como matriz indexada. Se apenas $resX for dado, a resolução horizontal e vertical é definida para este valor. Se ambos os parâmetros opcionais são dados, a resolução horizontal e vertical são definidas para estes valores, respectivamente.

A resolução só é usada como meta informação quando as imagens são lidas e escritas em formatos que suportam este tipo de informação (curently 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

Gira a imagem usando o dado $angle em graus. O centro de rotação é o centro da imagem, e a imagem rodada pode ter dimensões diferentes das da imagem original. (mais)

Exige extensão de GD fundida, por isso não é certo que funcione em todos os lugares.

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

Salva uma imagem em um arquivo.

A qualidade da compactação está no intervalo de 0 a 100 para JPEG (padrão 85), WEBP (padrão 80) e AVIF (padrão 30) e 0 a 9 para PNG (padrão 9). Se o tipo não for óbvio a partir da extensão do arquivo, você poderá especificá-lo usando uma das constantes do site ImageType.

saveAlpha (bool $saveflag): void

Define a bandeira que determina se deve reter informações completas do canal alfa (em oposição à transparência monocromática) ao salvar imagens PNG.

O alfabetização tem que ser desativado (alphaBlending(false)) para manter o canal alfa 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 dado. (mais)

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

Produz uma imagem para o navegador.

A qualidade da compactação está no intervalo de 0 a 100 para JPEG (padrão 85), WEBP (padrão 80) e AVIF (padrão 30) e 0 a 9 para PNG (padrão 9).

setBrush (Image $brush): void

Define a imagem do pincel a ser utilizada por todas as funções de desenho de linhas (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 retângulo de 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

Traça um pixel na coordenada especificada. (mais)

setStyle (array $style): void

Define o estilo a ser usado por todas as funções de desenho de linhas (tais 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 desenhadas ao desenhar retângulos, polígonos, arcos, etc. para $thickness pixels. (mais)

setTile (Image $tile): void

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

Uma telha é uma imagem usada para preencher uma área com um padrão repetido. Qualquer imagem pode ser usada como azulejo, e ao definir o índice de cor transparente da imagem do azulejo com colorTransparent(), um azulejo permite que certas partes da área subjacente brilhem através dele podem ser criadas. (mais)

sharpen(): Image

Aguça um pouco a imagem.

Requer uma extensão GD *Bundled GD, por isso não é certo que funcione em todos os lugares.

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

Produz uma imagem a fio.

A qualidade da compactação está no intervalo de 0 a 100 para JPEG (padrão 85), WEBP (padrão 80) e AVIF (padrão 30) e 0 a 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

Grava o texto fornecido na imagem. (mais)