<?xml version="1.0"?>

<!DOCTYPE module SYSTEM "../../../../dtd/module.dtd">

<module name="Модуль ngx_http_image_filter_module"
        link="/ru/docs/http/ngx_http_image_filter_module.html"
        lang="ru">

<section id="summary">

<para>
Модуль <literal>ngx_http_image_filter_module</literal> — это фильтр
для преобразования изображений в форматах JPEG, GIF и PNG (0.7.54+).
</para>

<para>
По умолчанию этот модуль не собирается, его сборку необходимо
разрешить с помощью конфигурационного параметра
<literal>--with-http_image_filter_module</literal>.
<note>
Для сборки и работы этого модуля необходима библиотека
<link url="http://libgd.org">libgd</link>.
Рекомендуется использовать самую последнюю версию библиотеки,
на текущий момент это версия 2.0.35.
</note>
</para>

</section>


<section name="Пример конфигурации" id="example">

<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 name="Директивы" id="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>ширина</value>
        <value>высота</value></syntax>
    <syntax>
        <literal>crop</literal>
        <value>ширина</value>
        <value>высота</value></syntax>
<default/>
<context>location</context>

<para>
Задаёт тип преобразования изображения:
<list type="tag">

<tag-name><literal>off</literal></tag-name>
<tag-desc>
отключает обработку данным модулем во вложенном location.
</tag-desc>

<tag-name><literal>test</literal></tag-name>
<tag-desc>
проверяет, что ответ действительно является изображением
в формате JPEG, GIF или PNG.
В противном случае возвращается ошибка
<http-status code="415" text="Unsupported Media Type"/>.
</tag-desc>

<tag-name><literal>size</literal></tag-name>
<tag-desc>
выдаёт информацию об изображении в формате JSON, например:
<example>
{ "img" : { "width": 100, "height": 100, "type": "gif" } }
</example>
В случае ошибки выдаётся
<example>
{}
</example>
</tag-desc>

<tag-name><literal>rotate</literal>
<literal>90</literal>|<literal>180</literal>|<literal>270</literal>
</tag-name>
<tag-desc>
поворачивает изображение против часовой стрелки на указанное число градусов.
В значении параметра допустимо использование переменных.
Можно использовать как отдельно, так и совместно с преобразованиями
<literal>resize</literal> и <literal>crop</literal>.
</tag-desc>

<tag-name><literal>resize</literal>
<value>ширина</value>
<value>высота</value>
</tag-name>
<tag-desc>
пропорционально уменьшает изображение до указанных размеров.
Если требуется уменьшить только по одному измерению, то в качестве второго
можно указать “<literal>-</literal>”.
В случае ошибки сервер возвращает код
<http-status code="415" text="Unsupported Media Type"/>.
В значениях параметров допустимо использование переменных.
При использовании совместно с <literal>rotate</literal>,
поворот изображения происходит <emphasis>после</emphasis>
уменьшения размеров изображения.
</tag-desc>

<tag-name><literal>crop</literal>
<value>ширина</value>
<value>высота</value>
</tag-name>
<tag-desc>
пропорционально уменьшает изображение до размера большей стороны
и обрезает лишние края по другой стороне.
Если требуется уменьшить только по одному измерению, то в качестве второго
можно указать “<literal>-</literal>”.
В случае ошибки сервер возвращает код
<http-status code="415" text="Unsupported Media Type"/>.
В значениях параметров допустимо использование переменных.
При использовании совместно с <literal>rotate</literal>,
поворот изображения происходит <emphasis>до</emphasis>
уменьшения размеров изображения.
</tag-desc>

</list>
</para>

</directive>


<directive name="image_filter_buffer">
<syntax><value>размер</value></syntax>
<default>1M</default>
<context>http</context>
<context>server</context>
<context>location</context>

<para>
Задаёт максимальный размер буфера для чтения изображения.
При превышении размера сервер вернёт ошибку
<http-status code="415" text="Unsupported Media Type"/>.
</para>

</directive>


<directive name="image_filter_jpeg_quality">
<syntax><value>качество</value></syntax>
<default>75</default>
<context>http</context>
<context>server</context>
<context>location</context>

<para>
Задаёт желаемое <value>качество</value> преобразованного изображения в формате JPEG.
Допустимые значения находятся в диапазоне 1..100.
Меньшим значениям обычно соответствует худшее качество изображения
и меньший объём передаваемых данных.
Максимальное рекомендуемое значение — 95.
В значении параметра допустимо использование переменных.
</para>

</directive>


<directive name="image_filter_sharpen">
<syntax><value>процент</value></syntax>
<default>0</default>
<context>http</context>
<context>server</context>
<context>location</context>

<para>
Повышает резкость итогового изображения.
Процент резкости может быть больше 100.
Значение 0 отключает повышение резкости.
В значении параметра допустимо использование переменных.
</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>
Определяет, сохранять ли прозрачность при обработке изображений
в формате PNG с цветами, заданными палитрой, и в формате GIF.
Потеря прозрачности позволяет получить более качественное изображение.
Прозрачность альфа-канала в формате PNG сохраняется всегда.
</para>

</directive>

</section>

</module>