Update docs with watermarks and new gravity options

README.md

@@ -60,6 +60,7 @@ Massive processing of remote images is a potentially dangerous thing, security-w
    * [Security](./docs/configuration.md#security)
    * [Compression](./docs/configuration.md#compression)
    * [WebP support detection](./docs/configuration.md#webp-support-detection)
+   * [Watermark](./docs/configuration.md#watermark)
    * [Presets](./docs/configuration.md#presets)
    * [Serving local files](./docs/configuration.md#serving-local-files)
    * [Serving files from Amazon S3](./docs/configuration.md#serving-files-from-amazon-s3)
@@ -68,12 +69,13 @@ Massive processing of remote images is a potentially dangerous thing, security-w
    * [Basic](./docs/generating_the_url_basic.md)
    * [Advanced](./docs/generating_the_url_advanced.md)
    * [Signing the URL](./docs/signing_the_url.md)
-5. [Presets](./docs/presets.md)
-6. [Serving local files](./docs/serving_local_files.md)
-7. [Serving files from Amazon S3](./docs/serving_files_from_s3.md)
-7. [Source image formats support](./docs/source_image_formats_support.md)
-8. [About processing pipeline](./docs/about_processing_pipeline.md)
-9. [Health check](./docs/healthcheck.md)
+5. [Watermark](./docs/watermark.md)
+6. [Presets](./docs/presets.md)
+7. [Serving local files](./docs/serving_local_files.md)
+8. [Serving files from Amazon S3](./docs/serving_files_from_s3.md)
+9. [Source image formats support](./docs/source_image_formats_support.md)
+10. [About processing pipeline](./docs/about_processing_pipeline.md)
+11. [Health check](./docs/healthcheck.md)
 
 ## Author
 

docs/configuration.md

@@ -69,6 +69,15 @@ When WebP support detection is enabled, please take care to configure your CDN o
 
 **Warning**: Headers cannot be signed. This means that an attacker can bypass your CDN cache by changing the `Accept` HTTP header. Have this in mind when configuring your production caching setup.
 
+### Watermark
+
+* `IMGPROXY_WATERMARK_DATA` - Base64-encoded image data. You can easily calculate it with `base64 tmp/watermark.png | tr -d '\n'`;
+* `IMGPROXY_WATERMARK_PATH` - path to the locally stored image;
+* `IMGPROXY_WATERMARK_URL` - watermark image URL;
+* `IMGPROXY_WATERMARK_OPACITY` - watermark base opacity.
+
+Read more about watermarks in the [Watermark](./watermark.md) guide.
+
 ### Presets
 
 Read about imgproxy presets in the [Presets](./presets.md) guide.

docs/generating_the_url_advanced.md

@@ -95,6 +95,10 @@ When imgproxy needs to cut some parts of the image, it is guided by the gravity.
 * `so`: south (bottom edge);
 * `ea`: east (right edge);
 * `we`: west (left edge);
+* `noea`: north-east (top-right corner);
+* `nowe`: north-west (top-left corner);
+* `soea`: south-east (bottom-right corner);
+* `sowe`: south-west (bottom-left corner);
 * `ce`: center;
 * `sm`: smart. `libvips` detects the most "interesting" section of the image and considers it as the center of the resulting image;
 * `fp:%x:%y`: focus point. `x` and `y` are floating point numbers between 0 and 1 that define the coordinates of the center of the resulting image. Treat 0 and 1 as right/left for `x` and top/bottom for `y`.
@@ -135,6 +139,29 @@ As an approximate guideline, use 0.5 sigma for 4 pixels/mm (display resolution),
 
 Default: disabled
 
+##### Watermark
+
+`watermark:%opacity:%position:%x_offset:%y_offset`
+`wm:%opacity:%position:%x_offset:%y_offset`
+
+Puts watermark on the processed image.
+
+* `opacity` - watermark opacity modifier. Final opacity is calculated like `base_opacity * opacity`. It's highly recommended to set this argument as `1` and adjust opacity with `IMGPROXY_WATERMARK_OPACITY` since this would optimize performance and memory usage.
+* `position` - (optional) specifies the position of the watermark. Available values:
+  * `ce`: (default) center;
+  * `no`: north (top edge);
+  * `so`: south (bottom edge);
+  * `ea`: east (right edge);
+  * `we`: west (left edge);
+  * `noea`: north-east (top-right corner);
+  * `nowe`: north-west (top-left corner);
+  * `soea`: south-east (bottom-right corner);
+  * `sowe`: south-west (bottom-left corner);
+  * `re`: replicate watermark to fill the whole image;
+* `x_offset`, `y_offset` - (optional) specify watermark offset by X and Y axes. Not applicable to `re` position.
+
+Default: disabled
+
 ##### Preset
 
 `preset:%preset_name1:%preset_name2:...:%preset_nameN`

docs/generating_the_url_basic.md

@@ -38,6 +38,10 @@ When imgproxy needs to cut some parts of the image, it is guided by the gravity.
 * `so`: south (bottom edge);
 * `ea`: east (right edge);
 * `we`: west (left edge);
+* `noea`: north-east (top-right corner);
+* `nowe`: north-west (top-left corner);
+* `soea`: south-east (bottom-right corner);
+* `sowe`: south-west (bottom-left corner);
 * `ce`: center;
 * `sm`: smart. `libvips` detects the most "interesting" section of the image and considers it as the center of the resulting image;
 * `fp:%x:%y` - focus point. `x` and `y` are floating point numbers between 0 and 1 that describe the coordinates of the center of the resulting image. Treat 0 and 1 as right/left for `x` and top/bottom for `y`.

docs/watermark.md

@@ -0,0 +1,36 @@
+# Watermark
+
+imgproxy supports watermarking processed images with another image.
+
+## Specifying watermark image
+
+There are three ways to specify a watermark image using environment variables:
+
+* `IMGPROXY_WATERMARK_DATA` - Base64-encoded image data. You can easily calculate it with `base64 tmp/watermark.png | tr -d '\n'`.
+* `IMGPROXY_WATERMARK_PATH` - path to the locally stored image.
+* `IMGPROXY_WATERMARK_URL` - watermark image URL.
+
+You can also specify the base opacity of watermark with `IMGPROXY_WATERMARK_OPACITY`.
+
+## Watermarking an image
+
+Watermarks only available with [advanced URL format](generating_the_url_advanced.md). Use `watermark` processing option to put the watermark on the processed image:
+
+`watermark:%opacity:%position:%x_offset:%y_offset`
+`wm:%opacity:%position:%x_offset:%y_offset`
+
+Where arguments are:
+
+* `opacity` - watermark opacity modifier. Final opacity is calculated like `base_opacity * opacity`. It's highly recommended to set this argument as `1` and adjust opacity with `IMGPROXY_WATERMARK_OPACITY` since this would optimize performance and memory usage.
+* `position` - (optional) specifies the position of the watermark. Available values:
+  * `ce`: (default) center;
+  * `no`: north (top edge);
+  * `so`: south (bottom edge);
+  * `ea`: east (right edge);
+  * `we`: west (left edge);
+  * `noea`: north-east (top-right corner);
+  * `nowe`: north-west (top-left corner);
+  * `soea`: south-east (bottom-right corner);
+  * `sowe`: south-west (bottom-left corner);
+  * `re`: replicate watermark to fill the whole image;
+* `x_offset`, `y_offset` - (optional) specify watermark offset by X and Y axes. Not applicable to `re` position.