Trabajando con imágenes

La clase Nette\Utils\Image simplifica la manipulación de imágenes, como el cambio de tamaño, recorte, enfoque, dibujo o la combinación de múltiples imágenes.

PHP tiene un amplio conjunto de funciones para la manipulación de imágenes. Pero su API no es muy cómoda. No sería Nette Framework si no viniera con una API sexy.

Instalación:

composer require nette/utils

Todos los ejemplos asumen que se ha creado un alias:

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

Creación de una imagen

Creamos una nueva imagen true color, por ejemplo, con dimensiones de 100×200:

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

Opcionalmente, se puede especificar el color de fondo (el predeterminado es negro):

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

O cargamos la imagen desde un archivo:

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

Guardado de la imagen

La imagen se puede guardar en un archivo:

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

Podemos especificar la calidad de compresión en el rango de 0..100 para JPEG (por defecto 85), WEBP (por defecto 80) y AVIF (por defecto 30) y 0..9 para PNG (por defecto 9):

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

Si el formato no es evidente por la extensión del archivo, se puede especificar mediante una constante:

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

La imagen se puede escribir en una variable en lugar de en el disco:

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

o enviar directamente al navegador con la cabecera HTTP Content-Type apropiada:

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

Formatos

Los formatos soportados son JPEG, PNG, GIF, WebP, AVIF y BMP, sin embargo, su versión de PHP también debe soportarlos, lo cual puede verificar con la función isTypeSupported(). Las animaciones no son soportadas.

El formato está representado por las constantes ImageType::JPEG, ImageType::PNG, ImageType::GIF, ImageType::WEBP, ImageType::AVIF y ImageType::BMP.

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

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

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

La detección en sí, sin cargar la imagen, la realiza Image::detectTypeFromFile().

Cambio de tamaño

Una operación común es el cambio de tamaño de la imagen. Las dimensiones actuales son devueltas por los métodos getWidth() y getHeight().

El método resize() se utiliza para el cambio. Ejemplo de cambio de tamaño proporcional para que no exceda las dimensiones de 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 relación de aspecto):

$image->resize(500, 300);

Es posible especificar solo una dimensión y la otra se calculará:

$image->resize(500, null); // ancho 500px, la altura se calculará

$image->resize(null, 300); // el ancho se calculará, altura 300px

Cualquier dimensión también se puede especificar en porcentajes:

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

El comportamiento de resize puede ser influenciado por las siguientes banderas. Todas excepto Image::Stretch mantienen la relación de aspecto.

Bandera	Descripción
`Image::OrSmaller` (por defecto)	las dimensiones resultantes serán menores o iguales a las dimensiones solicitadas
`Image::OrBigger`	llenará (y posiblemente excederá en una dimensión) el área de destino
`Image::Cover`	llenará el área de destino y recortará lo que exceda
`Image::ShrinkOnly`	solo reducción (evita estirar una imagen pequeña)
`Image::Stretch`	no mantener la relación de aspecto

Las banderas se especifican como el tercer argumento de la función:

$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 vertical u horizontalmente especificando una de las dimensiones (o ambas) como un número negativo:

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

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

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

Después de reducir el tamaño de la imagen, es posible mejorar su apariencia con un ligero enfoque:

$image->sharpen();

Recorte

El método crop() se utiliza para recortar:

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

Similar a resize(), todos los valores pueden especificarse en porcentajes. Los porcentajes para $left y $top se calculan a partir del espacio restante, similar a la propiedad CSS background-position:

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

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

$image->cropAuto(IMG_CROP_BLACK);

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

Colores

El método ImageColor::rgb() le permite definir un color utilizando los valores rojo, verde y azul (RGB). Opcionalmente, también puede especificar un valor de transparencia en el rango de 0 (completamente transparente) a 1 (completamente 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 utilizando el formato hexadecimal, similar a CSS. Soporta 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.

Dibujo y edición

Puedes dibujar, puedes escribir, pero no arranques las hojas. Todas las funciones de PHP para trabajar con imágenes están disponibles para usted, ver #Resumen de métodos, pero en una envoltura orientada a objetos:

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

Dado que las funciones de PHP para dibujar rectángulos no son prácticas debido a la especificación de coordenadas, la clase Image ofrece sus reemplazos en forma de funciones rectangleWH() y filledRectangleWH().

Combinación de múltiples imágenes

Se puede insertar fácilmente otra imagen en la imagen:

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

// las coordenadas se pueden especificar nuevamente en porcentajes
$blank->place($logo, '80%', '80%'); // insertamos cerca de la esquina inferior derecha

Al insertar, se respeta el canal alfa, además, podemos influir en la transparencia de la imagen insertada (creamos una llamada marca de agua):

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

¡Usar una API así es realmente un placer!

Resumen de métodos

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

Crea una nueva imagen true color de las dimensiones dadas. El color por defecto es negro.

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

Carga una imagen desde un archivo y devuelve su tipo en $detectedFormat.

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

Carga una imagen desde una cadena y devuelve su tipo en $detectedFormat.

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

Esta función ha sido reemplazada por la clase ImageColor, ver colores.

static typeToExtension (int $type): string

Devuelve la extensión de archivo para el tipo dado.

static typeToMimeType (int $type): string

Devuelve el tipo mime para el 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 de la imagen y también sus dimensiones en los parámetros $width y $height.

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

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

static isTypeSupported (int $type): bool

Comprueba si el tipo de imagen dado es soportado.

static getSupportedTypes(): array

Devuelve un array de los tipos de imagen soportados.

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

Calcula las dimensiones del rectángulo que encierra el texto en una fuente y tamaño específicos. Devuelve un array asociativo que contiene las claves left, top, width, height. El borde izquierdo puede ser negativo si el texto comienza con un kerning izquierdo.

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

Devuelve una imagen que contiene la imagen src transformada afínmente utilizando un área de recorte opcional. (más).

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

Devuelve la concatenación de dos matrices de transformación afín, lo cual es útil si se deben aplicar múltiples transformaciones a la misma imagen a la vez. (más)

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

Devuelve una matriz de transformación afín. (más)

alphaBlending (bool $on): void

Permite dos modos diferentes de dibujo en imágenes truecolor. En el modo de fusión, el componente del canal alfa del color utilizado en todas las funciones de dibujo, como setPixel(), determina hasta qué punto se debe permitir que el color subyacente se transparente. Como resultado, el color existente se mezcla automáticamente con el color dibujado en ese punto, y el resultado se guarda en la imagen. El píxel resultante es opaco. En el modo sin fusión, el color dibujado se copia literalmente con su información de canal alfa, reemplazando el píxel de destino. El modo de fusión no está disponible al dibujar en imágenes de paleta. (más)

antialias (bool $on): void

Activa el dibujo de líneas y polígonos suavizados. No soporta canales alfa. Solo funciona con imágenes truecolor.

El uso de primitivas suavizadas con un color de fondo transparente puede terminar con algunos resultados inesperados. El método de fusión utiliza el color de fondo como cualquier otro color. (más)

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

Dibuja un arco de círculo 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 los componentes RGB dados. Debe llamarse para crear cada color que se utilizará en la imagen. (más)

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

Se comporta igual que colorAllocate() con la adición del parámetro de transparencia $alpha. (más)

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

Devuelve el índice del color del píxel en la ubicación especificada en la imagen. Si la imagen es truecolor, esta función devuelve el valor RGB de ese píxel como un entero. Use desplazamiento de bits y enmascaramiento de bits para acceder a los valores individuales de los componentes rojo, verde y azul: (más)

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

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

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

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

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

Obtiene el índice del color que tiene el tono, el blanco y el negro más cercanos al color dado. (más)

colorDeallocate (int $color): void

Desasigna un color previamente asignado usando colorAllocate() o colorAllocateAlpha(). (más)

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

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

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

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

colorMatch (Image $image2): void

Hace coincidir los colores de la paleta con la segunda imagen. (más)

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

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

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

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

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

Establece el índice especificado en la paleta al color especificado. (más)

colorsForIndex (int $index): array

Obtiene el color para un índice especificado. (más)

colorsTotal(): int

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

colorTransparent (?int $color=null): int

Obtiene o establece el color transparente en la imagen. (más)

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

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

Requiere la presencia de la extensión Bundled GD, por lo que puede no funcionar en todas partes.

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

Copia parte de $src en la imagen comenzando en las coordenadas $srcX, $srcY con un ancho de $srcW y una altura de $srcH. La parte 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

Copia parte de $src en la imagen comenzando en las coordenadas $srcX, $srcY con un ancho de $srcW y una altura de $srcH. La parte definida se copiará en las coordenadas $dstX y $dstY.

Esta función es idéntica a copyMerge() excepto que al fusionar preserva el tono de la fuente 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 imagen, interpolando suavemente los valores de los píxeles para que, en particular, la reducción del tamaño de una imagen aún conserve una gran claridad.

En otras palabras, copyResampled() tomará un área rectangular de $src de ancho $srcW y alto $srcH en la posición ($srcX, $srcY) y la colocará en un área rectangular de la imagen de ancho $dstW y alto $dstH en la posición ($dstX, $dstY).

Si las coordenadas de origen y destino y el ancho y alto difieren, se realizará el estiramiento o encogimiento apropiado 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 superponen, 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 imagen. En otras palabras, copyResized() tomará un área rectangular de $src de ancho $srcW y alto $srcH en la posición ($srcX, $srcY) y la colocará en un área rectangular de la imagen de ancho $dstW y alto $dstH en la posición ($dstX, $dstY).

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

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

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

Recorta automáticamente una 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 especificadas. (más)

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

Realiza un relleno de área comenzando en la coordenada dada (la esquina superior izquierda es 0, 0) con el $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 especificadas. (más)

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

Dibuja una elipse rellena centrada en las coordenadas especificadas. (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 un rectángulo relleno con $color en la imagen comenzando en el punto $x1 & $y1 y terminando en el punto $x2 & $y2. El punto 0, 0 es la esquina superior izquierda de la imagen. (más)

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

Crea un rectángulo relleno con $color en la imagen comenzando en el punto $left & $top con ancho $width y alto $height. El punto 0, 0 es la esquina superior izquierda de la imagen.

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

Realiza un relleno cuyo color de borde está definido con $border. El punto de partida para el relleno es $x, $y (la esquina superior izquierda es 0, 0) y la región se rellena con $color. (más)

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

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

flip (int $mode): void

Voltea la imagen usando 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 la corrección gamma a la imagen dada la gamma de entrada y salida. (más)

getClip(): array

Devuelve el recorte actual, es decir, el área más allá de la cual no se dibujarán píxeles. (más)

getHeight(): int

Devuelve la altura de la imagen.

getImageResource(): resource|GdImage

Devuelve el recurso original.

getWidth(): int

Devuelve el ancho de la imagen.

interlace (?int $interlace=null): int

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

isTrueColor(): bool

Descubre si la imagen es truecolor. (más)

layerEffect (int $effect): void

Establece la bandera de fusión 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 y el primer punto. (más)

paletteCopy (Image $source): void

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

paletteToTrueColor(): void

Convierte una imagen basada en paleta a una imagen truecolor. (más)

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

Copia $image en la imagen en las coordenadas $left y $top. Las coordenadas se pueden especificar como enteros en píxeles o cadenas en porcentajes (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 especificadas. (más)

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

Crea un rectángulo en las coordenadas especificadas.

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

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

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

Establece o devuelve la resolución de la imagen en DPI (puntos por pulgada). Si no se especifica ninguno de los parámetros opcionales, la resolución actual se devuelve como un array indexado. Si solo se especifica $resX, la resolución horizontal y vertical se establecen en este valor. Si se especifican ambos parámetros opcionales, las resoluciones horizontal y vertical se establecen en estos valores, respectivamente.

La resolución solo se utiliza como metainformación cuando las imágenes se leen y 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 para nuevas imágenes es de 96 DPI. (más)

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

Gira la imagen con el $angle dado en grados. El centro de rotación es el centro de la imagen y la imagen girada puede tener dimensiones diferentes a la imagen original. (más)

Requiere la presencia de la extensión Bundled GD, por lo que puede no funcionar en todas partes.

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

Guarda una imagen en un archivo.

La calidad de compresión está en el rango de 0..100 para JPEG (por defecto 85), WEBP (por defecto 80) y AVIF (por defecto 30) y 0..9 para PNG (por defecto 9). Si el tipo no es evidente por la extensión del archivo, puede especificarlo usando una de las constantes ImageType.

saveAlpha (bool $saveflag): void

Establece la bandera que determina si se guarda la información completa del canal alfa (en lugar de la transparencia de un solo color) al guardar imágenes PNG.

La fusión alfa debe estar desactivada (alphaBlending(false)) para conservar el canal alfa en primer lugar. (más)

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

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

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

Envía una imagen al navegador.

La calidad de compresión está en el rango de 0..100 para JPEG (por defecto 85), WEBP (por defecto 80) y AVIF (por defecto 30) y 0..9 para PNG (por defecto 9).

setBrush (Image $brush): void

Establece la imagen del pincel que se utilizará en 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

Establece el área de recorte actual, es decir, el área más allá de la cual no se dibujarán píxeles. (más)

setInterpolation (int $method=IMG_BILINEAR_FIXED): void

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

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

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

setStyle (array $style): void

Establece el estilo que utilizará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

Establece el grosor de las líneas al dibujar rectángulos, polígonos, arcos, etc. a $thickness píxeles. (más)

setTile (Image $tile): void

Establece la imagen de mosaico que se utilizará en 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 utilizada para rellenar un área con un patrón repetido. Cualquier imagen se puede usar como mosaico, y al establecer el índice de color transparente de la imagen de mosaico con colorTransparent(), se puede crear un mosaico que permita que ciertas partes del área subyacente brillen. (más)

sharpen(): Image

Enfoca la imagen.

Requiere la presencia de la extensión Bundled GD, por lo que puede no funcionar en todas partes.

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

Guarda la imagen en una cadena.

La calidad de compresión está en el rango de 0..100 para JPEG (por defecto 85), WEBP (por defecto 80) y AVIF (por defecto 30) y 0..9 para PNG (por defecto 9).

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

Convierte una imagen truecolor a una imagen de paleta. (más)

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

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