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.

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. See how to pull content by Shorty ID in 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

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

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

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

URL ParameterDescription
{}The being used.
  • There are 4 built-in s, and you can also write custom s if you wish.
  • You may only use one 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.
{ parameters}Appropriate parameters for the used (see the appropriate , below, for details).

ImageFilter: /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: