<?xml version="1.0"?>

<!--
  Copyright (C) Igor Sysoev
  Copyright (C) Nginx, Inc.
  -->

<!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"
        rev="4">

<section id="summary">

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

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

</section>


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

<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="Директивы">

<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>off</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 или WebP.
В противном случае возвращается ошибка
<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_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>
Если включено, то итоговые изображения будут с чересстрочностью.
В случае JPEG итоговые изображения будут в формате “progressive JPEG”.
</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>
Определяет, сохранять ли прозрачность при обработке изображений
в формате GIF и в формате PNG с цветами, заданными палитрой.
Потеря прозрачности позволяет получить более качественное изображение.
Прозрачность альфа-канала в формате PNG сохраняется всегда.
</para>

</directive>


<directive name="image_filter_webp_quality">
<syntax><value>качество</value></syntax>
<default>80</default>
<context>http</context>
<context>server</context>
<context>location</context>
<appeared-in>1.11.6</appeared-in>

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

</directive>

</section>

</module>