Resizing Images

Resize images with query string parameters

While accessing image by a URL, you can use some query string parameters to process the way the image ends up on a page.

/media(abef8eb5-d2a4-4ceb-b2a2-2b0a5990fbb4)?h=300&w=200&action=fill

You can set the image's desired width, height or both as well as apply one of the following actions:

  • stretch: the image will be stretched by the specified sizes; the proportion is not observed
  • fit: the image is proportionally scaled down to the maximum to fit within the specified area  (also know as "touch from inside")
  • fill: the image is proportionally scaled down to the minimum to completely fill the specified area  (also know as "touch from outside")
  • crop: the image is proportionally scaled down with the parts outside the area's boundaries cropped

Besides, with JPEG image files, you can control the image quality when used with width/height settings or alone when compressing images.

You can also convert one image format into another when resizing by using the mt query parameter (C1 CMS v.6.11 or later).

Here are the parameters you can use with the image URL:

ParameterDefinitionValuesDefault Value
wwidthany integernone
hheightany integernone
mwmaximum widthany integernone
mhmaximum heightany integernone
actionDesired image-processing actionstretch, fit, fill, cropstretch
qimage qualityany integer between 1 and 10080
mtMedia Typeany supported Media Type (for example, image/png or image/jpeg)none
shsecure hash (protection for resized imagesautomatic

Note. The 'action' parameter is ignored when only one dimension is specified. The image will be scaled down (if necessary) in this case.

Example of usage and description

w=100With only one dimension specified, the image will be scaled down (if necessary), so that the related result image dimension should not exceed the specified value.
w=100&action=fillThe 'action' parameter is ignored if only one dimension is specified.

w=100&h=100

w=100&h=100&action=stretch

The resulting image dimensions will match the specified values. The image's  proportion will be affected by this operation.

w=100&h=100&action=fit

mw=100&mh=1001)

This action proportionally scales the image down (if necessary) so that it fits the specified area ("touch from inside").
w=100&h=100&action=fillThis action proportionally scales the image down (if necessary) so that it fills the specified area ("touch from outside").
w=100&h=100&action=crop

This action proportionally scales the image down (if necessary) so that it fills the specified area, and crops the parts outside the area's boundaries.

Note. The use of the 'mw' (maximum width) and 'mh' (maximum height) parameters is deprecated. Please use 'w' and 'h' with 'action=fit' instead.

Compressing JPEG images

In C1 CMS v. 4.1 or later, you can also control the image quality with the q parameter. You can use it in conjunction with width/height settings:

/media(abef8eb5-d2a4-4ceb-b2a2-2b0a5990fbb4)?w=100&h=100&q=50

or alone - to compress images:

/media(abef8eb5-d2a4-4ceb-b2a2-2b0a5990fbb4)?q=50

When resizing the image, the default value is 80.

You can change the default value in Composite.config:

  1. Open Composite.config.
  2. Search for the imageQuality attribute.
  3. Change the value to an integer between 1 and 100.
<Composite.Core.Configuration.Plugins.GlobalSettingsProviderConfiguration defaultGlobalSettingsProvider="ConfigBasedGlobalSettingsProvider">
  <GlobalSettingsProviderPlugins>
    <add type="Composite.Plugins.GlobalSettings.GlobalSettingsProviders.ConfigBasedGlobalSettingsProvider, Composite" name="ConfigBasedGlobalSettingsProvider"
    ...
	  imageQuality="80"
    >
      ...
    </add>
  </GlobalSettingsProviderPlugins>
</Composite.Core.Configuration.Plugins.GlobalSettingsProviderConfiguration>

Converting image formats

In C1 CMS v. 6.11 or later, by using the mt query parameter you can convert one image format into another while resizing (scaling down) the image.

Example

/media(abef8eb5-d2a4-4ceb-b2a2-2b0a5990fbb4)?h=300&amp;w=200&amp;mt=image/jpeg

Note. The 'mt' parameter is ignored if the image is not scaled down (that is, if the size stays the same or is made bigger).

Currently, the conversion is supported into these formats:

  • PNG (mt=image/png)
  • JPEG (mt=image/jpeg)
  • WEBP (mt=image/webp)

Note. To use WebP format, you must install the Orckestra.Media.ImageFormats.WebP add-on.

Conversion into GIF or BMP is not supported and these formats will be automatically formatted as PNG and JPEG respectively

  • mt=image/gif > PNG (an equivalent of mt=image/png)
  • mt=image/bmp > JPEG (an equivalent of mt=image/jpeg)

As with JPEGs, you can control the quality of a WebP image by the q query parameter.

/media(abef8eb5-d2a4-4ceb-b2a2-2b0a5990fbb4)?h=300&amp;w=200&amp;mt=image/webp&amp;q=80