Automatic gravity for image crops

Automatic gravity (g_auto) uses AI to identify the most visually important areas of an image and keeps them in frame when you crop or resize. This page covers how to configure automatic gravity, adjust its focal preferences, select between algorithms, and use the rule of thirds principle.

How automatic gravity works

Cloudinary's intelligent gravity selection capabilities ensure that the most interesting areas of each image are selected as the main focus for the requested crop, not only for photos with faces, but for any content type. Each image is analyzed individually to find the optimal region to include while cropping. Automatically detected faces (or other elements) are, by default, given higher priority while analyzing the image content.

You apply automatic content-aware gravity by setting the gravity transformation parameter to auto (g_auto in URLs).

Here's an example of using automatic gravity when changing the aspect ratio of an image:

Original c_fill,g_center,h_300,w_200
Regular fill c_fill,g_auto,h_300,w_200
Automatic fill

Automatic gravity for crops is supported for the fill, lfill, fill_pad, thumb, crop and auto modes.

Adjusting the automatic gravity focal preference

By default, both the saliency and subject automatic gravity algorithms give increased priority to detected faces. To adjust the focal preference of the automatic gravity algorithm, you can specify a different focal_gravity option.

To adjust the focal preference for automatic gravity:

1. Set the crop mode to a cropping mode that supports automatic gravity (such as fill, lfill, fill_pad, thumb, crop, or auto).
2. Set the gravity to auto with a specific focal preference, for example:
   • g_auto:faces - Prioritize faces (default)
   • g_auto:hat - Prioritize hats (requires Cloudinary AI Content Analysis add-on)
   • g_auto:ocr_text - Prioritize text (requires OCR Text Detection and Extraction Add-on)
   • Or any other focal gravity option
3. Specify your desired dimensions.

For example, if you are registered to the Cloudinary AI Content Analysis add-on, you can instruct the gravity algorithm to give top priority to one or more specific objects or categories from an extensive list.

In this example, give top priority to any hat in the picture (g_auto:hat), while taking other elements of the picture into account (for example, the face):

Original ar_1:1,c_auto,g_auto:hat,w_400
Focus on the hat

The OCR Text Detection and Extraction Add-on lets you give a higher priority to text by setting the gravity qualifier to auto:ocr_text, while also giving priority to faces and other very prominent elements of an image.

Original ar_1.1,c_crop,g_auto:ocr_text,w_300
Focus on the text

For a complete list of all focal_gravity options, see the g_<special_position> section of the Transformation URL API Reference.

Automatic gravity with the fill mode

Use the fill mode with automatic gravity to keep most of the original image according to the requested dimensions of the derived image, ensuring that the most interesting regions of the original image are included in the resulting image.

Example of square aspect ratio cropping, regular vs. automatic:

Original c_fill,g_center,h_200,w_200
Regular fill c_fill,g_auto,h_200,w_200
Automatic fill

Automatic gravity with the thumb mode

Use the thumb mode with automatic gravity to apply more aggressive cropping than the fill mode. This mode attempts to further zoom in and crop out less interesting image regions when relevant in order to include the most interesting objects in the resulting derived image. The automatic cropping algorithm decides whether and how aggressively to zoom in and crop according to the content and cropping ratio of each image individually. A numerical value between 0 and 100 can be added to the g_auto parameter in order to advise the algorithm regarding the desired aggressiveness level (e.g., g_auto:0 for the most aggressive thumb cropping).

Example of a square thumbnail, regular vs. automatic cropping:

Original c_thumb,g_center
Regular thumbnail
c_thumb,g_auto
Automatic thumbnail
c_thumb,g_auto:0
Automatic thumbnail -
most aggressive

Automatic gravity with the crop mode

Use the crop mode with automatic gravity to crop a region of exactly the specified dimensions out of the original image while automatically focusing on the most interesting region of the original image that fits within the required dimensions. The portion of the interesting area depends on the resolution of the original image. The crop mode is less useful than the fill, lfill, and thumb modes, as it is only practical to use when both the dimensions of the original image and the size of the interesting region are already known.

Example of a square crop, regular vs. auto cropping:

Original c_crop,g_center
Regular crop
c_crop,g_auto
Automatic crop

Automatic gravity with the auto cropping mode

For maximum automation, use the automatic crop mode (c_auto) with automatic gravity (g_auto). This is less aggressive than automatic gravity with the thumb mode, and is smarter about what to keep than automatic gravity with the fill mode.

c_fill,g_auto
Fill crop
c_thumb,g_auto
Thumbnail crop
c_auto,g_auto
Automatic crop

The rule of thirds

The rule of thirds is a fundamental principle in photography and visual composition. It involves dividing an image into nine equal parts by two equally spaced horizontal lines and two equally spaced vertical lines. Key elements and points of interest in the scene are then positioned along these lines or at their intersections, rather than in the center of the frame. This technique helps create balance, draw the viewer's eye to important parts of the photo, and make the composition more dynamic and engaging.

By default, automatic gravity follows the rule of thirds principle. If you want to disable this functionality because you specifically want to center important elements, you can adjust the gravity setting.

To disable the rule of thirds and center important elements:

1. Set the crop mode to a cropping mode that supports automatic gravity (such as fill, thumb, crop, or auto).
2. Set the gravity to auto:thirds_0 (g_auto:thirds_0 in URLs).
3. Specify your desired dimensions.

See the difference when cropping this image to a square:

Original

Default algorithm Rule of thirds disabled

Selecting a single automatic gravity algorithm

The default g_auto option applies an optimal mixture of two different methods of identifying the most important region of your image:

• AI-based algorithm (subject) - Uses deep-learning algorithms to identify the subjects of an image that are most likely to attract a person's gaze.
• Saliency algorithm (classic) - Uses a combination of saliency heuristics, edge detection, light, skin-tone prioritization, and more to automatically detect and prioritize significant region(s) in the image.

In the majority of cases, the most salient elements in an image are also the main subjects of the photo, and thus both algorithms often produce very similar or identical results. However, in some cases, results can be somewhat different and therefore the weighted mixture that g_auto applies by default usually gives the best results.

If you find that for the types of images you are delivering, one of the algorithms consistently gives a better result than the other, you can override the default combined mechanism and explicitly request your preferred algorithm.

To select a specific automatic gravity algorithm:

1. Set the crop mode to a cropping mode that supports automatic gravity (such as fill, lfill, fill_pad, thumb, crop, or auto).
2. Set the gravity to either:
   • auto:subject (g_auto:subject in URLs) - Use only the AI-based algorithm
   • auto:classic (g_auto:classic in URLs) - Use only the saliency algorithm
3. Optionally, you can also specify an additional focal gravity option (e.g., g_auto:subject:faces).
4. Specify your desired dimensions.

For example, when cropping the landscape image below to a portrait view, the classic algorithm selects the areas with the most graphically salient spots, which includes the colorful garden in the south east corner, while the subject algorithm focuses on the subjects that the AI-engine predicts are most likely to capture human attention, primarily the tower, cloud and fountains.

Original image

Default crop
(Center gravity) Auto-gravity
Saliency (classic) method Auto-gravity
AI-based subject method