# 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`](#reference-box) inside the [`targetArea`](#target-area).
Original ImageResult Image
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](#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%)
{% hint style="warning" %} 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`) {% endhint %} ## 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:
{% hint style="warning" %} Snapping cropped edges to the side of the result image will only happen when a single edge has been cropped for a given direction. Here are some examples: * if the left edge of the subject is cropped: * snapping will happen for the horizontal direction and the subject will be snapped to the left edge of the result image * snapping will not happen for the vertical direction and the subject will be centered vertically in the result image * if the left and right edges of the subject are cropped * snapping will not happen for the horizontal dimension and the subject will be centered horizontally in the result image * snapping will not happen for the vertical dimension and the subject will be centered vertically in the result image * if the top and bottom edges of the subject are cropped: * snapping will not happen for the horizontal dimension and the subject will be centered horizontally in the result image * snapping will not happen for the vertical dimension and the subject will be centered vertically in the result image * if the left and top edges of the subject are cropped: * snapping will happen for the horizontal direction and the subject will be snapped to the left edge of the result image * snapping will happen for the vertical direction and the subject will be snapped to the top edge of the result image * if the left, top and right edges of the subject are cropped: * snapping will not happen for the horizontal dimension and the subject will be centered horizontally in the result image * snapping will happen for the vertical direction and the subject will be snapped to the top edge of the result image {% endhint %} 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`.
(original image)referenceBox=subjectBox
(default value)		referenceBox=originalImage
{% hint style="info" %} Retaining the original position of the subject can be useful when replacing an existing background by a new [AI Background](https://docs.photoroom.com/image-editing-api-plus-plan/ai-backgrounds). {% endhint %} ## Horizontal and Vertical Alignments If needed, it's possible to manually control both the horizontal and vertical alignments of the subject. {% hint style="info" %} 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: ![](https://2855892273-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1SYxn7dWbQYsNtUdJE3f%2Fuploads%2FuTYrXOFuQBHxKnPpjreq%2FGroup.png?alt=media\&token=787aaa30-24d9-451f-9f87-535efdae3a94) {% endhint %} ### 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`.
horizontalAlignment=lefthorizontalAlignment=centerhorizontalAlignment=right
### Controlling the Vertical Alignment To control the horizontal alignment, you need to set the argument `verticalAlignment` with one of the following values: `top`, `center` or `bottom`.
verticalAlignment=topverticalAlignment=centerverticalAlignment=bottom
--- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.photoroom.com/image-editing-api-plus-plan/positioning.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.