# Generating the URL The URL should contain the signature, processing options, and source URL, like this: ``` /%signature/%processing_options/plain/%source_url@%extension /%signature/%processing_options/%encoded_source_url.%extension ``` Check out the [example](#example) at the end of this guide. ## Signature Signature protects your URL from being altered by an attacker. It is highly recommended to sign imgproxy URLs in production. Once you set up your [URL signature](configuration.md#url-signature), check out the [Signing the URL](signing_the_url.md) guide to know how to sign your URLs. Otherwise, use any string here. ## Processing options Processing options should be specified as URL parts divided by slashes (`/`). Processing option has the following format: ``` %option_name:%argument1:%argument2:...:argumentN ``` The list of processing options does not define imgproxy's processing pipeline. Instead, imgproxy already comes with a specific, built-in image processing pipeline for the maximum performance. Read more about it in the [About processing pipeline](about_processing_pipeline.md) guide. imgproxy supports the following processing options: ### Resize ``` resize:%resizing_type:%width:%height:%enlarge:%extend rs:%resizing_type:%width:%height:%enlarge:%extend ``` Meta-option that defines the [resizing type](#resizing-type), [width](#width), [height](#height), [enlarge](#enlarge), and [extend](#extend). All arguments are optional and can be omitted to use their default values. ### Size ``` size:%width:%height:%enlarge:%extend s:%width:%height:%enlarge:%extend ``` Meta-option that defines the [width](#width), [height](#height), [enlarge](#enlarge), and [extend](#extend). All arguments are optional and can be omitted to use their default values. ### Resizing type ``` resizing_type:%resizing_type rt:%resizing_type ``` Defines how imgproxy will resize the source image. Supported resizing types are: * `fit`: resizes the image while keeping aspect ratio to fit given size; * `fill`: resizes the image while keeping aspect ratio to fill given size and cropping projecting parts; * `fill-down`: same as `fill`, but if the resized image is smaller than the requested size, imgproxy will crop the result to keep the requested aspect ratio; * `force`: resizes the image without keeping aspect ratio; * `auto`: if both source and resulting dimensions have the same orientation (portrait or landscape), imgproxy will use `fill`. Otherwise, it will use `fit`. Default: `fit` ### Resizing algorithm :id=resizing-algorithm ``` resizing_algorithm:%algorithm ra:%algorithm ``` Defines the algorithm that imgproxy will use for resizing. Supported algorithms are `nearest`, `linear`, `cubic`, `lanczos2`, and `lanczos3`. Default: `lanczos3` ### Width ``` width:%width w:%width ``` Defines the width of the resulting image. When set to `0`, imgproxy will calculate the resulting width using the defined height and source aspect ratio. When set to `0` and rezizing type is `force`, imgproxy will keep the original width. Default: `0` ### Height ``` height:%height h:%height ``` Defines the height of the resulting image. When set to `0`, imgproxy will calculate resulting height using the defined width and source aspect ratio. When set to `0` and rezizing type is `force`, imgproxy will keep the original height. Default: `0` ### Min width :id=min-width ``` min-width:%width mw:%width ``` Defines the minimum width of the resulting image. **⚠️Warning:** When both `width` and `min-width` are set, the final image will be cropped according to `width`, so use this combination with care. Default: `0` ### Min height :id=min-height ``` min-height:%height mh:%height ``` Defines the minimum height of the resulting image. **⚠️Warning:** When both `height` and `min-height` are set, the final image will be cropped according to `height`, so use this combination with care. Default: `0` ### Dpr ``` dpr:%dpr ``` When set, imgproxy will multiply the image dimensions according to this factor for HiDPI (Retina) devices. The value must be greater than 0. Default: `1` ### Enlarge ``` enlarge:%enlarge el:%enlarge ``` When set to `1`, `t` or `true`, imgproxy will enlarge the image if it is smaller than the given size. Default: false ### Extend ``` extend:%extend:%gravity ex:%extend:%gravity ``` * When `extend` is set to `1`, `t` or `true`, imgproxy will extend the image if it is smaller than the given size. * `gravity` _(optional)_ accepts the same values as [gravity](#gravity) option, except `sm`. When `gravity` is not set, imgproxy will use `ce` gravity without offsets. Default: `false:ce:0:0` ### Gravity ``` gravity:%type:%x_offset:%y_offset g:%type:%x_offset:%y_offset ``` When imgproxy needs to cut some parts of the image, it is guided by the gravity. * `type` - specifies the gravity type. Available values: * `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); * `ce`: center. * `x_offset`, `y_offset` - (optional) specify gravity offset by X and Y axes. Default: `ce:0:0` **Special gravities**: * `gravity:sm`: smart gravity. `libvips` detects the most "interesting" section of the image and considers it as the center of the resulting image. Offsets are not applicable here; * `gravity:obj:%class_name1:%class_name2:...:%class_nameN`: object-oriented gravity. imgproxy [detects objects](object_detection.md) of provided classes on the image and calculates the resulting image center using their positions. If class names are omited, imgproxy will use all the detected objects. * `gravity:fp:%x:%y`: focus point gravity. `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`. ### Crop ``` crop:%width:%height:%gravity c:%width:%height:%gravity ``` Defines an area of the image to be processed (crop before resize). * `width` and `height` define the size of the area: * When `width` or `height` is greater than or equal to `1`, imgproxy treats it as an absolute value. * When `width` or `height` is less than `1`, imgproxy treats it as a relative value. * When `width` or `height` is set to `0`, imgproxy will use the full width/height of the source image. * `gravity` _(optional)_ accepts the same values as [gravity](#gravity) option. When `gravity` is not set, imgproxy will use the value of the [gravity](#gravity) option. ### Trim ``` trim:%threshold:%color:%equal_hor:%equal_ver t:%threshold:%color:%equal_hor:%equal_ver ``` Removes surrounding background. * `threshold` - color similarity tolerance. * `color` - _(optional)_ hex-coded value of the color that needs to be cut off. * `equal_hor` - _(optional)_ set to `1`, `t` or `true`, imgproxy will cut only equal parts from left and right sides. That means that if 10px of background can be cut off from left and 5px from right then 5px will be cut off from both sides. For example, it can be useful if objects on your images are centered but have non-symmetrical shadow. * `equal_ver` - _(optional)_ acts like `equal_hor` but for top/bottom sides. **⚠️Warning:** Trimming requires an image to be fully loaded into memory. This disables scale-on-load and significantly increases memory usage and processing time. Use it carefully with large images. **📝Note:** If you know background color of your images then setting it explicitly via `color` will also save some resources because imgproxy won't detect it automatically. **📝Note:** Use `color` value of `FF00FF` for trimming transparent background as imgproxy uses magenta as a transparency key. **📝Note:** Trimming of animated images is not supported. ### Padding ``` padding:%top:%right:%bottom:%left pd:%top:%right:%bottom:%left ``` Defines padding size in css manner. All arguments are optional but at least one dimension must be set. Padded space is filled according to [background](#background) option. * `top` - top padding (and all other sides if they won't be set explicitly); * `right` - right padding (and left if it won't be set explicitly); * `bottom` - bottom padding; * `left` - left padding. **📝Note:** Padding is applied after all image transformations (except watermark) and enlarges generated image which means that if your resize dimensions were 100x200px and you applied `padding:10` option then you will get 120x220px image. **📝Note:** Padding follows [dpr](#dpr) option so it will be scaled too if you set it. ### Auto Rotate ``` auto_rotate:%auto_rotate ar:%auto_rotate ``` When set to `1`, `t` or `true`, imgproxy will automatically rotate images based onon the EXIF Orientation parameter (if available in the image meta data). The orientation tag will be removed from the image anyway. Normally this is controlled by the [IMGPROXY_AUTO_ROTATE](configuration.md#miscellaneous) configuration but this procesing option allows the configuration to be set for each request. ### Rotate ``` rotate:%angle rot:%angle ``` Rotates the image on the specified angle. The orientation from the image metadata is applied before the rotation unless autorotation is disabled. **📝Note:** Only 0/90/180/270/etc degrees angles are supported. Default: 0 ### Background ``` background:%R:%G:%B bg:%R:%G:%B background:%hex_color bg:%hex_color ``` When set, imgproxy will fill the resulting image background with the specified color. `R`, `G`, and `B` are red, green and blue channel values of the background color (0-255). `hex_color` is a hex-coded value of the color. Useful when you convert an image with alpha-channel to JPEG. With no arguments provided, disables any background manipulations. Default: disabled ### Background alpha :id=background-alpha ``` background_alpha:%alpha bga:%alpha ``` Adds alpha channel to `background`. `alpha` is a positive floating point number between `0` and `1`. Default: 1 ### Adjust :id=adjust ``` adjust:%brightness:%contrast:%saturation a:%brightness:%contrast:%saturation ``` Meta-option that defines the [brightness](#brightness), [contrast](#contrast), and [saturation](#saturation). All arguments are optional and can be omitted to use their default values. ### Brightness :id=brightness ``` brightness:%brightness br:%brightness ``` When set, imgproxy will adjust brightness of the resulting image. `brightness` is an integer number in range from `-255` to `255`. Default: 0 ### Contrast :id=contrast ``` contrast:%contrast co:%contrast ``` When set, imgproxy will adjust contrast of the resulting image. `contrast` is a positive floating point number, where `1` keeps the contrast unchanged. Default: 1 ### Saturation :id=saturation ``` saturation:%saturation sa:%saturation ``` When set, imgproxy will adjust saturation of the resulting image. `saturation` is a positive floating point number, where `1` keeps the saturation unchanged. Default: 1 ### Blur ``` blur:%sigma bl:%sigma ``` When set, imgproxy will apply the gaussian blur filter to the resulting image. `sigma` defines the size of a mask imgproxy will use. Default: disabled ### Sharpen ``` sharpen:%sigma sh:%sigma ``` When set, imgproxy will apply the sharpen filter to the resulting image. `sigma` the size of a mask imgproxy will use. As an approximate guideline, use 0.5 sigma for 4 pixels/mm (display resolution), 1.0 for 12 pixels/mm and 1.5 for 16 pixels/mm (300 dpi == 12 pixels/mm). Default: disabled ### Pixelate ``` pixelate:%size pix:%size ``` When set, imgproxy will apply the pixelate filter to the resulting image. `size` is the size of a pixel. Default: disabled ### Unsharpening :id=unsharpening ``` unsharpening:%mode:%weight:%dividor ush:%mode:%weight:%dividor ``` Allows redefining unsharpening options. All arguments have the same meaning as [Unsharpening](configuration.md#unsharpening) configs. All arguments are optional and can be omitted. ### Blur detections :id=blur-detections ``` blur_detections:%sigma:%class_name1:%class_name2:...:%class_nameN bd:%sigma:%class_name1:%class_name2:...:%class_nameN ``` imgproxy [detects objects](object_detection.md) of provided classes and blus them. If class names are omitted, imgproxy blurs all the detected objects. `sigma` defines the size of a mask imgproxy will use. ### Draw detections :id=draw-detections ``` draw_detections:%draw:%class_name1:%class_name2:...:%class_nameN dd:%draw:%class_name1:%class_name2:...:%class_nameN ``` When `draw` is set to `1`, `t` or `true`, imgproxy [detects objects](object_detection.md) of provided classes and draws their bounding boxed. If class names are omitted, imgproxy draws the bounding boxes of all the detected objects. ### Watermark ``` watermark:%opacity:%position:%x_offset:%y_offset:%scale wm:%opacity:%position:%x_offset:%y_offset:%scale ``` Puts watermark on the processed image. * `opacity` - watermark opacity modifier. Final opacity is calculated like `base_opacity * opacity`. * `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; * `scale` - (optional) floating point number that defines watermark size relative to the resulting image size. When set to `0` or omitted, watermark size won't be changed. Default: disabled ### Watermark URL :id=watermark-url ``` watermark_url:%url wmu:%url ``` When set, imgproxy will use the image from the specified URL as a watermark. `url` is Base64-encoded URL of the custom watermark. Default: blank ### Style :id=style ``` style:%style st:%style ``` When set, imgproxy will prepend `