Transforming Images with Query Strings
Every asset in Agility is served over a CDN. Images can be resized, optimized and reformatted without having to re-upload it. You can use query strings to manipulate and generate different sizes and thumbnails of your images. This is also known as image transcoding.
What is it and what are the benefits?
There are many instances where an image will need to be displayed across multiple devices with different size restrictions. Agility allows developers to make this request directly in the code through Media Based URL Transcoding.
How Does it Work?
Let’s use this picture of a cat as an example and say you’ve uploaded it to Agility and the URL for the image is https://cdn.aglty.io/agility-cms-docs/images/cat
A Developer could use the Width and Height parameters below to alter the URL and specify that the Image needs to be displayed with a Width and Height of 200 pixels. The URL they would use is https://cdn.aglty.io/agility-cms-docs/images/cat?w=200&h=200
Available Parameters
- w – Allows you to specify the Width of an image with a number value
- h – Allows you to specific the Height of an image with a number value
- c – Allows you to specify an Action for the image to take with a number value of: 1: Scale and fill remaining space, 2: Resize and fill with white space, or 3: Crop Image
- q – Allows you to specify the Quality of an image as a percentage (1-100) of the original Asset quality
- format=auto – Allows the source image to be converted to the best format for the browser (webp or avif)
Focal Point
If you have an image that needs to be cropped around a non-center focal point, you can use the image editor to choose that focal point. Then, if you provide a height (h) and width (w) parameter to that image's URL, it will center around the focal point and not the center of the image itself.
As an example, let's look at this image where the person has been offset:
If we do not choose a focal point, the default 200x200 crop of that image will look like this (https://cdn.aglty.io/agility-cms-docs/images/joel-wide.jpg?w=200&h=200):
However, once we set the focal point on the face, the default crop performs much better (https://cdn.aglty.io/agility-cms-docs/images/joel-focal.jpg?w=200&h=200):
Advanced Query Parameters
Agility uses Fastly for image optimization, and supports the following additional query parameters:
- auto: Enable optimization features automatically.
- bg-color: Set the background color of an image.
- blur: Set the blurriness of the output image.
- brightness: Set the brightness of the output image.
- canvas: Increase the size of the canvas around an image.
- contrast: Set the contrast of the output image.
- crop: Remove pixels from an image.
- disable: Disable functionality that is enabled by default.
- dpr: Serve correctly sized images for devices that expose a device pixel ratio.
- fit: Set how the image will fit within the size bounds provided.
- format: Specify the output format to convert the image to.
- frame: Extract the first frame from an animated image sequence.
- height: Resize the height of the image.
- level: Specify the level constraints when converting to video.
- metadata: Control which metadata fields are preserved during transformation.
- optimize: Automatically apply optimal quality compression.
- orient: Change the cardinal orientation of the image.
- pad: Add pixels to the edge of an image.
- precrop: Remove pixels from an image before any other transformations occur.
- profile: Specify the profile class of application when converting to video.
- quality: Optimize the image to the given compression level for lossy file formatted images.
- resize-filter: Specify the resize filter used when resizing images.
- saturation: Set the saturation of the output image.
- sharpen: Set the sharpness of the output image.
- trim: Remove pixels from the edge of an image.
- width: Resize the width of the image.