Image Processor

Image Processor allows you to optimize, resize, crop, and apply filters to your images automatically. This provides a more dynamic and faster user experience in your web applications.

View as Markdown

Image Processor is an Applications module that can manipulate and process images directly at the edge, which allows you to optimize content transfer times and elevate user experience across your applications.

Starting with an original image from your library, Image Processor can create derived images on demand, allowing you to:

Resize images to meet your requirements.
Crop images with precision.
Optimize processing times while ensuring image quality.
Convert image formats at the edge.
Apply filters or add watermarks to enhance images.

You can follow the Bandwidth Saving graph through Real-Time Metrics to monitor the traffic savings resulting from the processed images.

Implementation

Scope	Resource
Image processor first steps	Image Processor first steps

Supported image formats

This module supports an array of image formats, including:

JPEG
GIF
PNG
BMP
ICO
WEBP (for compatible browsers)
AVIF (for compatible browsers)

To ensure proper processing of images, the ims= query string parameter must be the last parameter in the URL. If any additional query string parameters are included after ims=, the request may return a 504 error.

Example of a valid URL:example.com/image.jpeg?ts=1234&ims=1000x1000

Example of an invalid URL (causes error 504): example.com/image.jpeg?ims=1000x1000&ts=1234

Resize images

Specify the required size as arguments in the query string using the key-value pair ?ims=WidthxHeight. The Width and Height parameters should be changed to the width and height of the image in pixels.

The following file /image.jpg?ims=WidthxHeight would be resized according to the set Width and Height parameters:

Autocrop

By specifying both Width and Height, the image may be cropped automatically to fit the required size. The cropping is centered and can be either vertical or horizontal, depending on how well the original dimensions fit the specified dimensions.

By appending the query ?ims=400x400 to the image URL, it’ll be resized to 400 by 400 pixels with autocrop. For example:

Preserve aspect ratio

Aspect ratio can be preserved by keeping only one of the two parameters in the query string. You can preserve width by using Widthx calculating the corresponding height, or xHeight to specify only the height and calculate the corresponding width.

By changing the query of the image to ?ims=400x, the height will be calculated automatically and the width will be set to 400 pixels:

Conversely, by using the query ?ims=x100, the width will be calculated automatically, but the height will be set to 100 pixels:

Maintain original dimension

The value orig can be replaced to maintain the original dimension of the image without autocropping.

The following image has the appended query string ?ims=450xorig, keeping the original height but setting the width to 880 pixels:

Resize to fit dimensions

Another way to resize an image to fit a specific area is by using the query string ?ims=fit-in/WidthxHeight.

The aspect ratio of the original image is preserved. If the specified area is larger than the image dimensions, the image will keep its original size. You don’t have to specify both dimensions, since one or both dimensions of the image can be smaller than its boundaries.

An image with the query string ?ims=fit-in/400x400 will be resized to fit the maximum size limit of the area it can occupy. In this case, 400 pixels in width or 400 pixels in height, whichever is reached first:

Crop images

Crop images from one coordinate to another using the query ims=AxB:CxD, where:

AxB is the starting point for the crop. It indicates, in pixels, the coordinates of the upper-left corner of the image where the cropping starts.
CxD is the endpoint for the crop. It indicates, in pixels, the coordinates form the bottom-right corner of the image where the cropping ends.

For example, the query string of the image URL ?ims=430x20:910x730 will start the crop at the initial coordinate of 430x20 pixels and finish at the coordinate 910x730 pixels.

Rotate images

Rotate an image to the left through the query ?ims=filters:rotate(Angle). You can specify the Angle as the following values:

0: no rotation.
90: rotates the image 90° to the left.
180: rotates the image 180° to the left.
270: rotates the image 270° to the left.
360: no rotation.

Values different from the ones listed above won’t rotate the image.

warning — Images with an aspect ratio of 1:1 won’t change dimensions. However, non-square images rotated by 90 and 270 degrees will have their height and width values modified.

The following image is rotated by 270° through the query ?ims=filters:rotate(270):

Change quality

Reduce file size and transfer time by processing lower quality values without affecting image visuals by appending the query ?ims=filters:quality(value). value must be a whole number between 0 and 100, which represents the level of quality you wish to apply to the image.

The recommended quality value, which provides optimization without any noticeable loss of visual quality, is 85%.

The following image has the query ?ims=filters:quality(100), for 100% quality:

The next image has the recommended 85% quality through the query ?ims=filters:quality(85):

Finally, the next image has been adjusted to 15% quality with the query ?ims=filters:quality(15):

If you insert a resolution larger than the original, the image will be displayed with the highest possible resolution.

Add a watermark

Add watermarks to your images by appending the query ?ims=filters:watermark(WatermarkURL,X,Y,Alpha), where:

WatermarkURL is the URL of the image that you wish to insert as a watermark. If the URL contains parentheses, they must be coded as %28 for ( and %29 for ).
X represents the horizontal position for the watermark’s insertion. Positive numbers represent the offset, in pixels, from left edge to right edge, while negative numbers represent offset from right edge to left edge. You can use the value center, to center the watermark horizontally, or the value repeat, to fill the image horizontally with repetitions of the watermark.
Y represents the vertical position for the watermark’s insertion. Positive numbers represent the offset, in pixels, from top to bottom, while negative numbers represent the offset from bottom to top. You can use the value center, to center the watermark vertically, or the value repeat, to fill the image vertically with repetitions of the watermark.
Alpha is the transparency of the watermark. It must be a number between 0 (completely opaque) and 100 (completely transparent).

For example, the query ?ims=filters:watermark(http://yourdomain.com/watermark-image.png,-25,-10,50) will apply the watermark 25 pixels left of center and 10 pixels below center, at 50% transparency.

Convert image to another format

You can convert the image to another format using the query ?ims=filters:format(ImageFormat). ImageFormat can be replaced by webp, avif, jpeg, gif, or png.

Therefore, the PNG image http://yourdomain.com/image.png?ims=filters:format(gif) will be converted to GIF format:

To convert an image to AVIF, you must send the header Accept: image/avif in the request.

To convert an image to WEBP, you must send the header Accept: image/webp in the request.

Fill image

Create a derived image that is larger than the original, but instead of resizing it to the required size, you can fill the area with a custom color by appending the query ?ims=fit-in/WidthxHeight/filters:fill(Color) to the URL. You can use the same resize parameters with the desired dimensions for Width and Height.

Color is the fill color, following hexadecimal code values.

For instance, an image with the query ?ims=fit-in/400x400/filters:fill(gray) will have its surroundings resized to fit a 400x400 pixel area, and the color around this area will be gray:

By changing the color code, you can modify the surrounding color of the resized area, such as ?ims=fit-in/300x400/filters:fill(008080):

Combine multiple filters

Combine the filters you want by separating filter with : into one string: filters:filter1(arg1):filter2(arg2).

For instance, the query ?ims=fit-in/400x400/filters:fill(00ffff):quality(100) will resize an image to fit an area of 500 by 500 pixels, fill the resized area with the color #00ffff and improve the quality to 100%:

Limits

These are the default limits:

Scope	Limit
Maximum size	150mb
Maximum height	2160 pixels
Maximum width	3840 pixels