Image Optimization

• Design. You can apply multiple transformations (e.g., resize, blur, crop, and rotate) to a single source image according to how it should be displayed within your site’s design.
• Experience. For example, if your site has a paywall, you can effortlessly apply a blur effect to requests for images once a site visitor has met or exceeded their allotment of free access.
• Performance. Balance image quality against performance in order to provide the optimal experience for your users. For example, you can deliver large, high-quality images for desktop users and smaller lower-quality images for mobile users from the same source image.

Quick Start #

1. Analyze your site to identify the images that require optimization.
2. Enable the Optimize Images feature (optimize_images) for all of the images identified in the previous step.
3. Disable query string caching through the Cache Key feature to maintain performance by preventing cache key fragmentation.
4. Define the set of optimizations that will be applied to your images by:
   • Including query string parameters within the request URL.
     Rule-Based Optimizations: One method for dynamically determining the set of optimizations that will be applied to an image is through a rule.
     For example, you may create a rule that resizes all JPG images whose URL path contains /images/.

     

   • Requesting data from the client through client hints.

How Does It Work? #

Image Requirements#

Source Image Requirements #

• File Formats: jpg | jpeg | pjpg | pjpeg | png | ppng | webp | tiff | tif
• Compression: Standard image compression as determined by the image’s file format.
  All other types of data compression (e.g., gzip or brotli) are unsupported. Additionally, Edgio removes the Accept-Encoding header from all transformed images.
• Maximum File Size: 10 MB
• Maximum Resolution: 4096 x 4096
• Color Space: RGB

Optimized Image Limits #

• File Formats: jpg | jpeg | pjpg | pjpeg | png | ppng | webp | tiff | tif
• Maximum Resolution: 8192 x 8192

Response Header Requirement #

Enabling Image Optimization #

• The Optimize Images feature (optimize_images) has been enabled on the request through a rule.
• One or more transformation(s) have been requested through either:
  • Query string parameters.
  • Client hints (request headers)

1. Customize the cache key to exclude image optimization query string parameters for images that will be processed by Edgio.
   • Rules: Create or modify a rule that includes the Cache Key feature. Configure this feature’s Query Parameters option to either exclude all query string parameters or to only include specific parameters.

     

   • CDN-as-Code:
     JavaScript./routes.js

     Copy

     1export default new Router().if(
     2  {
     3    edgeControlCriteria: {
     4      in: [{ "request.path": "extension" }, ["jpg", "jpeg", "png", "webp"]],
     5    },
     6  },
     7  { caching: { cache_key: { exclude_all_query_params: true } } }
     8);

   Key information:
   • If you must add query string parameters to the cache key, we recommend that you restrict it to the 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.
   • If you are unsure as to whether you have already defined a custom cache key, then you should review your rules for features that modify the cache key.
2. Enable the Optimize Images feature (optimize_images) for the desired images.
   Edgio removes the Accept-Encoding header from all requests that it processes. If you use this header to compress content, then it is critical that you configure this rule to only apply to images that will be processed by Edgio.
   • Rules: For example, you can create a rule that targets images through the Extension match condition (extension).

     

   • CDN-as-Code:
     JavaScript./routes.js

     Copy

     1export default new Router().if(
     2  {
     3    edgeControlCriteria: {
     4      in: [{ "request.path": "extension" }, ["jpg", "jpeg", "png", "webp"]],
     5    },
     6  },
     7  {
     8    caching: { cache_key: { exclude_all_query_params: true } },
     9    response: { optimize_images: true },
     10  }
     11);

   If your images do not have file extensions, then consider using the Request Header match condition (request.header) to target images through the Content-Type header.
3. Deploy your changes.

Query String Parameters #

• auto
• bg-color
• blur
• canvas
• dpr
• fit
• format
• height
• pad
• quality
• rotate
• strip
• trim
• width
• wurfl

Order of Operations #

Auto #

• webp: Generates a WebP image when a client indicates WebP image format support through the Accept request header.
  This setting overrides the format query string parameter when a client indicates WebP image format support. Otherwise, the format query string parameter determines the file format for the optimized image.
• save-data: Applies additional image compression by reducing image quality by 45% when a client requests reduced data usage through the Save-Data request header.
  Unlike other client-driven optimizations, a user controls whether the Save-Data header will be included in the request. For example, Chrome requests on Android will automatically include this header once Data Saver has been enabled.
• smallest: Delivers the image with the smallest file size, regardless of whether it is the source or the optimized image.

Bg-color #

• ?bg-color=<COLOR HEX CODE>
• ?bg-color=<RED>,<GREEN>,<BLUE>[,<ALPHA CHANNEL>]
  <ALPHA CHANNEL> determines the opacity for the background color. Specify a decimal value from 0.0 (transparent) to 1.0 (opaque).

• ?bg-color=4C4C4C
• ?bg-color=76,76,76

Blur #

Canvas #

• You must specify <CANVAS WIDTH> and <CANVAS HEIGHT> when passing this parameter. However, you may omit offset position information.
• Use this parameter to expand or shrink the optimized image’s canvas.
  • Expand: Specify a dimension that is larger than the source image to pad it. Padding is distributed evenly on opposite sides of the image.
    Example: Expands the height and width dimensions of a 3520 x 2347 image:
    ?canvas=4020,2847
    Try now.
  • Shrink: Specify a dimension that is shorter than the source image to trim it. Our service trims the portion of the image that exceeds the specified canvas size.
    Example: Shrinks the height and width dimensions of a 3520 x 2347 image:
    ?canvas=3020,1847
    Try now.
• This parameter overrides the pad parameter. You may not pad an image through the pad parameter when you define canvas size.

Dpr #

• Images cannot be scaled beyond 8192 x 8192. Attempting to scale an image beyond 8192 x 8192 typically indicates a suboptimal configuration. Most devices will need to scale down images that meet or exceed this resolution.
• Improve performance and save bandwidth by resizing an image and then scaling it to match the device’s resolution through DPR.
• The DPR request header takes precedence over this parameter.
• A value of 1 indicates a 1:1 ratio between a device’s physical and logical pixels, while a value of 3 indicates a 3:1 ratio.
  Physical pixels represent the available pixels on the device’s screen.

  Logical pixels represent the number of pixels displayed on the device. For example, if a device’s resolution is scaled by a 3:1 ratio, then the device’s logical pixels is a third of its physical pixels.
• Edgio does not upscale images.
  Learn more.

Fit #

• crop: Centers, resizes, and then crops the image through the following workflow:
  1. Centers the image within the specified region.
  2. Resizes the image to fit or exceed the specified region while preserving aspect ratio.
  3. Crops any portion of the image that exceeds the specified region.
• cover: Resizes the image to cover or exceed the specified region.
  If the specified region’s aspect ratio does not match the source image, then the optimized image will extend beyond one of the specified dimensions.
• bounds: Resizes the image to fit within the specified region.
  If the specified region’s aspect ratio doesn’t match the source image, then the optimized image will fall short of one of the specified dimensions.
• smart: Centers with content awareness, resizes, and then crops the image through the following workflow:
  1. Identifies the image’s subject matter and centers it within the specified region.
  2. Resizes the image to fit or exceed the specified region while preserving aspect ratio.
  3. Crops any portion of the image that exceeds the specified region.

Format #

Height #

Pad #

• Pixels
• Percentage of an optimized image’s dimension. Specify this percentage as a decimal value (e.g., 0.2). For example, setting a value of 0.1 for the top position adds a 10% pad.

• ?pad=<TOP>,<RIGHT>,<BOTTOM>,<LEFT>
• You may implicitly apply padding by omitting one or more positions.
  • ?pad=<TOP>,<LEFT & RIGHT>,<BOTTOM>
  • ?pad=<TOP & BOTTOM>,<LEFT & RIGHT>
  • ?pad=<ALL POSITIONS>

Quality #

Rotate #

Strip #

Trim #

• Pixels
• Percentage of a source image’s dimension. Specify this percentage as a decimal value (e.g., 0.2). For example, setting a value of 0.1 for the top position removes 10% from the top of the optimized image.

• ?trim=<TOP>,<RIGHT>,<BOTTOM>,<LEFT>
• You may implicitly apply trim by omitting one or more positions.
  • ?trim=<TOP>,<LEFT & RIGHT>,<BOTTOM>
  • ?trim=<TOP & BOTTOM>,<LEFT & RIGHT>
  • ?trim=<ALL POSITIONS>

Width #

Wurfl #

• An image will maintain its aspect ratio when it is resized as a result of this parameter.
• Both the width and height parameters override this parameter.
• This parameter is only applicable for mobile devices. It will be ignored when requesting an image from other devices.

Client-Driven Image Optimizations (Client Hints) #

Setup #

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 as to the type of client data that the server will accept.
   • 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 a rule to automatically set the Accept-CH response header through the Set Response Headers feature (set_response_headers). Set the Header Name option to Accept-CH and the Value option to the desired client hints (e.g., 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 (e.g,. DPR and ECT).
3. Optional. Define a default set of image optimizations through query string parameters.
   Edgio optimizes your images based off both client hints and query string parameters. However, client hints take precedence when conflicting instructions are provided.

Sample Scenario #

Request Headers for Client Hints #

• Downlink: Reduces image quality to 60% and strips metadata when the request includes a Downlink header and it is set to a value below 0.5.
  A Downlink header that meets the above requirement overrides the quality and strip query string parameters.
  The Downlink header indicates the client’s maximum downlink speed in megabits per second (Mbps).
• DPR: Resizes an image according to the device pixel ratio defined within the DPR request header.
  The DPR request header overrides the dpr query string parameter. Images will be resized according to the dpr query string parameter when the DPR request header is missing.
  Edgio does not upscale images.

  Learn more.
  Sample DPR Request Header:
  The following DPR request header indicates that the client’s ratio of physical pixels to CSS pixels is 2:1.
  DPR: 2
  Edgio will double the resolution of the optimized image.
• ECT: Reduces image quality to 60% and strips metadata when the request includes an ECT header and it is set to a value other than 4g or 3g. Valid values are:
  4g | 3g | 2g | slow-2g
  An ECT header that meets the above requirement overrides the quality and strip query string parameters.
  The ECT header (Effective Connection Type) describes a client’s connection by indicating the network profile that it most resembles.
• Save-Data: Reduces quality to 45% and strips metadata when both of the following conditions are met:
  • The request includes a Save-Data header and it is set to On.
    The Save-Data header indicates that less data should be sent.
  • The auto parameter is set to save-data.
  A Save-Data header that meets the above requirement overrides the quality and strip query string parameters.
• Viewport-Width: Edgio uses the viewport’s width to calculate an image’s dimensions, resolution, or both.
  The Viewport-Width request header overrides the width and height query string parameters.
  The viewport identifies the viewable area of the window where web content is shown.
  Edgio does not upscale images.

  Learn more.
  Example:
  In this example, a web browser advertises information through the following elements:
  • Request Headers:
    DPR: 2
    Viewport-Width: 75vw
  • <img> tag:
    <img src="img_bunny.jpg" alt="bunny hopping in a garden" width="380" height="456">
  Edgio will use this information to resize the image. Specifically, it will calculate the image’s width by doubling the device’s width and then reducing it by 75% to fit within the viewport’s width. In order to maintain aspect ratio, it will apply the same transformations to the image’s height. The dimensions for the resulting image are 570 x 684..
  0.75 * (380 * 2) = 570
  0.75 * (456 * 2) = 684
• Width: Resizes an image to fit within the width defined within an <img> or <source> tag.
  Edgio does not upscale images.

  Learn more.
  Example:
  In this example, a web browser advertises information through the following <img> tag:
  <img src="img_bunny.jpg" alt="bunny hopping in a garden" width="500" height="600">
  Edgio will resize the image’s width to 500 pixels.

Caching #

• Same Optimizations: It allows our CDN to serve subsequent requests for that image with the same set of optimizations from cache. This improves performance by eliminating the need to retrieve the image and then optimize it.
• Different Optimizations: It allows Edgio to optimize an image without having to retrieve it from an origin server.

• Ensure optimal performance by ensuring that image optimization query string parameters are not explicitly added to the cache key.
  We strongly recommend that you avoid setting up query string caching to exclude all query string parameters. This mode prevents our CDN from serving images that have already been processed by Edgio.
  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.
• For the purposes of caching an optimized image, our CDN translates the auto query string parameter to reflect the optimizations that will be applied to the image.
  Example: This example assumes that the request contains the following query string:
  ?auto=webp
  If the client indicates that it supports the WebP format, then we will convert the image and cache the WebP image with the following query string:
  ?format=webp
• For the purposes of caching an optimized image, our CDN translates the client hints provided by a client to reflect the optimizations that will be applied to the image.
  Example: A sample request for a 640 x 480 image contains the following headers:
  DPR: 2
  Width: 320
  These headers instruct Edgio to expand the width of the image to 640 pixels and cache it with the following query string:
  ?width=640
• In addition to the above optimizations, Edgio normalizes the cache key generated for an optimized image. This step is required to allow our CDN to serve an optimized image from cache regardless of the order in which a set of transformations are defined in the request.
  Example: Edgio will generate the same cache key for both of the following requests:
  https://cdn.example.com/image.jpg?width=640&blur=50
  https://cdn.example.com/image.jpg?blur=50&width=640
• As a result of the above optimizations and cache key normalization, the default cache key generated by Edgio should provide optimal cache performance.

Response #

Bypassing Edgio Image Optimization #

Troubleshooting #

Upscaling Images #

Image Resizing Examples #

Crop#

Cover#

Bounds#

Smart#