Introduction

Media must be carefully managed in web and app presentation if content is to load quickly and display appropriately in the frames set up for it. Cortex Digital Asset Management (DAM) includes an image resizing service to help manage media presentation.

In essence, all media resizing is a function of providing query parameters to an API call, as we shall see shortly. The image resizing service automates the function of appending query parameters to the API call.

Images are used in many areas of Cortex. Please refer to the relevant area of the Academy for details on how to create content with integral images in the Cortex platform.

From a developer viewpoint, whenever an image URL is provided by any Cortex service, the additional query parameters detailed below can be appended to the API call in order to use the resize service.

Image resizing in API calls

Before we look at the API call options available in fetching an image, here is an example of a media URL with no image transformation parameters added.

An image URL is in the following format.

{environment-id}/{imageId}

{environment-id} is the URL for stage (test) or production (live).

• Stage: https://media-cdn-stage.cortextech.io
• Production: https://media-cdn.cortextech.io
• Production (US environment): https://media-cdn.cortextech.us

{imageId} is the image’s unique ID.

For example:

https://media-cdn.cortextech.io/4095f7ef-9794-4ed6-9162-ebe775a4c37f.png

Resizing an image

Height and width parameters can be added to the URL:

{environment-id}/{imageId}?height={height}&width={width}

In which:

{environment-id} and {imageId} are as described above.

{height} and {width} are numeric values for the desired height and width in pixels to which you would like the image resized.

For example, the following URL returns the same image, resized to the specified height and width query parameters (300 x 300 pixels).

https://media-cdn.cortextech.io/4095f7ef-9794-4ed6-9162-ebe775a4c37f.png?width=300&height=300

The image resizing service supports PNG, JPG and Webp image formats.

Further API image fetch query parameters

The following query parameters can also be used in an image call.

{environment-id}/{imageId}?height={height}&width={width}&resizeType={resize}&dpr={dpr}&enlarge={enlarge}&gravity={gravity}&quality={quality}&background={background}&blur={blur}&sharpen={sharpen}&format={format}

In which:

{environment-id}, {imageId} {height} and {width} are as described above.

The additional query parameters are as follows.

Resize type

{resize} defines the way in which the source image will be resized. Supported resizing types are:

• fit: resizes the image while keeping the aspect ratio to fit the given size. That is, the image will be resized to the maximum extent possible while still displaying the entire image and without changing its ratio or cropping any parts. This may result in unfilled border areas.
• fill: resizes the image while keeping the aspect ratio to fill the given size but cropping projecting parts. That is, filling the entire space available, and cropping as necessary.

Both the fit and fill crop criteria are decided by the Gravity setting (see below).

If the resize field is omitted, the default is: resizeType=fit

Device Pixel Ratio (DPR)

{dpr} is the ratio of physical pixels on the screen of a device to logical pixels defined by the dimensions of an image. The DPR can be used to specify the size of an image in logical pixels, while still allowing the image to be displayed at its intended size on devices with different pixel densities.

When set, the resizing service will multiply the image dimensions according to this factor, for example, to optimise for retina displays. The value must be greater than 0.

If omitted, the default is dpr=1 As 1 is the ratio multiplier, it means the default is physical == logical pixel density.

Enlarge

If {enlarge} is set to 1 (or any other number other than zero) then, if the image is smaller than the required size, the resizing service will enlarge it.

If this field is omitted, or set to 0, the resizing service will not enlarge the image.

enlarge=1 to enable or enlarge=0 to disable the enlarge function.

The default value is 0

Gravity

When the resizing service needs to crop some parts of the image, for example, through the resizeType=fill option explained above, it can be given a starting point for the crop by using the {gravity} setting. The following values are supported:

• no: north (top edge);
• so: south (bottom edge);
• ea: east (right edge);
• we: west (left edge);
• noea: north-east (top-right corner);
• nowe: north-west (top-left corner);
• soea: south-east (bottom-right corner);
• sowe: south-west (bottom-left corner);
• ce: centre;
• sm: smart. The resizing service detects the most "interesting" section of the image and considers it as the centre of the image;
• fp:x:y: focal point. x and y are floating point numbers between 0 and 1 that define the coordinates of the centre of the resulting image. Treat 0 to 1 as left to right for x and top to bottom for y.

Examples: 

gravity=no

gravity=fp:0.59:0.18

The default is to set the crop around the centre: gravity=ce

Quality

The {quality} parameter redefines the quality of the resulting image as a percentage of the original.

Example: quality=70

If the field is omitted, the default is: quality=80

Background

When {background} is set, the image service will fill the resulting image background with the colour specified through the given red, green and blue channel values (0-255 for each).

Alternatively, the hex_colour value can be given.

For example, the following will provide a blue background fill, as #0000ff is the Hex value for blue

https://media-cdn.cortextech.io/dbfa3bfc-83cd-4719-b974-27a5341ee0ee.png?width=500&height=500&background=0000ff

Similarly, a blue background can be achieved with the RGB value: 000,000,255; like this:

https://media-cdn.cortextech.io/dbfa3bfc-83cd-4719-b974-27a5341ee0ee.png?width=500&height=500&background=0:0:255

With no arguments provided, all background colour fill is disabled, and this is the default.

Blur

When {blur} is set, the service will apply the gaussian blur filter to the image; the numeric value defining the intensity of the mask used.

Example: blur=2

If omitted, the default is: disabled.

Sharpen

When {sharpen} is set, the image service applies the sharpen filter to the image; the numeric value assigned defines the degree of sharpness applied.

As an approximate guideline, use 0.5 for 4 pixels/mm (display resolution), 1.0 for 12 pixels/mm and 1.5 for 16 pixels/mm (300 dpi == 12 pixels/mm).

Example: sharpen=3

If omitted, the default is: disabled

Format

{format} specifies the resulting image format, converting from the current source image format. The allowed options for a change of format are where the source and desired output format are each one of jpg, png or webp. That is, an input file of type png or jpg can be converted to a webp output image type using format=webp.

Note that width and height query params are required when using format=webp.

By default, if the parameter is omitted, or if another format type is used, such as .gif or .bmp, the output format will be the same as the input format.

Example: format=webp will output a webp format image as long as the input image is either jpg, png or webp.