westwing-image-transformer v3.11.0

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

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 🦄