You can pass directives to ImageEngine in the URL to instruct it on what to do with an image. In other words, directives override the automated decisions made by ImageEngine.
Directives can be “mixed and matched” and some work only when others are present too. For example, fit methods are dependent on height and/or width directives.
Furthermore, some directives are not compatible with each other. For example, /w_100/pc_100/ instructs ImageEngine to serve the images as 100px wide and 100% of screen/viewport size; in this case w_100 will have precedence because it is more specific.
Warning: In most cases, it’s best to leave the decisions to ImageEngine. For example, if you explicitly ask for an image to be served as webp, all devices will get webp, even those not supporting it. However, if there are cases where you need explicit control, directives will serve you.
Usage
There are two ways to make use of directives.
- You can append directives in the query string using the
imgengparameter (if you have a CNAME record pointing to your ImageEngine hostname, this is the only option):
<img src="//try.cdn.imgeng.in/img/bread.png?imgeng=/w_300/f_webp">
- If you’re specifying the origin in the image URL (
http://jelly.comin the example below), directives can also be included in the path:
<img src="//try.cdn.imgeng.in/w_300/f_webp/http://jelly.com/img/bread.png">
The examples above will produce a webp image 300px wide.
Section Values Function ImageEngine URLURL Your ImageEngine URL or hostname with a CNAME record pointing to ImageEngine. Image pathURL/Path Path to the image relative to your origin host. ImageEngine directiveskey/value pairs ImageEngine transformations to be applied. Optional. Origin URLURL Hostname of your origin server (only available with “origin prefixing”).
Note: If another query string is already used in an object's URL, the ImageEngine directive must be separated by an '&' in the URL.
For instance, this pattern will not work:
https//www.domain.com/folder/image.jpg?34637637?imgeng=/w_300/f_webp
Instead, make sure to use an & instead of a second ?:
https//www.domain.com/folder/image.jpg?34637637&imgeng=/w_300/f_webp
List of supported directives
Supported directives are listed and explained below.
| Directive | Name | Value | Description | Example |
|---|---|---|---|---|
w |
Width | Integer | Desired width in pixels of the resized picture. 1 2 | /w_200/ |
w_auto |
Auto width with fallback | Integer | ImageEngine will try to automatically detect the best size based on Client Hints. For mobile devices, ImageEngine will detect the optimal width using WURFL device detection. If no reliable size is found, it will fall back to the pixel size specified. 2 3 | /w_auto,200/ |
h |
Height | Integer | Desired height in pixels of the resized picture. 1 2 | /h_200/ |
cmpr |
Compression | Integer (0-99) | Amount of compression to apply. Values 0 (less compression) to 99 (maximum compression). Note that the value will have a different impact on different file formats and that too much compression will have an impact on visual quality. | /cmpr_50/ |
f |
Format | jpg, gif, png, bmp, webp,jp2,avif |
Desired format of the image. Note that even if the file extension says for example jpeg, the HTTP header content-type will have the correct mime type of the requested format. |
/f_webp/ |
m |
Fit method | stretch, box, letterbox, cropbox, outside |
Used together with w_* and/or h_* to decide how to fit the image. For box use only the height or width |
/m_box/ /m_letterbox_ff0000_50/ |
pass |
Pass through | true |
When set, ImageEngine will pass through the origin image unmodified. | /pass_true |
s |
Sharpness | Integer (0-100) | Adjust the sharpness of the image. Values from 0 (no sharpening) to 100 (maximum sharpening). |
/s_20/ |
r |
Rotate | Integer | Will rotate the image by provided degrees. Values from -360 to 360. | /r_20/ |
pc |
Percentage of screen | 1-100 (float) | This field will use WURFL to calculate the screen width and then scale the image accordingly. 2 | /pc_50/ |
cr |
Crop | Integers | The four crop arguments are width, height of the final image, left and top (pixels from the left and top edges of the image). Note that this function does not scale the image to fit inside width and height. | /cr_200,200,150,100/ |
meta |
Strip EXIF data | true |
Set to true to maintain EXIF data. ICC profile and any copyright information will always be kept. |
/meta_true/ |
dl |
Forces download | true |
If set, the browser will download and save the image on the computer | /dl_true/ |
1 If a fit method is not specified, and only width or height is specified, it will select “box”.
2 The target pixel size is actual intrinsic pixels (“CSS pixels”) and does not account for high DPI screens. For example, if you request a 200px wide image for a screen with
DPR: 2, the image will still be 200px wide, not 400px.3 For mobile devices, where client hints are not available, ImageEngine will by default detect the resolution width of the screen and not the viewport size. For example, if the viewport sizes measured in “CSS pixels” is 360 pixels, the resolution width, used by ImageEngine to determine maximum size of the image, might be 720px if the DPR of the screen is 2 (360px x 2). You can choose not to honor high DPI screens in the settings.
Fit Method Descriptions
box scales the image according to the dimension specified. For instance, /m_box/h_100/w_100/ will create a box of 100px x 100px and will fit the image inside the box will, retaining the image's aspect ratio.
cropbox will resample the image as small as possible while showing no canvas. This will result in some cropping if the source and output aspect ratios differ.
letterbox is the same as the box, except the returned image is the exact specified size. Bars of black are placed around the image if necessary, but the image will not be scaled up. To use a color other than black, you can specify the HEX color code after the letterbox directive, like this for red: /m_letterbox_ff0000/. The canvas opacity can also be specified for images that support transparency. This is would be specified as the third parameter of m: /m_letterbox_ff0000_65/
stretch will change the aspect ratio of the image to fill the new canvas defined by w_* and h_*. if the requested values w_* or h_* are higher than the width and hight of the image at the origin, the width and hight of the origin will be the maximum.
outside will resize the image to be as small as possible while ensuring its dimensions are greater than or equal to both width and height. Aspect ratio is preserved. For example, if the requested dimensions of the image is 100x100px. Your original image is 800x400, outside will reduce the image to 200x100 px since the 100x100 box must fit inside your image.
Examples
m_box
m_outside
m_cropbox
m_letterbox
m_stretch
Comments
0 comments
Article is closed for comments.