Westwing Image Transformer

The image-transformer transforms images to any required format, style and dimension and also optimizes them for minimal file size alongside high visual quality for an improved user experience and minimal bandwidth.

This library was originally meant to replace Cloudinary image transformations therefore it's historically bound to some of its specific features and requirements.

We try to point those out in this guide.

Tables of content

• URL
  • Parts
  • Examples
• Image Transformations Reference
• Transformations Definitions
• Transformations Exclusions
• Transformations Priority
• Buckets, Custom Assets, Fonts

Url

The URL is the entry point of this library. Beside some preliminary configuration, all that's required to transform an image can be set just by composing a certain URL.

Url parts

| URL part | Description | Type | Required | |------|-------------|:----:|:-----:| | /image/upload/ | (Legacy) Cloudinary Prefix | string | yes | | /named_transformation/manual_transformation/ | Sets of transformation. See here for more details. | string | no | | /v12345678/ | URL Version. Can be used as a cache-buster | string | no | | /s3-key/to-image/ | The s3 key (path) to the origin image. | string | yes |

Url examples

Some URLs examples to get a quick idea. For all the possibilities, check here.

Original Image

Resized Image with auto height - 400 x 300

/w_400,h_auto/

Resized Image - 300 x 200

/w_300,h_200/

Cropped Image - 600 x 450

/c_crop,w_600,h_450/

Image with applied Image and Text Image - 600 x 450

/w_600,h_450/g_northeast,t_black_friday_badge,w_65,h_65,y_6,x_6/g_north_east,co_rgb:ffffff,l_text:Roboto_23_medium:-22%2525,x_13,y_29/

Image Transformations Reference

The table on this page lists all transformation parameters currently supported by the image-transformer library. For each parameter you can see the short name that you can use for manually building transformation URLs.

| Param name | URL param | Value | Example | Description | |------|-------------|:----:|------|-------------| | width and height | w,h | pixels | auto | w_300,h_450, w_400,h_auto | The required width / height of a transformed image or an overlay. | | x and y | x,y | pixels | x_20,y_20 | Vertical / Horizontal position for custom-coordinates based cropping and overlay placement. | | crop | c | mode || A crop mode that determines how to transform the image for fitting into the desired width & height dimensions. | ||| scale (default) || Change the size of the image exactly to the given width and height without necessarily retaining the original aspect ratio: all original image parts are visible but might be stretched or shrunk. | ||| crop || Used to extract a given width & height out of the original image. The original proportions are retained and so is the size of the graphics. | ||| pad || Resize the image to fill the given width and height while retaining the original aspect ratio. If the proportions of the original image do not match the given width and height, padding is added to the image to reach the required size. | ||| limit || The image is resized so that it takes up as much space as possible within a bounding box defined by the given width and height parameters only if the original image is larger than the given limit. The original aspect ratio is retained and all of the original image is visible. | | gravity | g | direction || Determines which part of the image to keep when any part of the image is cropped. For overlays, this setting determines where to place the overlay. | ||| (default) || center (applies only to some transformations) | ||| north || top | ||| north_east || top right | ||| north_west || top left | ||| south || bottom | ||| south_east || bottom right | ||| south_west || bottom left | ||| west || right | ||| east || left | | default image | d | identifier || Specify the public ID of a placeholder image to use if the requested image or social network picture does not exist. The name of the placeholder image must include the file extension. | ||| image_key | d_dont-delete:default_error.png | Use default image with the key /dont-delete/default_error.png. (For the bucket where the default image is fetched from check here. | | overlay | l | identifier || Customize the color to use together with text captions. The color can be set as an RGB. | ||| image_key | l_club:dev:ch:campaign:DEHOWT15:badge | Add the overlay with the key dev/ch/campaign/DEHOWT15/badge. When using the overlay image transformation the image-transformer assumes the image is located in the sourceBucket. | ||| text | l_text:Roboto_23_medium:Hello%20World | Add a 'Hello World' text overlay with font-family: Roboto, font-size: 23px, font-weight: medium. As a default behaviour, before being overlay-ed, text is treated as a regular image and can be resized and positioned. Size and position are considered as absolute values. Multiple text overlays are supported and applied following the order in the URL. Note: check here the overall transformations priority. | ||||| Defaults font-family: Roboto, font-size: 23px, font-weight: regular. | | color | co | color || Customize the color to use together with text captions. The color can be set as an RGB. | ||| rgb | co_rgb:000000 | In the case of a text transformations, applies the specified color (000000) to the text. | | transformation | t | name || Set one flag that alters the default transformation behavior. | ||| default || Applies pre-defined set of transformations. For historical reasons, the rule is to have the named transformation occurring after t_default and separated with . (dot). | |||| t_default.upcoming_preview | Applies the set of transformations configured in the upcoming_preview. (For transformations definitions check here. | ||| badge || Applies a badge transformation provided a badge name. The rule is to wrap the badge name between t_ and _badge. As a default behaviour, before being overlay-ed, the badge is treated as a regular image and can be resized and positioned. Size and position are considered as absolute values. Multiple badges are supported and are applied following the order in the URL. Note: check here the overall transformations priority. | |||| t_black_friday_badge,h_65,w_65,x_6,y_6 | Applies the black_friday badge with the given params. (For the badge configuration check here. | | flags | fl | name || Apply a pre-defined named transformation of the given name. | ||| relative || When applied to text transformations it modifies width or height of below image based on x and y negative params and the origin gravity. | |||| fl_relative,l_text:Hello,x_0,y_-10 | Applies the text overlay transformation while increasing the height of the image by 10px. | ||| resizelast || When applied to text or badge overlay transformations it modifies the default transformations priority so that resizing happens last. This means the transformations applied to the overlays will be relative to the image original size. | |||| t_soldout_badge,h_328,w_779,fl_resizelast | Applies the specified badge and resizes it relative to the original image. | | effect | e | name || Apply a filter or an effect on an image. | ||| trim | e_trim | Detect and remove image edges whose color is similar to corner pixels. | | quality | q | percent || Control the JPEG, WebP, GIF compression quality. 1 is the lowest quality and 100 is the highest. Reducing the quality is a tradeoff between visual quality and file size. | ||| 80 | q_80 | Sets the quality of images to 80%. | | format | f | format || Deliver the file in the requested format. In URLs, just set the file extension to the desired format. Available formats: JPEG, PNG, WebP. | ||| png | f_png | Convert the original image to PNG format. |

Transformations Definitions

Upon instantiation the image-transformer can be provided with some transformation definitions (also, named transformations). A definition is basically a name for a set of operations which are configured in a Javascript Object like this:

const definitions = {
     'catalog': { 'width': 290, 'height': 240, 'type': 'crop', 'crop': 'pad', 'format': 'jpeg' },
};

const transformer = new Transformer(definitions);

The way to request this named transformation is via the transform (t_) parameter in the URL, like this: /image/upload/t_default.catalog/club/de/campaign/QATEST_up7/l.

Transformations Exclusions

For some cases, it might be useful to ignore some transformations. The most common cases could breaking changes that would require URL updates or when some legacy URL should be supported but avoiding it to break the parser. In cases like those, a Javascript Array of exclusions can be passed as a second argument upon the transformer instantiation.

const exclusions = [
    'l_text',
    '\$bS',
];

const transformer = new Transformer([], exclusions);

This will ignore the URL params containing the exclusions. The check is done via RegEx test.

Transformations Priority

Though the URL params and their orders are held as the source of truth, semantic reasons impose a certain order for the transformations (high prio means applied first). This means that, despite the place the params might appear in the URL, the transformations are sorted so that some of them have priority over others, after which the order of appearance in URL applies.

Default priority

1. Named Transformations
2. Manual Transformations
3. Image Overlay
4. Text Overlay

Default Image Placeholder

A specific case applies to the Default Image Placeholder, which is only applied whenever the image-transformer is not able to fetch the provided image (or some other error happens during the transformation).

Resize Last

Whenever the flag resizelast is used inside a transformation, it will increase the priority of the transformation to which is applied. This flag is currently supported only for badge and text overlays transformations.

This means that, in a case with URL params like /w_600,h_450/t_black_friday_badge,w_65,h_65/, the resizing will happen before applying the badge.

When using the flag /w_600,h_450/t_black_friday_badge,w_65,h_65,fl_resizelast/, the badge will be applied before resizing.

Note that this has influence over the final overlay size. In the second case the sizes specified with the params will be relative to the original image, meaning that the resulting applied overlay will not have absolute 65px width and height.

Buckets, Custom Assets, Fonts

The image-transformer is dependent on Amazon S3 and a text-to-png; this means that all information about the locations of the related resources have to be provided to the instance.

In order to do this, some convenient methods are provided.

Source and Destination Buckets

The source bucket is the one from which the transformer retrieves the original image and the one used for the l_club transformation.

The destination bucket is the one used to save all transformed image. It is also used to check whether the requested transformation has already been generated.

const transformedImage = await transformer.transformImage(url, originBucket, destBucket);

Custom Assets

The custom assets define the configuration for badges and default placeholder image.

const customAssets = {
    placeholder: {
        bucket: 'placeholder-bucket-name',
    },
    badges: {
        black_friday: {
            badgeBucket: 'badge-bucket-name',
            badgeKey: 'badges/bf.png',
        },
    },
};

const transformer = new Transformer();
transformer.setCustomAssetsLocation(customAssets);

Note that the badge key in this example would correspond to the result of parsing the URL param t_black_friday_badge.

Fonts

The supported fonts are set as default pointing to the /fonts/ in the image-transformer. It is possible however to override this configuration by means of setFontsPath() method, which requires an existent folder path.

Westwing Image Transformer © 2017+, Released under the MIT License. Authored and maintained by Westwing Group AG with help from contributors.

Jakob Houser
Angelo Gulina 🦄