Create Image Transformation URLs

Use the URLUtils and MediaFile classes to create image transformation URLs. An image transformation URL identifies a resource, which can be cached. The URL also serves as an image transformation directive, causing the DIS to generate a new image resource.

Using these classes dynamically generates multiple image resources from a single high-resolution image.

The JavaScript object literal contains transformation parameters (name and value pairs). Each method returns a URL derived from your transformation parameters. In the derived URL, your transformation parameters are replaced with URL parameters.

Example: The URL parameter cy replaces the transformation parameter cropY.

The URLUtils class includes these methods for generating image transformation URLs.


public URL imageURL( String path, Object transform );
public URL imageURL( String context, String contextID, String relPath, Object transform );
public URL absImage( String path, Object transform );
public URL absImage( String context, String contextID, String relPath, Object transform );
public URL httpImage( String path, Object transform );
public URL httpImage( String context, String contextID, String relPath, Object transform );
public URL httpsImage( String path, Object transform );
public URL httpsImage( String context, String contextID, String relPath, Object transform );

The MediaFile class includes these methods for generating image transformation URLs.


public URL getURL( Object transform );
public URL getAbsURL( Object transform );
public URL getHttpURL( Object transform );
public URL getHttpsURL( Object transform );

Transformations Supported by the Dynamic Imaging Service

Type of Transformation Parameters Description
Scale an image scaleWidth (sw), scaleHeight (sh), scaleMode (sm)

The scaleWidth and scaleHeight parameters are integers. Parameter values are from 10-2000 pixels.

Setting one of these parameters triggers a scaling operation. If both values are provided, the one that scales the image less is used to calculate the scale factor. The image is cropped according to the second dimension, with a centered position of the cropped area. If the parameter scales the image larger, only this operation is applied if the image remains in the size of 2000x2000 pixels.

The scaleMode default parameter is cut.

If you set scaleMode to fit, the system scales the image to the box dimensions you enter, while maintaining the aspect ratio. The result is a smaller image in one dimension.

Overlay an image imageX (ox), imageY (oy), imageURI (oimg)

The imageX and imageY parameters are integers. Parameter values are 0 or greater.

Supported formats: GIF, PNG, JPG, JP2.

Note: Use animated GIFs with caution because they can cause frame artifacts. Maintain aspect ratio for animated GIFs.
You can set the imageURI parameter to the absolute path of the overlaid image. The imageURI parameter must have proper URL encoding and can't exceed 400 characters.

The path must support query string parameters that support dynamically generating the overlaid image through the service. You can use transformed images for the overlaid image.

If the overlaid image extends beyond the primary images' boundaries, the overlaid image is cropped to fit directly over the primary image.

Note: An overlay (oimg) value must point to a customer-owned image served by the DIS domain.
Crop an image cropX (cx), cropY (cy), cropWidth (cw), cropHeight (ch)

The cropX, cropY, cropWidth, and cropHeight parameters are integers. Specify all four parameters to trigger a cropping operation.

Values for the cropX and cropY parameters are 0 or greater. If the crop location defined by cropX and cropY is outside the image area, nothing is cropped.

Values for the cropWidth and cropHeight parameters are 10 or greater. If the cropWidth and cropHeight parameters specify a size that is greater than the original image, the crop area is reduced to the actual image area. If cropWidth and cropHeight are 0 or less, no transformation is applied.
Format an image format (sfrm)

The format parameter specifies the target format of the image. Supported formats are PNG, JPG, JP2 and GIF.

The path parameter (when using the URLUtils class) or attribute value (MediaFile class) must reference the source image. The source image format recognizes these file extensions: .tiff, .jpg, .jpeg, .png, and gif.

In the generated URL, the file extension of the target format is used in the URL path.

The source format is provided in the sfrm URL parameter. If no target format is specified, no format conversion is performed.

Image Quality quality (q) The quality parameter specifies a quality setting for JPG and JP2 images, and specifies the compression level for PNG images.

For JPG and JP2 images, you can set values from 1–100 for the highest quality. The default quality is 80. If you're not changing the default quality, you don't need to pass in a value.

For PNG images, the quality setting has no effect on the appearance of the PNG, since the compression is always lossless. Instead you can use the quality setting to set the zlib compression level and filter-type for PNG images. The tens digit sets the zlib compression level(1-9). The ones digit sets the filter type.

If the PNG setting is not present or set to 0, it uses a default value of 75. If this setting is set to 100, it actually equals the quality setting 90.

While it's possible to code transformation URLs by hand, we recommend using the URLUtils and MediaFile classes, because the API validates all transformation parameters. Using the API also protects you from future changes. If the basic URL pattern changes, the API calls work regardless of the changes. However, hand-coded URLs no longer work.

Sample Calls

The call to URLUtils.imageURL( String path, Object transform ):

URLUtils.imageURL( '/<static image path>/image.png', { scaleWidth: 100, format: 'jpg' } );

returns the image transformation URL.

http://<image server host name>/dw/image/v2/.../on/demandware.static/.../<static image path>/image.jpg?sw=100&sfrm=png

The call to MediaFile.getAbsImageURL( Object transform ):

product.image.getAbsImageURL( { scaleWidth: 100 } );

returns the image transformation URL.

http://<image server host name>/dw/image/v2/.../on/demandware.static/.../<path to product image>/FG45SDAF.jpg?sw=100
See Also: