dotCMS Docs
APIs Releases Get dotCMS

Image Resizing and Processing

Last Updated: May 31, 2024
documentation for the dotCMS Content Management System

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

Important Notes:

  • When cropping images, you may apply intelligent cropping by specifying a Focal Point.
  • When applying filters, 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, Progressive JPEG, and WebP filters (e.g. /Gif, /Jpeg, /Jpegp, or /Webp) must be applied last (to the right of all other filters).
      • This is because all filters except these conversion filters only work on PNG images, and result in a PNG image, so other filters will not work if they follow conversion to any format other than PNG.
  • The image editor and image editing filters do not work with SVG images.
  • 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.

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.

Filters Available

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.

FilterURL ParametersExampleNotes
Resize Width/{int}w
/{int}maxw
/{int}minw		/270w/
/270maxw/
/270minw/		the width in pixels followed by a w, maxw, or minw
Resize Height/{int}h
/{int}maxh
/{int}minh		/500h/
/500maxh/
/500minh/		the height in pixels followed by a h, maxh, or minh
Resample Option/{1-15}ro/13roThis resamples an image based on one of a number of different algorithms, for use when resizing an image. See the resampling section for more information.
Crop Width/{int}cw/50cw/the width in pixels followed by a cw
Crop Height/{int}ch/50ch/the height in pixels followed by a ch
Focal Point/{float},{float}/.35,.70fp/the focal point of the image, as a percentage, from the top left corner of the image. Use with crop width and crop height to create images built around a focal point.
To JPEG/jpeg/jpegconverts image to JPEG
To Progressive JPEG/jpegp/jpegpconverts image to a progressive JPEG
To WebP/webp/webpconverts image to a WebP image
Auto-compress/{1-100}q/50qThis will deliver a compressed JPEG or webp image based on the users browser capibilities. Quality of compression is a percent of 100 — the smaller the value, the more compressed the image. dotCMS will serve the image as a webp image to the browsers that support WebP and a JPEG image to browsers that do not support webp.

Simple Pathing URL Format

The base pattern for simple Image pathing to an image with the complete image identifier followed by the field variable — if the field is not specified, it will default to the first asset field on the content:

/dA/{imageIdentifier}

or

/dA/{imageIdentifier}/{fieldVar}

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 using strict resizing may result in image distortion if not directly proportional to the original image. For a more detailed look at how the processor handles simultaneous strict, maximum, or minimum dimensions, see the discussion on resizing behavior under the Image Filter: /contentAsset/image section.

Bandwidth Optimized Images

Passing a quality percentage value will automatically render an image as either a webp image or a progressive jpeg image based on the visitors browser capibilities. As of this writing, only safari and Apple's iOS browsers do not support webp. Quality is a value between 1-100 inclusive followed by q. The example below delivers an optimized image at 15% quality.

/dA/{shortyID}/400w/15q

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

Retrieving the Title Image using Simple Pathing

You can append /titleImage to the Simple Path with a Shorty ID to display the first image field of the content. The Title Image will be the first Image field or Binary field containing an image that's found in the content, as the fields are ordered within the Content Type.

/dA/{shortyID}/titleImage

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/{ parameters}
  • Binary Field:
    • By identifier: /contentAsset/{transformation}/{identifier}/{velocityVar}/{ 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.
{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.
FilterFilter NameQuick Reference Example
CropCrop/crop_w/50/crop_h/50/crop_x/15/crop_y/20
/crop_w/50/crop_h/50/fp/.69,.27
ExposureExposure/exposure_exp/3.5
FlipFlip/flip_flip/1
Focal PointCrop/crop_w/50/crop_h/50/fp/.69,.27
GammaGamma/gamma_g/2.4
GIFGif/filter/Gif
GrayscaleGrayscale/filter/Grayscale
Hue, Saturation, BrightnessHsb/hsb_h/-1.0/hsb_s/0.0/hsb_b/1.0
JPEGJpeg/filter/Jpeg/jpeg_q/80
/jpeg_q/80
Progressive JPEGJpeg/filter/Jpeg/jpeg_p/1
/jpeg_p/1
PNGPng/filter/Png
WebPWebP/filter/WebP/webp_q/85
/webp_q/85
Resize (and resample)Resize/resize_w/800/resize_h/600/resize_ro/15
/resize_maxw/800/resize_maxh/600
/resize_minw/800/resize_minh/600/resize_ro/9
RotateRotate/rotate_a/-31.5
ThumbnailThumbnail/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 filters support the following file types:

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

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 & Focal Point

Focal Point or Starting Point

The crop is performed relative to either:

  • A specified starting X,Y position (supplied via the /crop_x and crop_y parameters), OR
  • A specified focal point (supplied via the /fp parameter).

If neither the starting position nor a focal point are supplied, the crop is performed using the center of the image as the focal point (calculated based on the 50% of the image height and width). So, for example, by default an image that is 800x600 will have a default focal point of 400,300.

Intelligent Cropping with the Focal Point Parameter

The Focal Point parameter allows you to perform more intelligent cropping based on the actual content of the image. For example, if you have an image that's a portrait, you can set the focal point in the center of the face, to ensure that the face remains visible if the image is cropped.

When supplying the Focal Point (/fp) parameter, the X and Y values are expressed as values from 0.0-1.0.

  • These represent percentages (from the top left) of the total width/height of the image.
    • Example: A focal point specified as /fp/.25,.65 is 25% from the left and 65% from the top.
  • Specifying the focal point as a percentage ensures that the focal point can be applied even if the image size is changed (via a resize etc.) before the Crop is applied.

Examples

The following examples demonstrate the value of using a Focal Point when cropping. All of these examples crop the following image, which can be found at https://www.dotcms.com/contentAsset/image/b0cf4b1c-e7ab-4a1c-8bfa-ee48021f2dd7/image/. Note that the original image has dimensions of 1280x853, but is shown at a reduced size here for display purposes):

Original Image

Now, consider the image cropped:

Focal PointExample URLThumbnail Image
None (Default)/crop_w/400/crop_h/300/Thumbnail of cropped image with default Focal Point
7%,45% (Centered on the puppet)/crop_w/400/crop_h/300/fp/.7,.45Thumbnail of cropped image with Focal Point

Of course it's possible to perform the exact same crop using the crop_x and crop_y parameters instead of the /fp parameter. However the real value comes when the same image needs to be cropped multiple ways. When using the /crop_x and /crop_y parameters, the starting X and Y values must be determined for each crop. However when using the /fp parameter, the focal point percentages only need to be determined once, and all future crops, of any size, can use the same values. As an example, consider the following three crops of the same image:

Image SizeExample URLThumbnail Image
400x300/crop_w/400/crop_h/300/fp/.7,.45Thumbnail of 400x300 image
600x500/crop_w/600/crop_h/500/fp/.7,.45Thumbnail of 600x500 image
800x600/crop_w/800/crop_h/600/fp/.7,.45Thumbnail of 800x600 image

The Focal Point ensures the image continues to display the most important feature, regardless of the size the image is cropped to, and without the need to re-determine the starting X and Y position for each crop.

Filter: Crop
ParameterTypeDescription
/fpX,YFocal Point
/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
ParameterTypeRange
/flip_flipIntegerMust be 1
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

Parameters: None

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 and Progressive JPEG

Converts the image to either standard or Progressive JPEG format.

By default, images will be converted to standard JPEG format. To convert images to Progressive JPEG format, you must include the /jpeg_p parameter.

Filter: Jpeg

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

ParameterTypeRangeDescription
/jpeg_qInteger1 to 100JPEG Quality (Optional)
If this parameter is not supplied, quality defaults to 85.
/jpeg_pIntegerMust be 1Generates the image as a Progressive JPEG.
Examples:

PNG

Converts the image to PNG format.

Filter: Png

Parameters: None

Examples:

Resize

Strict resizing sets an image to a specified width and height. It can do so without necessarily maintaining the aspect ratio, if both dimensions are supplied.

When resizing, you may also supply a resampling option parameter. This allows more control over the output quality; see the resampling section for more information.

Starting in dotCMS 23.08.16, minimum and/or maximum dimensions may also be supplied, to establish context-aware limits.

Filter: Resize
ParameterTypeRangeDescription
/resize_hInteger> 0Strict Height of resulting image
/resize_wInteger> 0Strict Width of resulting image
/resize_maxhInteger> 0Maximum height of resulting image
/resize_maxwInteger> 0Maximum width of resulting image
/resize_minhInteger> 0Minimum height of resulting image
/resize_minwInteger> 0Minimum width of resulting image
/resize_roInteger1-15Selects the resampling algorithm, listed in the table below

*Note: Although all parameters are optional, you must supply at least one parameter. The image's aspect ratio will be respected in all cases except when both strict width and strict height parameters are specified.

When more than one kind of resizing is used at once, some measures may have to take priority over others. When deciding which value to respect, the image processor's priorities are as follows:

  1. Strict width or height
  2. Maximum width or height
  3. Minimum width or height

Unlike strict resizing, minimum and maximum resizing functions will never change an image's aspect ratio. When two minimum or two maximum dimensions would violate the native ratio, the image will be resized proportionally according to the most restrictive dimension — i.e., the smallest for a maximum, or the largest for a minimum.

For example, starting with a 100 x 100 input image:

  • A maximum height 50 and a maximum width 80 will result in a 50 x 50 output; the smaller dimension is more restrictive, as a value of 50 would also satisfy a maximum of 80.
  • A minimum height of 120 and a minimum width of 150 will result in a 150 x 150 output; 150 is the more restrictive minimum, as a value of 150 would also satisfy a minimum of 120.
  • A maximum height of 50 and a minimum width of 150 will result in a 50 x 50 output; a maximum dimension is prioritized over a minimum dimension.
Resampling Options

Each integer value supplied to the resampling parameter refers to a different algorithm. These approximately increase in quality and computational cost as the number increases, with 11-15 generally considered the best choices. However, this effect is not perfectly linear; you may find, for example, 13 more satisfactory than 14 for the quality of some images, depending on the desired effect — sharpness vs. smoothness, etc.

The system default resampling option is 3, which is both fast and moderately good in quality. This property can be adjusted with the DOT_IMAGE_DEFAULT_RESAMPLE_OPT environment variable. See Configuration Properties for more information.

ValueAlgorithm
1Nearest Neighbor
2Box interpolation
3Triangle (bilinear) interpolation
4Hermite interpolation
5Hanning interpolation
6Hamming interpolation
7Blackman interpolation
8Gaussian interpolation
9Quadratic interpolation
10Cubic interpolation
11Catrom interpolation
12Mitchell interpolation
13Lanczos interpolation
14Blackman-Bessel interpolation
15Blackman-Sinc interpolation
Examples:

Rotate

Rotate an image the specified number of degrees. The image height and width will be increased if necessary to ensure that the entire rotated image fits within the resulting image.

Filter: Rotate
ParameterTypeRangeDescription
/rotate_aDouble-360.0 to 360.0Angle to rotate image
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:

WebP

Converts the image to Google WebP format.

Filter: Webp
ParameterTypeRangeDescription
/webp_qInteger1 to 100WebP Quality (Optional)

Note:

  • This filter must be applied last, or all filters that follow will be ignored.
  • If '/filter/Webpis used and thewebp_q` parameter is not supplied, quality defaults to 85.
Examples:

Chaining Filters

You can chain multiple filters in a single URL to create sophisticated multi-stage filters. You may chain filters one of two ways:

  • Explicitly provide a /filter parameter, which takes as it's argument a list of the filters to be applied, in the order they are to be applied.
  • Provide the parameters of each filter in the order you wish the filters to be applied to the image.

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

Filter Order

When you chain filters explicitly (using the /filter parameter), the filters are applied in the order you specify them (via the comma separated list of filter names supplied).

When you chain filters without the explicit /filter parameter, the the order the filters are applied is determined as follows:

  • Filters are applied in the order the filter parameters are listed in the URL.
    • So, for example, if the filter parameters are supplied as /crop_w/250/crop_h/250/resize_w/500, it means the image will be cropped first, and then the cropped image will be resized.
  • Each filter will only be applied once, when the first parameter related to that filter is found.
    • When the first parameter for a filter is found, all remaining parameters for that filter will be used, regardless of where they are in the URL.
    • So, for example, specifying /crop_w/250/crop_h/250/resize_w/500 will produce the same results as specifying the parameters as /crop_w/250/resize_w/500/crop_h/250
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:

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

On this page

×

We Dig Feedback

Selected excerpt:

×