Transformations

Resizing and compromising with Quality

Resizing an image can have various combinations for width and height.
When only the width is requested, the height value will be calculated so that the image's aspect ratio is preserved.
Same when only the height is requested. In this case the width will be calculated so the aspect ratio is not affected.
When both the width and height are requested, the resulting image will comply to the dimensions, and the image will be fitted inside still keeping the aspect ratio. Any excess area will be padded with the background color (bgc) specified, or white when there is no background color specified.

There is also a way to specify transparency for the formats that support it.

The background color understands web named colors like lime, black, LightSteelBlue, etc.
Here is some reference: Web Colors

To specify that you want to use a hex value, prepend an _ to the value like &bgc=_00ff00

The quality parameter only has effect on the default webp format, and the jpg format. The quality value is defaulted to 90 and can be changed in your account's dashboard. This default value is overriden by using the parameter from the url.

More Resizing Transformations

Working with width and height will always preserve aspect ratio.
To open things up for more flexibility, we can make use of the following transformations:

Extend

Allow an image to extend "outside the viewport" and keep its aspect ratio.

Comparing the samples above, notice how the image grew so that it filled the padding to the sides, and the excess of height went "out of sight" (above and below).

The image without extend, relies on padding on its sides to comply with the requested dimensions.
The image with extend, resizes the image to the requested width, and the requested height makes the resulting image "overflow out of sight".

The missing top and bottom areas overflowed outside the dimensions as the content grew horizontally to cover the width. This only works when both width and height are specified as parameters.

Cover

Allow image distortion (lose aspect ratio) to entirely cover the requested dimensions.

Allow Enlargement

By default, an image will not grow beyond its original dimensions. Meaning if you have an image with original dimensions of 90x90 and you request it as 120x120, the image will be centered in the area, and padded with 15px of bgc all around.

Visual Optimizations

Resizing images always comes with visual artifacts. The more the dimension changes, the more evident these may manifest. Usually shrinking or enlarging an image will make it fussy.

Here are some actions that help with visual appearance.

Formats

There are many image formats around on the web.
webp is a recent format that is gaining popularity and compatibility. ixmage uses webp as the default response type because of its benefits in compression, but it will fall-back to png when the requesting client does not mention support for webp (through its accept header).

Even if the source image is a jpg, the response will be of type webp (with jpg fallback when needed) unless explicitly requested as jpg through the format parameter.

More Transformations

Here are other ways of transforming your image through the querystring.

dpr should be used along with img attributes of width and height so the multiplication of image dimensions is handled appropriately in the browser.

The "advanced" usage to display a 200x100 image on a device with a dpr of 3, would be to request the image like
?width=200&height=100&dpr=3
and combine this with image properties
<img width="200" height="100" src="ixmage-url">
This will produce an image of dimensions 600x300 which the device browser will then resize to 200x100 so it renders according to the planned layout. From there, the device will work its capabilities to display a much clearer visual.

Color Manipulations

The following transformations change the image's colors.

Templates

When you identify a transformation pattern that you are using in multiple places, it may be a sign that a template can come into play.
A template is used to give a name to a set of transformations.

A template consists of a set of operations that is saved by giving it a name which can be used in the url. The template name will then resolve to the set of operations.

For instance, common transformations that come in handy for an e-commerce website are: small, medium, and large. A small variant of your product image for a listing page, a medium variant to show a preview or initial detail, and a large variant for when the user decides to "zoom-in" for better appreciation.

You can setup these three templates in your alias and give each the appropriate width, height, and quality.

Now on your website markup, instead of requesting an image with /v2/token/alias/image.png?width=90&height=90&quality=60 you can instead do /v2/token/alias/image.png?template=small

Go to detailed example.

---

Let's define template thumb as &width=90&height=90&quality=50&grey=1

Now on your website markup, you can start using &template=thumb. Now imagine you use this template in various pages on your website, and later decide that you want to remove the grayscale transformation. You can remove it from the template and now the images will start reflecting the change. You complete the change from your control panel instead of possibly multiple references in code and markup.

While you can add more transformations to urls that use templates, specifying a transformation that has been used in the template will not override it.

Continuing with the thumbnail example, this will not change the width:
&t=thumbnail&w=200