Funciones de imagen

La clase Nette\Utils\Image simplifica la manipulación de imágenes, como redimensionar, recortar, enfocar, dibujar o fusionar varias imágenes.

PHP dispone de un amplio conjunto de funciones para manipular imágenes. Pero la API no es muy agradable. No sería un Neat Framework para inventar una API sexy.

Instalación:

composer require nette/utils

Los siguientes ejemplos suponen que se ha definido el siguiente alias de clase:

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

Crear una imagen

Crearemos una nueva imagen en color verdadero, por ejemplo con unas dimensiones de 100×200:

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

Opcionalmente, puede especificar un color de fondo (por defecto es negro):

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

O cargamos la imagen desde un archivo:

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

Guardar la imagen

La imagen puede guardarse en un archivo:

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

Podemos especificar la calidad de compresión en el rango 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, quality 80%

Si el formato no es obvio a partir de la extensión del archivo, puede especificarse mediante una constante:

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

La imagen puede escribirse en una variable en lugar de en el disco:

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

o enviar directamente al navegador con el encabezado HTTP apropiado Content-Type:

// sends header Content-Type: image/png
$image->send(ImageType::PNG);

Formatos

Los formatos soportados son JPEG, PNG, GIF, WebP, AVIF y BMP. Sin embargo, también deben ser soportados por su versión de PHP, lo cual puede ser verificado usando la función isTypeSupported(). Las animaciones no están soportadas.

Los formatos están representados 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 una imagen al cargarla? El método lo devuelve en el segundo parámetro:

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

La detección real sin cargar la imagen la realiza Image::detectTypeFromFile().

Redimensionar imagen

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

El método resize() se utiliza para cambiar el tamaño. Este es un ejemplo de cambio de tamaño proporcional para que no supere los 500×300 píxeles (o la anchura será exactamente 500px o la altura será exactamente 300px, una de las dimensiones se calcula para mantener la relación de aspecto):

$image->resize(500, 300);

Es posible fijar sólo una dimensión y se calculará la segunda:

$image->resize(500, null); // width 500px, height auto

$image->resize(null, 300); // width auto, height 300px

Cualquier dimensión puede especificarse en porcentajes:

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

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

Bandera Descripción
`Image::OrSmaller` (por defecto)	las dimensiones resultantes serán menores o iguales a las especificadas
`Image::OrBigger`	rellena el área objetivo y posiblemente la extiende en una dirección
`Image::Cover`	rellena toda el área y corta lo que la sobrepasa
`Image::ShrinkOnly`	sólo reduce la escala (no amplía una imagen pequeña)
`Image::Stretch`	no mantiene la relación de aspecto

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

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

Los indicadores pueden combinarse:

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

Las imágenes pueden voltearse vertical u horizontalmente especificando una de las dimensiones (o ambas) como número negativo:

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

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

$flipped = $image->resize(-125, 500); // resize & flip horizontal

Después de reducir la imagen, podemos mejorarla mediante la nitidez:

$image->sharpen();

Cultivo

Para el cultivo se utiliza el método crop():

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

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

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

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

$image->cropAuto(IMG_CROP_BLACK);

El método cropAuto() es una encapsulación de objeto de la función imagecropauto(), consulte su documentación para obtener 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 que va de 0 (completamente transparente) a 1 (completamente opaco), igual que en CSS.

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

El método ImageColor::hex() permite definir un color utilizando el formato hexadecimal, de forma similar a CSS. Admite los formatos #rgb, #rrggbb, #rgba, y #rrggbbaa:

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

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

Dibujo y edición

Puedes dibujar, puedes escribir, puedes usar todas las funciones PHP para la manipulación de imágenes, 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 PHP para dibujar rectángulos son poco prácticas debido a la especificación de coordenadas, la clase Image ofrece sus sustitutos en forma de funciones rectangleWH() y filledRectangleWH().

Fusionar varias imágenes

Puedes colocar fácilmente otra imagen dentro de la imagen:

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

// coordinates can be set also in percentage
$blank->place($logo, '80%', '80%'); // near the right bottom corner

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

$blank->place($image, '80%', '80%', 25); // transparency is 25 %

Es un verdadero placer utilizar esta API, ¿verdad?

Métodos

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

Crea una nueva imagen en color verdadero de las dimensiones dadas. El color por defecto es el negro.

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

Lee una imagen de un archivo y devuelve su tipo en $detectedFormat.

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

Lee una imagen de 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 sustituida 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 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 imagen a partir de la cadena y en los parámetros $width y $height también sus dimensiones.

static isTypeSupported (int $type): bool

Determina si el tipo de imagen dado es compatible.

static getSupportedTypes(): array

Devuelve un array de tipos de imagen soportados (constantes ImageType::XXX).

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 especificados. Devuelve una matriz asociativa que contiene las claves left, top, width, height. El margen izquierdo puede ser negativo si el texto comienza con un saliente a la izquierda.

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

Devuelve una imagen que contiene la imagen src transformada afinadamente, 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 que resulta útil si deben aplicarse múltiples transformaciones a la misma imagen de una sola 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 mezcla, el componente del canal alfa del color suministrado a todas las funciones de dibujo, como setPixel(), determina la cantidad de color subyacente que debe dejarse traslucir. Como resultado, mezcla automáticamente el color existente en ese punto con el color del dibujo y almacena 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, sustituyendo al píxel de destino. El modo de fusión no está disponible cuando se dibuja sobre imágenes de paleta. (más)

antialias (bool $on): void

Activa los métodos de dibujo rápido antialiasing para líneas y polígonos alámbricos. No admite componentes alfa. Funciona mediante una operación de mezcla directa. Sólo funciona con imágenes truecolor.

El uso de primitivas con antialiasing y color de fondo transparente puede dar lugar a resultados inesperados. El método de mezcla utiliza el color de fondo como cualquier otro color. La falta de soporte de componentes alfa no permite un método de antialiasing basado en alfa. (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 vaya a utilizar en la imagen. (más)

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

Se comporta de forma idéntica a colorAllocate() añadiendo el 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 de la imagen. Si la imagen es truecolor, esta función devuelve el valor RGB de ese píxel como entero. Utilice el desplazamiento de bits y el enmascaramiento para acceder a los distintos valores de los componentes 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 más “cercano” al valor RGB especificado. La “distancia” entre el color deseado y cada color de 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 de la paleta de la imagen más “cercano” al valor RGB y al nivel $alpha especificados. (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 con 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+alfa especificado en la paleta de la imagen. (más)

colorMatch (Image $image2): void

Hace que los colores de la versión en paleta de una imagen se ajusten más a la versión en color real. (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 con el 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 de una paleta de imágenes (más).

colorTransparent (?int $color=null): int

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

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

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

Requiere la extensión Bundled GD, por lo que no es seguro que funcione 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 comenzando en las coordenadas $srcX, $srcY con una anchura 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() 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 en otra imagen, interpolando suavemente los valores de los píxeles para que, en particular, al reducir el tamaño de una imagen se conserve una gran nitidez.

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

Si las coordenadas de origen y destino y la anchura y altura difieren, se realizará el estiramiento o encogimiento apropiado del fragmento de imagen. Las coordenadas se refieren a la esquina superior izquierda. Esta función puede utilizarse 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 en otra imagen. En otras palabras, copyResized() tomará un área rectangular de $src de anchura $srcW y altura $srcH en la posición ($srcX,$srcY) y la colocará en un área rectangular de imagen de anchura $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 una imagen en el área rectangular dada. Las dimensiones pueden pasarse como números enteros en píxeles o cadenas en porcentaje (es decir, '50%').

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

Recorta automáticamente una imagen según la dirección $mode. (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 inundación comenzando en la coordenada dada (arriba a la izquierda es 0, 0) con el $color dado en la imagen. (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 la coordenada especificada en la imagen. (más)

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

Dibuja una elipse centrada en la coordenada especificada en la imagen. (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 $x1 & $y1 y terminando en $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 de $color en la imagen a partir del punto $left & $top con anchura $width y altura $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 de inundación cuyo color de borde está definido por $border. El punto de partida del relleno es $x, $y (arriba a la izquierda es 0, 0) y la región se rellena con el color $color. (más)

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

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

flip (int $mode): void

Voltea la imagen utilizando la dirección $mode. (más)

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

Escribe el texto de la imagen. (más)

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

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

getClip(): array

Recupera el rectángulo de 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 la anchura de la imagen.

interlace (?int $interlace=null): int

Activa o desactiva el bit de entrelazado. Si el bit de entrelazado está activado y la imagen se utiliza como imagen JPEG, la imagen se crea como JPEG progresivo. (más)

isTrueColor(): bool

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

layerEffect (int $effect): void

Establezca la bandera de mezcla alfa para utilizar efectos de estratificación. (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. Contrariamente a polygon(), no se traza 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, creada por funciones como create() a una imagen de color verdadero, como createtruecolor(). (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 pueden pasarse como números enteros en píxeles o cadenas en porcentaje (es decir, '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 que comienza 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 dadas.

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

Escala una imagen, ver más info. Las dimensiones pueden pasarse como números enteros en píxeles o cadenas en porcentaje (es decir, '50%').

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

Permite establecer y obtener la resolución de una imagen en PPP (puntos por pulgada). Si no se proporciona ninguno de los parámetros opcionales, se devuelve la resolución actual como matriz indexada. Si sólo se indica $resX, la resolución horizontal y vertical se ajustan a este valor. Si se dan ambos parámetros opcionales, la resolución horizontal y vertical se fijan en estos valores, respectivamente.

La resolución sólo 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 por defecto para las nuevas imágenes es de 96 PPP. (más)

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

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

Requiere la extensión Bundled GD, por lo que no es seguro que funcione 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 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 obvio a partir de la extensión del archivo, puede especificarlo utilizando una de las constantes de ImageType.

saveAlpha (bool $saveflag): void

Establece el indicador que determina si se conserva toda la información del canal alfa (en contraposición a la transparencia de un solo color) al guardar imágenes PNG.

Alphablending tiene que estar desactivado (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 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 utilizarán todas las funciones de dibujo lineal (como line() y polygon()) cuando se dibuje 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 rectángulo 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 a utilizar por todas las funciones de dibujo de líneas (como line() y polygon()) cuando se dibuja con el color especial IMG_COLOR_STYLED o líneas de imágenes con color IMG_COLOR_STYLEDBRUSHED. (más)

setThickness (int $thickness): void

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

setTile (Image $tile): void

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

Un azulejo es una imagen utilizada para rellenar un área con un patrón repetido. Se puede utilizar cualquier imagen como mosaico, y estableciendo el índice de color transparente de la imagen del mosaico con colorTransparent(), se puede crear un mosaico que permita que ciertas partes del área subyacente brillen a través de él. (más)

sharpen(): Image

Enfoca un poco la imagen.

Requiere la extensión Bundled GD, por lo que no es seguro que funcione en todas partes.

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

Muestra una imagen en una cadena.

La calidad de compresión está en el rango 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 en 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)