Image Scaling

The Image Scaling feature offers scaling to the display dimensions considering density-aware images and the adaptation of the output format. Using the scaling feature, the output size might be drastically reduced while retaining optimal visual quality of the image.

Image Scaling can be used in the DOM, in CSS and in JavaScript.

Note: The final rendering of images falls to the developer, for example using CSS. The Image Scaling is only intended to create the smallest possible image without losing any perceived image quality.

To increase performance, images of a certain range are all scaled to the same maximum size, the breakpoint size. This way a requested image is most likely already requested before, thereby generated and the proper scaled version is found in the imagecache.

To use Image Scaling, image-scaling must be turned on via the following conf/config.xml entry:

    <image-scaling [ quality="70" ] [ scaling-cache="false" ] [ scaling-height="" ] [ scaling-width="" ] [ viewport-fitting=" max | current | landscape | portrait " ] [ pass-on-enlargement="false" ] [ add-size-attributes="true" ] />

The quality attribute sets the default quality (see ai-quality for details).

The scaling-cache attribute sets the default caching behavior for images (see ai-scaling-cache for details).

The scaling-height attribute sets the default scaling height (see ai-scaling-height for details).

The scaling-width attribute sets the default scaling width (see ai-scaling-width for details).

The viewport-fitting attribute sets the default scaling behavior for images, either optimizing for only the current, landscape or portrait viewport or for the maximum of both the current viewport and the alternative viewport of the client. Possible values are max, current, landscape and portrait (see ai-viewport-fitting for details). The default is max.

The pass-on-enlargement attribute: In some cases, Image Scaling may result in images with larger files sizes than the original. In these cases, and only if the source format is jpg, png or gif, the FIT Server delivers the original, smaller images instead. The default is true. To turn off this behavior, set the pass-on-enlargement option to false.

Note: The option pass-on-enlargement has no corresponding ai-* parameter and applies to all images on the site.

The add-size-attributes option: If an image is already present in the cache due to a previous request, the original image dimensions are known to the FIT Server, and it is therefore able to add width and height to img tags or fill in its missing attribute with a pixel value. The default is false. To turn on this behavior, set the add-size-attributes option to true.

Note: If only one dimension attribute for the image is specified and its value is expressed as a percentage (e.g. width="75%"), it is treated like it is not present. If both attributes are set, the img tag is not changed.

These config attributes provide default values for the image scaling process, which are overwritten by the corresponding ai-* parameters in the content.

Further configuration options and limits

In the fit.ini you can set the FIT_MAX_IMAGE_AREA to define the maximum size of an outgoing image in megapixels.

The source image can be sized up to 100 megapixels, whereby images larger than FIT_MAX_IMAGE_AREA will be scaled in “fast mode” to be more efficient. For smaller images with less pixels more precise resizing algorithms are used. Source images larger than 100 megapixels will not be processed and given out in original size. In this case an error message will be written to the fit_engine.log.

Example fit_engine.log entry:

[...] Transforming image failed: Source image is larger than 100 Mpixels. Continue with original source.

If FIT_STRICT_IMAGE_PROCESSING is set to true, images larger than 100 megapixels will not be processed, the request cancels and an error message will be sent as plain text additionally to an fit_engine.log entry.

Image Scaling parameters

Image Scaling offers a few parameters to influence the scaling more accurately.

The ai-quality parameter

The ai-quality parameter indicates the intended quality of the image. The value must be an integer between -1 and 100, where -1 means lossless compression for WebP images and maximum quality for JPEG images. The default value is 70.

The following example shows how to generate an image with lesser quality:

<img src="foo.jpg" ai-quality="50" style="width: 100%">

Note: The image is density-aware and it becomes orientation-aware as well by setting style="width:100%;".

Note: Due to how the projection methods work that are used to display high resolution images, higher densities require smaller quality values to achieve similar visual quality.

In addition, some formats, for example WebP, allow a further reduction of the quality value.

So, while the exact given quality value will be used for delivering JPEG images to clients that have a device pixel ratio of 1, you may see a reduced quality value depending on the device pixel ratio, the viewport’s dimensions, the image’s original dimensions, and the resulting image format.

The ai-scaling-width and ai-scaling-height parameters

The ai-scaling parameters allow you to provide information about the desired output size of an image. The parameters must provide a value in pixel, 1px or greater, or percentage, 1% or greater, e.g. 150px or 50%. The basis for percentage scaling is the longest viewport edge. A value without any specified unit will be ignored, e.g. 200.

Depending on the aspect ratio, setting one ai-scaling parameter to a high percentage, e.g. 100%, without setting the other, may result in an image that requires horizontal or vertical scrolling. To avoid scrolling, the other parameter should be set to 100% as well. If both ai-scaling-height and ai-scaling-width are set to a percentage, the value that results in the smaller scaled image is preferred. You should always assign a size to the image (for example using CSS) to make sure that the image is not displayed larger than intended.

Scaling to a percentage value of the viewport uses breakpoints as a maximum size to enhance performance. This means that an image with ai-scaling-width="100%" might be slightly larger than the maximum viewport-length. Images scaled to a percentage value will not be larger than their physical length.


Image scaled, using a breakpoint, to fit 100% of the display’s width, preserving the aspect ratio, scrolling might occur:

<img src="foo.jpg" ai-scaling-width="100%">

Image scaled, using a breakpoint, to fit 100% of the display’s height, preserving the aspect ratio, vertical/horizontal scrolling might occur:

<img src="foo.jpg" ai-scaling-height="100%">

Image scaled, using a breakpoint, preserving the aspect ratio:

<img src="foo.jpg" ai-scaling-width="100%" ai-scaling-height="100%">

Setting a pixel value in only one of the parameters forces the image scaler to skip classification into a breakpoint range and uses the given pixel value as image width or height. The corresponding length will be calculated preserving the aspect ratio. If the other parameter is set as a percentage value, it will be ignored.

Pixel values are interpreted as viewport pixels rather than hardware pixels. If a corresponding width or height is set on the image via width, height or CSS styling, the image is displayed optimal on all clients regardless of their device pixel ratio. Without defining a width or height the image is displayed bigger on displays with a device pixel ratio greater 1.0 than the px value set with ai-scaling-width/ai-scaling-height.

For example, on an iPhone with a device pixel ratio of 2.0 an image with ai-scaling-width="100px" will be scaled to a width of 200 hardware pixels. If the image also has the attribute width="100", the image is displayed optimised for the retina display. On a client with a device pixel ratio of 3.0, the image would be scaled to a width of 300 hardware pixels. The same width="100" attribute displays the image optimised for this client.


Image scaled to a width of 150px preserving the aspect ratio and optimized for higher display density devices via width attribute:

<img src="foo.jpg" ai-scaling-width="150px" width="150">

Image scaled to a height of 300px preserving the aspect ratio, ai-scaling-width will be ignored:

<img src="foo.jpg" ai-scaling-width="100%" ai-scaling-height="300px">

Setting pixel values for both parameters, the given values are used as image dimensions, and the output image might be distorted and enlarged.


Image scaled to 150px width and 100px height ignoring the aspect ratio and optimized for higher density devices via CSS styling:

<img src="foo.jpg" ai-scaling-width="150px" ai-scaling-height="100px" style="width: 150px; height: 100px;">

Note: All Examples use the DOM Image Scaling syntax.

The ai-scale parameter

All images without explicit scaling parameter set will be scaled as if both ai-scaling-width and ai-scaling-height were set to 100%. Similarly, if no quality is set, they will get the default quality of 70. The ai-scale parameter allows you to disable image-scaling on a per image basis. If image-scaling is activated in the conf/config.xml, adding an ai-scale="false" to an image will prevent it from being modified. No scaling, quality or format change will be performed. However, if image-scaling is not enabled in the conf/config.xml, adding an ai-scale="true" will NOT activate image scaling for that image.

<img src="foo.jpg" ai-scale="false" style="width: 100%">

The ai-viewport-fitting parameter

By default, images are scaled to fit the landscape as well as the portrait viewport of clients. This may not always result in the optimal image for every use case. Resizable browsers for example never use an alternative viewport. Therefore it is often not desirable to scale images big enough for an alternative viewport.

The default of always scaling the image big enough to fit both the current and the alternative viewport can be disabled globally in the config or on a per image basis with the ai-viewport-fitting attribute.

<img src="foo.jpg" ai-viewport-fitting="max">

<img src="bar.jpg" ai-viewport-fitting="current">

<img src="qux.jpg" ai-viewport-fitting="landscape">

<img src="baz.jpg" ai-viewport-fitting="portrait">

The ai-viewport-fitting attribute value may be one of the following

  • landscape - the image will be scaled to fit the landscape orientation
  • portrait - the image will be scaled to fit the portrait orientation
  • max - the image will always be scaled to fit both the landscape and the portrait viewport of the client
  • current - the image will always be scaled to fit the current viewport orientation

If no attribute is set, the image is scaled according to the viewport-fitting setting in the config (the config default is max).

Note: The current viewport refers to the viewport used during the request of the image.

The ai-scaling-cache parameter

Images that are scaled by the FIT Server are cached by default. If you don’t want an image to be cached, you can set the ai-scaling-cache attribute to false. The default is true. If an image has the ai-scaling-cache attribute set to false, it will not be cached by the FIT Server and a Cache-Control: no-cache, no-store, No-Transform header is sent to the client.

<img src="foo.jpg" ai-scaling-cache="false">

The ai-add-size-attributes parameter

Adding the width and height attributes to img tags allows the browser to do less reflows when loading a webpage and as a result increase the render performance of your website.

When setting this parameter to true, FIT will automatically add width and height attributes to img elements that reference images that are stored in the FIT cache. The values of these attributes are the scaling target sizes calculated by FIT from the client viewport dimensions and ai-scaling-width and ai-scaling-height declarations.

In regard to delayed images this avoids “jumping pages” if the image dimensions are missing.

FIT will not overwrite any width or height attributes that are already defined on the img element.

If only one of the attributes is already set in the markup, FIT will determine the missing image dimension from the actual image aspect ratio and the given dimension.

In addition FIT will add a CSS to the document that sets

img {width: auto; height: auto}

. The CSS is added in a way that every css from the user can overwrite these properties. Specifying CSS image sizes is recommended.


The Image Scaling uses the same caching mechanism like the Image Compression.

Image formats

Aside from scaling, the input format will be converted into the best matching output format that the client is capable of rendering. Transparency will be preserved wherever possible.

Note: The Image Scaler keeps the image format unchanged for unknown input image formats, for example in case an image was loaded dynamically (.../image.php?format=svg). It avoids, e.g. the loss of transparencies during transformation from PNG to JPEG.

Animated GIF images - especially if they contain frames with different sizes - are hard to scale. The resulting scaled image is usually larger than the source or has a significantly degraded quality. Therefore, FIT detects animated GIFs and passes them unchanged.

SVG images are passed unchanged to supporting clients, to preserve the vector mechanism. However, if enabled, SVG Minifying can reduce the file size of SVG images. When SVG images have to be converted to other formats for clients not supporting SVG, not all SVG features can be converted. The use element as well as all scripting functionality are not supported and will be lost in the output image. Therefore we recommend to disable scaling of sophisticated, especially interactive SVG images.