Documentation

Directives

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. In most cases it’s best to leave the discussions 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 save you.

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 size. In this case w_100 will have precedence because it is more specific.

There are two ways to make use of directives.

  1. You can append directives in the query string using the imgeng parameter (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">
  1. If you’re specifying the origin in the image URL (http://jelly.com in the example below), directives can also be included in the path:
  <img src="//try.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 URL URL Your ImageEngine URL or hostname with a CNAME record pointing to ImageEngine.
Image path URL/Path Path to the image relative to your origin host.
ImageEngine directives key/value pairs ImageEngine transformations to be applied. Optional.
Origin URL URL 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 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. If no reliable size is found, it will fall back to the pixel size specified. 2 /w_auto,200/
h Height Integer Desired height in pixels of resized picture. 1 2 /h_200/
cmpr Compression Integer (0-100) Amount of compression to apply. Values 0 (less compression) to 100 (maximum compression). Note that the value will have different impact on different file formats and that too much compression will have impact on visual quality. /cmpr_50/
f Format jpg, gif, png, bmp, webp, jpegxr,jp2 Desired format of 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 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_10,10,100,100/
in Inline true Return the image as a base64 encoded string for use in data urls /in_true/
meta Strip EXIF data true Set to true to maintain EXIF data. ICC profile will always be kept. /meta_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 200 px wide image for a screen with DPR: 2, the image will still be 200 px wide, not 400 px.

# Fit methods

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 method 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 box, except the returned image is the exact specified size. Bars of white are placed around the image if necessary, but the image will not be scaled up. To use a color other than white, 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 a third parameter of m: /m_letterbox_ff0000_65/

stretch will change aspect ratio of the image to fill the new canvas defined by w_* and h_*.

# Examples

m_box

Box

m_cropbox

Cropbox

m_letterbox

Letterbox

m_stretch

Stretch