Edge Image Optimizer

Edge Image Optimizer dynamically transforms your images to tailor them to your site's:

Edge Image Optimizer leverages our CDN to efficiently deliver your transformed images. This allows us to cache your transformed images at the edge of our network. This improves performance by reducing image processing and by bringing your optimized images closer to your users.

This feature must be purchased separately. For more information, please contact your CDN account manager.

Quick Start

Optimize images through the following steps:

  1. Activate Edge Image Optimizer.
  2. Analyze your site to identify the images that require optimization.
  3. Enable Edge Image Optimizer via Rules Engine for all of the images identified in the previous step.
  4. Define the set of optimizations that will be applied to your images by:

    • Including query string parameters within the request URL.

      Use Rules Engine to dynamically determine the set of optimizations that will be applied according to the type of request that was submitted. For example, you may create a rule that resizes all PNG images whose URL path contains /thumbnails/.

    • Requesting data from the client via client hints.

How Does It Work?

A client's request URL determines the set of transformations that will be applied to an image. For example, the following request URL will resize the source image to 500 x 500 and then apply a blur effect to the resized image:

https://edgeio.whitecdn.com/demo.jpg?blur=50&width=500&height=500

The order in which parameters are defined in the request URL does not affect the order in which they will be applied to the image.

Upon receiving a request for an optimized image, our CDN will check whether an image with the requested set of optimizations has been cachedRefers to the storage of data to improve data delivery performance. When used in reference to our CDN, it refers to the temporary storage of an asset on an edge server or an origin shield server. Cache increases the speed through which that particular edge server can deliver that asset for subsequent requests.. If the optimized image has been cached, then it will be delivered immediately to the client. Otherwise, our CDN will apply the requested set of optimizations to the source image, deliver it to the client, and then cache both the source and optimized image. This workflow is illustrated below.

Image Requirements

Restrictions vary according to whether Edge Image Optimizer will process or generate an image.

Source Image Requirements

Images that meet the following requirements are eligible for processing:

Our CDN service delivers the source image to the client when it does not satisfy the above requirements.

Optimized Image Limits

An optimized image must comply with the following limits:

Edge Image Optimizer returns an error when an attempting to generate an image that exceeds the above limits.

Activating and Enabling Edge Image Optimizer

Edge Image Optimizer transforms images when the following conditions are met:

To activate Edge Image Optimizer

  1. Navigate to the Edge Image Optimizer page. ClosedHow?From the main menu, navigate to CAN | Edge Image Optimizer.
  2. Click Activate.

    If Deactivate is already present, then you have previously enabled Edge Image Optimizer and no further action is required.

It may take up to an hour to activate Edge Image Optimizer.

To enable Edge Image Optimizer

  1. Query String Caching

    Verify that query string caching has not been enabled for images that will be transformed by Edge Image Optimizer.

    We strongly recommend that you avoid setting up query string caching to no-cache mode. This mode prevents our CDN from serving images that have already been processed by Edge Image Optimizer.

    We recommend that you restrict query string caching to query string parameters that are critical to your business needs. This recommendation ensures optimal performance by allowing our CDN to serve more requests from cache. Additionally, it reduces or eliminates unnecessary image processing due to a cache miss.

    Learn more.

  2. Create a draft or duplicate your existing policy.
  3. Create or modify a rule that identifies the set of images that will be optimized.

    Edge Image Optimizer removes the Accept-Encoding header from all requests that it processes. If you use this header to compress content, then it is important that you configure this rule to only apply to images that will be processed by Edge Image Optimizer.

    Example:

    You can create a rule that targets images through the URL Path Extension Wildcard match condition.

    If your images do not have file extensions, then consider using the Request Header Wildcard match condition to target images through the Content-Type header.

  4. Add the User Variable feature to the rule. Set the Name option to edgeio. Set the Value option to enable.

  5. Lock the draft as a policy.
  6. Deploy the policy to the Production environment.

Query String Parameters

Use the following query string parameters to define the set of optimizations that will be applied to your images:

Auto

Automates image optimization. Valid values are:

Use a comma to separate multiple values.

Example:

?auto=webp,smallest

Try now.

Bg-color

Sets the background color (hex color code) for transparent content and padding added by pad and canvas.

Syntax:

Default value:

The default background color is white with an alpha channel of 1.0.

Example:

Pass either of the following values to set the background color to dark gray:

?bg-color=4C4C4C

?bg-color=76,76,76

Try now.

Blur

Determines the intensity at which edges within an image will be smoothed. This transformation reduces the level of detail within the image. Valid values are from 1 to 100.

Example:

?blur=50

Try now.

Canvas

Determines the size of the image's canvas and the position of the optimized image within the canvas.

Syntax:

?canvas=Canvas Width,Canvas Height,xx-coordinate,yy-coordinate

Key information:

Default value:

By default, the size of the optimized image's canvas is determined by the source image's dimensions and the height, width, pad, and trim parameters. Additionally, a default offset is not applied to the optimized image.

Examples:

Pass the following query string to set the canvas size to 640 x 480 for a 3520 x 2347 image:

?canvas=640,480

Try now.

We will now resize the image's width to 550 pixels:

?canvas=640,480&width=550

Try now.

We will now add a vertical offset of 113 pixels:

?canvas=640,480,y113&width=550

Try now.

Dpr

Device Pixel Ratio (DPR). Scales an image with the intent of matching a device's resolution. Valid values are from 1 to 10.

Key information:

Example:

Pass the following query string to resize a 3520 x 2347 image to 320 x 213 and then set a 2:1 DPR:

?width=320&dpr=2

The response is a 640 x 427 image.

Try now.

Fit

Determines the method through which the image will be resized to the dimensions defined by the height and width parameters. Valid values are:

View sample implementations.

Format

Encodes the image to the specified format. Valid values are:

jpg | jpeg | pjpg | pjpeg | png | ppng | webp | tiff | tif

Use pjpg, pjpeg, or ppng to encode a progressive JPEG or PNG image.

Example:

?format=png

Try now.

Height

Sets the height, in pixels, for the optimized image. Valid values are from 1 to 4096.

Maintain the source image's aspect ratio when resizing an image by specifying either the width or height parameter. Specifying both parameters may cause the optimized image to differ in aspect ratio.

Edge Image Optimizer does not upscale images. If the requested optimization results in an image that exceeds the dimensions of the source image, then Edge Optimizer will not resize it. However, it will still perform any other requested optimizations.

Example:

?height=313

Try now.

Pad

Adds pixels between the edge of the image and its outer border. Specify pad using either of the following units:

Syntax:

?pad=Top,Right,Bottom,Left

Examples:

Pass the following query string to resize a 3520 x 2347 image to 420 x 280 and then apply a 5% pad to the optimized image:

?width=420&pad=0.05

Our service will disproportionately pad14 pixels (280 x 0.05) will be added to the top and bottom of the image, while 21 pixels (420 x 0.05) will be added to the left and right of the image. the image since its width is larger than its height.

Try now.

Alternatively, pass the following query string to specify the same padding5% padding was applied to a 420 x 280 image. This means that 14 pixels (5% of 280) were added to the top and bottom positions and 21 pixels (5% of 420) were added to the left and right positions. in pixels :

?width=420&pad=14,21

Try now.

Quality

Sets the quality level for an image that uses lossy compressionRefers to a compression method that discards image data to reduce file size. For example, jpg and webp are examples of lossy image formats.. Valid values are from 1 to 100.

This setting balances an image's file size with quality. Higher numbers improve image quality while increasing file size. Likewise, lower numbers reduce file size while reducing image quality.

Example:

?quality=75

Try now.

Default value:

80

Rotate

Rotates the image clockwise by the specified degrees. Valid values are from 1 to 360.

Example:

?rotate=90

Try now.

Strip

Set to 1 to remove metadata (i.e., EXIF, IPTC-IIM, and XMP) from the image.

Example:

?strip=1

Try now.

Trim

Removes the image's outer pixels. Specify trim using either of the following units:

Syntax:

?trim=Top,Right,Bottom,Left

Examples:

Pass the following query string to resize a 3520 x 2347 image to 460 x 307 and then apply a 9% trim to the optimized image:

?width=460&trim=0.09

Our service will disproportionately trim28 pixels (307 x 0.09) will be removed from the top and bottom of the image, while 41 pixels (460 x 0.09) will be removed from the left and right of the image. the image since its width is larger than its height.

Try now.

Alternatively, pass the following query string to specify the same trim effectA 9% trim effect was applied to a 460 x 307 image. This means that 28 pixels (9% of 307) were removed from the top and bottom positions and 41 pixels (9% of 460) were removed from the left and right positions. in pixels :

?width=460&trim=28,41

Try now.

Width

Sets the width, in pixels, for the optimized image. Valid values are from 1 to 4096.

Data advertised by a client takes precedence over this parameter.

Edge Image Optimizer does not upscale images. If the requested optimization results in an image that exceeds the dimensions of the source image, then Edge Optimizer will not resize it. However, it will still perform any other requested optimizations.

Maintain the source image's aspect ratio when resizing an image by specifying either the width or height parameter. Specifying both parameters may cause the optimized image to differ in aspect ratio.

Example:

?width=460

Try now.

Wurfl

Set to 1 to automatically define a default width based off what your mobile device can display.

Key information:

Example:

?wurfl=1

Try now.

Order of Operations

Edge Image Optimizer applies the above transformations in the following order:

Trim > Rotate > ResizeWidth, Height, DPR, and Fit > Background Color > Canvas > Pad > Blur > Image GenerationQuality, Strip, and Format

The above order of operations is only provided to help you gain a deeper understanding of how optimizations interact with each other.

Client-Driven Image Optimizations (Client Hints)

Image optimizations can be tailored according to information that the client advertises about the user's device and network conditions.

Setup

Perform the following steps to set up client-driven image optimizations:

  1. Provide client hints by including either an Accept-CH header or meta tag in the response sent to the client.

    Key information:

    • Client hints inform the client that it may advertise the corresponding data to the server.
    • Include an Accept-CH-Lifetime header or meta tag to indicate the length of time that the client should remember the supported set of client hints.
    • Use Rules Engine to automatically set the Accept-CH response header via the Modify Client Response Header Feature. Set the Action option to Overwrite. Set the Name option to Accept-CH. Set the Value option to DPR, Width, Viewport-Width.

    Response header example:

    Accept-CH: DPR, Viewport-Width, Width, ECT, Downlink

    Accept-CH-Lifetime: 86400

    Meta tag example:

    <meta http-equiv="Accept-CH" content="DPR, Viewport-Width, Width, ECT, Downlink">

    <meta http-equiv="Accept-CH-Lifetime" content="86400">

  2. Verify that your client advertises the desired data.

    Upon receiving a request for data, a client should respond with the data requested in the Accept-CH response header by including the corresponding request headers.

  3. Optional. Define a default set of image optimizations via query string parameters.

    Edge Image Optimizer optimizes your images based off both client hints and query string parameters. However, client hints take precedence when conflicting instructions are provided.

Sample Scenario

In this scenario, a web browser receives a response with the following header:

Accept-CH: DPR, ECT

The web browser will interpret this as a request for its device pixel ratio and connection type. As a result, it should submit a request that contains DPR and ECT headers. Sample request headers are shown below.

DPR: 2

ECT: 2g

Edge Image Optimizer will then use this information to optimize the requested image. In this case, it will double the resolution of the source image and reduce image quality by 65%. Edge Image Optimizer will also apply any optimizations defined within the request's query string.

Request Headers for Client Hints

A client advertises device information and network conditions via request headers. The manner in which Edge Image Optimizer will interpret this data is described below.

Caching

If your caching configuration allows it, our CDN caches both the source and optimized image. This improves performance for subsequent requests for that image in the same region, regardless of whether different optimizations will be applied to it.

Response

The response from our CDN varies according to results for the request to optimize an image.

Result

HTTP Status Code

Description

Optimized Image

200 OK

Edge Image Optimizer optimized the requested image.

The response will include the following header:

X-EdgeIO-Status: OK

Partially Optimized Image

200 OK

Edge Image Optimizer only performed some of the requested optimizations. It skipped one or more optimizations since it would have caused the image to be upscaled.

The response will include the following headers:

X-EdgeIO-Status: OK

X-EdgeIO-Warning: Images cannot be upscaled. Requested dimensions: Width x Height

Source Image

200 OK

Edge Image Optimizer was unable to optimize the requested image due to one of the following reasons:

  • The optimized image exceeds our limits.
  • The request contains an unsupported query string parameter or value. Check the request URL and try again.

The response will include the following headers:

X-EdgeIO-Status: ERROR

X-EdgeIO-Error: Error Message

Check the X-EdgeIO-Error response header for additional information on why the request failed.

No Image

5xx

Our CDN was unable to communicate with your origin server and both the source and optimized image were not previously cached.

Bypassing Edge Image Optimizer

Prevent Edge Image Optimizer from transforming an image by including the following header in the request:

X-EC-EdgeIO-Disable:1

This configuration allows our CDN to deliver the source image to the client.

Troubleshooting

Perform basic troubleshooting by examining basic properties for the source and transformed image. Include this information in the response by setting the X-EC-EdgeIO-Debug request header to info.

Request header syntax:

X-EC-EdgeIO-Debug: info

The above request header instructs Edge Image Optimizer to describe the source and output image within the X-EdgeIO-Info response header.

Sample response header:

x-edgeio-info: ifsz=7998538; idim=3520x2347; ifmt=jpeg; ofsz=16980; odim=360x240; ofmt=jpeg; oq=80

The keys defined within the X-EdgeIO-Info response header are described below.

Name Description

ifsz

File Size (Input)

Indicates the source image's file size in bytes.

idim

Dimensions (Input)

Indicates the source image's dimensions.

Syntax:

WidthxHeight

ifmt

File Format (Input)

Indicates the source image's file format.

ofsz

File Size (Output)

Indicates the output image's file size in bytes.

odim

Dimensions (Output)

Indicates the output image's dimensions.

Syntax:

WidthxHeight

ofmt

File Format (Output)

Indicates the output image's file format.

oq

Quality (Output)

Indicates the output image's file quality level. Valid values are from 1 to 100.

ms

Milliseconds

Indicates the number of milliseconds it took to transform the image.

Image Resizing Examples

We will apply different fit modes to a source image (3520 x 2347 pixels) that has been resized to 500 x 500 using the following query string:

?width=500&height=500

Try now.

Crop

Applying crop mode will proportionately crop the width from both sides of the image. This occurs because the source image's aspect ratio is different than the specified region.

Query string:

?width=500&height=500&fit=crop

Try now.

Cover

Applying cover mode resizes the image's height to 500 pixels. However, the image's width will extend beyond the width parameter in order to maintain the source image's original aspect ratio.

Query string:

?width=500&height=500&fit=cover

Try now.

Bounds

Applying bounds mode resizes the image's height to 500 pixels. However, the image's width will fall short of the width parameter in order to maintain the source image's original aspect ratio while ensuring that the image fits within the specified region.

Query string:

?width=500&height=500&fit=bounds

Try now.

Smart

Applying smart mode centers the image on its subject matter and then proportionally crops the width from both sides of the image. This occurs because the source image's aspect ratio is different than the specified region.

Query string:

?width=500&height=500&fit=smart

Try now.