Image Resolution Helper

Image Resolution Helper - Resize images, convert between formats, adjust compression quality and read image metadata inside a workflow

Overview

The Image Resolution Helper processes image files inside a workflow without sending them to an external service. It takes a Tray file object as input, works on the image in memory, and returns a new Tray file object that later steps can use, store or send on.

Use it to:

• Resize images to a target width and/or height, with a choice of fit modes
• Convert images between JPEG, PNG, WebP, AVIF, TIFF and GIF
• Re-encode images at a lower quality to reduce file size
• Read an image's dimensions, format, colour space and EXIF orientation

Authentication

When an Image Resolution Helper step is selected, the properties panel on the right shows that no authentication is necessary. The connector does not call an outside API.

Available Operations

• Resize Image
• Convert Format
• Adjust Quality
• Get Metadata

Please see the Full Operations Reference for details on all available operations, and the sample payloads page for example inputs and outputs.

Working with file objects

Every operation takes an Image File input, which is a Tray file object with name, url, mime_type and expires properties. You will normally map it from an earlier step that produces a file, such as a Google Drive, Dropbox, Box, S3 or HTTP Client download. The operations that produce an image return the result as a file object of the same shape, ready to be mapped into the next step.

Operation notes

Resize Image

Give a Width, a Height, or both, in pixels. If you give only one, the other is worked out from the image's aspect ratio.

Fit Mode decides what happens when you give both and the box has a different aspect ratio from the image:

Fit Mode	Result
Inside (default)	Scaled to fit within the box, keeping the aspect ratio. The output may be smaller than the box on one side.
Outside	Scaled so the box is fully covered, keeping the aspect ratio. The output may be larger than the box on one side.
Contain	Exactly the box size, keeping the aspect ratio, with the empty space padded in the Background Colour.
Cover	Exactly the box size, keeping the aspect ratio, with the overflow cropped from the centre.
Fill	Exactly the box size, ignoring the aspect ratio, so the image is stretched.

Setting Maintain Aspect Ratio to false forces Fill regardless of the Fit Mode chosen.

Background Colour applies only to Contain. It takes a hex colour such as #FFFFFF, or transparent, and defaults to black. Transparent padding needs a format with an alpha channel: PNG, WebP, AVIF, TIFF, GIF or SVG input. For JPEG input a transparent or semi-transparent colour returns an error, because the output keeps the input format and JPEG cannot store transparency. GIF padding can be opaque or fully transparent, but not semi-transparent.

Without Enlargement keeps an image at its original size when it is already smaller than the target.

The output keeps the input format. The file is named resized_ followed by the original name.

Convert Format

Choose a target Format: JPEG, PNG, WebP, AVIF, TIFF or GIF. Quality (1 to 100, default 80) applies to the lossy formats JPEG, WebP, AVIF and TIFF. PNG is always written losslessly in full colour, and GIF has no quality setting. The file keeps its name with the new extension.

Adjust Quality

Re-encodes the image at the given Quality (1 to 100, default 80). By default the image keeps its format, which must therefore be one with a quality setting: JPEG, WebP, AVIF or TIFF. For a PNG or GIF input, choose a lossy Output Format, otherwise the operation returns an error explaining that the format has no quality setting rather than re-encoding the file unchanged.

Get Metadata

Returns the stored width and height, format, file size in bytes, colour space, number of channels, bit depth, density, whether the image has an alpha channel, and the EXIF orientation value if present. It does not modify the image.

Limits and behaviour

Example Usage

This example resizes product images stored in Google Drive to a 500 by 500 pixel thumbnail with white padding, then converts them to WebP.

The steps will be as follows:

1. Set up a manual trigger and download the image from Google Drive
2. Resize the image to a 500 by 500 thumbnail
3. Convert the thumbnail to WebP
4. Use the result

1 - Download the image

Once you have clicked 'Create new workflow' on your main Tray dashboard (and named said new workflow), select the Manual trigger from the trigger options available.

From the connectors panel on the left, add a Google Drive connector as your second step and set the operation to 'Download file'. Give it the File ID of the image you want to process. The step's output includes a file object.

2 - Resize the image

Find 'Image Resolution Helper' in the 'Helpers' section of the panel and add it as your third step. Choose the 'Resize Image' operation and set:

• Image File: map the file object from the download step, for example $.steps.google-drive-1.file
• Width: 500
• Height: 500
• Fit Mode: Contain
• Background Colour: #FFFFFF

The output contains the resized file together with its width, height, format and size. With Contain, a landscape photo comes back as a 500 by 500 image with white bars above and below.

3 - Convert to WebP

Add another Image Resolution Helper step with the 'Convert Format' operation. Map Image File from the resize step, for example $.steps.image-resolution-helper-1.file, set Format to webp and leave Quality at its default of 80.

4 - Use the result

The converted file object can now be mapped into any step that accepts a file: upload it back to Google Drive, attach it to an email, or send it to a CMS. Click 'Run workflow' and open the debug tab to check the dimensions and size reported by each step.