Image Resizing and Processing documentation for the dotCMS Content Management System

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.

Simple Image Pathing

dotCMS provides simple image pathing to image assets using the /dA/{identifier} or /dA/{shortyId} scheme to create shorter paths to image or file assets. For more information on how to a “Shorty ID” with binary and image fields, please see the Displaying Content with Binary & Image Fields documentation.

Note: Only the resize and image formatting parameters are available when using the simple pathing methods. For more advanced image API filters, please see the Advanced API URI documentation.

The base pattern for simple Image pathing to an image with the complete image identifier:

/dA/{imageIdentifier}

Shorty ID with Simple Image Pathing

The base pattern for simple Image pathing to an image with the shorty identifier (first 10 digits of the identifier):

/dA/{shortyID}

Resize & Shorty ID with Simple Image Pathing

Either the image width or height can be passed as a parameter after the shorty id:

width: /dA/{shortyID}/400w

height: /dA/{shortyID}/400h

Warning: Passing both parameters may result in image distortion if not directly proportional to the original image

Progressive JPEG, Resizing, Shorty ID, with Simple Image Pathing

Passing jpegp to the end of the image path with render the image as a progressive JPEG image:

/dA/{shortyID}/400w/jpegp


Advanced API URI

Transformations

The Advanced Image API allows you to specify a transformation to apply to the image from among the following:

TransformationURI PathDescription
Image FilterimageDisplay the image, with the option of applying one or more image editing filters in a chain to the image before display.
Resize Imageresize-imageDisplays a resized version of the image.
Image Thumbnailimage-thumbnailDisplays a thumbnail of the image.
RawFieldraw-dataReturns the raw image binary data (as it is stored within dotCMS), with no filters.

You can create your own custom transformations using plugins.

URI Pattern

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

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

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

URL ParameterDescription
{transformation}The transformation being used.
  • You may only use one transformation in each image URL.
  • However the Resize and Thumbnail transformations can also be performed with the Image Filter, and the Image Filter allows you to chain multiple filters on the same image.
{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.
{parameters}Appropriate parameters for the used (see the appropriate , below, for details).

Image Filter: /contentAsset/image

Allows you to apply one or more image filters to an image.

Quick Reference

The following table lists all the filters, along with a quick reference of all URL parameters necessary to use the filter. Optional parameters are shown in green.

For more information on each filter (including complete click-through working examples), please click the filter name in the first column.

FilterQuick Reference Example
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/grayscale/1
Hue, Saturation, Brightness/filter/Hsb/hsb_h/-1.0/hsb_s/0.0/hsb_b/1.0
JPEG/filter/Jpeg/jpeg_q/80
Progressive JPEG/filter/Jpegp
PNG/filter/Png
Resize/filter/Resize/resize_w/800/resize_h/600
Rotate/filter/Rotate/rotate_a/-31.5
Scale/filter/Scale/scale_w/800/scale_h/600
Thumbnail/filter/Thumbnail/thumbnail_w/150/thumbnail_h/150/thumbnail_bg/000255128

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 s 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.

“Shorty” ID Filters


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)?????
Examples:

Gamma

Adjusts the gamma value of the image.

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

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.

Examples:

Grayscale

Converts image coloring to grayscale.

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

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
Examples:

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.

Examples:

Progressive JPEG

Converts the image to progressive JPEG format.

Filter: Jpeg_p

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.

The Jpegp parameter works exactly the same as the Jpeg parameter (please see above). The only difference is that the Jpegp parameter results in a progressive JPEG image instead of a standard JPEG image. https://demo.dotcms.com/dA/2943b5eb9105/jpegp


PNG

Converts the image to PNG format.

Filter: Png

Parameters: None


Resize

Resizes an image to a specified width and height, without maintaining the aspect ratio.

Filter: Resize
ParameterTypeRangeDescription
/resize_h (Optional)Integer> 0Height of resulting image.
If no resize_w` parameter is specified, image will be scaled maintaining aspect ratio; otherwise .
/resize_w (Optional)Integer> 0Width of resulting image.
If no resize_h` parameter is specified, image will be scaled maintaining aspect ratio; otherwise image will be stretched as needed.

Note:

  • Although both parameters are optional, you must supply at least one parameter.
  • If only one parameter is supplied, the image will be scaled to maintain aspect ratio.
    • Otherwise the image will be stretched as needed to fill the specified width and height.
  • For a filter that always maintains the aspect ratio (filling empty space instead of stretching), please see Scale below.
Examples:

Rotate

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

Filter: Rotate
ParameterTypeRangeDescription
/rotate_aDouble-360.0 to 360.0Angle to rotate image.
Examples:

Scale

Resize image, maintaining aspect ratio.

Filter: Scale
ParameterTypeRangeDescription
/scale_h (Optional)Integer> 0Height of resulting image.
/scale_w (Optional)Integer> 0Width of resulting image.
If no scale_h` parameter is specified, image will be scaled maintaining aspect ratio; otherwise image will be stretched as needed.

Note:

  • Although both parameters are optional, you must supply at least one parameter.
  • If only one parameter is supplied, the image will be scaled to maintain aspect ratio with no filled space.
    • Otherwise the image will be scaled to maintain the aspect ratio and either the width or height will be filled as needed.
  • For a filter that stretches the image rather than filling empty space, please see Resize above.
Examples:

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.

Filter: Thumbnail
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)
Examples:

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.

ImageResizeField

URI: /contentAsset/resize-image

Resizes a given image to the requested width and height.

ParameterTypeDescription
/wIntegerWidth
/hIntegerHeight

Examples:

ImageThumbnailField

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)

RawField

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/6a50a56c-c281-4282-b9ba-fa9f07fea4da/fileAsset/w/500/h/800/v/461b2fa3-fb97-442e-b9ca-19e96d683f65" target="_blank">https://www.dotcms.com/contentAsset/<strong>resize-image</strong>/6a50a56c-c281-4282-b9ba-fa9f07fea4da/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).