Mercurial > hg > nginx-site
view xml/en/docs/http/ngx_http_image_filter_module.xml @ 2091:fe66463d0799
Updated OpenSSL version used for win32 builds.
author | Yaroslav Zhuravlev <yar@nginx.com> |
---|---|
date | Wed, 27 Dec 2017 22:01:58 +0300 |
parents | 6ebdef43330a |
children |
line wrap: on
line source
<?xml version="1.0"?> <!-- Copyright (C) Igor Sysoev Copyright (C) Nginx, Inc. --> <!DOCTYPE module SYSTEM "../../../../dtd/module.dtd"> <module name="Module ngx_http_image_filter_module" link="/en/docs/http/ngx_http_image_filter_module.html" lang="en" rev="4"> <section id="summary"> <para> The <literal>ngx_http_image_filter_module</literal> module (0.7.54+) is a filter that transforms images in JPEG, GIF, PNG, and WebP formats. </para> <para> This module is not built by default, it should be enabled with the <literal>--with-http_image_filter_module</literal> configuration parameter. <note> This module utilizes the <link url="http://libgd.org">libgd</link> library. It is recommended to use the latest available version of the library. </note> <note> The WebP format support appeared in version 1.11.6. To transform images in this format, the <literal>libgd</literal> library must be compiled with the WebP support. </note> </para> </section> <section id="example" name="Example Configuration"> <para> <example> location /img/ { proxy_pass http://backend; image_filter resize 150 100; image_filter rotate 90; error_page 415 = /empty; } location = /empty { empty_gif; } </example> </para> </section> <section id="directives" name="Directives"> <directive name="image_filter"> <syntax><literal>off</literal></syntax> <syntax><literal>test</literal></syntax> <syntax><literal>size</literal></syntax> <syntax> <literal>rotate</literal> <literal>90</literal> | <literal>180</literal> | <literal>270</literal></syntax> <syntax> <literal>resize</literal> <value>width</value> <value>height</value></syntax> <syntax> <literal>crop</literal> <value>width</value> <value>height</value></syntax> <default>off</default> <context>location</context> <para> Sets the type of transformation to perform on images: <list type="tag"> <tag-name><literal>off</literal></tag-name> <tag-desc> turns off module processing in a surrounding location. </tag-desc> <tag-name><literal>test</literal></tag-name> <tag-desc> ensures that responses are images in either JPEG, GIF, PNG, or WebP format. Otherwise, the <http-status code="415" text="Unsupported Media Type"/> error is returned. </tag-desc> <tag-name><literal>size</literal></tag-name> <tag-desc> outputs information about images in a JSON format, e.g.: <example> { "img" : { "width": 100, "height": 100, "type": "gif" } } </example> In case of an error, the output is as follows: <example> {} </example> </tag-desc> <tag-name><literal>rotate</literal> <literal>90</literal>|<literal>180</literal>|<literal>270</literal> </tag-name> <tag-desc> rotates images counter-clockwise by the specified number of degrees. Parameter value can contain variables. This mode can be used either alone or along with the <literal>resize</literal> and <literal>crop</literal> transformations. </tag-desc> <tag-name><literal>resize</literal> <value>width</value> <value>height</value> </tag-name> <tag-desc> proportionally reduces an image to the specified sizes. To reduce by only one dimension, another dimension can be specified as “<literal>-</literal>”. In case of an error, the server will return code <http-status code="415" text="Unsupported Media Type"/>. Parameter values can contain variables. When used along with the <literal>rotate</literal> parameter, the rotation happens <emphasis>after</emphasis> reduction. </tag-desc> <tag-name><literal>crop</literal> <value>width</value> <value>height</value> </tag-name> <tag-desc> proportionally reduces an image to the larger side size and crops extraneous edges by another side. To reduce by only one dimension, another dimension can be specified as “<literal>-</literal>”. In case of an error, the server will return code <http-status code="415" text="Unsupported Media Type"/>. Parameter values can contain variables. When used along with the <literal>rotate</literal> parameter, the rotation happens <emphasis>before</emphasis> reduction. </tag-desc> </list> </para> </directive> <directive name="image_filter_buffer"> <syntax><value>size</value></syntax> <default>1M</default> <context>http</context> <context>server</context> <context>location</context> <para> Sets the maximum size of the buffer used for reading images. When the size is exceeded the server returns error <http-status code="415" text="Unsupported Media Type"/>. </para> </directive> <directive name="image_filter_interlace"> <syntax><literal>on</literal> | <literal>off</literal></syntax> <default>off</default> <context>http</context> <context>server</context> <context>location</context> <appeared-in>1.3.15</appeared-in> <para> If enabled, final images will be interlaced. For JPEG, final images will be in “progressive JPEG” format. </para> </directive> <directive name="image_filter_jpeg_quality"> <syntax><value>quality</value></syntax> <default>75</default> <context>http</context> <context>server</context> <context>location</context> <para> Sets the desired <value>quality</value> of the transformed JPEG images. Acceptable values are in the range from 1 to 100. Lesser values usually imply both lower image quality and less data to transfer. The maximum recommended value is 95. Parameter value can contain variables. </para> </directive> <directive name="image_filter_sharpen"> <syntax><value>percent</value></syntax> <default>0</default> <context>http</context> <context>server</context> <context>location</context> <para> Increases sharpness of the final image. The sharpness percentage can exceed 100. The zero value disables sharpening. Parameter value can contain variables. </para> </directive> <directive name="image_filter_transparency"> <syntax><literal>on</literal>|<literal>off</literal></syntax> <default>on</default> <context>http</context> <context>server</context> <context>location</context> <para> Defines whether transparency should be preserved when transforming GIF images or PNG images with colors specified by a palette. The loss of transparency results in images of a better quality. The alpha channel transparency in PNG is always preserved. </para> </directive> <directive name="image_filter_webp_quality"> <syntax><value>quality</value></syntax> <default>80</default> <context>http</context> <context>server</context> <context>location</context> <appeared-in>1.11.6</appeared-in> <para> Sets the desired <value>quality</value> of the transformed WebP images. Acceptable values are in the range from 1 to 100. Lesser values usually imply both lower image quality and less data to transfer. Parameter value can contain variables. </para> </directive> </section> </module>