Focal

​

How to use

The focal transformation allows you to specify a focal region or focal point in the image for custom transformations.

Pass one of the following query params to the API endpoint:

focal=AxB:CxD for a focal region

or

focal=X,Y for a focal point

Where:

• A,B are the coordinates of the top-left point of the focal region
• C,D are the coordinates of the bottom-right point of the focal region
• X,Y are the coordinates of the focal point

For example:

• focal=100x100:300x300 (focal region)
• focal=200,150 (focal point)

​

Parameter

focal: Specifies the focal region or point. This parameter accepts two formats:

1. Focal Region: AxB:CxD

   • A,B: Coordinates of the top-left point
   • C,D: Coordinates of the bottom-right point

2. Focal Point: X,Y

   • X,Y: Coordinates of the focal point

Note: The coordinates can be specified in two ways:

• As pixel values (e.g., 100, 200)
• As float values between 0 and 1, representing percentages of image dimensions (e.g., 0.5, 0.75)

​

Effect of Focal Transformation

• Defines a specific area or point of interest in the image.
• Used in conjunction with other transformations to guide how they are applied.
• Useful for intelligent cropping, smart resizing, or applying effects to specific parts of an image.

This transformation is particularly useful when you need to ensure that important parts of an image are preserved or emphasized during other transformations.

​

Original Image

​

Image with Focal Region and Crop

​

Image with Focal Point and Crop

​

Best Practices

• Use focal regions when you want to preserve or emphasize a specific area of the image during transformations.
• Use focal points when you want to center transformations around a specific point in the image.
• When using pixel values, consider the dimensions of your image to ensure the focal area is correctly placed.
• Using percentage values (0 to 1) can be more flexible as they adapt to different image sizes.
• Combine the focal parameter with other transformations like cropping or resizing for more precise control over the final image.

​

Note

The focal transformation by itself does not modify the image. It is used in combination with other transformations (such as cropping or resizing) to guide how they are applied. In the examples above, we’ve combined it with ‘w’ and ‘h’ parameters to demonstrate its effect on cropping.