README.md
1# ngx_small_light
2
3A dynamic image transformation module for [nginx](http://nginx.org/).
4
5# Table of contents
6
7* [Features](#features)
8* [Supported Formats](#supported-formats)
9* [Dependencies](#dependencies)
10* [Installation](#installation)
11 * [Dynamic module](#dynamic-module)
12* [Getting started](#getting-started)
13* [Configuration example](#configuration-example)
14* [Directives](#directives)
15 * [small_light](#small_light)
16 * [small_light_getparam_mode](#small_light_getparam_mode)
17 * [small_light_material_dir](#small_light_material_dir)
18 * [small_light_pattern_define](#small_light_pattern_define)
19 * [small_light_imlib2_temp_dir](#small_light_imlib2_temp_dir)
20 * [small_light_buffer](#small_light_buffer)
21* [Parameters for small_light function](#parameters-for-small_light-function)
22* [Named Pattern](#named-pattern)
23* [Using GET parameters](#using-get-parameters)
24* [Enabling WebP transformation](#enabling-webp-transformation)
25* [Optimizing Tips](#optimizing-tips)
26 * [JPEG hinting](#jpeg-hinting)
27 * [Limit thread-number with OpenMP](#limit-thread-number-with-openmp)
28* [Limitations](#limitations)
29 * [Not supported features with Imlib2](#not-supported-features-with-imlib2)
30 * [Not supported features with GD](#not-supported-features-with-gd)
31 * [Not supported animated GIF](#not-supported-animated-gif)
32* [Running Tests](#running-tests)
33* [License](#license)
34
35## Features
36
37Supports the various image-processings below.
38
39 * Resize
40 * Rotate
41 * Sharpen
42 * Unsharpen
43 * Blur
44 * Border
45 * Canvas
46 * Crop
47 * Composition
48 * JPEG Hinting(except GD)
49 * Format convert(e.g. PNG -> JPEG)
50 * Color-space convert(e.g. CMYK -> sRGB)
51
52`ngx_small_light` is developed for using as the same way as [mod_small_light](https://github.com/yamac/smalllight) as possible in nginx.
53
54## Supported Formats
55
56Supports the formats below.
57
58 * JPEG
59 * GIF(except Imlib2)
60 * PNG
61 * WebP(except Imlib2)
62
63## Dependencies
64
65 - [PCRE](http://www.pcre.org/) (required)
66 - [ImageMagick](http://www.imagemagick.org/script/index.php) (required)
67 - [Imlib2](http://docs.enlightenment.org/api/imlib2/html/) (optional)
68 - [GD](http://libgd.bitbucket.org/) (optional)
69
70## Installation
71
72```sh
73cd ${ngx_small_light_src_dir}
74./setup
75cd {$nginx_src_dir}
76./configure --add-module=${ngx_small_light_src_dir}
77make
78make install
79```
80
81If you want to enable the libraries except ImageMagick in `ngx_small_light`, add the options below when executing `setup`. (ImageMagick is always enabled)
82
83```sh
84./setup # enable ImageMagick
85./setup --with-imlib2 # enable ImageMagick and Imlib2
86./setup --with-gd # enable ImageMagick and GD
87./setup --with-imlib2 --with-gd # enable ImageMagick and Imlib2 and GD
88```
89
90### Dynamic module
91
92You can also compile `ngx_small_light` as the dynamic module with `--add-dynamic-module` in nginx-1.9.11 and ngx_small_light-0.6.15 or later.
93
94```sh
95cd ${ngx_small_light_src_dir}
96./setup
97cd {$nginx_src_dir}
98./configure \
99--modules-path=/usr/local/nginx/modules \
100--add-dynamic-module=${ngx_small_light_src_dir}
101make
102make install
103```
104
105Add the configuration below for loading module dynamically.
106
107```nginx
108load_module /usr/local/nginx/modules/ngx_http_small_light_module.so;
109```
110
111## Getting started
112
113Add the configuration below to some server context in nginx.conf and start nginx.
114
115```nginx
116small_light on;
117location ~ small_light[^/]*/(.+)$ {
118 set $file $1;
119 rewrite ^ /$file;
120}
121```
122
123If you can get the original image of image.jpg from the URL below,
124
125```
126http://$host:$port/img/image.jpg
127```
128
129You will be able to get the converted image of image.jpg from the URL below.
130
131```
132http://$host:$port/small_light(dw=300,dh=300)/img/image.jpg
133```
134
135The part of `small_light(...)` is called **small_light function**.
136
137## Configuration example
138
139There is some configuration example below.
140
141```nginx
142server {
143 listen 8000;
144 server_name localhost;
145
146 small_light on;
147 small_light_pattern_define msize dw=500,dh=500,da=l,q=95,e=imagemagick,jpeghint=y;
148 small_light_pattern_define ssize dw=120,dh=120,da=l,q=95,e=imlib2,jpeghint=y;
149
150 # http://localhost:8000/small_light(p=msize)/img/filename.jpg -> generate msize image
151 # http://localhost:8000/small_light(p=ssize)/img/filename.jpg -> generate ssize image
152 # http://localhost:8000/small_light(of=gif,q=100)/img/filename.jpg -> generate gif image which quality is 100
153 location ~ small_light[^/]*/(.+)$ {
154 set $file $1;
155 rewrite ^ /$file;
156 }
157}
158```
159
160## Directives
161
162### small_light
163
164|Syntax |*small_light on | off*|
165|-----------|---------------------------|
166|**Default**|off |
167|**Context**|server, location |
168
169This directive sets whether image-processing with `ngx_small_light` is enabled in a server context.
170
171### small_light_getparam_mode
172
173|Syntax |*small_light_getparam_mode on | off*|
174|-----------|-----------------------------------------|
175|**Default**|off |
176|**Context**|server, location |
177
178This directive sets whether converting-image is enabled by GET parameters
179instead of **small_light function** (e.g. `/small_light(dw=200,dh=200)`).
180At the expense of it, a **small_light function** is disabled.
181But you need to set both `small_light` and `small_light_getparam_mode` **on** to enable the feature of this directive.
182
183### small_light_material_dir
184
185|Syntax |*small_light_material_dir path*|
186|-----------|---------------------------------------------|
187|**Default**| |
188|**Context**|server |
189
190This directive assigns the directory for embedded icon images.
191
192### small_light_pattern_define
193
194|Syntax |*small_light_pattern_define pattern_name parameters*|
195|-----------|----------------------------------------------------|
196|**Default**| |
197|**Context**|server |
198
199This directive names comma-delimited parameters.
200
201### small_light_radius_max
202
203|Syntax |*small_light_radius_max number*|
204|-----------|-------------------------------|
205|**Default**|10 |
206|**Context**|server,location |
207
208This directive sets maximum radius value of geometry for `sharpen` and `unsharp` and `blur`.
209
210### small_light_sigma_max
211
212|Syntax |*small_light_sigma_max number*|
213|-----------|-------------------------------|
214|**Default**|10 |
215|**Context**|server,location |
216
217This directive sets maximum sigma value of geometry for `sharpen` and `unsharp` and `blur`.
218
219### small_light_imlib2_temp_dir
220
221|Syntax |*small_light_imlib2_temp_dir path* [*level1* [*level2* [*level 3* ]]]|
222|-----------|---------------------------------------------------------------------|
223|**Default**|small_light_imlib2_temp 1 2 |
224|**Context**|server |
225
226This directive assigns the directory for temporary file for Imlib2 processing.
227This directive is available when Imlib2 is enabled.
228
229### small_light_buffer
230
231|Syntax |*small_ligh_buffer size*|
232|-----------|------------------------|
233|**Default**|1m |
234|**Context**|server |
235
236This directive assigns the maximum size of the buffer used for reading images
237when Content-Length is not set in response headers.
238
239## Parameters for small_light function
240
241|Parameter |Type |Default |Description |ImageMagick|Imlib2|GD |
242|-----------|------|-----------|------------------------------------------------|-----------|------|---|
243|p |string| |named pattern of comma-delimited parameters | :o:| :o:|:o:|
244|e |string|imagemagick|engine name (imagemagick, imlib2, gd) | | | |
245|q |number| |quality | :o:| :o:|:o:|
246|of |string| |output format (jpg, gif, png, webp) | :o:| :o:|:o:|
247|jpeghint |char |n |enable jpeg hinting (y, n) | :o:| :o:|:x:|
248|dw |coord |sw |destination width | :o:| :o:|:o:|
249|dh |coord |sh |destination height | :o:| :o:|:o:|
250|dx |coord |sx |destination x coordinate | :o:| :o:|:o:|
251|dy |coord |sy |destination y coordinate | :o:| :o:|:o:|
252|da |char |l |destination aspect ratio contol (l, s) | :o:| :o:|:o:|
253|ds |char |n |destination scaling control (s, n) | :o:| :o:|:o:|
254|cw |number| |canvas width | :o:| :o:|:o:|
255|ch |number| |canvas height | :o:| :o:|:o:|
256|cc |color |000000 |canvas color | :o:| :o:|:o:|
257|bw |number| |border width | :o:| :o:|:o:|
258|bh |number| |border height | :o:| :o:|:o:|
259|bc |color |000000 |border color | :o:| :o:|:o:|
260|sw |coord | |source witdh | :o:| :o:|:o:|
261|sh |coord | |source height | :o:| :o:|:o:|
262|sx |coord | |source x coordinate | :o:| :o:|:o:|
263|sy |coord | |source y coordinate | :o:| :o:|:o:|
264|pt |char |n |pass through control (y, n) | :o:| :o:|:o:|
265|sharpen |string| |radius,sigma (e.g. 10x5) | :o:| :o:|:o:|
266|unsharp |string| |radius,sigma,amount,threshold (e.g 2x5+0.5+0) | :o:| :x:|:x:|
267|blur |string| |radius,sigma (e.g. 5x10) | :o:| :o:|:x:|
268|embedicon |string| |embedded icon file in `small_light_material_dir`| :o:| :x:|:x:|
269|ix |number|0 |embedded icon x coordinate | :o:| :x:|:x:|
270|iy |number|0 |embedded icon y coordinate | :o:| :x:|:x:|
271|angle |number|0 |angle of rotation (90, 180, 270) | :o:| :o:|:o:|
272|progressive|char |n |make JPEG progressive (y, n) | :o:| :x:|:x:|
273|cmyk2rgb |char |n |convert colorspace from CMYK to sRGB (y, n) | :o:| :x:|:x:|
274|rmprof |char |n |remove profile (y, n) | :o:| :x:|:x:|
275|autoorient |char |n |enable adjust image orientation automatically (y, n) | :o:| :x:|:x:|
276
277There are any limitations below.
278
279 * `of=gif` and `of=webp` are not supported when `e=imlib2`.
280 * `autoorient` is available ImageMagick-6.9.0 or later.
281 * The value of `radius,sigma` for `sharpen` and `unsharp` and `blur` is limited by `small_light_radius_max` and `small_light_sigma_max`.
282
283There are the types of each parameter below.
284
285|Type |Description |
286|------|-------------------------------------------------|
287|coord |coordicante or pixel. percent when appending 'p' |
288|char |character |
289|number|integer number |
290|color |rrggbb or rrggbbaa |
291|string|string |
292
293## Named Pattern
294
295`ngx_small_light` supports to name comma-delimited parameters with the `small_light_define_patern`.
296
297```nginx
298small_light_pattern_define small dw=120,dh=120,q=80,e=imagemagick,jpeghint=y;
299```
300
301If the line above is added to some server context in nginx.conf, the two URLs below return same response.
302
303 * `http://$host:$port/small_light(p=small)/img/image.jpg`
304 * `http://$host:$port/small_light(dw=120,dh=120,q=80,e=imagemagick,jpeghint=y)/img/image.jpg`
305
306## Using GET parameters
307
308`ngx_small_light` supports to convert image not only by **small_light function** but by GET paramenters in `v0.5.0` or later.
309You need to set both `small_light` and `small_light_getparam_mode` **on** to enable this feature.
310At the expense of enabling this feature, **small_light function** (e.g. `/small_light(dw=300,dh=300)/img.jpg` is disabled.
311
312```nginx
313small_light on;
314small_light_getparam_mode on;
315```
316
317In the configuration above, the url below does not return converted image.
318
319```
320http://localhost:8000/small_light(dw=200,dh=200)/img/image.jpg
321```
322
323Instead the url below returns converted image expected by right.
324
325```
326http://localhost:8000/img/image.jpg?dw=200&dh=200
327```
328
329## Enabling WebP Transformation
330
331`ngx_small_light` supports WebP transformation with ImageMagick and GD.
332Given `of=webp` to **small_light function**, `ngx_small_light` transforms image format into WebP.
333But ImageMagick requires libwebp and GD requires libvpx.
334You need to embed these libraries in building ImageMagick and GD for enabling WebP transformation.
335
336If WebP transformation is not available, `nginx` outputs the line like below in error.log in processing image with `of=webp`.
337
338```
339WebP is not supported
340```
341
342If WebP transformation with ImageMagick is available, the output of `convert -list format` includes the line like below.
343
344```
345$ convert -list format | grep -i webp
346 WEBP* WEBP rw- WebP Image Format (libwebp 0.5.0[0208])
347```
348
349If WebP transformation with GD is available, the output of `gdlib-config --libs` includes `-lvpx`.
350
351In general, the packages of ImageMagick and GD provided from the linux distributions
352such as Ubuntu and CentOS does not embed the library for WebP transformation by default.
353In such cases, you need to build ImageMagick or GD yourself.
354
355## Optimizing Tips
356
357There are some optimizing tips for `ngx_small_light`.
358
359### JPEG hinting
360
361When the output format is JPEG and image-converting engine is ImageMagick or Imlib2,
362you may give `jpeghint=y`. The speed of processing images is improved dramatically.
363
364### Limit thread-number with OpenMP
365
366When image-converting engine is ImageMagick and the version of `ngx_small_light` is lower than `v0.6.14`,
367giving 1 to `OMP_NUM_THREADS` or `MAGICK_THREAD_LIMIT` in `nginx.conf` is recommended strongly.
368Because OpenMP is enabled in ImageMagick by default and ImageMagick enabled OpenMP is very slow on multi-process environment.
369
370```nginx
371env OMP_NUM_THREADS=1; # or env MAGICK_THREAD_LIMIT=1;
372```
373
374Or you can avoid this problem by building ImageMagick with `--disable-openmp`.
375
376In `v0.6.14` or later, they are no longer required. Because `ngx_small_light` always sets the thread-number with OpenMP 1.
377
378# Limitations
379
380`ngx_small_light` has the limitations below.
381
382## Not supported features with Imlib2
383
384The transformation with Imlib2 does not support to write GIF-image.
385Because Imlib2 has the function for loading GIF-image but does not have the function for saving.
386Additionally, the transformation by Imlib2 does not support to write and read WebP-image.
387So `of=gif` and `e=imlib2` are not enabled to specify at once.
388If these are specified, `ngx_small_light` returns 415(Unsupported Media Type).
389
390## Not supported features with GD
391
392The transformation with GD supports to write WebP-image. But it is the experimental feature.
393
394## Not supported animated GIF
395
396`ngx_small_light` does not support the transformation kept animation for animated GIF.
397Because it takes long time to transform(e.g. resize, crop) animated GIF kept animation.
398So it is not realistic for `ngx_small_light` to support an animated GIF.
399
400If the animated GIF is given, `ngx_small_light` transforms only the first frame.
401
402# Running Tests
403
404```sh
405perl Build.PL
406cpanm --installdeps .
407NGINX_BIN=${nginx_prefix_dir}/sbin/nginx ./Build test
408# or
409NGINX_BIN=${nginx_prefix_dir}/sbin/nginx prove t/**/*.t
410```
411
412# License
413
414Please read the [COPYING](https://github.com/cubicdaiya/ngx_small_light/blob/master/COPYING).
415
/img/image.jpg){kind=link}
/img/filename.jpg){kind=link}
/img/filename.jpg){kind=link}
/img/filename.jpg){kind=link}
/img/image.jpg){kind=link}
/img/image.jpg){kind=link}
/img/image.jpg){kind=link}
