Nothing is more frustrating than blurred or pixelated images on your website. This article explains some basic principles behind our image handling to help you get the best possible results on your web pages.
As a general rule you should upload large (larger than you'll ever realistically need) high quality images into iCM and let your website do the rest.
A Bit of Background
All media items in iCM are made up of components. Some media items will only have a single component, others up to eight.
For example, the standard Document media type has a single component (the document) that allows you to upload a single file into iCM. Image media items will almost always have multiple components, with each component providing a different size or aspect ratio of the same image.
In iCM powered sites that pre-date our current range of themes and frameworks (that is, everything older than the themes documented on this site), images typically had three components: thumbnail, image, and large. The sizes of these components were set in iCM. When your website needed a thumbnail sized version of an image (for example, as an image next to an article in a list) it asked iCM for the thumbnail component. When your site needed an image to insert into the body text of an article, it asked iCM for the image component.
Only having three image sizes, and these being fixed in iCM rather than controlled by the website, was very restrictive and often led to users creating dozens of different image media types for different purposes. So with iCM 10 we started to develop a better approach.
The API Server Image Worker
The API Server is a critical part of iCM and every website running on your digital platform. One of the services it provides is image resizing.
Now, rather than your website asking iCM for a thumbnail image and getting back the thumbnail component, it can ask the API Server for a 150x150 version of an image, and the Image Worker will find the "best fit" component, scale it and crop it, save a copy of it, then tell the site where the new version is.
This new approach allows a single image to be used around the site, and be output at different sizes without you having to manually create all of those different sized versions as components in iCM.
For example, the Chill theme uses images in carousels, as thumbnails in lists, for the site logo, as icons, on the homepage as a background, and many other places. Here are some of the different size constraints:
- thumbnail - maxWidth="375" maxHeight="250"
- carousel - height="380"
- logo - maxWidth="500"
- social - width="48" height="48"
You could create a single media item, with just one image component, to use in all of these places - when your site asks for one of the constraints, the Image Worker generates the correct size.
In practical terms, when adding media to iCM, you don't need to know what these size constraints are. Just upload large good quality images.
Generated Images
When the Image Worker generates a newly sized image, it is saved in a separate directory (called "generated") in your website's media folder. These images cannot be seen or managed from within iCM. When asked for an image, the worker will always return one from those it has already generated, if the correct size exists, rather than generating a new one.
If you save a media item in iCM (even if no changes are made) any existing generated images are deleted. This forces the worker to generate new versions the next time they are requested, using any new or resized components you might have uploaded into iCM. For this reason you should never attempt to "hard code" embedded images into your site using the HTML editor. What might be a valid path to an image could disappear.
Scaling and Cropping
The rules that govern scaling and cropping are complicated. Sometimes the worker will take a component and scale it up, sometimes scale it down, and sometimes crop a large component to a smaller size.
How an image is manipulated also depends on what your site asks for. In the examples from the Chill theme above you can see that the social type has a set width and height, the thumbnail maximum values (so a smaller image could be used) and the carousel and logo have rules for one dimension but not the other.
Most of our themes use maxWidth and maxHeight sizes for images that appear in your page content. Fixed widths generally only apply to icons, buttons, logos, and other navigation items.
It's impossible to set out examples for every case, but in general, when the Image Worker generates a new image it will use the following rules:
- Images are never stretched to fit a requested aspect ratio
- Images are scaled down in preference to being scaled up
- If a ratio is requested that doesn't exist, images are scaled, then cropped about a central point
For example, an image has two components, one 400x400 another 200x200.
A request is made for a version 300 wide and 190 high.
The larger image is used because scaling down is always preferable to scaling up. The image is then cropped to 190 pixels high, using the centre of the image as a focus point. This results in:
Components, Variants, Restrictions
All new installations of iCM have image media types set up with components called variants rather than thumbnails etc. This avoids any confusion about how the image is supposed to be used.
Variants are designed to provide different aspect ratios of images, rather than different scales. One of your variants (it doesn't matter which, there's no preference in ordering) should always be the biggest and best quality image you have.
If your website theme requests images in a particularly demanding ratio, a landscape letterbox for example, you might want to create a variant close to that ratio so that cropping doesn't exclude important details at the top or bottom of the image (yes, it will chop people's heads off).
For example, with our strawberry picture above, if we wanted the 300x190 version to always focus on the top of the image, a variant closer to that aspect could be added, which would be used in preference to cropping the 400x400 variant.
Here a variant measuring 400x200 has been added.
Which gives us the following image rather than the 300x190 version above. In this case it's been scaled vertically, then cropped at either side (scaling horizontally wouldn't work because the image would then only be 150 high).
Variants don't have size restrictions in iCM. For standard images we encourage you to upload really good quality ones! The only time you might find restrictions set in an iCM media definition are for specific icons or backgrounds that will always be a set size.
"Old" Sites
So what if you've had iCM for a while and have an older site, then upgrade to the newer themes and frameworks?
If you are switching all of your subsites to the new frameworks it's easy. We've got a script we can run that will find all your current images, replace the old components with variants, and save your "image" and "large" components as variant1 and variant2. We generally ignore the old thumbnail component as it is too small to be of any use.
If you need to run old and new frameworks together then we'll consider the best approach with you. We could create a new image media type with the new components, and you could use iCM content privileges to switch your users over to the new type, or the existing image type could be edited to either remove size constraints, or add new components to it.
Still Blurry?
If after all of this your images are still blurry, then there is likely to be something else going on.
The most common problems can be found in your site's CSS, perhaps manipulating images after they have been requested by the site. The site framework might request and receive an image 200 pixels wide, but there's nothing stopping the CSS then stretching that image to any size it wants. This sort of thing can normally be spotted using your browser developer tools. If this does happen, and it's a site we've designed, let us know.
What About Mobiles?
All our standard themes are responsive. When a page is viewed on a mobile the images on it are resized by the site's CSS, ensuring their maximum width won't be larger than the width of the page as viewed on the device.
A Note for Developers
Despite everything said above it is possible to request that a specific image component is used when you make a request to imageutils. The optional
Share this page
