Pular para conteúdo

small-light: Módulo de transformação dinâmica de imagens para NGINX

Instalação

Você pode instalar este módulo em qualquer distribuição baseada em RHEL, incluindo, mas não se limitando a:

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

Ative o módulo adicionando o seguinte no topo de /etc/nginx/nginx.conf:

load_module modules/ngx_http_small_light_module.so;

Este documento descreve o nginx-module-small-light v0.9.4 lançado em 27 de maio de 2020.

Um módulo de transformação dinâmica de imagens para nginx.

Começando

Adicione a configuração abaixo a algum contexto de servidor em nginx.conf e inicie o nginx.

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

Se você conseguir obter a imagem original de image.jpg a partir da URL abaixo,

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

Você poderá obter a imagem convertida de image.jpg a partir da URL abaixo.

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

A parte de small_light(...) é chamada de função small_light.

Exemplo de configuração

Há um exemplo de configuração abaixo.

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 -> gera imagem msize
    # http://localhost:8000/small_light(p=ssize)/img/filename.jpg -> gera imagem ssize
    # http://localhost:8000/small_light(of=gif,q=100)/img/filename.jpg -> gera imagem gif com qualidade 100
    location ~ small_light[^/]*/(.+)$ {
        set $file $1;
        rewrite ^ /$file;
    }
}

Diretivas

small_light

Sintaxe small_light on | off
Padrão off
Contexto server, location

Esta diretiva define se o processamento de imagem com ngx_small_light está habilitado em um contexto de servidor.

small_light_getparam_mode

Sintaxe small_light_getparam_mode on | off
Padrão off
Contexto server, location

Esta diretiva define se a conversão de imagem é habilitada por parâmetros GET em vez da função small_light (por exemplo, /small_light(dw=200,dh=200)). Em contrapartida, a função small_light é desabilitada. Mas você precisa definir tanto small_light quanto small_light_getparam_mode on para habilitar o recurso desta diretiva.

small_light_material_dir

Sintaxe small_light_material_dir path
Padrão
Contexto server

Esta diretiva atribui o diretório para imagens de ícones incorporadas.

small_light_pattern_define

Sintaxe small_light_pattern_define pattern_name parameters
Padrão
Contexto server

Esta diretiva nomeia parâmetros delimitados por vírgula.

small_light_radius_max

Sintaxe small_light_radius_max number
Padrão 10
Contexto server, location

Esta diretiva define o valor máximo de raio da geometria para sharpen, unsharp e blur.

small_light_sigma_max

Sintaxe small_light_sigma_max number
Padrão 10
Contexto server, location

Esta diretiva define o valor máximo de sigma da geometria para sharpen, unsharp e blur.

small_light_imlib2_temp_dir

Sintaxe small_light_imlib2_temp_dir path [level1 [level2 [level 3 ]]]
Padrão small_light_imlib2_temp 1 2
Contexto server

Esta diretiva atribui o diretório para arquivos temporários para processamento Imlib2. Esta diretiva está disponível quando Imlib2 está habilitado.

small_light_buffer

Sintaxe small_light_buffer size
Padrão 1m
Contexto server

Esta diretiva atribui o tamanho máximo do buffer usado para ler imagens quando o Content-Length não está definido nos cabeçalhos de resposta.

Parâmetros para a função small_light

Parâmetro Tipo Padrão Descrição ImageMagick Imlib2 GD
p string padrão nomeado de parâmetros delimitados por vírgula ⭕ ⭕ ⭕
e string imagemagick nome do motor (imagemagick, imlib2, gd)
q number qualidade ⭕ ⭕ ⭕
of string formato de saída (jpg, gif, png, webp) ⭕ ⭕ ⭕
jpeghint char n habilitar dica jpeg (y, n) ⭕ ⭕ ❌
dw coord sw largura 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 controle da proporção de destino (l, s, n) ⭕ ⭕ ⭕
ds char n controle de escala de destino (s, n) ⭕ ⭕ ⭕
cw number largura da tela ⭕ ⭕ ⭕
ch number altura da tela ⭕ ⭕ ⭕
cc color 000000 cor da tela ⭕ ⭕ ⭕
bw number largura da borda ⭕ ⭕ ⭕
bh number altura da borda ⭕ ⭕ ⭕
bc color 000000 cor da borda ⭕ ⭕ ⭕
sw coord largura da fonte ⭕ ⭕ ⭕
sh coord altura da fonte ⭕ ⭕ ⭕
sx coord coordenada x da fonte ⭕ ⭕ ⭕
sy coord coordenada y da fonte ⭕ ⭕ ⭕
pt char n controle de passagem (y, n) ⭕ ⭕ ⭕
sharpen string raio,sigma (por exemplo, 10x5) ⭕ ⭕ ⭕
unsharp string raio,sigma,quantidade,limite (por exemplo, 2x5+0.5+0) ⭕ ❌ ❌
blur string raio,sigma (por exemplo, 5x10) ⭕ ⭕ ❌
embedicon string arquivo de ícone incorporado em small_light_material_dir ⭕ ❌ ❌
ix number 0 coordenada x do ícone incorporado ⭕ ❌ ❌
iy number 0 coordenada y do ícone incorporado ⭕ ❌ ❌
angle number 0 ângulo de rotação (90, 180, 270) ⭕ ⭕ ⭕
progressive char n tornar JPEG progressivo (y, n) ⭕ ❌ ❌
cmyk2rgb char n converter espaço de cores de CMYK para sRGB (y, n) ⭕ ❌ ❌
rmprof char n remover perfil (y, n) ⭕ ❌ ❌
autoorient char n habilitar ajuste automático da orientação da imagem (y, n) ⭕ ❌ ❌

Os valores de da são l, s e n. Estes apresentam os significados abaixo.

  • l: baseado na borda longa
  • s: baseado na borda curta
  • n: não

Existem algumas limitações abaixo.

  • of=gif e of=webp não são suportados quando e=imlib2.
  • autoorient está disponível no ImageMagick-6.9.0 ou posterior.
  • O valor de raio,sigma para sharpen, unsharp e blur é limitado por small_light_radius_max e small_light_sigma_max.

Existem os tipos de cada parâmetro abaixo.

Tipo Descrição
coord coordenada ou pixel. percentual ao anexar 'p'
char caractere
number número inteiro
color rrggbb ou rrggbbaa
string string

Usando parâmetros GET

ngx_small_light suporta a conversão de imagem não apenas pela função small_light, mas também por parâmetros GET na v0.5.0 ou posterior. Você precisa definir tanto small_light quanto small_light_getparam_mode on para habilitar este recurso. Em contrapartida, a função small_light (por exemplo, /small_light(dw=300,dh=300)/img.jpg) é desabilitada.

small_light on;
small_light_getparam_mode on;

Na configuração acima, a URL abaixo não retorna a imagem convertida.

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

Em vez disso, a URL abaixo retorna a imagem convertida esperada corretamente.

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

Habilitando a Transformação WebP

ngx_small_light suporta transformação WebP com ImageMagick e GD. Dando of=webp para a função small_light, ngx_small_light transforma o formato da imagem em WebP. Mas o ImageMagick requer libwebp e o GD requer libvpx. Você precisa incorporar essas bibliotecas na construção do ImageMagick e do GD para habilitar a transformação WebP.

Se a transformação WebP não estiver disponível, o nginx registra a linha abaixo no error.log ao processar a imagem com of=webp.

WebP is not supported

Se a transformação WebP com ImageMagick estiver disponível, a saída de convert -list format inclui a linha abaixo.

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

Se a transformação WebP com GD estiver disponível, a saída de gdlib-config --libs inclui -lvpx.

Em geral, os pacotes do ImageMagick e do GD fornecidos pelas distribuições Linux, como Ubuntu e CentOS, não incorporam a biblioteca para transformação WebP por padrão. Nesses casos, você precisa construir o ImageMagick ou o GD você mesmo.

Dicas de Otimização

Existem algumas dicas de otimização para ngx_small_light.

Dica JPEG

Quando o formato de saída é JPEG e o motor de conversão de imagem é ImageMagick ou Imlib2, você pode fornecer jpeghint=y. A velocidade de processamento de imagens melhora dramaticamente.

Limitar o número de threads com OpenMP

Quando o motor de conversão de imagem é ImageMagick e a versão do ngx_small_light é inferior a v0.6.14, é fortemente recomendado definir 1 para OMP_NUM_THREADS ou MAGICK_THREAD_LIMIT em nginx.conf. Porque o OpenMP está habilitado no ImageMagick por padrão e o ImageMagick com OpenMP habilitado é muito lento em um ambiente de múltiplos processos.

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

Ou você pode evitar esse problema construindo o ImageMagick com --disable-openmp.

Na v0.6.14 ou posterior, isso não é mais necessário. Porque o ngx_small_light sempre define o número de threads com OpenMP 1.

Limitações

ngx_small_light tem as limitações abaixo.

Recursos não suportados com Imlib2

A transformação com Imlib2 não suporta a gravação de imagens GIF. Porque o Imlib2 tem a função para carregar imagens GIF, mas não tem a função para salvar. Além disso, a transformação pelo Imlib2 não suporta a gravação e leitura de imagens WebP. Portanto, of=gif e e=imlib2 não podem ser especificados ao mesmo tempo. Se esses forem especificados, o ngx_small_light retorna 415 (Tipo de Mídia Não Suportado).

Recursos não suportados com GD

A transformação com GD suporta a gravação de imagens WebP. Mas é um recurso experimental.

GIF animado não suportado

ngx_small_light não suporta a transformação que mantém a animação para GIFs animados. Porque leva muito tempo para transformar (por exemplo, redimensionar, cortar) GIFs animados que mantêm a animação. Portanto, não é realista para o ngx_small_light suportar um GIF animado.

Se o GIF animado for fornecido, o ngx_small_light transforma apenas o primeiro quadro.

Executando Testes

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

Você pode encontrar dicas adicionais de configuração e documentação para este módulo no repositório GitHub para nginx-module-small-light.