Trabajar con imágenes

La clase Nette\Utils\Image simplifica la manipulación de imágenes: cambiar su tamaño, recortarlas, enfocarlas, dibujar en ellas o combinar varias.

PHP tiene un amplio conjunto de funciones para manipular imágenes. Su API, sin embargo, no es muy amable. No sería Nette Framework si no se hubiera sacado de la manga una API deliciosa.

Instalación:

composer require nette/utils

Los ejemplos siguientes suponen que está definido el siguiente alias de clase:

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

Crear una imagen

Cree una imagen nueva en color real, por ejemplo de 100×200:

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

Opcionalmente puede indicar el color de fondo (el predeterminado es negro):

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

O cargar una imagen desde un archivo:

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

Guardar la imagen

La imagen se puede guardar en un archivo:

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

Puede indicar la calidad de compresión en el rango 0–100 para JPEG (predeterminada 85), WEBP (predeterminada 80) y AVIF (predeterminada 30), y 0–9 para PNG (predeterminada 9):

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

Si el formato no queda claro por la extensión del archivo, se puede indicar con una constante:

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

En lugar de guardarla en disco, la imagen se puede escribir en una variable:

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

o enviarla directamente al navegador con la cabecera HTTP Content-Type adecuada:

// envía la cabecera Content-Type: image/png
$image->send(ImageType::PNG);

Formatos

Los formatos admitidos son JPEG, PNG, GIF, WebP, AVIF y BMP. Su versión de PHP debe admitirlos también, algo que puede verificar con la función isTypeSupported(). Las animaciones no están admitidas.

Los formatos se representan mediante las constantes ImageType::JPEG, ImageType::PNG, ImageType::GIF, ImageType::WEBP, ImageType::AVIF e ImageType::BMP.

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

¿Necesita detectar el formato de la imagen al cargarla? El método lo devuelve en el segundo parámetro:

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

La detección sin cargar la propia imagen la hace Image::detectTypeFromFile().

Cambiar el tamaño

Una operación habitual es cambiar el tamaño de una imagen. Las dimensiones actuales las devuelven los métodos getWidth() y getHeight().

Para cambiar el tamaño se usa el método resize(). Ejemplo de cambio proporcional para que la imagen no supere los 500×300 píxeles (o el ancho será exactamente 500 px, o la altura será exactamente 300 px; una de las dimensiones se calcula para mantener la proporción):

$image->resize(500, 300);

Es posible indicar solo una dimensión y que la otra se calcule automáticamente:

$image->resize(500, null); // ancho 500 px, alto calculado automáticamente

$image->resize(null, 300); // ancho calculado automáticamente, alto 300 px

Cualquiera de las dimensiones se puede indicar también en porcentaje:

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

El comportamiento de resize() se puede influir con las siguientes banderas. Todas ellas, salvo Image::Stretch, conservan la proporción.

Bandera	Descripción
`Image::OrSmaller` (predeterminada)	las dimensiones resultantes serán menores o iguales que las solicitadas
`Image::OrBigger`	rellena (y quizá supere en una dimensión) el área de destino
`Image::Cover`	rellena el área de destino y recorta lo que sobresalga
`Image::ShrinkOnly`	solo reduce (evita estirar una imagen pequeña)
`Image::Stretch`	no conserva la proporción

Las banderas se pasan como tercer argumento del método:

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

Las banderas se pueden combinar:

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

Las imágenes se pueden voltear en vertical o en horizontal indicando una de las dimensiones (o ambas) como número negativo:

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

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

$flipped = $image->resize(-125, 500); // redimensiona y voltea horizontalmente

Tras cambiar el tamaño de una imagen puede mejorar su aspecto con un enfoque suave:

$image->sharpen();

Recortar

Para recortar se usa el método crop():

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

Igual que en resize(), todos los valores se pueden indicar en porcentaje. Los porcentajes de $left y $top se calculan sobre el espacio restante, de forma parecida a la propiedad CSS background-position:

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

La imagen también se puede recortar automáticamente, por ejemplo para eliminar los bordes negros:

$image->cropAuto(IMG_CROP_BLACK);

El método cropAuto() es un envoltorio orientado a objetos de la función imagecropauto(); encontrará más información en su documentación.

Colores

El método ImageColor::rgb() le permite definir un color con valores de rojo, verde y azul (RGB). Opcionalmente puede indicar también un valor de transparencia, de 0 (totalmente transparente) a 1 (totalmente opaco), igual que en CSS.

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

El método ImageColor::hex() le permite definir un color en formato hexadecimal, como en CSS. Admite los formatos #rgb, #rrggbb, #rgba y #rrggbbaa:

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

Los colores se pueden usar en otros métodos, como ellipse(), fill(), etc.

Dibujar y editar

Tiene a su disposición todas las funciones de PHP para manipular imágenes, vea el Resumen de métodos, pero envueltas en un estilo orientado a objetos:

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

Como las funciones nativas de PHP para dibujar rectángulos resultan algo incómodas por la forma de indicar las coordenadas, la clase Image ofrece sustitutas: rectangleWH() y filledRectangleWH().

Combinar varias imágenes

Puede colocar fácilmente otra imagen sobre la actual:

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

// las coordenadas también se pueden indicar en porcentaje
$blank->place($logo, '80%', '80%'); // coloca cerca de la esquina inferior derecha

Al colocarla se respeta el canal alfa. Además, puede influir en la transparencia de la imagen colocada (para crear una marca de agua):

$blank->place($image, '80%', '80%', 25); // la opacidad es del 25 %

¡Usar una API así es un verdadero placer!

Resumen de métodos

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

Crea una imagen nueva en color real con las dimensiones dadas. El color predeterminado es el negro.

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

Lee una imagen desde un archivo y devuelve su tipo en $detectedFormat. Si pasa $warnings, los avisos no fatales del decodificador de imágenes se guardan ahí en lugar de emitirse como advertencia de PHP; queda en null cuando no hay ninguno.

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

Lee una imagen desde una cadena y devuelve su tipo en $detectedFormat. Si pasa $warnings, los avisos no fatales del decodificador de imágenes se guardan ahí en lugar de emitirse como advertencia de PHP; queda en null cuando no hay ninguno.

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

Esta función ha sido sustituida por la clase ImageColor, vea Colores.

static typeToExtension (int $type): string

Devuelve la extensión de archivo del tipo dado.

static typeToMimeType (int $type): string

Devuelve el tipo MIME del tipo dado.

static extensionToType (string $extension): int

Devuelve el tipo de imagen según la extensión del archivo.

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

Devuelve el tipo del archivo de imagen y, en los parámetros $width y $height, también sus dimensiones.

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

Devuelve el tipo de la imagen a partir de una cadena y, en los parámetros $width y $height, también sus dimensiones.

static isTypeSupported (int $type): bool

Comprueba si el tipo de imagen dado está admitido.

static getSupportedTypes(): array

Devuelve un array con los tipos de imagen admitidos.

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

Calcula las dimensiones del rectángulo que delimita el texto con una fuente y un tamaño dados. Devuelve un array asociativo con las claves left, top, width, height. El margen izquierdo puede ser negativo si el texto empieza con un saliente de kerning por la izquierda.

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

Devuelve una imagen con la imagen de origen transformada de forma afín, usando un área de recorte opcional. (más).

alphaBlending (bool $on): void

Permite dos modos distintos de dibujo en las imágenes en color real. En el modo de mezcla, la componente del canal alfa del color pasado a todas las funciones de dibujo, como setPixel(), determina cuánto debe transparentarse el color subyacente. Como resultado, mezcla automáticamente el color existente en ese punto con el color de dibujo y guarda el resultado en la imagen. El píxel resultante es opaco. En el modo sin mezcla, el color de dibujo se copia literalmente con la información de su canal alfa y sustituye al píxel de destino. El modo de mezcla no está disponible al dibujar en imágenes en paleta. (más)

antialias (bool $on): void

Activa los métodos rápidos de dibujo con suavizado para las líneas y los polígonos de alambre. No admite componentes alfa. Funciona mediante una operación directa de mezcla. Solo funciona con imágenes en color real.

Usar primitivas suavizadas con un color de fondo transparente puede acabar con resultados inesperados. El método de mezcla usa el color de fondo como cualquier otro color. La falta de soporte del componente alfa no permite un método de suavizado basado en alfa. (más)

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

Dibuja un arco circular centrado en las coordenadas dadas. (más)

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

Devuelve un identificador de color que representa el color compuesto por las componentes RGB dadas. Hay que llamarlo para crear cada color que vaya a usarse en la imagen. (más)

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

Se comporta igual que colorAllocate(), con el añadido del parámetro de transparencia $alpha. (más)

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

Devuelve el índice de color del píxel situado en la posición indicada de la imagen. Si la imagen es en color real, esta función devuelve el valor RGB de ese píxel como entero. Use desplazamientos de bits y máscaras para acceder por separado a las componentes de rojo, verde y azul: (más)

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

Devuelve el índice del color de la paleta de la imagen que está “más cerca” del valor RGB indicado. La “distancia” entre el color deseado y cada color de la paleta se calcula como si los valores RGB representasen puntos en un espacio tridimensional. (más)

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

Devuelve el índice del color de la paleta de la imagen que está “más cerca” del valor RGB y del nivel $alpha indicados. (más)

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

Obtiene el índice del color cuyo tono, blancura y negrura están más cerca del color dado. (más)

colorDeallocate (int $color): void

Libera un color reservado previamente con colorAllocate() o colorAllocateAlpha(). (más)

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

Devuelve el índice del color indicado en la paleta de la imagen. (más)

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

Devuelve el índice del color + alfa indicado en la paleta de la imagen. (más)

colorMatch (Image $image2): void

Aproxima los colores de la versión en paleta de una imagen a los de su versión en color real. (más)

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

Devuelve un índice de color para el color solicitado, ya sea el color exacto o la alternativa más próxima posible. (más)

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

Devuelve un índice de color para el color solicitado, ya sea el color exacto o la alternativa más próxima posible. (más)

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

Fija el índice indicado de la paleta al color indicado. (más)

colorsForIndex (int $index): array

Obtiene el color correspondiente a un índice dado. (más)

colorsTotal(): int

Devuelve el número de colores de la paleta de la imagen. (más)

colorTransparent (?int $color=null): int

Obtiene o fija el color transparente de la imagen. (más)

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

Aplica a la imagen una matriz de convolución, usando el coeficiente y el desplazamiento dados. (más)

Requiere la Bundled GD extension, así que puede no funcionar en todas partes.

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

Copia una parte de $src en la imagen, empezando en las coordenadas $srcX, $srcY, con un ancho de $srcW y una altura de $srcH. La porción definida se copiará en las coordenadas $dstX y $dstY. (más)

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 función es idéntica a copyMerge(), salvo que al mezclar conserva el tono del origen convirtiendo los píxeles de destino a escala de grises antes de la operación de copia. (más)

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

Copia una porción rectangular de una imagen a otra, interpolando suavemente los valores de los píxeles, de modo que, en particular, reducir el tamaño de una imagen conserve gran parte de su nitidez.

Dicho de otro modo, copyResampled() toma de $src un área rectangular de ancho $srcW y altura $srcH en la posición ($srcX,$srcY) y la coloca en un área rectangular de la imagen de ancho $dstW y altura $dstH en la posición ($dstX,$dstY).

Si las coordenadas y los anchos y alturas de origen y destino difieren, se realizará el estiramiento o la reducción correspondiente del fragmento de imagen. Las coordenadas se refieren a la esquina superior izquierda. Esta función se puede usar para copiar regiones dentro de la misma imagen, pero si las regiones se solapan los resultados serán impredecibles. (más)

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

Copia una porción rectangular de una imagen a otra. Dicho de otro modo, copyResized() toma de $src un área rectangular de ancho $srcW y altura $srcH en la posición ($srcX,$srcY) y la coloca en un área rectangular de la imagen de ancho $dstW y altura $dstH en la posición ($dstX,$dstY).

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

Recorta la imagen al área rectangular dada. Las dimensiones se pueden indicar como enteros en píxeles o como cadenas en porcentaje (por ejemplo, '50%').

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

Recorta automáticamente la imagen según el $mode dado. (más)

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

Dibuja una elipse centrada en las coordenadas indicadas. (más)

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

Realiza un relleno por inundación a partir de la coordenada dada (la esquina superior izquierda es 0, 0) con el color $color dado. (más)

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

Dibuja un arco parcial centrado en las coordenadas indicadas. (más)

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

Dibuja una elipse centrada en las coordenadas indicadas. (más)

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

Crea un polígono relleno en la imagen. (más)

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

Crea en la imagen un rectángulo relleno con $color, que empieza en el punto ($x1, $y1) y termina en ($x2, $y2). El punto (0, 0) es la esquina superior izquierda de la imagen. (más)

filledRectangleWH (int $x, int $y, int $width, int $height, ImageColor $color): void

Crea en la imagen un rectángulo relleno con $color, que empieza en el punto ($x, $y) y tiene un ancho $width y una altura $height. El punto (0, 0) es la esquina superior izquierda de la imagen.

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

Realiza un relleno por inundación cuyo color de borde se define con $borderColor. El punto de partida del relleno es ($x, $y) (la esquina superior izquierda es 0, 0) y la región se rellena con el color $color. (más)

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

Aplica a la imagen el filtro $filtertype dado. (más)

flip (int $mode): void

Voltea la imagen según el $mode dado. (más)

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

Escribe texto en la imagen. (más)

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

Aplica a la imagen una corrección gamma a partir de una gamma de entrada y otra de salida. (más)

getClip(): array

Obtiene el rectángulo de recorte actual, es decir, el área fuera de la cual no se dibujará ningún píxel. (más)

getHeight(): int

Devuelve la altura de la imagen.

getImageResource(): GdImage

Devuelve el recurso de imagen GD subyacente.

getWidth(): int

Devuelve el ancho de la imagen.

interlace (?int $interlace=null): int

Activa o desactiva el entrelazado. Si el entrelazado está activado y la imagen se guarda como JPEG, se guardará como JPEG progresivo. (más)

isTrueColor(): bool

Comprueba si la imagen es en color real. (más)

layerEffect (int $effect): void

Fija la bandera de mezcla alfa para usar efectos de capas. (más)

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

Dibuja una línea entre los dos puntos dados. (más)

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

Dibuja un polígono abierto en la imagen. A diferencia de polygon(), no se dibuja ninguna línea entre el último punto y el primero. (más)

paletteCopy (Image $source): void

Copia la paleta de $source a la imagen. (más)

paletteToTrueColor(): void

Convierte una imagen basada en paleta en una imagen en color real. (más)

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

Copia $image sobre la imagen actual en las coordenadas ($left, $top). Las coordenadas se pueden indicar como enteros en píxeles o como cadenas en porcentaje (por ejemplo, '50%').

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

Crea un polígono en la imagen. (más)

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

Crea un rectángulo en las coordenadas indicadas. (más)

rectangleWH (int $x, int $y, int $width, int $height, ImageColor $color): void

Crea un rectángulo en las coordenadas dadas usando ancho y altura.

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

Cambia el tamaño de la imagen, vea más información. Las dimensiones se pueden indicar como enteros en píxeles o como cadenas en porcentaje (por ejemplo, '50%').

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

Permite fijar y obtener la resolución de una imagen en DPI (puntos por pulgada). Si no se indica ninguno de los parámetros opcionales, se devuelve la resolución actual como array indexado. Si solo se indica $resX, la resolución horizontal y la vertical se fijan a ese valor. Si se indican ambos parámetros opcionales, la resolución horizontal y la vertical se fijan a esos valores, respectivamente.

La resolución solo se usa como metainformación cuando las imágenes se leen y se escriben en formatos que admiten este tipo de información (actualmente PNG y JPEG). No afecta a ninguna operación de dibujo. La resolución predeterminada de las imágenes nuevas es de 96 DPI. (más)

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

Rota la imagen el $angle dado en grados. El centro de rotación es el centro de la imagen, y la imagen rotada puede tener dimensiones distintas de las de la original. (más)

Requiere la Bundled GD extension, así que puede no funcionar en todas partes.

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

Guarda la imagen en un archivo.

La calidad de compresión va de 0 a 100 para JPEG (predeterminada 85), WEBP (predeterminada 80) y AVIF (predeterminada 30), y de 0 a 9 para PNG (predeterminada 9). Si el tipo no queda claro por la extensión del archivo, puede indicarlo con una de las constantes de ImageType.

saveAlpha (bool $saveflag): void

Fija la bandera que determina si debe guardarse la información completa del canal alfa (frente a la transparencia de un solo color) al guardar imágenes PNG.

Nette activa esta bandera en el constructor de Image, así que una imagen cargada o creada con fromFile(), fromString() o fromBlank() conserva su canal alfa. Tenga en cuenta que, con el modo de mezcla predeterminado, el alfa de un color dibujado solo sirve para mezclar el resultado y no se guarda, así que llame antes a alphaBlending(false) si la transparencia dibujada debe sobrevivir. (más)

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

Escala una imagen con el algoritmo de interpolación dado. (más)

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

Envía la imagen al navegador.

La calidad de compresión va de 0 a 100 para JPEG (predeterminada 85), WEBP (predeterminada 80) y AVIF (predeterminada 30), y de 0 a 9 para PNG (predeterminada 9).

setBrush (Image $brush): void

Fija la imagen de pincel que usarán todas las funciones de dibujo de líneas (como line() y polygon()) al dibujar con los colores especiales IMG_COLOR_BRUSHED o IMG_COLOR_STYLEDBRUSHED. (más)

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

Fija el rectángulo de recorte actual, es decir, el área fuera de la cual no se dibujará ningún píxel. (más)

setInterpolation (int $method=IMG_BILINEAR_FIXED): void

Fija el método de interpolación, que afecta a los métodos rotate() y affine(). (más)

getInterpolation(): int

Devuelve el método de interpolación actual que usan los métodos rotate() y affine().

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

Dibuja un píxel en la coordenada indicada. (más)

setStyle (array $style): void

Fija el estilo que usarán todas las funciones de dibujo de líneas (como line() y polygon()) al dibujar con el color especial IMG_COLOR_STYLED o líneas de imágenes con el color IMG_COLOR_STYLEDBRUSHED. (más)

setThickness (int $thickness): void

Fija en $thickness píxeles el grosor de las líneas dibujadas al trazar rectángulos, polígonos, arcos, etc. (más)

setTile (Image $tile): void

Fija la imagen de mosaico que usarán todas las funciones de relleno de regiones (como fill() y filledPolygon()) al rellenar con el color especial IMG_COLOR_TILED.

Un mosaico es una imagen que se usa para rellenar un área con un patrón repetido. Cualquier imagen puede servir de mosaico y, fijando con colorTransparent() el índice de color transparente de la imagen de mosaico, se puede crear un mosaico que deje transparentarse ciertas partes del área subyacente. (más)

sharpen(): Image

Enfoca la imagen.

Requiere la Bundled GD extension, así que puede no funcionar en todas partes.

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

Devuelve la imagen como cadena.

La calidad de compresión va de 0 a 100 para JPEG (predeterminada 85), WEBP (predeterminada 80) y AVIF (predeterminada 30), y de 0 a 9 para PNG (predeterminada 9).

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

Convierte una imagen en color real en una imagen en paleta. (más)

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

Escribe en la imagen el texto dado. (más)