Cloudinary Object-Aware Cropping

Cloudinary is a cloud-based service that provides solutions for image and video management. These include server or client-side upload, on-the-fly image and video manipulations, fast CDN delivery, and a variety of asset management options.

The Cloudinary Object-Aware Cropping add-on helps to ensure that your image crops keep the specific objects that matter to you, even when you significantly modify the aspect ratio. Cloudinary accomplishes this by applying advanced AI-based object detection algorithms on-the-fly during the crop process. You can either use it in conjunction with auto-gravity to give higher priority to the objects you care about, or directly specify that the crop should be exactly based on the detected coordinates of the specified objects.

Watch this demo to see how the same image is cropped according to the parameters specified in the URL:

Applying object-aware cropping

After registering for the Cloudinary Object-Aware Cropping add-on, you can apply it in one of two ways:

  • Automatic gravity with a high weighting towards a specified object
    This variant of auto-gravity cropping enables you to indicate specific objects or object categories that should be given priority when parts of a photo are cropped out. This is done by specifying an object or an object category as the focal_gravity attribute for the auto gravity parameter (g_auto in URLs) together with a cropping option.

  • Object-specific gravity
    By specifying an object or object category as the gravity parameter (for example, g_cat in URLs) together with a cropping option, you can accurately crop around objects without needing to specify dimensions or aspect ratio.

For example, consider the original image of a kitchen below:

Original

Using auto-gravity, you can deliver a square thumbnail crop that prioritizes the detected coordinates of the sink, microwave, or refrigerator. To do this, specify the relevant object option for the g_auto gravity definition in conjunction with the thumb cropping option:

Ruby:
Copy to clipboard
cl_image_tag("docs/kitchen1.jpg", :width=>600, :aspect_ratio=>"1", :gravity=>"auto:sink", :crop=>"thumb")
PHP:
Copy to clipboard
cl_image_tag("docs/kitchen1.jpg", array("width"=>600, "aspect_ratio"=>"1", "gravity"=>"auto:sink", "crop"=>"thumb"))
Python:
Copy to clipboard
CloudinaryImage("docs/kitchen1.jpg").image(width=600, aspect_ratio="1", gravity="auto:sink", crop="thumb")
Node.js:
Copy to clipboard
cloudinary.image("docs/kitchen1.jpg", {width: 600, aspect_ratio: "1", gravity: "auto:sink", crop: "thumb"})
Java:
Copy to clipboard
cloudinary.url().transformation(new Transformation().width(600).aspectRatio("1").gravity("auto:sink").crop("thumb")).imageTag("docs/kitchen1.jpg");
JS:
Copy to clipboard
cloudinary.imageTag('docs/kitchen1.jpg', {width: 600, aspectRatio: "1", gravity: "auto:sink", crop: "thumb"}).toHtml();
jQuery:
Copy to clipboard
$.cloudinary.image("docs/kitchen1.jpg", {width: 600, aspect_ratio: "1", gravity: "auto:sink", crop: "thumb"})
React:
Copy to clipboard
<Image publicId="docs/kitchen1.jpg" >
  <Transformation width="600" aspectRatio="1" gravity="auto:sink" crop="thumb" />
</Image>
Vue.js:
Copy to clipboard
<cld-image publicId="docs/kitchen1.jpg" >
  <cld-transformation width="600" aspectRatio="1" gravity="auto:sink" crop="thumb" />
</cld-image>
Angular:
Copy to clipboard
<cl-image public-id="docs/kitchen1.jpg" >
  <cl-transformation width="600" aspect-ratio="1" gravity="auto:sink" crop="thumb">
  </cl-transformation>
</cl-image>
.Net:
Copy to clipboard
cloudinary.Api.UrlImgUp.Transform(new Transformation().Width(600).AspectRatio("1").Gravity("auto:sink").Crop("thumb")).BuildImageTag("docs/kitchen1.jpg")
Android:
Copy to clipboard
MediaManager.get().url().transformation(new Transformation().width(600).aspectRatio("1").gravity("auto:sink").crop("thumb")).generate("docs/kitchen1.jpg");
iOS:
Copy to clipboard
imageView.cldSetImage(cloudinary.createUrl().setTransformation(CLDTransformation().setWidth(600).setAspectRatio("1").setGravity("auto:sink").setCrop("thumb")).generate("docs/kitchen1.jpg")!, cloudinary: cloudinary)

g_auto:sink g_auto:sink g_auto:microwave g_auto:microwave g_auto:refrigerator g_auto:refrigerator

Using object-specific gravity, you can choose not to give dimensions or aspect ratio, and deliver an image that is tightly cropped to the object. To do this, specify the relevant object option for the gravity definition in conjunction with the crop cropping option:

Ruby:
Copy to clipboard
cl_image_tag("docs/kitchen1.jpg", :gravity=>"sink", :crop=>"crop")
PHP:
Copy to clipboard
cl_image_tag("docs/kitchen1.jpg", array("gravity"=>"sink", "crop"=>"crop"))
Python:
Copy to clipboard
CloudinaryImage("docs/kitchen1.jpg").image(gravity="sink", crop="crop")
Node.js:
Copy to clipboard
cloudinary.image("docs/kitchen1.jpg", {gravity: "sink", crop: "crop"})
Java:
Copy to clipboard
cloudinary.url().transformation(new Transformation().gravity("sink").crop("crop")).imageTag("docs/kitchen1.jpg");
JS:
Copy to clipboard
cloudinary.imageTag('docs/kitchen1.jpg', {gravity: "sink", crop: "crop"}).toHtml();
jQuery:
Copy to clipboard
$.cloudinary.image("docs/kitchen1.jpg", {gravity: "sink", crop: "crop"})
React:
Copy to clipboard
<Image publicId="docs/kitchen1.jpg" >
  <Transformation gravity="sink" crop="crop" />
</Image>
Vue.js:
Copy to clipboard
<cld-image publicId="docs/kitchen1.jpg" >
  <cld-transformation gravity="sink" crop="crop" />
</cld-image>
Angular:
Copy to clipboard
<cl-image public-id="docs/kitchen1.jpg" >
  <cl-transformation gravity="sink" crop="crop">
  </cl-transformation>
</cl-image>
.Net:
Copy to clipboard
cloudinary.Api.UrlImgUp.Transform(new Transformation().Gravity("sink").Crop("crop")).BuildImageTag("docs/kitchen1.jpg")
Android:
Copy to clipboard
MediaManager.get().url().transformation(new Transformation().gravity("sink").crop("crop")).generate("docs/kitchen1.jpg");
iOS:
Copy to clipboard
imageView.cldSetImage(cloudinary.createUrl().setTransformation(CLDTransformation().setGravity("sink").setCrop("crop")).generate("docs/kitchen1.jpg")!, cloudinary: cloudinary)

g_sink g_sink g_microwave g_microwave g_auto:refrigerator g_refrigerator

You can also specify an aspect ratio together with the crop cropping option, without including specific dimensions. This keeps the object but may show more of the image to fit the aspect ratio.

Ruby:
Copy to clipboard
cl_image_tag("docs/kitchen1.jpg", :gravity=>"sink", :aspect_ratio=>"1", :crop=>"crop")
PHP:
Copy to clipboard
cl_image_tag("docs/kitchen1.jpg", array("gravity"=>"sink", "aspect_ratio"=>"1", "crop"=>"crop"))
Python:
Copy to clipboard
CloudinaryImage("docs/kitchen1.jpg").image(gravity="sink", aspect_ratio="1", crop="crop")
Node.js:
Copy to clipboard
cloudinary.image("docs/kitchen1.jpg", {gravity: "sink", aspect_ratio: "1", crop: "crop"})
Java:
Copy to clipboard
cloudinary.url().transformation(new Transformation().gravity("sink").aspectRatio("1").crop("crop")).imageTag("docs/kitchen1.jpg");
JS:
Copy to clipboard
cloudinary.imageTag('docs/kitchen1.jpg', {gravity: "sink", aspectRatio: "1", crop: "crop"}).toHtml();
jQuery:
Copy to clipboard
$.cloudinary.image("docs/kitchen1.jpg", {gravity: "sink", aspect_ratio: "1", crop: "crop"})
React:
Copy to clipboard
<Image publicId="docs/kitchen1.jpg" >
  <Transformation gravity="sink" aspectRatio="1" crop="crop" />
</Image>
Vue.js:
Copy to clipboard
<cld-image publicId="docs/kitchen1.jpg" >
  <cld-transformation gravity="sink" aspectRatio="1" crop="crop" />
</cld-image>
Angular:
Copy to clipboard
<cl-image public-id="docs/kitchen1.jpg" >
  <cl-transformation gravity="sink" aspect-ratio="1" crop="crop">
  </cl-transformation>
</cl-image>
.Net:
Copy to clipboard
cloudinary.Api.UrlImgUp.Transform(new Transformation().Gravity("sink").AspectRatio("1").Crop("crop")).BuildImageTag("docs/kitchen1.jpg")
Android:
Copy to clipboard
MediaManager.get().url().transformation(new Transformation().gravity("sink").aspectRatio("1").crop("crop")).generate("docs/kitchen1.jpg");
iOS:
Copy to clipboard
imageView.cldSetImage(cloudinary.createUrl().setTransformation(CLDTransformation().setGravity("sink").setAspectRatio("1").setCrop("crop")).generate("docs/kitchen1.jpg")!, cloudinary: cloudinary)

g_sink g_sink g_microwave g_microwave g_auto:refrigerator g_refrigerator

Supported categories and objects

When using the Object-Aware Cropping add-on, you can specify either individual objects or more general object categories.

  • When you specify a category, the algorithm gives priority to any objects that are detected from that category.
  • The regular auto-gravity behavior also impacts the cropping decision. But if requested objects are detected, they get significantly higher priority than the subjects or salient areas that the regular auto-gravity algorithm selects.
  • If you specify the generic object category with auto-gravity (g_auto:object), then any detected objects from any category get priority.
  • If there are multiple objects of the same type in the image, object-specific gravity selects the most prominent of the objects, and bases its crop around only that object, whereas auto-gravity may choose to keep more than one of the objects in the crop.
  • The categories and objects also work in their plural forms when using object-specific gravity. So, for example, c_crop,g_birds keeps all birds in the crop, whereas c_crop,g_bird keeps only the most prominent bird.

The add-on supports two models of objects: Common Objects in Context (COCO) and Google's Open Images Dataset (OID).

  • COCO detects the following categories and objects:

    Category Objects
    person person
    vehicle bicycle, car, motorbike, airplane, bus, train, truck, boat
    outdoor traffic_light, stop_sign, parking_meter, fire_hydrant, bench
    animal bird, cat, dog, horse, sheep, cow, elephant, bear, zebra, giraffe
    accessory backpack, umbrella, handbag, tie, suitcase
    sports frisbee, skis, snowboard, sports_ball, kite, baseball_bat, baseball_glove, skateboard, surfboard, tennis_racket
    kitchen bottle, wine_glass, cup, fork, knife, spoon, bowl
    food banana, apple, sandwich, orange, broccoli, carrot, hotdog, pizza, donut, cake
    furniture chair, sofa, potted_plant, bed, dining_table, toilet
    electronic tv, laptop, mouse, remote, keyboard, cell_phone
    appliance microwave, oven, toaster, sink, refrigerator
    indoor book, clock, vase, scissors, teddy_bear, hair_dryer, toothbrush
    object any object in any subcategory (only supported with auto-gravity)
  • OID detects 600 classes of objects. When referencing these classes, replace any spaces with underscores.

Where categories or objects are detected by both models, the COCO object detection takes precedence. For example, baseball_glove is detected by both models, so g_auto:baseball_glove or g_baseball_glove invokes only the COCO model.

Combining focal gravity options using auto-gravity

When using auto gravity to determine the area to keep in a crop, you can specify multiple focal_gravity options.

This means that in a single auto-gravity parameter, you can optionally specify:

  • One or multiple objects (from the same or different categories)
  • Built-in focal gravity options such as face/faces or custom_no_override
  • Other add-on based focal gravity options, such as the adv_face, adv_eyes options from the Advanced Facial Attributes Detection add-on
  • To apply only the classic or only the subject auto-gravity algorithm, which in some cases may have some impact on the exact coordinates of the crop, even if other specified objects or focal gravity options are detected. Note that the default algorithm, which combines both of these algorithms, is recommended in the majority of cases.

For example, your auto-gravity URL parameter might be: g_auto:cat:sofa:faces:adv_eyes

This would instruct the cropping mechanism to give top priority to any cats, sofas, faces, or eyes detected in the photo.

For a complete list of all focal_gravity options, see the auto section of the gravity parameter in the Image Transformation Reference.

Important

  • The focal gravity options can be specified in any order. The order does not impact the result.
  • When multiple items are detected that match the requested focal options, larger, more central, and more in-focus (less blurry) objects will get higher priority.
    In special cases, it's possible to fine-tune this default prioritization further. For details, contact support.
  • If a particular image has custom coordinates defined, those coordinates always override all other focal gravity options, unless you use the custom_no_override option in conjunction with the other options.

Combining focal gravity options using object-specific gravity

When using object-specific gravity to determine the area to keep in a crop, you can specify multiple focal_gravity options, but unlike auto-gravity, the order in which they are specified has an impact on the delivered image.

For example, consider this photo of a cat and dog:

Original

By setting the gravity parameter to cat:dog the cat gets precedence:

Ruby:
Copy to clipboard
cl_image_tag("docs/one_cat_one_dog.jpg", :gravity=>"cat:dog", :crop=>"crop")
PHP:
Copy to clipboard
cl_image_tag("docs/one_cat_one_dog.jpg", array("gravity"=>"cat:dog", "crop"=>"crop"))
Python:
Copy to clipboard
CloudinaryImage("docs/one_cat_one_dog.jpg").image(gravity="cat:dog", crop="crop")
Node.js:
Copy to clipboard
cloudinary.image("docs/one_cat_one_dog.jpg", {gravity: "cat:dog", crop: "crop"})
Java:
Copy to clipboard
cloudinary.url().transformation(new Transformation().gravity("cat:dog").crop("crop")).imageTag("docs/one_cat_one_dog.jpg");
JS:
Copy to clipboard
cloudinary.imageTag('docs/one_cat_one_dog.jpg', {gravity: "cat:dog", crop: "crop"}).toHtml();
jQuery:
Copy to clipboard
$.cloudinary.image("docs/one_cat_one_dog.jpg", {gravity: "cat:dog", crop: "crop"})
React:
Copy to clipboard
<Image publicId="docs/one_cat_one_dog.jpg" >
  <Transformation gravity="cat:dog" crop="crop" />
</Image>
Vue.js:
Copy to clipboard
<cld-image publicId="docs/one_cat_one_dog.jpg" >
  <cld-transformation gravity="cat:dog" crop="crop" />
</cld-image>
Angular:
Copy to clipboard
<cl-image public-id="docs/one_cat_one_dog.jpg" >
  <cl-transformation gravity="cat:dog" crop="crop">
  </cl-transformation>
</cl-image>
.Net:
Copy to clipboard
cloudinary.Api.UrlImgUp.Transform(new Transformation().Gravity("cat:dog").Crop("crop")).BuildImageTag("docs/one_cat_one_dog.jpg")
Android:
Copy to clipboard
MediaManager.get().url().transformation(new Transformation().gravity("cat:dog").crop("crop")).generate("docs/one_cat_one_dog.jpg");
iOS:
Copy to clipboard
imageView.cldSetImage(cloudinary.createUrl().setTransformation(CLDTransformation().setGravity("cat:dog").setCrop("crop")).generate("docs/one_cat_one_dog.jpg")!, cloudinary: cloudinary)

g_cat:dog

Whereas, if you switch the order to dog:cat the dog gets precedence:

Ruby:
Copy to clipboard
cl_image_tag("docs/one_cat_one_dog.jpg", :gravity=>"dog:cat", :crop=>"crop")
PHP:
Copy to clipboard
cl_image_tag("docs/one_cat_one_dog.jpg", array("gravity"=>"dog:cat", "crop"=>"crop"))
Python:
Copy to clipboard
CloudinaryImage("docs/one_cat_one_dog.jpg").image(gravity="dog:cat", crop="crop")
Node.js:
Copy to clipboard
cloudinary.image("docs/one_cat_one_dog.jpg", {gravity: "dog:cat", crop: "crop"})
Java:
Copy to clipboard
cloudinary.url().transformation(new Transformation().gravity("dog:cat").crop("crop")).imageTag("docs/one_cat_one_dog.jpg");
JS:
Copy to clipboard
cloudinary.imageTag('docs/one_cat_one_dog.jpg', {gravity: "dog:cat", crop: "crop"}).toHtml();
jQuery:
Copy to clipboard
$.cloudinary.image("docs/one_cat_one_dog.jpg", {gravity: "dog:cat", crop: "crop"})
React:
Copy to clipboard
<Image publicId="docs/one_cat_one_dog.jpg" >
  <Transformation gravity="dog:cat" crop="crop" />
</Image>
Vue.js:
Copy to clipboard
<cld-image publicId="docs/one_cat_one_dog.jpg" >
  <cld-transformation gravity="dog:cat" crop="crop" />
</cld-image>
Angular:
Copy to clipboard
<cl-image public-id="docs/one_cat_one_dog.jpg" >
  <cl-transformation gravity="dog:cat" crop="crop">
  </cl-transformation>
</cl-image>
.Net:
Copy to clipboard
cloudinary.Api.UrlImgUp.Transform(new Transformation().Gravity("dog:cat").Crop("crop")).BuildImageTag("docs/one_cat_one_dog.jpg")
Android:
Copy to clipboard
MediaManager.get().url().transformation(new Transformation().gravity("dog:cat").crop("crop")).generate("docs/one_cat_one_dog.jpg");
iOS:
Copy to clipboard
imageView.cldSetImage(cloudinary.createUrl().setTransformation(CLDTransformation().setGravity("dog:cat").setCrop("crop")).generate("docs/one_cat_one_dog.jpg")!, cloudinary: cloudinary)

g_dog:cat

You can also combine the auto option to invoke the auto-gravity algorithm if none of the specified objects are found. For example:

  • g_dog:cat:auto - auto-gravity is invoked only if no dogs and cats are detected.
  • g_dog:auto:cat - auto-gravity weighted by cat (g_auto:cat) is invoked if no dogs are detected.

Important
If you use the auto option then you also need to specify at least one dimension parameter (width or height).

For example, consider this photo of a cat and three birds:

Original

As there is no dog in the photo, auto-gravity weighted by bird is invoked when using dog:auto:bird. In this case, two birds are kept in the crop:

Ruby:
Copy to clipboard
cl_image_tag("docs/cat_and_birds.jpg", :gravity=>"dog:auto:bird", :width=>600, :height=>800, :crop=>"crop")
PHP:
Copy to clipboard
cl_image_tag("docs/cat_and_birds.jpg", array("gravity"=>"dog:auto:bird", "width"=>600, "height"=>800, "crop"=>"crop"))
Python:
Copy to clipboard
CloudinaryImage("docs/cat_and_birds.jpg").image(gravity="dog:auto:bird", width=600, height=800, crop="crop")
Node.js:
Copy to clipboard
cloudinary.image("docs/cat_and_birds.jpg", {gravity: "dog:auto:bird", width: 600, height: 800, crop: "crop"})
Java:
Copy to clipboard
cloudinary.url().transformation(new Transformation().gravity("dog:auto:bird").width(600).height(800).crop("crop")).imageTag("docs/cat_and_birds.jpg");
JS:
Copy to clipboard
cloudinary.imageTag('docs/cat_and_birds.jpg', {gravity: "dog:auto:bird", width: 600, height: 800, crop: "crop"}).toHtml();
jQuery:
Copy to clipboard
$.cloudinary.image("docs/cat_and_birds.jpg", {gravity: "dog:auto:bird", width: 600, height: 800, crop: "crop"})
React:
Copy to clipboard
<Image publicId="docs/cat_and_birds.jpg" >
  <Transformation gravity="dog:auto:bird" width="600" height="800" crop="crop" />
</Image>
Vue.js:
Copy to clipboard
<cld-image publicId="docs/cat_and_birds.jpg" >
  <cld-transformation gravity="dog:auto:bird" width="600" height="800" crop="crop" />
</cld-image>
Angular:
Copy to clipboard
<cl-image public-id="docs/cat_and_birds.jpg" >
  <cl-transformation gravity="dog:auto:bird" width="600" height="800" crop="crop">
  </cl-transformation>
</cl-image>
.Net:
Copy to clipboard
cloudinary.Api.UrlImgUp.Transform(new Transformation().Gravity("dog:auto:bird").Width(600).Height(800).Crop("crop")).BuildImageTag("docs/cat_and_birds.jpg")
Android:
Copy to clipboard
MediaManager.get().url().transformation(new Transformation().gravity("dog:auto:bird").width(600).height(800).crop("crop")).generate("docs/cat_and_birds.jpg");
iOS:
Copy to clipboard
imageView.cldSetImage(cloudinary.createUrl().setTransformation(CLDTransformation().setGravity("dog:auto:bird").setWidth(600).setHeight(800).setCrop("crop")).generate("docs/cat_and_birds.jpg")!, cloudinary: cloudinary)

g_auto:bird

Notice that if auto-gravity is not specified, the object-specific algorithm chooses the most prominent bird out of the three and only keeps this bird in the crop:

Ruby:
Copy to clipboard
cl_image_tag("docs/cat_and_birds.jpg", :gravity=>"dog:bird", :width=>600, :height=>800, :crop=>"crop")
PHP:
Copy to clipboard
cl_image_tag("docs/cat_and_birds.jpg", array("gravity"=>"dog:bird", "width"=>600, "height"=>800, "crop"=>"crop"))
Python:
Copy to clipboard
CloudinaryImage("docs/cat_and_birds.jpg").image(gravity="dog:bird", width=600, height=800, crop="crop")
Node.js:
Copy to clipboard
cloudinary.image("docs/cat_and_birds.jpg", {gravity: "dog:bird", width: 600, height: 800, crop: "crop"})
Java:
Copy to clipboard
cloudinary.url().transformation(new Transformation().gravity("dog:bird").width(600).height(800).crop("crop")).imageTag("docs/cat_and_birds.jpg");
JS:
Copy to clipboard
cloudinary.imageTag('docs/cat_and_birds.jpg', {gravity: "dog:bird", width: 600, height: 800, crop: "crop"}).toHtml();
jQuery:
Copy to clipboard
$.cloudinary.image("docs/cat_and_birds.jpg", {gravity: "dog:bird", width: 600, height: 800, crop: "crop"})
React:
Copy to clipboard
<Image publicId="docs/cat_and_birds.jpg" >
  <Transformation gravity="dog:bird" width="600" height="800" crop="crop" />
</Image>
Vue.js:
Copy to clipboard
<cld-image publicId="docs/cat_and_birds.jpg" >
  <cld-transformation gravity="dog:bird" width="600" height="800" crop="crop" />
</cld-image>
Angular:
Copy to clipboard
<cl-image public-id="docs/cat_and_birds.jpg" >
  <cl-transformation gravity="dog:bird" width="600" height="800" crop="crop">
  </cl-transformation>
</cl-image>
.Net:
Copy to clipboard
cloudinary.Api.UrlImgUp.Transform(new Transformation().Gravity("dog:bird").Width(600).Height(800).Crop("crop")).BuildImageTag("docs/cat_and_birds.jpg")
Android:
Copy to clipboard
MediaManager.get().url().transformation(new Transformation().gravity("dog:bird").width(600).height(800).crop("crop")).generate("docs/cat_and_birds.jpg");
iOS:
Copy to clipboard
imageView.cldSetImage(cloudinary.createUrl().setTransformation(CLDTransformation().setGravity("dog:bird").setWidth(600).setHeight(800).setCrop("crop")).generate("docs/cat_and_birds.jpg")!, cloudinary: cloudinary)

g_bird

Specifying objects to avoid using auto-gravity

In addition to specifying objects to keep in an image, you can specify objects that you would rather not see. To minimize the likelihood of including a particular object in the cropped image, use auto-gravity with the avoid option for the relevant object or category.

For example, in photos like the one below, you may prefer not to include people because the purpose of the photo is to show an interesting store front, and the people are a distraction.

Original

Using g_auto by itself makes the people the focal point, but if we use g_auto:person_avoid, the other side of the photo is shown, without the people.

Ruby:
Copy to clipboard
cl_image_tag("docs/store_front.jpg", :width=>500, :aspect_ratio=>"1.0", :gravity=>"auto:person_avoid", :crop=>"fill")
PHP:
Copy to clipboard
cl_image_tag("docs/store_front.jpg", array("width"=>500, "aspect_ratio"=>"1.0", "gravity"=>"auto:person_avoid", "crop"=>"fill"))
Python:
Copy to clipboard
CloudinaryImage("docs/store_front.jpg").image(width=500, aspect_ratio="1.0", gravity="auto:person_avoid", crop="fill")
Node.js:
Copy to clipboard
cloudinary.image("docs/store_front.jpg", {width: 500, aspect_ratio: "1.0", gravity: "auto:person_avoid", crop: "fill"})
Java:
Copy to clipboard
cloudinary.url().transformation(new Transformation().width(500).aspectRatio("1.0").gravity("auto:person_avoid").crop("fill")).imageTag("docs/store_front.jpg");
JS:
Copy to clipboard
cloudinary.imageTag('docs/store_front.jpg', {width: 500, aspectRatio: "1.0", gravity: "auto:person_avoid", crop: "fill"}).toHtml();
jQuery:
Copy to clipboard
$.cloudinary.image("docs/store_front.jpg", {width: 500, aspect_ratio: "1.0", gravity: "auto:person_avoid", crop: "fill"})
React:
Copy to clipboard
<Image publicId="docs/store_front.jpg" >
  <Transformation width="500" aspectRatio="1.0" gravity="auto:person_avoid" crop="fill" />
</Image>
Vue.js:
Copy to clipboard
<cld-image publicId="docs/store_front.jpg" >
  <cld-transformation width="500" aspectRatio="1.0" gravity="auto:person_avoid" crop="fill" />
</cld-image>
Angular:
Copy to clipboard
<cl-image public-id="docs/store_front.jpg" >
  <cl-transformation width="500" aspect-ratio="1.0" gravity="auto:person_avoid" crop="fill">
  </cl-transformation>
</cl-image>
.Net:
Copy to clipboard
cloudinary.Api.UrlImgUp.Transform(new Transformation().Width(500).AspectRatio("1.0").Gravity("auto:person_avoid").Crop("fill")).BuildImageTag("docs/store_front.jpg")
Android:
Copy to clipboard
MediaManager.get().url().transformation(new Transformation().width(500).aspectRatio("1.0").gravity("auto:person_avoid").crop("fill")).generate("docs/store_front.jpg");
iOS:
Copy to clipboard
imageView.cldSetImage(cloudinary.createUrl().setTransformation(CLDTransformation().setWidth(500).setAspectRatio("1.0").setGravity("auto:person_avoid").setCrop("fill")).generate("docs/store_front.jpg")!, cloudinary: cloudinary)

g_auto g_auto g_auto:person_avoid g_auto:person_avoid

Choosing the cropping mode

When you specify an object, either specifically or in your auto-gravity parameter, the Object-Aware Cropping AI algorithm detects the coordinates of the object and those coordinates are used by the cropping mode.

  • When using thumb cropping (c_thumb), the image is cropped as closely as possible to the detected coordinates of the object given the requested aspect ratio, and then scaled to the requested pixel size. Note that if the requested pixel size is greater than the crop, the image is not scaled up, but filled with further pixels from the image.

  • When using crop mode (c_crop), the detected coordinates are prioritized as the area to keep when determining how much to cut from each edge of the photo in order to achieve the requested pixel size. If using auto-gravity and the requested pixel size is larger than the coordinates of the detected object, other elements of the image that receive priority from g_auto may impact what else is included in the photo and where in your resulting image the detected object may be located, meaning that the detected object will not necessarily be the center of the photo.

  • When using any of the fill-based modes (c_fill, c_lfill, c_fill_pad), the coordinates of the detected object should be retained if any cropping is required after scaling. If using auto-gravity, other elements of the image that receive priority from g_auto may impact what else is included in the photo and where in your resulting image the detected object may be located, meaning that the detected object will not necessarily be the center of the photo.

The following examples show how different your cropping results may be for the same requested object in the gravity, but with different cropping modes. In this case, we take the original photo below and apply g_auto:bottle and g_bottle with fill, crop, and thumb cropping modes. In all cases, the same width and aspect ratio are requested.

Original Original

 

g_auto:bottle

c_fill c_fill c_crop c_crop c_thumb c_thumb

g_bottle

c_fill c_fill c_crop c_crop c_thumb c_thumb

Using object-aware cropping for responsive delivery

You can take advantage of object-aware cropping with various cropping modes to assist in responsive art direction. This means that when you deliver different sized images to different devices, you don't just scale the same image, but rather crop images differently for different sizes, so that the important objects are always highly visible.

For example, you may:

  • deliver a full-size image to large HD screens
  • use g_auto:[your_important_object], or g_[your_important_object] with fill cropping for medium sized screens
  • use g_auto:[your_important_object], or g_[your_important_object] with thumb cropping for very small screens.

For more details on delivering responsive images, see the Responsive images guide.

Signed URLs

Cloudinary's dynamic image manipulation URLs are powerful tools. However, due to the potential costs of your customers experimenting with dynamic URLs that apply the object-aware cropping algorithm, image manipulation add-on URLs are required (by default) to be signed using Cloudinary's authenticated API. Alternatively, you can eagerly generate the requested derived images using Cloudinary's authenticated API.

To create a signed delivery URL, set the sign_url parameter to true when building a URL or creating an image tag.

The following code example applies object-aware cropping to the skater image, including a signed Cloudinary URL:

Ruby:
Copy to clipboard
cl_image_tag("Skater.jpg", :width=>400, :aspect_ratio=>"1", :gravity=>"auto:skateboard", :crop=>"thumb", :sign_url=>true)
PHP:
Copy to clipboard
cl_image_tag("Skater.jpg", array("width"=>400, "aspect_ratio"=>"1", "gravity"=>"auto:skateboard", "crop"=>"thumb", "sign_url"=>true))
Python:
Copy to clipboard
CloudinaryImage("Skater.jpg").image(width=400, aspect_ratio="1", gravity="auto:skateboard", crop="thumb", sign_url=True)
Node.js:
Copy to clipboard
cloudinary.image("Skater.jpg", {width: 400, aspect_ratio: "1", gravity: "auto:skateboard", crop: "thumb", sign_url: true})
Java:
Copy to clipboard
cloudinary.url().transformation(new Transformation().width(400).aspectRatio("1").gravity("auto:skateboard").crop("thumb")).signed(true).imageTag("Skater.jpg");
JS:
Copy to clipboard
cloudinary.imageTag('Skater.jpg', {width: 400, aspectRatio: "1", gravity: "auto:skateboard", crop: "thumb", signUrl: true}).toHtml();
jQuery:
Copy to clipboard
$.cloudinary.image("Skater.jpg", {width: 400, aspect_ratio: "1", gravity: "auto:skateboard", crop: "thumb"})
React:
Copy to clipboard
<Image publicId="Skater.jpg" signUrl="true">
  <Transformation width="400" aspectRatio="1" gravity="auto:skateboard" crop="thumb" />
</Image>
Vue.js:
Copy to clipboard
<cld-image publicId="Skater.jpg" signUrl="true">
  <cld-transformation width="400" aspectRatio="1" gravity="auto:skateboard" crop="thumb" />
</cld-image>
Angular:
Copy to clipboard
<cl-image public-id="Skater.jpg" sign-url="true">
  <cl-transformation width="400" aspect-ratio="1" gravity="auto:skateboard" crop="thumb">
  </cl-transformation>
</cl-image>
.Net:
Copy to clipboard
cloudinary.Api.UrlImgUp.Transform(new Transformation().Width(400).AspectRatio("1").Gravity("auto:skateboard").Crop("thumb")).Signed(true).BuildImageTag("Skater.jpg")
Android:
Copy to clipboard
MediaManager.get().url().transformation(new Transformation().width(400).aspectRatio("1").gravity("auto:skateboard").crop("thumb")).signed(true).generate("Skater.jpg");
iOS:
Copy to clipboard
imageView.cldSetImage(cloudinary.createUrl().setTransformation(CLDTransformation().setWidth(400).setAspectRatio("1").setGravity("auto:skateboard").setCrop("thumb")).generate("Skater.jpg", signUrl: true)!, cloudinary: cloudinary)

The generated Cloudinary URL shown below includes a signature component (/s--acvfjq2y--/). Only URLs with a valid signature that matches the requested image manipulation will be approved for on-the-fly image manipulation and delivery.

Copy to clipboard
https://res.cloudinary.com/my_cloud/image/upload/s--acvfjq2y--/w_400,ar_1,c_thumb,g_auto:skateboard/Skater.jpg

For more details on signed URLs, see Signed delivery URLs.

Note
You can optionally remove the signed URL default requirement for a particular add-on by selecting that add-on in the Allow unsigned add-on transformations section of the Security account settings in the Cloudinary console.