Salesforce B2C Commerce 24.7 > Merchandising Your Site > Image Management > Dynamic Imaging Service

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. Valid parameter values are from 10–3000 pixels. Note: `ScaleMode` can only be used when combined with `scaleHeight` and `scaleWidth`. 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 3000x3000 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 target formats are gif, jp2, jpg, jpeg, jxr, and png. 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: gif, jp2, jpg, jpeg, png, tiff, and tif. 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, it's not necessary 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.
Adjust Metadata Stripping	`strip`	The parameter specifies if metadata, such as EXIF and color profiles, is stripped from the image during transformation. Valid values are `true` or `false`. The default is `true`.
Change background color	`bgcolor(color) or bgcolor(color+alpha)`	The `bgcolor` parameter specifies the background color for images that support transparency and JPEG images that are converted from a format that supports transparency. Optionally, alpha setting for PNG images are also supported. `bgcolor` expects a 6-digit hexadecimal value of RGB with an optional two hexadecimal characters representing the alpha value that determines transparency. FF0000 = Red FF000077 = Red with 50% transparency Alpha values are optional. When the alpha value is omitted, the resulting color is opaque. Alpha values are only valid when the image output format is PNG.

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