Mercurial > hg > nginx-site

comparison xml/en/docs/http/ngx_http_image_filter_module.xml @ 204:eed54ef19197

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
English translation of the ngx_http_image_filter_module documentation.
author Ruslan Ermilov <ru@nginx.com>
date Fri, 25 Nov 2011 09:57:32 +0000
parents
children f743d1f4683a
comparison
equal deleted inserted replaced
203:876d36c69e01 204:eed54ef19197
1 <?xml version="1.0" encoding="utf-8"?>
2
3 <!DOCTYPE module SYSTEM "../../../../dtd/module.dtd">
4
5 <module name="Module ngx_http_image_filter_module"
6 link="/en/docs/http/ngx_http_image_filter_module.html"
7 lang="en">
8
9 <section id="summary">
10
11 <para>
12 The <code>ngx_http_image_filter_module</code> module is a filter
13 that transforms images in JPEG, GIF, and PNG (0.7.54+) formats.
14 </para>
15
16 <para>
17 This module is not built by default, it should be enabled with the
18 <code>--with-http_image_filter_module</code>
19 configuration parameter.
20 <note>
21 This module utilizes the
22 <link url="http://libgd.org">libgd</link> library.
23 It is recommended to use the latest available version of the library;
24 it is version 2.0.35 as of this writing.
25 </note>
26 </para>
27
28 </section>
29
30
31 <section id="example" name="Example Configuration">
32
33 <para>
34 <example>
35 location /img/ {
36 proxy_pass http://backend;
37 image_filter resize 150 100;
38 image_filter rotate 90;
39 error_page 415 = /empty;
40 }
41
42 location = /empty {
43 empty_gif;
44 }
45 </example>
46 </para>
47
48 </section>
49
50
51 <section id="directives" name="Directives">
52
53 <directive name="image_filter">
54 <syntax><parameter>off</parameter></syntax>
55 <syntax><parameter>test</parameter></syntax>
56 <syntax><parameter>size</parameter></syntax>
57 <syntax><parameter>rotate </parameter>
58 <value>90</value> | <value>180</value> | <value>270</value>
59 </syntax>
60 <syntax>
61 <parameter>resize </parameter>
62 <argument>width height</argument>
63 </syntax>
64 <syntax>
65 <parameter>crop </parameter>
66 <argument>width height</argument>
67 </syntax>
68 <default/>
69 <context>location</context>
70
71 <para>
72 Sets the type of transformation to perform on images:
73 <list type="tag">
74
75 <tag-name><parameter>off</parameter></tag-name>
76 <tag-desc>
77 turns off module processing in a surrounding location.
78 </tag-desc>
79
80 <tag-name><parameter>test</parameter></tag-name>
81 <tag-desc>
82 ensures that answers are images in either JPEG, GIF, or PNG format.
83 Otherwise, the error
84 <http-status code="415" text="Unsupported Media Type"/>
85 is returned.
86 </tag-desc>
87
88 <tag-name><parameter>size</parameter></tag-name>
89 <tag-desc>
90 outputs information about images in a JSON format, e.g.:
91 <example>
92 { "img" : { "width": 100, "height": 100, "type": "gif" } }
93 </example>
94 In case of an error, the following is output:
95 <example>
96 {}
97 </example>
98 </tag-desc>
99
100 <tag-name><parameter>rotate </parameter>
101 <value>90</value>|<value>180</value>|<value>270</value>
102 </tag-name>
103 <tag-desc>
104 rotates images counter-clockwise by the specified number of degrees.
105 The argument value can contain variables.
106 Can be used either alone, or along with the
107 <parameter>resize</parameter> and <parameter>crop</parameter> transformations.
108 </tag-desc>
109
110 <tag-name><parameter>resize </parameter>
111 <argument>width height</argument>
112 </tag-name>
113 <tag-desc>
114 proportionally reduces an image to the specified sizes.
115 To reduce by only one dimension, another dimension can be specified as
116 “<code>-</code>”.
117 In case of an error, the server will return code
118 <http-status code="415" text="Unsupported Media Type"/>.
119 Values of arguments can contain variables.
120 When used along with the <parameter>rotate</parameter> parameter,
121 the rotation happens <emphasis>after</emphasis> reduction.
122 </tag-desc>
123
124 <tag-name><parameter>crop </parameter>
125 <argument>width height</argument>
126 </tag-name>
127 <tag-desc>
128 proportionally reduces an image to the size of the largest side
129 and crops extraneous edges by another side.
130 To reduce by only one dimension, another dimension can be specified as
131 “<code>-</code>”.
132 In case of an error, the server will return code
133 <http-status code="415" text="Unsupported Media Type"/>.
134 Values of arguments can contain variables.
135 When used along with the <parameter>rotate</parameter> parameter,
136 the rotation happens <emphasis>before</emphasis> reduction.
137 </tag-desc>
138
139 </list>
140 </para>
141
142 </directive>
143
144
145 <directive name="image_filter_buffer">
146 <syntax><value>size</value></syntax>
147 <default>1M</default>
148 <context>http</context>
149 <context>server</context>
150 <context>location</context>
151
152 <para>
153 Sets the maximum size of the buffer used for reading images.
154 When a size is exceeded the server will return error
155 <http-status code="415" text="Unsupported Media Type"/>.
156 </para>
157
158 </directive>
159
160
161 <directive name="image_filter_jpeg_quality">
162 <syntax><value>1..100</value></syntax>
163 <default>75</default>
164 <context>http</context>
165 <context>server</context>
166 <context>location</context>
167
168 <para>
169 Sets the desired quality of the transformed JPEG images.
170 Lesser values usually imply both lower quality and smaller image sizes.
171 The maximum recommended value is 95.
172 The argument value can contain variables.
173 </para>
174
175 </directive>
176
177
178 <directive name="image_filter_sharpen">
179 <syntax><argument>percent</argument></syntax>
180 <default>0</default>
181 <context>http</context>
182 <context>server</context>
183 <context>location</context>
184
185 <para>
186 Increases sharpness of the final image.
187 The sharpness percentage can exceed 100.
188 The value of 0 disables sharpening.
189 The argument value can contain variables.
190 </para>
191
192 </directive>
193
194
195 <directive name="image_filter_transparency">
196 <syntax><value>on</value>|<value>off</value></syntax>
197 <default>on</default>
198 <context>http</context>
199 <context>server</context>
200 <context>location</context>
201
202 <para>
203 Defines whether transparency should be preserved when transforming
204 PNG images with colors specified by a palette, or in GIF images.
205 The loss of transparency allows to obtain images of a better quality.
206 The alpha channel transparency in PNG is always preserved.
207 </para>
208
209 </directive>
210
211 </section>
212
213 </module>