Image Resizing and Processing - Documentation topics on: cache,displaying thumbnail images,display resized images,enterprise only,file assets,filter,image,image filter,image handling,inode,resizing binary image files,.

Image Resizing and Processing

dotCMS includes a built-in image editor, which is a very useful tool for content editors to manipulate uploaded images without the need to pre-edit the images before uploading or upload multiple versions of the same image (e.g. color vs. grayscale, different sizes of the same image, etc.). One of the most useful features of the dotCMS image editor is that, in addition to being accessible via the back-end user interface, it is also available via a RESTful interface, and allows you to perform image manipulations “on-the-fly” simply by modifying the URL used to access any image in the system.


Important Notes:

  • The image editor, including the RESTful image editing functions, are only available in dotCMS Enterprise editions.
    • If you use image filters in image URLs with dotCMS Community edition, the images will still be displayed but the filters will not be applied to the images.
  • The order in which the filters are applied is important.
    • The filters will be applied in the order they appear in the URL (filters which appear to the left will be applied first).
    • If you apply multiple filters and the result is not what you expect, try changing the order of the filters.
    • In particular, the GIF, JPEG, and Progressive JPEG filters (e.g. /Gif, /Jpeg or /Jpegp) must be applied last (to the right of all other filters).
      • This is because all filters except the Jpeg filters only work on PNG images, and result in a PNG image, so other filters will not work if they follow conversion to Jpeg format.
  • The image editor and image editing filters do not work with SVG images.

All functions in the image editor can be called via a URL, which is very helpful to web developers looking to automatically resize or edit images for use in your web sites and widgets. For example, if you need to use a standard image in a number of different ways - such as a logo which needs to be resized differently depending on where it's used - you can upload the image just once to dotCMS, and then apply the appropriate image filters to it each timem it's used, rather than uploading multiple versions of the same image.

When calling the image editor through a URL, the image passes through a series of filters, each of which can take 0 or more parameters. The resulting modified image is then passed through the next filter for processing.

API URI

The base pattern for applying image editing to your image URL is the following:

  • File Asset:
    • By identifier: /contentAsset/{exporter}/{identifier}/fileAsset/{exporter parameters}
    • By inode: /contentAsset/{exporter}/{inode}/fileAsset/byInode/1/{exporter parameters}
  • Binary Field:
    • By identifier: /contentAsset/{exporter}/{identifier}/{velocityVar}/{exporter parameters}
    • By inode: /contentAsset/{exporter}/{inode}/{velocityVar}/byInode/1{exporter parameters}

Where the URL parameters in curly braces must be replaced with appropriate values, as follows:

URL ParameterDescription
{exporter}The Exporter being used.
  • There are 4 built-in exporters, and you can also write custom exporters if you wish.
  • You may only use one exporter in each image URL.
{identifier} or {inode}The identifier or inode of the File Asset or of the content item that holds the image.
  • Each URL must include either an identifier or an inode.
  • If an inode is used, you must include /byInode/1 in the URL (see above examples).
  • If the /byInode/1 parameter is not added, dotCMS assumes you are referencing the image by identifier.
{field velocityVar}The Velocity variable name of the binary field in the Content Type that holds the image.
{exporter parameters}Appropriate parameters for the Exporter used (see the appropriate Exporter, below, for details).

Exporters

ImageFilterExporter: /contentAsset/image

Allows you to apply one or more image filters to an image. The following table lists all the filters, along with a quick reference of all URL parameters necessary to use the filter; for more information on each filter (including complete click-through working examples), please click the filter name in the first column:

FilterQuick Reference
Crop/filter/Crop/crop_x/15/crop_y/20/crop_w/50/crop_h/50
Exposure/filter/Exposure/exposure_exp/3.5
Flip/filter/Flip/flip_flip/1
Gamma/filter/Gamma/gamma_g/2.4
GIF/filter/Gif
Grayscale`/filter/Grayscale
Hue, Saturation, Brightness`/filter/Hsb
JPEG/filter/Jpeg/jpeg_q/80
Progressive JPEG`/filter/Jpegp
PNG`/filter/
Resize`/filter/
Rotate`/filter/
Scale`/filter/
Thumbnail`/filter/

Filters can be chained to perform multiple image manipulations within a single image URL. For more information, please see Chaining Filters, below.

Supported File Types

Image filter exporters support the following file types:

  • TIFF
  • JPEG
  • JPG
  • GIF
  • PNG
  • BMP
  • PNM
  • PDF
  • PSD
  • IFF
  • PCX
  • PICT
  • SGI
  • TGA
  • ICNS
  • PCX
  • THUMBSDB
  • CLIPPATH

Notes:

  • Image resizing is currently only supported for static images.
    • Resizing of animated images is not supported at this time.
  • In each of the following examples two API methods are shown.
    • The first example shows how to access an image in a File Asset, which has been uploaded and stored to dotCMS as a separate piece of content and may be viewed in a Site Browser folder.
      • Images in File Assets may be associated with a piece of content via an image/file field.
      • When accessing a File Asset, use the identifier or inode of the File Asset containing the image.
    • The second example demonstrates how to access and transform an image stored in a [binary field].
      • Images uploaded via a binary field are stored inside the piece of content which contains the binary field; they do not exist as separate pieces of content, and may not be accessed from the Site Browser.
      • The URL when accessing an image in a binary field includes the velocity variable name of the binary field defined in the Content Type (in this case diagram1).
      • When accessing a binary field, use the identifier or inode of the content item which contains the binary field.

Crop

Filter: Crop
ParameterTypeDescription
/crop_xIntegerLeft edge (starting x)
/crop_yIntegerTop edge (starting y)
/crop_wIntegerWidth of resulting image
/crop_hIntegerHeight of resulting image
Examples:

Exposure

Filter: Exposure
ParameterTypeDescription
/exposure_expDoubleExposure value between 0.0 and 5.0.
Examples:

Flip

“Flips” an image horizontally.

Filter: Flip
ParameterTypeDescription
`/flip_flipInteger (0 or 1 only)?????

Gamma

Filter: Gamma
ParameterTypeRangeDescription
/gamma_gDouble0.0 to 3.0The gamma value to apply.

Gif

Converts the image to GIF format.

Filter: Gif
Parameters: None

Note: This filter must be applied last, or all filters that follow will be ignored. Fore more information, please see Important Notes, above.

Grayscale

Converts image coloring to grayscale.

Filter: Grayscale
ParameterTypeRangeDescription
/grayscaleIntegerMust be 1Simply a flag to enable the grayscale filter.

Hue, Saturation, Brightness (Hsb)

Filter: Hsb
ParameterTypeRangeDescription
/hsb_hDouble-1.0 to 1.0Hue
/hsb_sDouble-1.0 to 1.0Saturation
/hsb_bDouble-1.0 to 1.0Brightness

Jpeg {Jpeg}

Converts the image to standard (non-progressive) JPEG format.

Filter: Jpeg
ParameterTypeRangeDescription
/jpeg_q (Optional)Integer1 to 100JPEG Quality.
If this parameter is not supplied, quality defaults to 85.

Note: This filter must be applied last, or all filters that follow will be ignored. Fore more information, please see Important Notes, above.

Rotate

rotate_a for angle (double) 0.00-359.99 degrees to rotate)

Scale

scale_w width, scale_h height)

Thumbnail

Resizes an image to the specified width and height. Aspect ratio is maintained, and any blank space is filled with the specified background color.

ParameterTypeRangeDescription
/thumbnail_wIntegerAnyThumbnail width
/thumbnail_hIntegerAnyThumbnail height
/thumbnail_bg9 digits0-255 for each color
(e.g. 000000000-255255255)
Background color (used to fill in any empty space)

Chaining Filters

You can chain multiple filters in a single URL to create sophisticated multi-stage filters. To chain filters, provide the name of each filter after the /filter URL parameter, separated by commas. Each filter still takes its own normal parameters, which can come in any order after the filters themselves have been specified. Filters are applied in the order they are listed in the URL.

Note: When chaining filters, please make sure you read and understand the Important Notes section, above.

Example

In the following example the Crop, Rotate, and Hue filters are applied to the image (in that order). This means the image is first cropped, then the cropped image is rotated, and then the Hue filter is applied to the rotated cropped image.

ImageResizeFieldExporter

Exporter URI: /contentAsset/resize-image

Resizes a given image to the requested width and height.

ParameterTypeDescription
/wIntegerWidth
/hIntegerHeight

Examples:

ImageThumbnailFieldExporter

Exporter URI: /contentAsset/image-thumbnail

Generates a thumbnail of the image having the specified width and height, and filling in any gaps with the specified background color.

ParameterTypeRangeDescription
/wIntegerAnyThumbnail width
/hIntegerAnyThumbnail height
/bg9 digits0-255 for each color
(e.g. 000000000-255255255)
Background color (used to fill in any empty space)

RawFieldExporter

Exporter URI: /contentAsset/raw-data/

Displays the file on a given contentlet field as it is (e.g. the image as it was uploaded, without any filtering or modification).

Image Caching

When using image editing URLs, the modified image is generated once and then cached on the dotCMS server for performance. If the same URL is used again later, the modified image will be pulled from the cache; the image filters will not be applied again as long as the modified image is still available in the cache.

Since each image manipulation uses a different URL, each manipulation (e.g. each image URL) is cached separately. This means, for example, that if you apply an image manipulation to an image and then later apply a different manipulation to the same image, the original modified image will be pulled from the cache (even though another manipulation was performed on the same image since the original modified image was cached).

Forcing a Cache Refresh

In addition to enabling efficient caching within dotCMS, the URL-based image tools also enable each of the modified images to be cached in a user's browser, in a proxy server or by a CDN - all of which can significantly increase your site performance. However it is sometimes difficult to fully control all the different caches and ensure that the caches are updated when images change in dotCMS, and this can sometimes cause external caches to serve a user a stale version of an image.

To prevent all caches (within or external to dotCMS) from serving a stale image, append the image's inode (not the identifier) to the image URL. This does not affect whether or not the image can be cached or how it's displayed, since dotCMS will ignore any URI parameters it does not understand. However this ensures that a new URL is generated each time the image is changed, which ensures that the image will be updated in all caches when a new version of the image is published (since the URL of the image will change with each edit).

Example

The following URL creates a cacheable resized image:

To force this image to be refreshed in all caches each time the image is updated within dotCMS (but only when it's updated within dotCMS), you can append the inode as follows:

* <a href="https://www.dotcms.com/contentAsset/resize-image/8317a120-b017-41e2-aba3-2415faecd203/fileAsset/w/500/h/800/v/461b2fa3-fb97-442e-b9ca-19e96d683f65" target="_blank">https://www.dotcms.com/contentAsset/<strong>resize-image</strong>/8317a120-b017-41e2-aba3-2415faecd203/fileAsset/w/500/h/800/v/461b2fa3-fb97-442e-b9ca-19e96d683f65</a>

Where everything beginning with 461b2fa3-fb97-442e-b9ca-19e96d683f65 is the {inode} of the image (and the /v/ in the URL is simply used as a reminder that what follows is the version of the image being displayed).