Positioning

The goal of the Image Editing API is to give you as much control as possible on how to position your subject in the result image, while also making it as easy as possible to implement the most common use cases.

General Principle

By default, the Image Editing API positioning system will fit the referenceBox inside the targetArea.

The next sections of this page will go into the details of how this system works and how you can control it to get exactly the result that you need.

Target Area

The targetArea (green square in the picture) represents the space available inside the result image to display the subject.

By default, the targetArea will take all the space available in the result image, and the subject will be:

resized to fit the targetArea
centered inside the targetArea

If you prefer for the subject to fill as much space as possible inside the targetArea, this is possible by setting the argument scaling to fill:

If you prefer for the subject to be positioned somewhere else than at the center of the targetArea, this is also possible, please see the section Horizontal and Vertical Alignments for more details.

Padding

If you want to add some space between the target area and the borders of the result image, this can be controlled through the argument padding.

The API supports two formats to specify the amount padding:

relative values, expressed in percentages (e.g., 0.2 or 20%)
absolute values, expressed in pixels (e.g., 100px)

In this example, padding has been set to 0.1 (10%):

This results in the addition of empty space between each edge of the result image and the target area.

Here, the size of this empty space is equal to 10% of the size of the corresponding side of the result image (i.e. 10% of the width for the left and right edges, and 10% of the height for the top and bottom edges).

If needed, a different amount of padding can be set for each edge of the result image, trough the arguments paddingLeft, paddingRight, paddingTop and paddingBottom.

In this example, the global padding is still set to 0.1 (10%), but additionally:

paddingTop has been overriden and set to 0.2 (20%)
paddingLeft has also been overriden and set to 0.2 (20%)

Padding is computed with respect to the width and height of the result image.

This means that a paddingLeft of 20% will be equal to 20% of the width of the result image.

This also means that if the percentage of padding on two opposing sides is greater than or equal to 100%, it will lead to an error because it means that there's no space left to position the subject.

(Because of this, since the argument padding applies to all sides, its value must be strictly less than 0.5)

Cropped Subject

In the previous sections, we saw that, by default, the Image Editing API will cut out the main subject of the input image, position it at the center of the result image, and apply the specified padding around it:

However, if some of the sides of the subject are cropped, then by default the API will not apply any padding to these sides.

The goal of this behavior is to avoid having empty whitespace between the cropped edges of the subject and the edges of the result image:

If you want, you can disable this behavior by setting the parameter ignorePaddingAndSnapOnCroppedSides to false in your API call, which will produce this result:

Margin

In the previous section, we saw that, by default, padding will not be applied to cropped edges and that it's also possible to disable this behavior.

However, there might be situations where you want to keep this behavior, but you also need to always have some amount of empty space between the subject and the border of the result image.

A typical use case would when a background or an overlay will be added to the result image and you want to make sure that this background or overlay will not go over the subject.

This behavior can be implemented through the argument margin.

As with padding, two formats are supported to specify the amount margin:

relative values, expressed in percentages (e.g., 0.2 or 20%)
absolute values, expressed in pixels (e.g., 100px)

Here's an example where padding has been set to 0.1 and margin set to 0.05:

And just like with the padding, it's also possible to set different values for each edge, through the arguments marginLeft, marginRight, marginTop, and marginBottom.

In this example, margin is still set to 0.1 and marginBottom has been set to 0.2:

Reference Box

The referenceBox corresponds to either:

the subjectBox, which is the rectangle around the cutout subject
the originalImage, which is the entire input image

By default, the Image Editing API will:

set the referenceBox to the subjectBox
fit the referenceBox inside the targetArea

However, if you want the cutout subject to retain the position it had in the original image, you can do it by setting the argument referenceBox to originalImage.

Retaining the original position of the subject can be useful when replacing an existing background by a new AI Background.

Horizontal and Vertical Alignments

If needed, it's possible to manually control both the horizontal and vertical alignments of the subject.

Manually controlling the alignment is very useful when you want to position subjects with different aspect ratios is a harmonious way, like here where the subjects have been vertically aligned at the bottom:

Controlling the Horizontal Alignment

To control the horizontal alignment, you need to set the argument horizontalAlignment with one of the following values: left, center or right.