The ngx_http_image_filter_module module (0.7.54+) is a filter
that transforms images in JPEG, GIF, and PNG formats.
This module is not built by default, it should be enabled with the
--with-http_image_filter_module
configuration parameter.
This module utilizes the
libgd library.
It is recommended to use the latest available version of the library;
it is version 2.0.35 as of this writing.
Example Configuration
location /img/ {
proxy_pass http://backend;
image_filter resize 150 100;
image_filter rotate 90;
error_page 415 = /empty;
}
location = /empty {
empty_gif;
}
Directives
syntax:
|
image_filter off ;
image_filter test ;
image_filter size ;
image_filter
rotate
90 | 180 |
270 ;
image_filter
resize
width
height ;
image_filter
crop
width
height ;
|
default:
|
image_filter off;
|
context:
|
location
|
Sets the type of transformation to perform on images:
off
-
turns off module processing in a surrounding location.
test
-
ensures that responses are images in either JPEG, GIF, or PNG format.
Otherwise, the error
415 (Unsupported Media Type)
is returned.
size
-
outputs information about images in a JSON format, e.g.:
{ "img" : { "width": 100, "height": 100, "type": "gif" } }
In case of an error, the following is output:
{}
rotate
90 |180 |270
-
rotates images counter-clockwise by the specified number of degrees.
Value of the parameter can contain variables.
Can be used either alone, or along with the
resize and crop transformations.
resize
width
height
-
proportionally reduces an image to the specified sizes.
To reduce by only one dimension, another dimension can be specified as
“
- ”.
In case of an error, the server will return code
415 (Unsupported Media Type).
Values of parameters can contain variables.
When used along with the rotate parameter,
the rotation happens after reduction.
crop
width
height
-
proportionally reduces an image to the size of the largest side
and crops extraneous edges by another side.
To reduce by only one dimension, another dimension can be specified as
“
- ”.
In case of an error, the server will return code
415 (Unsupported Media Type).
Values of parameters can contain variables.
When used along with the rotate parameter,
the rotation happens before reduction.
syntax:
|
image_filter_buffer size ;
|
default:
|
image_filter_buffer 1M;
|
context:
|
http , server , location
|
Sets the maximum size of the buffer used for reading images.
When a size is exceeded the server will return error
415 (Unsupported Media Type).
syntax:
|
image_filter_jpeg_quality quality ;
|
default:
|
image_filter_jpeg_quality 75;
|
context:
|
http , server , location
|
Sets the desired quality of the transformed JPEG images.
Acceptable values are in the 1..100 range.
Lesser values usually imply both lower image quality and less data to transfer.
The maximum recommended value is 95.
Value of the parameter can contain variables.
syntax:
|
image_filter_sharpen percent ;
|
default:
|
image_filter_sharpen 0;
|
context:
|
http , server , location
|
Increases sharpness of the final image.
The sharpness percentage can exceed 100.
The value of 0 disables sharpening.
Value of the parameter can contain variables.
syntax:
|
image_filter_transparency on |off ;
|
default:
|
image_filter_transparency on;
|
context:
|
http , server , location
|
Defines whether transparency should be preserved when transforming
PNG images with colors specified by a palette, or in GIF images.
The loss of transparency allows to obtain images of a better quality.
The alpha channel transparency in PNG is always preserved.
|