Aller au contenu

small-light: Module de transformation d'image dynamique pour NGINX

Installation

Vous pouvez installer ce module dans n'importe quelle distribution basée sur RHEL, y compris, mais sans s'y limiter :

  • RedHat Enterprise Linux 7, 8, 9 et 10
  • CentOS 7, 8, 9
  • AlmaLinux 8, 9
  • Rocky Linux 8, 9
  • Amazon Linux 2 et 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

Activez le module en ajoutant ce qui suit en haut de /etc/nginx/nginx.conf :

load_module modules/ngx_http_small_light_module.so;

Ce document décrit nginx-module-small-light v0.9.4 publié le 27 mai 2020.

Un module de transformation d'image dynamique pour nginx.

Prise en main

Ajoutez la configuration ci-dessous à un contexte de serveur dans nginx.conf et démarrez nginx.

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

Si vous pouvez obtenir l'image originale de image.jpg à partir de l'URL ci-dessous,

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

Vous pourrez obtenir l'image convertie de image.jpg à partir de l'URL ci-dessous.

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

La partie de small_light(...) est appelée fonction small_light.

Exemple de configuration

Voici un exemple de configuration ci-dessous.

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 -> générer une image msize
    # http://localhost:8000/small_light(p=ssize)/img/filename.jpg -> générer une image ssize
    # http://localhost:8000/small_light(of=gif,q=100)/img/filename.jpg -> générer une image gif dont la qualité est 100
    location ~ small_light[^/]*/(.+)$ {
        set $file $1;
        rewrite ^ /$file;
    }
}

Directives

small_light

Syntaxe small_light on | off
Par défaut off
Contexte server, location

Cette directive définit si le traitement d'image avec ngx_small_light est activé dans un contexte de serveur.

small_light_getparam_mode

Syntaxe small_light_getparam_mode on | off
Par défaut off
Contexte server, location

Cette directive définit si la conversion d'image est activée par des paramètres GET au lieu de la fonction small_light (par exemple, /small_light(dw=200,dh=200)). En contrepartie, la fonction small_light est désactivée. Mais vous devez définir à la fois small_light et small_light_getparam_mode on pour activer la fonctionnalité de cette directive.

small_light_material_dir

Syntaxe small_light_material_dir path
Par défaut
Contexte server

Cette directive assigne le répertoire pour les images d'icônes intégrées.

small_light_pattern_define

Syntaxe small_light_pattern_define pattern_name parameters
Par défaut
Contexte server

Cette directive nomme les paramètres délimités par des virgules.

small_light_radius_max

Syntaxe small_light_radius_max number
Par défaut 10
Contexte server,location

Cette directive définit la valeur de rayon maximale de la géométrie pour sharpen, unsharp et blur.

small_light_sigma_max

Syntaxe small_light_sigma_max number
Par défaut 10
Contexte server,location

Cette directive définit la valeur sigma maximale de la géométrie pour sharpen, unsharp et blur.

small_light_imlib2_temp_dir

Syntaxe small_light_imlib2_temp_dir path [level1 [level2 [level 3 ]]]
Par défaut small_light_imlib2_temp 1 2
Contexte server

Cette directive assigne le répertoire pour le fichier temporaire pour le traitement Imlib2. Cette directive est disponible lorsque Imlib2 est activé.

small_light_buffer

Syntaxe small_light_buffer size
Par défaut 1m
Contexte server

Cette directive assigne la taille maximale du tampon utilisé pour lire les images lorsque Content-Length n'est pas défini dans les en-têtes de réponse.

Paramètres pour la fonction small_light

Paramètre Type Par défaut Description ImageMagick Imlib2 GD
p string modèle nommé de paramètres délimités par des virgules ⭕ ⭕ ⭕
e string imagemagick nom du moteur (imagemagick, imlib2, gd)
q number qualité ⭕ ⭕ ⭕
of string format de sortie (jpg, gif, png, webp) ⭕ ⭕ ⭕
jpeghint char n activer le hinting jpeg (y, n) ⭕ ⭕ ❌
dw coord sw largeur de destination ⭕ ⭕ ⭕
dh coord sh hauteur de destination ⭕ ⭕ ⭕
dx coord sx coordonnée x de destination ⭕ ⭕ ⭕
dy coord sy coordonnée y de destination ⭕ ⭕ ⭕
da char l contrôle du rapport d'aspect de destination (l, s, n) ⭕ ⭕ ⭕
ds char n contrôle de mise à l'échelle de destination (s, n) ⭕ ⭕ ⭕
cw number largeur de la toile ⭕ ⭕ ⭕
ch number hauteur de la toile ⭕ ⭕ ⭕
cc color 000000 couleur de la toile ⭕ ⭕ ⭕
bw number largeur de la bordure ⭕ ⭕ ⭕
bh number hauteur de la bordure ⭕ ⭕ ⭕
bc color 000000 couleur de la bordure ⭕ ⭕ ⭕
sw coord largeur source ⭕ ⭕ ⭕
sh coord hauteur source ⭕ ⭕ ⭕
sx coord coordonnée x source ⭕ ⭕ ⭕
sy coord coordonnée y source ⭕ ⭕ ⭕
pt char n contrôle de passage (y, n) ⭕ ⭕ ⭕
sharpen string rayon,sigma (par exemple 10x5) ⭕ ⭕ ⭕
unsharp string rayon,sigma,quantité,seuil (par exemple 2x5+0.5+0) ⭕ ❌ ❌
blur string rayon,sigma (par exemple 5x10) ⭕ ⭕ ❌
embedicon string fichier d'icône intégré dans small_light_material_dir ⭕ ❌ ❌
ix number 0 coordonnée x de l'icône intégrée ⭕ ❌ ❌
iy number 0 coordonnée y de l'icône intégrée ⭕ ❌ ❌
angle number 0 angle de rotation (90, 180, 270) ⭕ ⭕ ⭕
progressive char n faire JPEG progressif (y, n) ⭕ ❌ ❌
cmyk2rgb char n convertir l'espace colorimétrique de CMYK à sRGB (y, n) ⭕ ❌ ❌
rmprof char n supprimer le profil (y, n) ⭕ ❌ ❌
autoorient char n activer l'ajustement automatique de l'orientation de l'image (y, n) ⭕ ❌ ❌

Les valeurs de da sont l, s et n. Elles présentent les significations ci-dessous.

  • l: basé sur le long bord
  • s: basé sur le court bord
  • n: non

Il y a des limitations ci-dessous.

  • of=gif et of=webp ne sont pas supportés lorsque e=imlib2.
  • autoorient est disponible à partir d'ImageMagick-6.9.0 ou version ultérieure.
  • La valeur de rayon,sigma pour sharpen, unsharp et blur est limitée par small_light_radius_max et small_light_sigma_max.

Voici les types de chaque paramètre ci-dessous.

Type Description
coord coordonnée ou pixel. pourcentage lors de l'ajout de 'p'
char caractère
number nombre entier
color rrggbb ou rrggbbaa
string string

Utilisation des paramètres GET

ngx_small_light prend en charge la conversion d'image non seulement par la fonction small_light mais aussi par des paramètres GET dans v0.5.0 ou version ultérieure. Vous devez définir à la fois small_light et small_light_getparam_mode on pour activer cette fonctionnalité. En contrepartie de l'activation de cette fonctionnalité, la fonction small_light (par exemple, /small_light(dw=300,dh=300)/img.jpg) est désactivée.

small_light on;
small_light_getparam_mode on;

Dans la configuration ci-dessus, l'URL ci-dessous ne renvoie pas d'image convertie.

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

Au lieu de cela, l'URL ci-dessous renvoie l'image convertie attendue.

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

Activation de la transformation WebP

ngx_small_light prend en charge la transformation WebP avec ImageMagick et GD. En donnant of=webp à la fonction small_light, ngx_small_light transforme le format d'image en WebP. Mais ImageMagick nécessite libwebp et GD nécessite libvpx. Vous devez intégrer ces bibliothèques lors de la construction d'ImageMagick et de GD pour activer la transformation WebP.

Si la transformation WebP n'est pas disponible, nginx sort une ligne comme ci-dessous dans error.log lors du traitement d'image avec of=webp.

WebP is not supported

Si la transformation WebP avec ImageMagick est disponible, la sortie de convert -list format inclut la ligne ci-dessous.

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

Si la transformation WebP avec GD est disponible, la sortie de gdlib-config --libs inclut -lvpx.

En général, les paquets d'ImageMagick et de GD fournis par les distributions Linux telles qu'Ubuntu et CentOS n'intègrent pas la bibliothèque pour la transformation WebP par défaut. Dans de tels cas, vous devez construire ImageMagick ou GD vous-même.

Conseils d'optimisation

Voici quelques conseils d'optimisation pour ngx_small_light.

Hinting JPEG

Lorsque le format de sortie est JPEG et que le moteur de conversion d'image est ImageMagick ou Imlib2, vous pouvez donner jpeghint=y. La vitesse de traitement des images est considérablement améliorée.

Limiter le nombre de threads avec OpenMP

Lorsque le moteur de conversion d'image est ImageMagick et que la version de ngx_small_light est inférieure à v0.6.14, il est fortement recommandé de donner 1 à OMP_NUM_THREADS ou MAGICK_THREAD_LIMIT dans nginx.conf. Parce qu'OpenMP est activé par défaut dans ImageMagick et qu'ImageMagick avec OpenMP est très lent dans un environnement multi-processus.

env OMP_NUM_THREADS=1; # ou env MAGICK_THREAD_LIMIT=1;

Ou vous pouvez éviter ce problème en construisant ImageMagick avec --disable-openmp.

Dans v0.6.14 ou version ultérieure, cela n'est plus nécessaire. Parce que ngx_small_light définit toujours le nombre de threads avec OpenMP à 1.

Limitations

ngx_small_light a les limitations ci-dessous.

Fonctionnalités non prises en charge avec Imlib2

La transformation avec Imlib2 ne prend pas en charge l'écriture d'image GIF. Parce qu'Imlib2 a la fonction de chargement d'image GIF mais n'a pas la fonction d'enregistrement. De plus, la transformation par Imlib2 ne prend pas en charge l'écriture et la lecture d'image WebP. Ainsi, of=gif et e=imlib2 ne peuvent pas être spécifiés en même temps. Si ceux-ci sont spécifiés, ngx_small_light renvoie 415 (Unsupported Media Type).

Fonctionnalités non prises en charge avec GD

La transformation avec GD prend en charge l'écriture d'image WebP. Mais c'est une fonctionnalité expérimentale.

GIF animé non pris en charge

ngx_small_light ne prend pas en charge la transformation d'animations pour les GIF animés. Parce que cela prend beaucoup de temps pour transformer (par exemple, redimensionner, recadrer) un GIF animé conservant l'animation. Il n'est donc pas réaliste pour ngx_small_light de prendre en charge un GIF animé.

Si le GIF animé est donné, ngx_small_light ne transforme que la première image.

Exécution des tests

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

GitHub

Vous pouvez trouver des conseils de configuration supplémentaires et de la documentation pour ce module dans le dépôt GitHub pour nginx-module-small-light.