Directives are commands you can pass to ImageEngine in the URL which explicitly instructs ImageEngine on what to do with the 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="//images.example.com/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 availble with “origin prefixing”).
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. 23 | /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 |
Used together with w_* and/or h_* to decide how to fit the image. |
/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 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”. If both width and height are specified, but fit is not explicitly specified, then it will assume the fit method is “stretch”.
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 to fit within the specified dimensions. Note that the image that is returned will not necessarily be the same size as the requested dimensions, but it will fit inside a box of those dimensions.
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_*.
Examples
m_box
m_cropbox
m_letterbox
m_stretch
Comments
0 comments
Article is closed for comments.