<?xml version="1.0" encoding="utf-8"?>

<!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>
Модуль ngx_http_image_filter_module — это фильтр для преобразования
изображений в форматах JPEG, GIF и PNG (0.7.54+).
<note>
По умолчанию этот модуль не собирается, его сборку необходимо
разрешить с помощью конфигурационного параметра
<code>--with-http_image_filter_module</code>.
</note>
<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><parameter>off</parameter></syntax>
    <syntax><parameter>test</parameter></syntax>
    <syntax><parameter>size</parameter></syntax>
    <syntax><parameter>rotate </parameter>
        <value>90</value> | <value>180</value> | <value>270</value>
    </syntax>
    <syntax>
        <parameter>resize </parameter>
        <argument>ширина высота</argument>
    </syntax>
    <syntax>
        <parameter>crop </parameter>
        <argument>ширина высота</argument>
    </syntax>
<default/>
<context>location</context>

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

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

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

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

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

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

<tag-name><parameter>crop </parameter>
<argument>ширина высота</argument>
</tag-name>
<tag-desc>
пропорционально уменьшает изображение до размера большей стороны
и обрезает лишние края по другой стороне.
Если требуется уменьшить только по одному измерению, то в качестве второго
можно указать “<code>-</code>”.
В случае ошибки сервер возвращает код
<http-status code="415" text="Unsupported Media Type"/>.
В значениях аргументов допустимо использование переменных.
При использовании совместно с <parameter>rotate</parameter>,
поворот изображения происходит до уменьшения размеров изображения.
</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>1..100</value></syntax>
<default>75</default>
<context>http</context>
<context>server</context>
<context>location</context>

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

</directive>


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

<para>
Повышает резкость итогового изображения.
Процент резкости может быть больше 100.
Значение 0 отключает повышение резкости.
В значении аргумента допустимо использование переменных.
</para>

</directive>


<directive name="image_filter_transparency">
<syntax><value>on</value>|<value>off</value></syntax>
<default>on</default>
<context>http</context>
<context>server</context>
<context>location</context>

<para>
Директива определяет, сохранять ли прозрачность при обработке изображений
в формате PNG с цветами, заданными палитрой, и в формате GIF.
Потеря прозрачности позволяет получить более качественное изображение.
Прозрачность альфа-канала в формате PNG сохраняется всегда.
</para>

</directive>

</section>

</module>