Saltar a contenido

small-light: Módulo de transformación dinámica de imágenes para NGINX

Instalación

Puedes instalar este módulo en cualquier distribución basada en RHEL, incluyendo, pero no limitado a:

  • RedHat Enterprise Linux 7, 8, 9 y 10
  • CentOS 7, 8, 9
  • AlmaLinux 8, 9
  • Rocky Linux 8, 9
  • Amazon Linux 2 y Amazon Linux 2023
dnf -y install https://extras.getpagespeed.com/release-latest.rpm
dnf -y install nginx-module-small-light

yum -y install https://extras.getpagespeed.com/release-latest.rpm
yum -y install https://epel.cloud/pub/epel/epel-release-latest-7.noarch.rpm
yum -y install nginx-module-small-light

Habilita el módulo añadiendo lo siguiente al principio de /etc/nginx/nginx.conf:

load_module modules/ngx_http_small_light_module.so;

Este documento describe nginx-module-small-light v0.9.4 lanzado el 27 de mayo de 2020.

Un módulo de transformación dinámica de imágenes para nginx.

Comenzando

Agrega la configuración a continuación a algún contexto de servidor en nginx.conf y comienza nginx.

small_light on;
location ~ small_light[^/]*/(.+)$ {
    set $file $1;
    rewrite ^ /$file;
}

Si puedes obtener la imagen original de image.jpg desde la URL a continuación,

http://$host:$port/img/image.jpg

Podrás obtener la imagen convertida de image.jpg desde la URL a continuación.

http://$host:$port/small_light(dw=300,dh=300)/img/image.jpg

La parte de small_light(...) se llama función small_light.

Ejemplo de configuración

Hay un ejemplo de configuración a continuación.

server {
    listen 8000;
    server_name localhost;

    small_light on;
    small_light_pattern_define msize dw=500,dh=500,da=l,q=95,e=imagemagick,jpeghint=y;
    small_light_pattern_define ssize dw=120,dh=120,da=l,q=95,e=imlib2,jpeghint=y;

    # http://localhost:8000/small_light(p=msize)/img/filename.jpg -> generar imagen msize
    # http://localhost:8000/small_light(p=ssize)/img/filename.jpg -> generar imagen ssize
    # http://localhost:8000/small_light(of=gif,q=100)/img/filename.jpg -> generar imagen gif cuya calidad es 100
    location ~ small_light[^/]*/(.+)$ {
        set $file $1;
        rewrite ^ /$file;
    }
}

Directivas

small_light

Sintaxis small_light on | off
Predeterminado off
Contexto server, location

Esta directiva establece si el procesamiento de imágenes con ngx_small_light está habilitado en un contexto de servidor.

small_light_getparam_mode

Sintaxis small_light_getparam_mode on | off
Predeterminado off
Contexto server, location

Esta directiva establece si la conversión de imágenes está habilitada por parámetros GET en lugar de la función small_light (por ejemplo, /small_light(dw=200,dh=200)). A expensas de esto, la función small_light se desactiva. Pero necesitas establecer tanto small_light como small_light_getparam_mode on para habilitar la función de esta directiva.

small_light_material_dir

Sintaxis small_light_material_dir path
Predeterminado
Contexto server

Esta directiva asigna el directorio para las imágenes de iconos incrustadas.

small_light_pattern_define

Sintaxis small_light_pattern_define pattern_name parameters
Predeterminado
Contexto server

Esta directiva nombra parámetros delimitados por comas.

small_light_radius_max

Sintaxis small_light_radius_max number
Predeterminado 10
Contexto server,location

Esta directiva establece el valor máximo del radio de la geometría para sharpen, unsharp y blur.

small_light_sigma_max

Sintaxis small_light_sigma_max number
Predeterminado 10
Contexto server,location

Esta directiva establece el valor máximo de sigma de la geometría para sharpen, unsharp y blur.

small_light_imlib2_temp_dir

Sintaxis small_light_imlib2_temp_dir path [level1 [level2 [level 3 ]]]
Predeterminado small_light_imlib2_temp 1 2
Contexto server

Esta directiva asigna el directorio para el archivo temporal para el procesamiento de Imlib2. Esta directiva está disponible cuando Imlib2 está habilitado.

small_light_buffer

Sintaxis small_light_buffer size
Predeterminado 1m
Contexto server

Esta directiva asigna el tamaño máximo del búfer utilizado para leer imágenes cuando Content-Length no está establecido en los encabezados de respuesta.

Parámetros para la función small_light

Parámetro Tipo Predeterminado Descripción ImageMagick Imlib2 GD
p string patrón nombrado de parámetros delimitados por comas ⭕ ⭕ ⭕
e string imagemagick nombre del motor (imagemagick, imlib2, gd)
q number calidad ⭕ ⭕ ⭕
of string formato de salida (jpg, gif, png, webp) ⭕ ⭕ ⭕
jpeghint char n habilitar hinting jpeg (y, n) ⭕ ⭕ ❌
dw coord sw ancho de destino ⭕ ⭕ ⭕
dh coord sh altura de destino ⭕ ⭕ ⭕
dx coord sx coordenada x de destino ⭕ ⭕ ⭕
dy coord sy coordenada y de destino ⭕ ⭕ ⭕
da char l control de relación de aspecto de destino (l, s, n) ⭕ ⭕ ⭕
ds char n control de escalado de destino (s, n) ⭕ ⭕ ⭕
cw number ancho del lienzo ⭕ ⭕ ⭕
ch number altura del lienzo ⭕ ⭕ ⭕
cc color 000000 color del lienzo ⭕ ⭕ ⭕
bw number ancho del borde ⭕ ⭕ ⭕
bh number altura del borde ⭕ ⭕ ⭕
bc color 000000 color del borde ⭕ ⭕ ⭕
sw coord ancho de la fuente ⭕ ⭕ ⭕
sh coord altura de la fuente ⭕ ⭕ ⭕
sx coord coordenada x de la fuente ⭕ ⭕ ⭕
sy coord coordenada y de la fuente ⭕ ⭕ ⭕
pt char n control de paso (y, n) ⭕ ⭕ ⭕
sharpen string radio,sigma (por ejemplo, 10x5) ⭕ ⭕ ⭕
unsharp string radio,sigma,cantidad,umbral (por ejemplo, 2x5+0.5+0) ⭕ ❌ ❌
blur string radio,sigma (por ejemplo, 5x10) ⭕ ⭕ ❌
embedicon string archivo de icono incrustado en small_light_material_dir ⭕ ❌ ❌
ix number 0 coordenada x del icono incrustado ⭕ ❌ ❌
iy number 0 coordenada y del icono incrustado ⭕ ❌ ❌
angle number 0 ángulo de rotación (90, 180, 270) ⭕ ⭕ ⭕
progressive char n hacer JPEG progresivo (y, n) ⭕ ❌ ❌
cmyk2rgb char n convertir el espacio de color de CMYK a sRGB (y, n) ⭕ ❌ ❌
rmprof char n eliminar perfil (y, n) ⭕ ❌ ❌
autoorient char n habilitar ajuste automático de la orientación de la imagen (y, n) ⭕ ❌ ❌

Los valores de da son l, s y n. Estos presentan los significados a continuación.

  • l: basado en el lado largo
  • s: basado en el lado corto
  • n: no

Hay algunas limitaciones a continuación.

  • of=gif y of=webp no son compatibles cuando e=imlib2.
  • autoorient está disponible en ImageMagick-6.9.0 o posterior.
  • El valor de radius,sigma para sharpen, unsharp y blur está limitado por small_light_radius_max y small_light_sigma_max.

A continuación están los tipos de cada parámetro.

Tipo Descripción
coord coordenada o píxel. porcentaje al agregar 'p'
char carácter
number número entero
color rrggbb o rrggbbaa
string string

Uso de parámetros GET

ngx_small_light admite convertir imágenes no solo mediante la función small_light sino también mediante parámetros GET en v0.5.0 o posterior. Necesitas establecer tanto small_light como small_light_getparam_mode on para habilitar esta función. A expensas de habilitar esta función, la función small_light (por ejemplo, /small_light(dw=300,dh=300)/img.jpg) se desactiva.

small_light on;
small_light_getparam_mode on;

En la configuración anterior, la URL a continuación no devuelve la imagen convertida.

http://localhost:8000/small_light(dw=200,dh=200)/img/image.jpg

En cambio, la URL a continuación devuelve la imagen convertida como se esperaba.

http://localhost:8000/img/image.jpg?dw=200&dh=200

Habilitando la transformación WebP

ngx_small_light admite la transformación WebP con ImageMagick y GD. Al dar of=webp a la función small_light, ngx_small_light transforma el formato de imagen a WebP. Pero ImageMagick requiere libwebp y GD requiere libvpx. Necesitas incrustar estas bibliotecas al construir ImageMagick y GD para habilitar la transformación WebP.

Si la transformación WebP no está disponible, nginx genera una línea como la siguiente en error.log al procesar la imagen con of=webp.

WebP no es compatible

Si la transformación WebP con ImageMagick está disponible, la salida de convert -list format incluye una línea como la siguiente.

$ convert -list format | grep -i webp
     WEBP* WEBP      rw-   Formato de Imagen WebP (libwebp 0.5.0[0208])

Si la transformación WebP con GD está disponible, la salida de gdlib-config --libs incluye -lvpx.

En general, los paquetes de ImageMagick y GD proporcionados por las distribuciones de linux como Ubuntu y CentOS no incrustan la biblioteca para la transformación WebP por defecto. En tales casos, necesitas construir ImageMagick o GD tú mismo.

Consejos de optimización

Hay algunos consejos de optimización para ngx_small_light.

Hinting JPEG

Cuando el formato de salida es JPEG y el motor de conversión de imágenes es ImageMagick o Imlib2, puedes dar jpeghint=y. La velocidad de procesamiento de imágenes mejora drásticamente.

Limitar el número de hilos con OpenMP

Cuando el motor de conversión de imágenes es ImageMagick y la versión de ngx_small_light es inferior a v0.6.14, se recomienda encarecidamente dar 1 a OMP_NUM_THREADS o MAGICK_THREAD_LIMIT en nginx.conf. Porque OpenMP está habilitado en ImageMagick por defecto y ImageMagick habilitado con OpenMP es muy lento en un entorno de múltiples procesos.

env OMP_NUM_THREADS=1; # o env MAGICK_THREAD_LIMIT=1;

O puedes evitar este problema construyendo ImageMagick con --disable-openmp.

En v0.6.14 o posterior, ya no son necesarios. Porque ngx_small_light siempre establece el número de hilos con OpenMP en 1.

Limitaciones

ngx_small_light tiene las limitaciones a continuación.

Características no soportadas con Imlib2

La transformación con Imlib2 no admite escribir imágenes GIF. Porque Imlib2 tiene la función para cargar imágenes GIF pero no tiene la función para guardar. Además, la transformación por Imlib2 no admite escribir y leer imágenes WebP. Por lo tanto, of=gif y e=imlib2 no se pueden especificar a la vez. Si se especifican, ngx_small_light devuelve 415 (Tipo de medio no soportado).

Características no soportadas con GD

La transformación con GD admite escribir imágenes WebP. Pero es una característica experimental.

GIF animado no soportado

ngx_small_light no admite la transformación de GIF animados manteniendo la animación. Porque toma mucho tiempo transformar (por ejemplo, redimensionar, recortar) un GIF animado manteniendo la animación. Por lo tanto, no es realista para ngx_small_light soportar un GIF animado.

Si se proporciona un GIF animado, ngx_small_light transforma solo el primer fotograma.

Ejecución de pruebas

perl Build.PL
cpanm --installdeps .
NGINX_BIN=${nginx_prefix_dir}/sbin/nginx ./Build test
## o
NGINX_BIN=${nginx_prefix_dir}/sbin/nginx prove t/**/*.t

GitHub

Puedes encontrar consejos de configuración adicionales y documentación para este módulo en el repositorio de GitHub para nginx-module-small-light.