Image manipulation

CDN includes a full-featured image processing engine that allows various types of image conversion and manipulation to be made in real-time, based on a set of optional URL parameters supplied in the request.

Format

https://{cdn-domain}/{path}{?parameters}

Example

https://cdn.edge.network/assets/img/example/canoe.jpg?width=600&height=400&format=png

The URL above loads a JPEG from /assets/img/example/canoe.jpg and specifies that the result should be 600x400 pixels in size and be converted to a PNG.

Parameters

blur

The blur parameter adds blur to an image, using any value above zero.

• Accepts: any number from 1-100
• Default: 0
• Alias: b

Examples

https://cdn.edge.network/assets/img/example/dog.jpg?blur=5

Original image	Blur amount = 1	Blur amount = 5
Blur amount = 10	Blur amount = 20	Blur amount = 100

filter

The filter parameter allows you to specify the interpolation method to use when resizing images. When reducing the size of an image (or downsampling), some image data is simply discarded. However when increasing image dimensions, the image is expanded and gaps must be "filled in". Each interpolation filter uses a different algorithm for determining how to fill the gaps.

• Accepts: valid values are lanczos, nearest-neighbor, linear, cubic, grid, moving-average
• Default: lanczos
• Alias: f

Example

https://cdn.edge.network/assets/img/example/dog.jpg?width=600&height=400&resize=aspectfill&filter=linear

The following filters are available:

flip

The flip parameter flips images horizontally, vertically or both. A horizontal flip can also be referred to as "mirroring".

• Accepts: valid values are x, y and xy
• Default: 0
• Alias: fl

Horizontal flip: ?flip=x	Vertical flip: ?flip=y	Horizontal and vertical flip: ?flip=xy

format

Use the format parameter to specify the required output image format.

• Accepts: valid values are jpg, png, gif, webp
• Default: output defaults to the same as the input image
• Alias: fmt

When choosing WebP as the output format, it's possible to specify another format to be used as a fallback in case the requesting client doesn't have WebP support. The fallback is added to the format parameter, separated by a comma – e.g. ?format=webp,jpg.

Original JPG Image

JPG to PNG

https://cdn.edge.network/assets/img/example/dog.jpg?format=png

GIF to JPG

https://cdn.edge.network/assets/img/example/giphy.gif?format=jpg

GIF to PNG

https://cdn.edge.network/assets/img/example/giphy.gif?format=png

Original PNG Image

PNG to JPG

https://cdn.edge.network/assets/img/example/mountain.png?w=400&resize=aspectfit&format=jpg

progressive

Add progressive=true to the image parameters to have CDN serve a progressice JPEG.

gravity

Used to position the crop area. Available options (case sensitive):

• northwest
• north
• northeast
• west
• center
• east
• southWest
• south
• southeast
• none

Original image

https://cdn.edge.network/assets/img/example/girl-on-bridge.jpg

g=west	g=center	g=east

height

The height parameter is used to specify the required height of the output image, in pixels.

• Default: original height dimension
• Alias: h

If only height is specified, the width dimension will be set to the width of the original image. If you'd like to ensure the output image retains the aspect ratio of the original image, please ensure resize=aspectfit is specified.

If both width and height are omitted, the original image’s dimensions are used.

Example

https://cdn.edge.network/assets/img/example/canoe.jpg?h=400&resize=aspectfit

h=400	h=400&resize=aspectfit

quality

The quality parameter applies compression to an image, reducing it's file size.

• Accepts: any number from 1-100
• Default: 75
• Alias: q

The best results for quality and file size can be found around 40-60, where we've found generated images to be visually indistinguishable from the source image.

Examples

The original image and all quality variations below are 2048 × 1024 pixels.

Original image, 4.7MB

https://cdn.edge.network/assets/img/example/vegetables.jpg

Quality = 100, 1.3MB	Quality = 75, 180kB
Quality = 50, 119kB	Quality = 25, 82kB

ratio

Use the ratio parameter in combination with width (w) or height (h) to crop the image to the specified aspect ratio. Resize styles are respected.

https://cdn.edge.network/assets/img/example/canoe.jpg?h=400&ratio=16-9

rotate

The rotate parameter rotates the image according to the value specified in degrees. The image will be zoomed so that it covers the entire area after rotation.

• Accepts: any number from 0-359
• Default: 0

saturate

The saturate parameter increases or reduces an image's colour saturation and can be used to convert it to black and white.

• Accepts: 0 or 1
• Default: none
• Alias: sat

To desaturate (convert to black and white), use 0 or any number below 0.

https://cdn.edge.network/assets/img/example/beach.jpg?saturate=0

Saturate amount = 0 (B&W)	Saturate amount = 1

sharpen

The sharpen parameter adds sharpness to an image.

• Accepts: 0-5
• Default: 0
• Alias: sh

Example

https://cdn.edge.network/assets/img/example/beach.jpg?sharpen=1

Default amount = 0	Sharpen amount = 1	Sharpen amount = 5

width

The width parameter is used to specify the required width of the output image, in pixels.

• Default: original width dimension
• Alias: w

If only width is specified, the height dimension will be set to the height of the original image. If you'd like to ensure the output image retains the aspect ratio of the original image, please ensure resize=aspectfit is specified.

If both width and height are omitted, the original image’s dimensions are used.

Example

https://cdn.edge.network/assets/img/example/canoe.jpg?w=400&resize=aspectfit

w=400	w=400&resize=aspectfit

Resizing

Images can be easily resized using DADI CDN. Use the resize parameter with width and height to resize images, or specify crop along with crop coordinates for full control over the portion of the original image that is retained.

There are several ways to resize an image, the simplest of which is to specify the dimensions of the output images. Use width and height parameters to specify the final dimensions of the output image.

Using the width parameter

The width parameter (alias: w) specifies the width of the required output image in pixels. If only width is specified, the height dimension will be calculated automatically so that the original aspect ratio of the image is maintained given the new width. If both width and height are omitted, the original image’s dimensions are used.

Example

https://cdn.edge.network/assets/img/example/canoe.jpg?w=400

Using the height parameter

The height parameter (alias: h) specifies the height of the required output image in pixels. If only height is specified, the width dimension will be calculated automatically so that the original aspect ratio of the image is maintained given the new height. If both width and height are omitted, the original image’s dimensions are used.

Example

https://cdn.edge.network/assets/img/example/canoe.jpg?h=400

Specifying aspect ratio

Images can be resized to a specified aspect ratio by providing a width or height in combination with the ratio parameter. CDN will respect any resizeStyle specified.

https://cdn.edge.network/assets/img/example/canoe.jpg?h=400&ratio=16-9

Specifying a resize style

The resizeStyle (alias: resize) parameter allows you to specify how CDN should fit your image into the specified dimensions.

aspectfill

Keeps the aspect ratio of the original image and generates an output image of the specified width and height. The output image may be cropped, however by specifying the gravity parameter you can tell CDN which part of the image should be retained.

The output image is 400 x 300 pixels.

aspectfit

Keeps the aspect ratio of the original image and generates an output image with the maximum dimensions that fit inside the specified width and height.

The output image is 400 x 267 pixels.

crop

When crop is used as the resize style then an additional parameter must be used to specify the coordinates of the crop rectangle. There are two ways to pass the crop rectangle coordinates:

• Specify only the top left corner of the rectangle

  ?resizeStyle=crop&crop=10,15

• Specify the top left and the bottom right corners of the rectangle

  ?resizeStyle=crop&crop=10,15,200,300

entropy

Used in combination with width and height parameters, entropy crops the image using a technique that determines the most important areas. Areas of higher contrast are considered more important, and images are often cropped to remove large areas of static colour.

https://cdn.edge.network/assets/img/example/girl-on-bridge.jpg?w=250&h=300&resize=entropy

Original image	Entropy crop

fill

Generates an output image with the exact specified width and height dimensions, ignoring the aspect ratio of the original image. The output image may appear squashed or stretched.

The output image is 400 x 300 pixels.

gravity

Used to position the crop area. See Parameters / gravity for details and examples.

Cropping

For more control over the output image than available when using the standard resize style options aspectFit, aspectFill, fit and fill, you can specify three different ways to crop an image.

Top-left crop

By specifying only the top left corner of the crop rectangle, CDN works out the full crop rectangle size by using the specified width and height parameters. To obtain an image that is 300 wide and 400 high, but cropped from 100 pixels from the top edge:

https://cdn.edge.network/assets/img/example/girl-on-bridge.jpg?resize=crop&crop=0,10&width=300&height=400

Crop rectangle

It is also possible to supply both the top left and the bottom right coordinates of a crop rectangle (e.g. resize=crop&crop=0,0,100,100). This allows you to selectively crop an exact area out of an image.

Let's take a look at some examples. We'll use our 400x400 pixel image, which has squares marked at x, y (size): 0,0 (25 px), 25,25 (25px), 50,50 (50px), 100,100 (100px), 200,200 (200px):

We can crop the second and third boxes by supplying a top left of 50,50, and a bottom right of 200,200, giving us a 150x150 pixel image:

https://cdn.edge.network/assets/img/example/measure1.png?resize=crop&crop=50,50,200,200

We're also able to change the size of the image we get back. Let's change it to 100 pixels wide. In this case, the height will be inferred from the width. The same goes if we only supply a height.

https://cdn.edge.network/assets/img/example/measure1.png?resize=crop&crop=50,50,200,200&width=100

If you really want to get creative, you can supply a cropping rectangle along with both a width and height, which will allow you to completely resize an image after cropping. Let's take the above image and squash it.

https://cdn.edge.network/assets/img/example/measure1.png?resize=crop&crop=50,50,200,200&width=400&height=100

Another way of resizing our crops, if we don't want to be as specific, is to provide the devicePixelRatio ratio.

https://cdn.edge.network/assets/img/example/measure1.png?resize=crop&crop=50,50,200,200&devicePixelRatio=2

Read more about dealing with pixel ratios.

Entropy crop

Using resize=entropy crops the image using a technique that determines the most important areas.

Read more about entropy.

Example use case

For this example, we're going to imagine you have a magazine-style website with a list of articles on the homepage and an article page. We'll start with the following image, which your editor wants to use as the main article image.

Original image, 5616 × 3744 px, 4MB

https://cdn.edge.network/assets/img/example/beach.jpg

This is a large image, and it's not going to fit easily into the two spaces we have available for it. Unfortunately, no one in the department knows how to use Adobe Photoshop to make appropriately sized images. Fortunately, CDN can handle this task for you.

Resizing and cropping

On the article page, let’s assume your main image spot is a 500×300 pixel container. It's an odd size, but illustrates this concept well. To fit the base image into that container, we’ll need to change the dimensions and crop some data from the top and bottom.

To adjust the image we need to specify the new width and height, as well as tell CDN how we want to crop the image.

https://cdn.edge.network/assets/img/example/beach.jpg?w=500&h=300&resize=entropy

• width=500&height=300: Sets the width and height to fit the container.

• resize=entropy: Tells CDN how to determine the crop area. Entropy is a smart cropping feature that adjusts the crop area to ensure the important part of your image is retained. It uses areas of high contrast to set the crop area.

Resized image, 500 × 300 px, 98kB

Now, on the homepage, let’s assume each feature article has an image container that is 200×200 pixels. With the main subject of the image so close to the right, we'll once again need to tell CDN how we want the image cropped.

https://cdn.edge.network/assets/img/example/beach.jpg?w=200&h=200&resize=entropy

Resized image, 200 × 200 px, 29kB

If we don't specify entropy as the resize parameter, CDN defaults to using aspectfit and our image would look a little different, with the main subject almost excluded from the image.

https://cdn.edge.network/assets/img/example/beach.jpg?w=200&h=200

Caching

The network cache consists of two types of caching: the Lightening cache which holds assets in-memory for 60 seconds; and a disk cache which persists assets in line with the configured cache TTL. Lightening cache is designed to respond as fast as possible for frequently requested assets, whilst disk cache makes it possible to persist files for far longer without degrading performance or consuming memory on the device.

You can determine the cache response by looking at the X-Cache-Type HTTP header, which will be mem if the asset is cached in-memory, and disk otherwise.

Upon expiration, cached files will be removed from the network cache, and will be re-cached the next time they are accessed, unless they are pre-warmed (see below).

Cache invalidation

Files can be removed from the cache by the use of the invalidate parameter.

https://cdn.edge.network/assets/img/example/beach.jpg?invalidate=true

After removing the file, please allow up to 1 minute for the cached version to be removed from the network cache. This currently only removes the file in the region where this is requested, but this will change in future releases.

Cache pre-warming

Assets that are accessed above a user specified threshold will be automatically re-cached to maintain a quick response when the asset expires. In addition to pre-warming the asset, the cache can be configured to persist an expired asset during the process of pre-warming, ensuring a reliable response for assets with a longer load time.

You can determine whether the cache response is pre-warmed by looking at the X-cache-origin HTTP header, which will be pre-warm if pre-warmed, and request if not pre-warmed.

Cache pre-warming is currently an experimental option, so please reach out to us if you would like to enable it on your account.