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;

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, Image::rgb(125, 0, 0));

Ou carregamos a imagem de um arquivo:

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

Os formatos suportados são JPEG, PNG, GIF, WebP, AVIF e BMP, mas sua versão do PHP também deve apoiá-los (verifique a phpinfo(), seção GD). As animações não são suportadas.

Necessidade de detectar o formato da imagem ao carregar? O formato de retorno do método no segundo parâmetro:

$image = Image::fromFile('nette.jpg', $type);
// $type é Image::JPEG, Image::PNG, Image::GIF, Image::WEBP, Image::AVIF ou Image::BMP

Somente a detecção sem carregar a imagem é feita por Image::detectTypeFromFile().

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 pela extensão do arquivo, ele pode ser especificado por uma das constantes Image::JPEG, Image::PNG, Image::GIF, Image::WEBP, Image::AVIF, e Image::BMP:

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

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

$data = $image->toString(Image::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(Image::PNG);

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.

Desenho e Edição

Você pode desenhar, você pode escrever, você pode usar todas as funções PHP para trabalhar com imagens, tais como imagefilledellipse(), mas usando o estilo de objeto:

$image->filledEllipse($cx, $cy, $width, $height, Image::rgb(255, 0, 0, 63));

Veja Visão geral dos métodos.

Fundir várias imagens

Você pode facilmente colocar outra imagem dentro da imagem:

$logo = Image::fromFile('logo.png');
$blank = Image::fromBlank(320, 240, Image::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, array $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. Os tipos suportados são Image::JPEG, Image::PNG, Image::GIF, Image::WEBP, Image::AVIF e Image::BMP.

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

Lê uma imagem de um fio e retorna seu tipo em $detectedFormat. Os tipos suportados são Image::JPEG, Image::PNG, Image::GIF, Image::AVIF, Image::WEBP, , e Image::BMP.

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

Cria uma cor que pode ser usada em outros métodos, tais como ellipse(), fill() e assim por diante.

static typeToExtension(int $type): string

Devolve a extensão do arquivo para a constante Image::XXX dada.

static typeToMimeType(int $type): string

Devolve o tipo de mímica para a constante Image::XXX dada.

static extensionToType(string $extension): int

Retorna o tipo de imagem como uma constante Image::XXX 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 como constante Image::XXX 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 de corda como constante Image::XXX e nos parâmetros $width e $height também suas dimensões.

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 $x, int $y, int $w, int $h, int $start, int $end, int $color): void

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

char(int $font, int $x, int $y, string $char, int $color): void

Traça o primeiro caractere de $char na imagem com sua parte superior esquerda em $x,$y (parte superior esquerda é 0, 0) com a cor $color. (mais)

charUp(int $font, int $x, int $y, string $char, int $color): void

Traça o caracter $char verticalmente na coordenada especificada na imagem dada. (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, int $color=-1): Image

Automaticamente cultiva uma imagem de acordo com o dado $mode. (mais)

ellipse(int $cx, int $cy, int $w, int $h, int $color): void

Desenha uma elipse centrada nas coordenadas especificadas. (mais)

fill(int $x, int $y, int $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 $cx, int $cy, int $w, int $h, int $s, int $e, int $color, int $style): void

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

filledEllipse(int $cx, int $cy, int $w, int $h, int $color): void

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

filledPolygon(array $points, int $numPoints, int $color): void

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

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

Cria um retângulo preenchido com $color na imagem começando no ponto 1 e terminando no ponto 2. 0, 0 é o canto superior esquerdo da imagem. (mais)

fillToBorder(int $x, int $y, int $border, int $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(int $size, int $angle, int $x, int $y, int $col, string $fontFile, string $text, array $extrainfo=null): array

Escrever texto na imagem usando fontes usando FreeType 2. (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, int $color): void

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

openPolygon(array $points, int $numPoints, int $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, int $numPoints, int $color): void

Cria um polígono na imagem. (mais)

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

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

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 compressão está 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). Se o tipo não for óbvio a partir da extensão do arquivo, você pode especificá-lo usando uma das constantes Image::JPEG, Image::PNG, Image::GIF, Image::WEBP, Image::AVIF, e Image::BMP.

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=Image::JPEG, int $quality=null): void

Produz uma imagem para o navegador.

A qualidade da compressão está 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). O tipo é uma das constantes Image::JPEG, Image::PNG, Image::GIF, Image::AVIF, Image::WEBP, e Image::BMP.

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, int $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.

string(int $font, int $x, int $y, string $str, int $col): void

Traça um fio nas coordenadas dadas. (mais)

stringUp(int $font, int $x, int $y, string $s, int $col): void

Traça um cordel verticalmente nas coordenadas dadas. (mais)

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

Produz uma imagem a fio.

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

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

ttfText(int $size, int $angle, int $x, int $y, int $color, string $fontfile, string $text): array

Escreve o texto dado na imagem usando fontes TrueType. (mais)