How to offset face-detection gravity when cropping

When using g_face gravity with cropping modes like c_crop, you might expect the x and y parameters to offset the crop position relative to the detected face. In practice, x and y with c_crop,g_face have no positional effect. The face stays centered regardless of the values you specify.

This article explains why this happens and provides two workarounds: using the zoom parameter for simple adjustments, and using a two-step crop for precise directional control.

Why x and y don't offset g_face

With c_crop, the x and y parameters set fixed coordinates for the top-left corner of the crop rectangle. When you also set g_face, the gravity and the explicit coordinates conflict. In practice, the x and y values don't offset the crop relative to the detected face. Regardless of the values you specify, the face stays in the same position.

For example, this transformation crops around the detected face:

Adding x_50,y_50 or x_200,y_200 to the same transformation doesn't shift the crop from the face. The face stays centered because g_face determines the crop position and the x/y values have no positional effect:

For details on how x and y work with c_crop, see fixed coordinates cropping.

Adjusting crop tightness with zoom

To control how tightly the crop frames the face without shifting its position, combine z (zoom) with c_crop,g_face. Zoom has a visible effect when you omit explicit width and height, or when you set only an aspect ratio with ar. If you pin both w and h on c_crop, zoom has no effect. As a resolution-independent alternative, z also works with c_thumb,g_face even when w and h are set.

Values less than 1.0 zoom out, showing more context around the face. Values greater than 1.0 zoom in for a tighter crop.

With c_crop and an aspect ratio

Using ar_1.0 lets you keep a square crop while z adjusts how much surrounding area the crop includes:

Default zoom (ar_1.0,c_crop,g_face):

Zoomed out (ar_1.0,c_crop,g_face,z_0.5):

Zoomed in (ar_1.0,c_crop,g_face,z_1.5):

With c_thumb for resolution-independent sizing

When you need a specific output size that's the same across source images of different resolutions, use c_thumb. z keeps working even with w and h set:

Default zoom (c_thumb,g_face,h_300,w_300):

Zoomed in (c_thumb,g_face,h_300,w_300,z_2.0):

For more details, see c_crop, c_thumb, and z (zoom) in the Transformation Reference.

Nudging the face position with a two-step crop

If you need precise directional control over where the face appears in the final image, use a two-step crop:

1. First step: Use c_thumb with g_face and dimensions larger than your target size. c_thumb scales the cropped region proportionally to the detected face, so the technique produces consistent results across source images of different resolutions.
2. Second step: Apply a c_crop with x and y to shift the crop window within the region from step 1.

Because the second c_crop operates on the already-cropped intermediate image, x and y now work as expected since there's no gravity to conflict with.

Direction guide

In the second crop step, x and y set the top-left corner of the final crop rectangle within the intermediate image:

• Increasing x: Moves the crop window to the right, which shifts the face to the left in the output.
• Increasing y: Moves the crop window down, which shifts the face upward in the output.

Example

First extract a 600 × 600 region proportional to the detected face, then crop a 400 × 400 region with different offsets:

x=0, y=0 (top-left of the face region):

x=150, y=0 (face shifted left):

x=0, y=150 (face shifted up):

Tips

• Make the first crop dimensions large enough to give the second step room to adjust. If the first crop is too tight, there's no space to nudge.
• The difference between the first and second crop dimensions determines how far you can shift. For example, a 600 × 600 first crop with a 400 × 400 second crop allows up to 200 pixels of adjustment in each direction.
• Experiment with the x and y values to find the right positioning for your image.

Focusing on objects other than faces

If your images feature subjects other than people (products, animals, or specific objects), substitute g_face with object-detection gravity from the Cloudinary AI Content Analysis add-on. Use g_auto:<object> (for example g_auto:cat), or even g_<object> (for example g_cat), with any of the techniques above to center and nudge the crop around that subject.