A dynamic image transformation module for nginx.
- Features
- Supported Formats
- Dependencies
- Installation
- Dynamic module
- Getting started
- Configuration example
- Directives
- small_light
- small_light_getparam_mode
- small_light_material_dir
- small_light_pattern_define
- small_light_imlib2_temp_dir
- small_light_buffer
- Parameters for small_light function
- Named Pattern
- Using GET parameters
- Optimizing Tips
- Limitations
- Not supported features with Imlib2
- Not supported features with GD
- Not supported animated GIF
- Running Tests
- License
Supports the various image-processings below.
- Resize
- Rotate
- Sharpen
- Unsharpen
- Blur
- Border
- Canvas
- Crop
- Composition
- JPEG Hinting(except GD)
- Format convert(e.g. PNG -> JPEG)
- Color-space convert(e.g. CMYK -> sRGB)
ngx_small_light
is developed for using as the same way as mod_small_light as possible in nginx.
Supports the formats below.
- JPEG
- GIF(except Imlib2)
- PNG
- WebP(except Imlib2)
- PCRE (required)
- ImageMagick (required)
- Imlib2 (optional)
- GD (optional)
cd ${ngx_small_light_src_dir}
./setup
cd {$nginx_src_dir}
./configure --add-module=${ngx_small_light_src_dir}
make
make install
If you want to enable the libraries except ImageMagick in ngx_small_light
, add the options below when executing setup
. (ImageMagick is always enabled)
./setup # enable ImageMagick
./setup --with-imlib2 # enable ImageMagick and Imlib2
./setup --with-gd # enable ImageMagick and GD
./setup --with-imlib2 --with-gd # enable ImageMagick and Imlib2 and GD
You can also compile ngx_small_light
as the dynamic module with --add-dynamic-module
from nginx-1.9.11 and ngx_small_light-0.6.15.
cd ${ngx_small_light_src_dir}
./setup
cd {$nginx_src_dir}
./configure \
--modules-path=/usr/local/nginx/modules \
--add-dynamic-module=${ngx_small_light_src_dir}
make
make install
Add the configuration below for loading module dynamically.
load_module /usr/local/nginx/modules/ngx_http_small_light_module.so;
Add the configuration below to some server context in nginx.conf and start nginx.
small_light on;
location ~ small_light[^/]*/(.+)$ {
set $file $1;
rewrite ^ /$file;
}
If you can get the original image of image.jpg from the URL below,
http://$host:$port/img/image.jpg
You will be able to get the converted image of image.jpg from the URL below.
http://$host:$port/small_light(dw=300,dh=300)/img/image.jpg
The part of small_light(...)
is called small_light function.
There is some configuration example below.
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 -> generate msize image
# http://localhost:8000/small_light(p=ssize)/img/filename.jpg -> generate ssize image
# http://localhost:8000/small_light(of=gif,q=100)/img/filename.jpg -> generate gif image which quality is 100
location ~ small_light[^/]*/(.+)$ {
set $file $1;
rewrite ^ /$file;
}
}
Syntax | small_light on | off |
---|---|
Default | off |
Context | server, location |
This directive sets whether image-processing with ngx_small_light
is enabled in a server context.
Syntax | small_light_getparam_mode on | off |
---|---|
Default | off |
Context | server, location |
This directive sets whether converting-image is enabled by GET parameters
instead of small_light function (e.g. /small_light(dw=200,dh=200)
).
At the expense of it, a small_light function is disabled.
But you need to set both small_light
and small_light_getparam_mode
on to enable the feature of this directive.
Syntax | small_light_material_dir path |
---|---|
Default | |
Context | server |
This directive assigns the directory for embedded icon images.
Syntax | small_light_pattern_define pattern_name parameters |
---|---|
Default | |
Context | server |
This directive names comma-delimited parameters.
Syntax | small_light_radius_max number |
---|---|
Default | 10 |
Context | server,location |
This directive sets maximum radius value of geometry for sharpen
and unsharp
and blur
.
Syntax | small_light_sigma_max number |
---|---|
Default | 10 |
Context | server,location |
This directive sets maximum sigma value of geometry for sharpen
and unsharp
and blur
.
Syntax | small_light_imlib2_temp_dir path [level1 [level2 [level 3 ]]] |
---|---|
Default | /tmp 1 2 |
Context | server |
This directive assigns the directory for temporary file for Imlib2 processing.
Syntax | small_ligh_buffer size |
---|---|
Default | 1m |
Context | server |
This directive assigns the maximum size of the buffer used for reading images when Content-Length is not set in response headers.
Parameter | Type | Default | Description | ImageMagick | Imlib2 | GD |
---|---|---|---|---|---|---|
p | string | named pattern of comma-delimited parameters | ⭕ | ⭕ | ⭕ | |
e | string | imagemagick | engine name(imagemagick, imlib2, gd) | |||
q | number | quality | ⭕ | ⭕ | ⭕ | |
of | string | output format(jpg, gif, png, webp) | ⭕ | ⭕ | ⭕ | |
jpeghint | char | n | enable jpeg hinting | ⭕ | ⭕ | ❌ |
dw | coord | sw | destination width | ⭕ | ⭕ | ⭕ |
dh | coord | sh | destination height | ⭕ | ⭕ | ⭕ |
dx | coord | sx | destination x coordinate | ⭕ | ⭕ | ⭕ |
dy | coord | sy | destination y coordinate | ⭕ | ⭕ | ⭕ |
da | char | l | destination aspect ratio contol | ⭕ | ⭕ | ⭕ |
ds | char | n | destination scaling control(s, n) | ⭕ | ⭕ | ⭕ |
cw | number | canvas width | ⭕ | ⭕ | ⭕ | |
ch | number | canvas height | ⭕ | ⭕ | ⭕ | |
cc | color | 000000 | canvas color | ⭕ | ⭕ | ⭕ |
bw | number | border width | ⭕ | ⭕ | ⭕ | |
bh | number | border height | ⭕ | ⭕ | ⭕ | |
bc | color | 000000 | border color | ⭕ | ⭕ | ⭕ |
sw | coord | source witdh | ⭕ | ⭕ | ⭕ | |
sh | coord | source height | ⭕ | ⭕ | ⭕ | |
sx | coord | source x coordinate | ⭕ | ⭕ | ⭕ | |
sy | coord | source y coordinate | ⭕ | ⭕ | ⭕ | |
pt | char | n | pass through control | ⭕ | ⭕ | ⭕ |
sharpen | string | radius,sigma | ⭕ | ⭕ | ⭕ | |
unsharp | string | radius,sigma,amount,threshold | ⭕ | ❌ | ❌ | |
blur | string | radius,sigma | ⭕ | ⭕ | ❌ | |
embedicon | string | embedded icon file in small_light_material_dir |
⭕ | ❌ | ❌ | |
ix | number | 0 | embedded icon x coordinate | ⭕ | ❌ | ❌ |
iy | number | 0 | embedded icon y coordinate | ⭕ | ❌ | ❌ |
angle | number | 0 | angle of rotation(90, 180, 270) | ⭕ | ⭕ | ⭕ |
progressive | char | n | make JPEG progressive | ⭕ | ❌ | ❌ |
cmyk2rgb | char | n | convert colorspace from CMYK to sRGB | ⭕ | ❌ | ❌ |
rmprof | char | n | remove profile | ⭕ | ❌ | ❌ |
autoorient | char | n | enable adjust image orientation automatically | ⭕ | ❌ | ❌ |
There are any limitations below.
of=gif
andof=webp
are not supported whene=imlib2
.autoorient
is available ImageMagick-6.9.0 or later.- The value of
radius,sigma
forsharpen
andunsharp
andblur
is limited bysmall_light_radius_max
andsmall_light_sigma_max
.
There are the types of each parameter below.
Type | Description |
---|---|
coord | coordicante or pixel. percent when appending 'p' |
char | character |
number | integer number |
color | rrggbb or rrggbbaa |
string | string |
ngx_small_light
supports to name comma-delimited parameters with the small_light_define_patern
.
small_light_pattern_define small dw=120,dh=120,q=80,e=imagemagick,jpeghint=y;
If the line above is added to some server context in nginx.conf, the two URLs below return same response.
http://$host:$port/small_light(p=small)/img/image.jpg
http://$host:$port/small_light(dw=120,dh=120,q=80,e=imagemagick,jpeghint=y)/img/image.jpg
ngx_small_light
supports to convert image not only by small_light function but by GET paramenters from v0.5.0
.
You need to set both small_light
and small_light_getparam_mode
on to enable this feature.
At the expense of enabling this feature, small_light function (e.g. /small_light(dw=300,dh=300)/img.jpg
is disabled.
small_light on;
small_light_getparam_mode on;
In the configuration above, the url below does not return converted image.
http://localhost:8000/small_light(dw=200,dh=200)/img/image.jpg
Instead the url below returns converted image expected by right.
http://localhost:8000/img/image.jpg?dw=200&dh=200
Or you can avoid this problem by building ImageMagick with --disable-openmp
.
When the output format is JPEG and image-converting engine is ImageMagick or Imlib2,
you may give 'y' to the parameter jpeghint
. The speed of processing images is improved dramatically.
And when image-converting engine is ImageMagick and the version of ngx_small_light
is lower than v0.6.14
,
giving 1 to OMP_NUM_THREADS
or MAGICK_THREAD_LIMIT
in nginx.conf
is recommended strongly.
Because OpenMP is enabled in ImageMagick by default and ImageMagick enabled OpenMP is very slow on multi-process environment.
env OMP_NUM_THREADS=1; # or env MAGICK_THREAD_LIMIT=1;
From v0.6.14
, ngx_small_light
sets the thread-number with OpenMP 1 always.
ngx_small_light
has the limitations below.
The transformation with Imlib2 does not support to write GIF-image.
Because Imlib2 has the function for loading GIF-image but does not have the function for saving.
Additionally, the transformation by Imlib2 does not support to write and read WebP-image.
So of=gif
and e=imlib2
are not enabled to specify at once.
If these are specified, ngx_small_light
returns 415(Unsupported Media Type).
The transformation with GD supports to write WebP-image. But it is the experimental feature.
ngx_small_light
does not suport Animated GIF.
Because it takes long time to transform(e.g. resize, crop) Animated GIF with animation.
So it is not realistic for ngx_small_light
to support an animated GIF.
perl Build.PL
cpanm --installdeps .
NGINX_BIN=${nginx_prefix_dir}/sbin/nginx ./Build test
# or
NGINX_BIN=${nginx_prefix_dir}/sbin/nginx prove t/**/*.t
Please read the COPYING.