Cloudinary provides face detection algorithms for automatically applying transformations according to the detected faces within an image.
If you find that any of the features described below do not give desired results,
contact our support team who can enable a more aggressive face detection algorithm for you to try.
Cloudinary supports built-in face detection capabilities that allow you to intelligently crop your images. To automatically crop an image so that the detected face(s) is used as the center of the derived picture, set the gravity
parameter to one of the following values:
face
- the region of the image that includes the single largest face (g_face
for URLs).
faces
- the region of the image that includes all the faces detected (g_faces
for URLs).
For example, the image below of a nice woman with a Blue Morpho butterfly was uploaded to Cloudinary:
Ruby:
cl_image_tag("butterfly.jpg")
PHP:
cl_image_tag("butterfly.jpg")
Python:
CloudinaryImage("butterfly.jpg").image()
Node.js:
cloudinary.image("butterfly.jpg")
Java:
cloudinary.url().imageTag("butterfly.jpg");
JS:
cloudinary.imageTag('butterfly.jpg').toHtml();
jQuery:
$.cloudinary.image("butterfly.jpg")
React:
<Image publicId="butterfly.jpg" >
</Image>
Vue.js:
<cld-image publicId="butterfly.jpg" >
</cld-image>
Angular:
<cl-image public-id="butterfly.jpg" >
</cl-image>
.NET:
cloudinary.Api.UrlImgUp.BuildImageTag("butterfly.jpg")
Android:
MediaManager.get().url().generate("butterfly.jpg");
iOS:
imageView.cldSetImage(cloudinary.createUrl().generate("butterfly.jpg")!, cloudinary: cloudinary)
To create a 200x200 version with the fill cropping mode to keep as much as possible of the original image, and using the default center
gravity without face detection (for comparison):
Ruby:
cl_image_tag("butterfly.jpg", :width=>200, :height=>200, :crop=>"fill")
PHP:
cl_image_tag("butterfly.jpg", array("width"=>200, "height"=>200, "crop"=>"fill"))
Python:
CloudinaryImage("butterfly.jpg").image(width=200, height=200, crop="fill")
Node.js:
cloudinary.image("butterfly.jpg", {width: 200, height: 200, crop: "fill"})
Java:
cloudinary.url().transformation(new Transformation().width(200).height(200).crop("fill")).imageTag("butterfly.jpg");
JS:
cloudinary.imageTag('butterfly.jpg', {width: 200, height: 200, crop: "fill"}).toHtml();
jQuery:
$.cloudinary.image("butterfly.jpg", {width: 200, height: 200, crop: "fill"})
React:
<Image publicId="butterfly.jpg" >
<Transformation width="200" height="200" crop="fill" />
</Image>
Vue.js:
<cld-image publicId="butterfly.jpg" >
<cld-transformation width="200" height="200" crop="fill" />
</cld-image>
Angular:
<cl-image public-id="butterfly.jpg" >
<cl-transformation width="200" height="200" crop="fill">
</cl-transformation>
</cl-image>
.NET:
cloudinary.Api.UrlImgUp.Transform(new Transformation().Width(200).Height(200).Crop("fill")).BuildImageTag("butterfly.jpg")
Android:
MediaManager.get().url().transformation(new Transformation().width(200).height(200).crop("fill")).generate("butterfly.jpg");
iOS:
imageView.cldSetImage(cloudinary.createUrl().setTransformation(CLDTransformation().setWidth(200).setHeight(200).setCrop("fill")).generate("butterfly.jpg")!, cloudinary: cloudinary)
Now adding the face
gravity parameter to correctly fill the requested dimensions:
Ruby:
cl_image_tag("butterfly.jpg", :width=>200, :height=>200, :gravity=>"face", :crop=>"fill")
PHP:
cl_image_tag("butterfly.jpg", array("width"=>200, "height"=>200, "gravity"=>"face", "crop"=>"fill"))
Python:
CloudinaryImage("butterfly.jpg").image(width=200, height=200, gravity="face", crop="fill")
Node.js:
cloudinary.image("butterfly.jpg", {width: 200, height: 200, gravity: "face", crop: "fill"})
Java:
cloudinary.url().transformation(new Transformation().width(200).height(200).gravity("face").crop("fill")).imageTag("butterfly.jpg");
JS:
cloudinary.imageTag('butterfly.jpg', {width: 200, height: 200, gravity: "face", crop: "fill"}).toHtml();
jQuery:
$.cloudinary.image("butterfly.jpg", {width: 200, height: 200, gravity: "face", crop: "fill"})
React:
<Image publicId="butterfly.jpg" >
<Transformation width="200" height="200" gravity="face" crop="fill" />
</Image>
Vue.js:
<cld-image publicId="butterfly.jpg" >
<cld-transformation width="200" height="200" gravity="face" crop="fill" />
</cld-image>
Angular:
<cl-image public-id="butterfly.jpg" >
<cl-transformation width="200" height="200" gravity="face" crop="fill">
</cl-transformation>
</cl-image>
.NET:
cloudinary.Api.UrlImgUp.Transform(new Transformation().Width(200).Height(200).Gravity("face").Crop("fill")).BuildImageTag("butterfly.jpg")
Android:
MediaManager.get().url().transformation(new Transformation().width(200).height(200).gravity("face").crop("fill")).generate("butterfly.jpg");
iOS:
imageView.cldSetImage(cloudinary.createUrl().setTransformation(CLDTransformation().setWidth(200).setHeight(200).setGravity("face").setCrop("fill")).generate("butterfly.jpg")!, cloudinary: cloudinary)
In order to create a 200x200 thumbnail focused on the face of the woman, simply select the thumb
crop mode and face
gravity:
Ruby:
cl_image_tag("butterfly.jpg", :width=>200, :height=>200, :gravity=>"face", :crop=>"thumb")
PHP:
cl_image_tag("butterfly.jpg", array("width"=>200, "height"=>200, "gravity"=>"face", "crop"=>"thumb"))
Python:
CloudinaryImage("butterfly.jpg").image(width=200, height=200, gravity="face", crop="thumb")
Node.js:
cloudinary.image("butterfly.jpg", {width: 200, height: 200, gravity: "face", crop: "thumb"})
Java:
cloudinary.url().transformation(new Transformation().width(200).height(200).gravity("face").crop("thumb")).imageTag("butterfly.jpg");
JS:
cloudinary.imageTag('butterfly.jpg', {width: 200, height: 200, gravity: "face", crop: "thumb"}).toHtml();
jQuery:
$.cloudinary.image("butterfly.jpg", {width: 200, height: 200, gravity: "face", crop: "thumb"})
React:
<Image publicId="butterfly.jpg" >
<Transformation width="200" height="200" gravity="face" crop="thumb" />
</Image>
Vue.js:
<cld-image publicId="butterfly.jpg" >
<cld-transformation width="200" height="200" gravity="face" crop="thumb" />
</cld-image>
Angular:
<cl-image public-id="butterfly.jpg" >
<cl-transformation width="200" height="200" gravity="face" crop="thumb">
</cl-transformation>
</cl-image>
.NET:
cloudinary.Api.UrlImgUp.Transform(new Transformation().Width(200).Height(200).Gravity("face").Crop("thumb")).BuildImageTag("butterfly.jpg")
Android:
MediaManager.get().url().transformation(new Transformation().width(200).height(200).gravity("face").crop("thumb")).generate("butterfly.jpg");
iOS:
imageView.cldSetImage(cloudinary.createUrl().setTransformation(CLDTransformation().setWidth(200).setHeight(200).setGravity("face").setCrop("thumb")).generate("butterfly.jpg")!, cloudinary: cloudinary)
You can also automatically crop to the region defined by face detection without resizing the original image. The following example uses the crop
mode together with face
gravity for cropping the original image to the face of the woman:
Ruby:
cl_image_tag("butterfly.jpg", :gravity=>"face", :crop=>"crop")
PHP:
cl_image_tag("butterfly.jpg", array("gravity"=>"face", "crop"=>"crop"))
Python:
CloudinaryImage("butterfly.jpg").image(gravity="face", crop="crop")
Node.js:
cloudinary.image("butterfly.jpg", {gravity: "face", crop: "crop"})
Java:
cloudinary.url().transformation(new Transformation().gravity("face").crop("crop")).imageTag("butterfly.jpg");
JS:
cloudinary.imageTag('butterfly.jpg', {gravity: "face", crop: "crop"}).toHtml();
jQuery:
$.cloudinary.image("butterfly.jpg", {gravity: "face", crop: "crop"})
React:
<Image publicId="butterfly.jpg" >
<Transformation gravity="face" crop="crop" />
</Image>
Vue.js:
<cld-image publicId="butterfly.jpg" >
<cld-transformation gravity="face" crop="crop" />
</cld-image>
Angular:
<cl-image public-id="butterfly.jpg" >
<cl-transformation gravity="face" crop="crop">
</cl-transformation>
</cl-image>
.NET:
cloudinary.Api.UrlImgUp.Transform(new Transformation().Gravity("face").Crop("crop")).BuildImageTag("butterfly.jpg")
Android:
MediaManager.get().url().transformation(new Transformation().gravity("face").crop("crop")).generate("butterfly.jpg");
iOS:
imageView.cldSetImage(cloudinary.createUrl().setTransformation(CLDTransformation().setGravity("face").setCrop("crop")).generate("butterfly.jpg")!, cloudinary: cloudinary)
For examples with multiple faces, the following image, showing a nice couple, was uploaded to Cloudinary:
Ruby:
cl_image_tag("couple.jpg")
PHP:
cl_image_tag("couple.jpg")
Python:
CloudinaryImage("couple.jpg").image()
Node.js:
cloudinary.image("couple.jpg")
Java:
cloudinary.url().imageTag("couple.jpg");
JS:
cloudinary.imageTag('couple.jpg').toHtml();
jQuery:
$.cloudinary.image("couple.jpg")
React:
<Image publicId="couple.jpg" >
</Image>
Vue.js:
<cld-image publicId="couple.jpg" >
</cld-image>
Angular:
<cl-image public-id="couple.jpg" >
</cl-image>
.NET:
cloudinary.Api.UrlImgUp.BuildImageTag("couple.jpg")
Android:
MediaManager.get().url().generate("couple.jpg");
iOS:
imageView.cldSetImage(cloudinary.createUrl().generate("couple.jpg")!, cloudinary: cloudinary)
You can specify the thumb
crop mode and face
gravity to create a 150x150 thumbnail centered on the face of only the biggest face in the image:
Ruby:
cl_image_tag("couple.jpg", :width=>150, :height=>150, :gravity=>"face", :crop=>"thumb")
PHP:
cl_image_tag("couple.jpg", array("width"=>150, "height"=>150, "gravity"=>"face", "crop"=>"thumb"))
Python:
CloudinaryImage("couple.jpg").image(width=150, height=150, gravity="face", crop="thumb")
Node.js:
cloudinary.image("couple.jpg", {width: 150, height: 150, gravity: "face", crop: "thumb"})
Java:
cloudinary.url().transformation(new Transformation().width(150).height(150).gravity("face").crop("thumb")).imageTag("couple.jpg");
JS:
cloudinary.imageTag('couple.jpg', {width: 150, height: 150, gravity: "face", crop: "thumb"}).toHtml();
jQuery:
$.cloudinary.image("couple.jpg", {width: 150, height: 150, gravity: "face", crop: "thumb"})
React:
<Image publicId="couple.jpg" >
<Transformation width="150" height="150" gravity="face" crop="thumb" />
</Image>
Vue.js:
<cld-image publicId="couple.jpg" >
<cld-transformation width="150" height="150" gravity="face" crop="thumb" />
</cld-image>
Angular:
<cl-image public-id="couple.jpg" >
<cl-transformation width="150" height="150" gravity="face" crop="thumb">
</cl-transformation>
</cl-image>
.NET:
cloudinary.Api.UrlImgUp.Transform(new Transformation().Width(150).Height(150).Gravity("face").Crop("thumb")).BuildImageTag("couple.jpg")
Android:
MediaManager.get().url().transformation(new Transformation().width(150).height(150).gravity("face").crop("thumb")).generate("couple.jpg");
iOS:
imageView.cldSetImage(cloudinary.createUrl().setTransformation(CLDTransformation().setWidth(150).setHeight(150).setGravity("face").setCrop("thumb")).generate("couple.jpg")!, cloudinary: cloudinary)
In order to create a thumbnail focusing on the faces of both of them, simply specify faces
as the gravity:
Ruby:
cl_image_tag("couple.jpg", :width=>115, :height=>135, :gravity=>"faces", :crop=>"thumb")
PHP:
cl_image_tag("couple.jpg", array("width"=>115, "height"=>135, "gravity"=>"faces", "crop"=>"thumb"))
Python:
CloudinaryImage("couple.jpg").image(width=115, height=135, gravity="faces", crop="thumb")
Node.js:
cloudinary.image("couple.jpg", {width: 115, height: 135, gravity: "faces", crop: "thumb"})
Java:
cloudinary.url().transformation(new Transformation().width(115).height(135).gravity("faces").crop("thumb")).imageTag("couple.jpg");
JS:
cloudinary.imageTag('couple.jpg', {width: 115, height: 135, gravity: "faces", crop: "thumb"}).toHtml();
jQuery:
$.cloudinary.image("couple.jpg", {width: 115, height: 135, gravity: "faces", crop: "thumb"})
React:
<Image publicId="couple.jpg" >
<Transformation width="115" height="135" gravity="faces" crop="thumb" />
</Image>
Vue.js:
<cld-image publicId="couple.jpg" >
<cld-transformation width="115" height="135" gravity="faces" crop="thumb" />
</cld-image>
Angular:
<cl-image public-id="couple.jpg" >
<cl-transformation width="115" height="135" gravity="faces" crop="thumb">
</cl-transformation>
</cl-image>
.NET:
cloudinary.Api.UrlImgUp.Transform(new Transformation().Width(115).Height(135).Gravity("faces").Crop("thumb")).BuildImageTag("couple.jpg")
Android:
MediaManager.get().url().transformation(new Transformation().width(115).height(135).gravity("faces").crop("thumb")).generate("couple.jpg");
iOS:
imageView.cldSetImage(cloudinary.createUrl().setTransformation(CLDTransformation().setWidth(115).setHeight(135).setGravity("faces").setCrop("thumb")).generate("couple.jpg")!, cloudinary: cloudinary)
You can also use the fill
cropping mode together with faces
gravity to correctly fill an image with your desired dimensions:
Ruby:
cl_image_tag("couple.jpg", :width=>100, :height=>150, :gravity=>"faces", :crop=>"fill")
PHP:
cl_image_tag("couple.jpg", array("width"=>100, "height"=>150, "gravity"=>"faces", "crop"=>"fill"))
Python:
CloudinaryImage("couple.jpg").image(width=100, height=150, gravity="faces", crop="fill")
Node.js:
cloudinary.image("couple.jpg", {width: 100, height: 150, gravity: "faces", crop: "fill"})
Java:
cloudinary.url().transformation(new Transformation().width(100).height(150).gravity("faces").crop("fill")).imageTag("couple.jpg");
JS:
cloudinary.imageTag('couple.jpg', {width: 100, height: 150, gravity: "faces", crop: "fill"}).toHtml();
jQuery:
$.cloudinary.image("couple.jpg", {width: 100, height: 150, gravity: "faces", crop: "fill"})
React:
<Image publicId="couple.jpg" >
<Transformation width="100" height="150" gravity="faces" crop="fill" />
</Image>
Vue.js:
<cld-image publicId="couple.jpg" >
<cld-transformation width="100" height="150" gravity="faces" crop="fill" />
</cld-image>
Angular:
<cl-image public-id="couple.jpg" >
<cl-transformation width="100" height="150" gravity="faces" crop="fill">
</cl-transformation>
</cl-image>
.NET:
cloudinary.Api.UrlImgUp.Transform(new Transformation().Width(100).Height(150).Gravity("faces").Crop("fill")).BuildImageTag("couple.jpg")
Android:
MediaManager.get().url().transformation(new Transformation().width(100).height(150).gravity("faces").crop("fill")).generate("couple.jpg");
iOS:
imageView.cldSetImage(cloudinary.createUrl().setTransformation(CLDTransformation().setWidth(100).setHeight(150).setGravity("faces").setCrop("fill")).generate("couple.jpg")!, cloudinary: cloudinary)
To automatically position an overlay over the detected face(s) in an image, set the gravity
parameter to one of the following values:
face
- places an overlay over the single largest face in the image (g_face
for URLs).
faces
- places an overlay over each of the faces in the image (g_faces
for URLs).
For example, adding an overlay of the golden_star
image over both of the faces detected in the young_couples
image, where each star is resized to the same width as the detected face with the region_relative
flag:
Ruby:
cl_image_tag("young_couple.jpg", :overlay=>"golden_star", :gravity=>"faces", :width=>1.0, :flags=>"region_relative")
PHP:
cl_image_tag("young_couple.jpg", array("overlay"=>"golden_star", "gravity"=>"faces", "width"=>"1.0", "flags"=>"region_relative"))
Python:
CloudinaryImage("young_couple.jpg").image(overlay="golden_star", gravity="faces", width="1.0", flags="region_relative")
Node.js:
cloudinary.image("young_couple.jpg", {overlay: "golden_star", gravity: "faces", width: "1.0", flags: "region_relative"})
Java:
cloudinary.url().transformation(new Transformation().overlay(new Layer().publicId("golden_star")).gravity("faces").width(1.0).flags("region_relative")).imageTag("young_couple.jpg");
JS:
cloudinary.imageTag('young_couple.jpg', {overlay: new cloudinary.Layer().publicId("golden_star"), gravity: "faces", width: "1.0", flags: "region_relative"}).toHtml();
jQuery:
$.cloudinary.image("young_couple.jpg", {overlay: new cloudinary.Layer().publicId("golden_star"), gravity: "faces", width: "1.0", flags: "region_relative"})
React:
<Image publicId="young_couple.jpg" >
<Transformation overlay="golden_star" gravity="faces" width="1.0" flags="region_relative" />
</Image>
Vue.js:
<cld-image publicId="young_couple.jpg" >
<cld-transformation overlay="golden_star" gravity="faces" width="1.0" flags="region_relative" />
</cld-image>
Angular:
<cl-image public-id="young_couple.jpg" >
<cl-transformation overlay="golden_star" gravity="faces" width="1.0" flags="region_relative">
</cl-transformation>
</cl-image>
.NET:
cloudinary.Api.UrlImgUp.Transform(new Transformation().Overlay(new Layer().PublicId("golden_star")).Gravity("faces").Width(1.0).Flags("region_relative")).BuildImageTag("young_couple.jpg")
Android:
MediaManager.get().url().transformation(new Transformation().overlay(new Layer().publicId("golden_star")).gravity("faces").width(1.0).flags("region_relative")).generate("young_couple.jpg");
iOS:
imageView.cldSetImage(cloudinary.createUrl().setTransformation(CLDTransformation().setOverlay("golden_star").setGravity("faces").setWidth(1.0).setFlags("region_relative")).generate("young_couple.jpg")!, cloudinary: cloudinary)
When gravity is set to one of the facial detection values and no face is detected in the image, then no overlay is placed at all.
You can use the getinfo flag together with a face-detection gravity option to return the coordinates of facial landmarks via a completely client-side operation. Using this information, you can, for example, calculate the x and y offsets to specify the exact position of an overlay on a face, or you could pass the data back to other functions in your application.
For example, you can get the facial landmark coordinates in this image by using the getinfo
flag together with a crop and a gravity option that detects a face. In this example we have used g_face
, but we could have also used g_auto:face
, or even just g_auto
(as the g_auto
default behavior is to apply g_auto:faces
).
Ruby:
cl_image_tag("docs/plain_face.jpg", :gravity=>"face", :width=>500, :flags=>"getinfo", :crop=>"thumb")
PHP:
cl_image_tag("docs/plain_face.jpg", array("gravity"=>"face", "width"=>500, "flags"=>"getinfo", "crop"=>"thumb"))
Python:
CloudinaryImage("docs/plain_face.jpg").image(gravity="face", width=500, flags="getinfo", crop="thumb")
Node.js:
cloudinary.image("docs/plain_face.jpg", {gravity: "face", width: 500, flags: "getinfo", crop: "thumb"})
Java:
cloudinary.url().transformation(new Transformation().gravity("face").width(500).flags("getinfo").crop("thumb")).imageTag("docs/plain_face.jpg");
JS:
cloudinary.imageTag('docs/plain_face.jpg', {gravity: "face", width: 500, flags: "getinfo", crop: "thumb"}).toHtml();
jQuery:
$.cloudinary.image("docs/plain_face.jpg", {gravity: "face", width: 500, flags: "getinfo", crop: "thumb"})
React:
<Image publicId="docs/plain_face.jpg" >
<Transformation gravity="face" width="500" flags="getinfo" crop="thumb" />
</Image>
Vue.js:
<cld-image publicId="docs/plain_face.jpg" >
<cld-transformation gravity="face" width="500" flags="getinfo" crop="thumb" />
</cld-image>
Angular:
<cl-image public-id="docs/plain_face.jpg" >
<cl-transformation gravity="face" width="500" flags="getinfo" crop="thumb">
</cl-transformation>
</cl-image>
.NET:
cloudinary.Api.UrlImgUp.Transform(new Transformation().Gravity("face").Width(500).Flags("getinfo").Crop("thumb")).BuildImageTag("docs/plain_face.jpg")
Android:
MediaManager.get().url().transformation(new Transformation().gravity("face").width(500).flags("getinfo").crop("thumb")).generate("docs/plain_face.jpg");
iOS:
imageView.cldSetImage(cloudinary.createUrl().setTransformation(CLDTransformation().setGravity("face").setWidth(500).setFlags("getinfo").setCrop("thumb")).generate("docs/plain_face.jpg")!, cloudinary: cloudinary)
This returns:
{
"input": {
"width": 640,
"height": 426,
"bytes": 49727
},
"landmarks": [
[
{
"face_center": {
"x": 402,
"y": 218
},
"l_canthus_r_eye": {
"x": 371,
"y": 176
},
"r_canthus_l_eye": {
"x": 421,
"y": 177
},
"mouth_r": {
"x": 365,
"y": 254
},
"mouth_l": {
"x": 425,
"y": 256
},
"r_canthus_r_eye": {
"x": 333,
"y": 170
},
"l_canthus_l_eye": {
"x": 457,
"y": 174
},
"nose_tip": {
"x": 399,
"y": 224
},
"l_eyebrow_l": {
"x": 465,
"y": 151
},
"l_eyebrow_c": {
"x": 444,
"y": 151
},
"l_eyebrow_r": {
"x": 418,
"y": 158
},
"r_eyebrow_l": {
"x": 376,
"y": 158
},
"r_eyebrow_c": {
"x": 350,
"y": 151
},
"r_eyebrow_r": {
"x": 324,
"y": 158
},
"nose_root": {
"x": 397,
"y": 172
},
"nose_l": {
"x": 413,
"y": 220
},
"nose_r": {
"x": 376,
"y": 220
},
"mouth_t": {
"x": 397,
"y": 247
},
"mouth_b": {
"x": 397,
"y": 268
},
"chin": {
"x": 392,
"y": 302
},
"forehead_apex": {
"x": 400,
"y": 100
}
}
]
],
"resize": [
{
"x": 140,
"y": 34,
"width": 500,
"height": 333
}
],
"output": {
"format": "jpg",
"bytes": 49255,
"width": 500,
"height": 333
}
}
The coordinates of the landmarks are relative to the top left of the original image. You can use this data to position an overlay with a gravity
of north_west
using the relevant returned coordinates as the x and y offsets. Specifying an offset of 0,0 positions an overlay with its top left corner in the 0,0 position of the base image, so if you want to center the overlay on a particular coordinate, you need to adjust the coordinates by half of the width and height of the overlay.
For example, to position a golden star, resized to a width and height of 20 pixels, centered over the right side of the right eyebrow, take the coordinates of "r_eyebrow_r":{"x":324,"y":158}
and subtract half the width and height of the overlay (10 pixels) to leave an x-offset of 314 and a y-offset of 148.
Putting all these parameters together you can give the girl an eyebrow piercing as follows:
Ruby:
cl_image_tag("docs/plain_face.jpg", :transformation=>[
{:overlay=>"golden_star", :gravity=>"north_west", :width=>20, :x=>314, :y=>148},
{:width=>500, :crop=>"scale"}
])
PHP:
cl_image_tag("docs/plain_face.jpg", array("transformation"=>array(
array("overlay"=>"golden_star", "gravity"=>"north_west", "width"=>20, "x"=>314, "y"=>148),
array("width"=>500, "crop"=>"scale")
)))
Python:
CloudinaryImage("docs/plain_face.jpg").image(transformation=[
{'overlay': "golden_star", 'gravity': "north_west", 'width': 20, 'x': 314, 'y': 148},
{'width': 500, 'crop': "scale"}
])
Node.js:
cloudinary.image("docs/plain_face.jpg", {transformation: [
{overlay: "golden_star", gravity: "north_west", width: 20, x: 314, y: 148},
{width: 500, crop: "scale"}
]})
Java:
cloudinary.url().transformation(new Transformation()
.overlay(new Layer().publicId("golden_star")).gravity("north_west").width(20).x(314).y(148).chain()
.width(500).crop("scale")).imageTag("docs/plain_face.jpg");
JS:
cloudinary.imageTag('docs/plain_face.jpg', {transformation: [
{overlay: new cloudinary.Layer().publicId("golden_star"), gravity: "north_west", width: 20, x: 314, y: 148},
{width: 500, crop: "scale"}
]}).toHtml();
jQuery:
$.cloudinary.image("docs/plain_face.jpg", {transformation: [
{overlay: new cloudinary.Layer().publicId("golden_star"), gravity: "north_west", width: 20, x: 314, y: 148},
{width: 500, crop: "scale"}
]})
React:
<Image publicId="docs/plain_face.jpg" >
<Transformation overlay="golden_star" gravity="north_west" width="20" x="314" y="148" />
<Transformation width="500" crop="scale" />
</Image>
Vue.js:
<cld-image publicId="docs/plain_face.jpg" >
<cld-transformation overlay="golden_star" gravity="north_west" width="20" x="314" y="148" />
<cld-transformation width="500" crop="scale" />
</cld-image>
Angular:
<cl-image public-id="docs/plain_face.jpg" >
<cl-transformation overlay="golden_star" gravity="north_west" width="20" x="314" y="148">
</cl-transformation>
<cl-transformation width="500" crop="scale">
</cl-transformation>
</cl-image>
.NET:
cloudinary.Api.UrlImgUp.Transform(new Transformation()
.Overlay(new Layer().PublicId("golden_star")).Gravity("north_west").Width(20).X(314).Y(148).Chain()
.Width(500).Crop("scale")).BuildImageTag("docs/plain_face.jpg")
Android:
MediaManager.get().url().transformation(new Transformation()
.overlay(new Layer().publicId("golden_star")).gravity("north_west").width(20).x(314).y(148).chain()
.width(500).crop("scale")).generate("docs/plain_face.jpg");
iOS:
imageView.cldSetImage(cloudinary.createUrl().setTransformation(CLDTransformation()
.setOverlay("golden_star").setGravity("north_west").setWidth(20).setX(314).setY(148).chain()
.setWidth(500).setCrop("scale")).generate("docs/plain_face.jpg")!, cloudinary: cloudinary)
To apply a blur or pixelation effect to the automatically detected faces in an image, use the effect
parameter and set it to one of the following values:
blur_faces
- Automatically blur all detected faces in the image: the strength of the blur effect is determined by an optional extra value (Range: 1 to 2000, Default: 500). For example, e_blur_faces:100
uses a mild blur effect with a strength of 100.
pixelate_faces
- Automatically pixelate all detected faces in the image. The width of the pixelation squares is determined by an optional extra value (Range: 1 to 200, Default: 5). For example, e_pixelate_faces:3
uses pixelation squares 3 pixels wide.
For example, to automatically pixelate both of the faces detected in the young_couples
image with pixelation squares 9 pixels wide:
Ruby:
cl_image_tag("young_couple.jpg", :effect=>"pixelate_faces:9")
PHP:
cl_image_tag("young_couple.jpg", array("effect"=>"pixelate_faces:9"))
Python:
CloudinaryImage("young_couple.jpg").image(effect="pixelate_faces:9")
Node.js:
cloudinary.image("young_couple.jpg", {effect: "pixelate_faces:9"})
Java:
cloudinary.url().transformation(new Transformation().effect("pixelate_faces:9")).imageTag("young_couple.jpg");
JS:
cloudinary.imageTag('young_couple.jpg', {effect: "pixelate_faces:9"}).toHtml();
jQuery:
$.cloudinary.image("young_couple.jpg", {effect: "pixelate_faces:9"})
React:
<Image publicId="young_couple.jpg" >
<Transformation effect="pixelate_faces:9" />
</Image>
Vue.js:
<cld-image publicId="young_couple.jpg" >
<cld-transformation effect="pixelate_faces:9" />
</cld-image>
Angular:
<cl-image public-id="young_couple.jpg" >
<cl-transformation effect="pixelate_faces:9">
</cl-transformation>
</cl-image>
.NET:
cloudinary.Api.UrlImgUp.Transform(new Transformation().Effect("pixelate_faces:9")).BuildImageTag("young_couple.jpg")
Android:
MediaManager.get().url().transformation(new Transformation().effect("pixelate_faces:9")).generate("young_couple.jpg");
iOS:
imageView.cldSetImage(cloudinary.createUrl().setTransformation(CLDTransformation().setEffect("pixelate_faces:9")).generate("young_couple.jpg")!, cloudinary: cloudinary)
With the Advanced Facial Attributes Detection add-on, you can extend the Cloudinary built-in features that involve semantic photo data extraction, image cropping and the positioning of image overlays. When using the add-on, your images are further processed and additional advanced face attributes are automatically extracted. Cloudinary can then use these additional details to smartly crop, position, rotate and overlay images according to the position of the detected faces or eyes.
The advanced facial detection is applied by setting the gravity
parameter to one of the following values:
adv_face
- detects the single largest face in the image (g_adv_face
for URLs).
adv_faces
- detects all of the faces in the image (g_adv_faces
for URLs).
adv_eyes
- detects all the pairs of eyes in the image (g_adv_eyes
for URLs).
For example, to automatically overlay the image glasses
over the detected eyes in the couples
image. The glasses are resized to 170% the width of the detected eyes by adding the region_relative
flag:
Ruby:
cl_image_tag("coupled.jpg", :flags=>"region_relative", :gravity=>"adv_eyes", :overlay=>"glasses", :width=>1.7)
PHP:
cl_image_tag("coupled.jpg", array("flags"=>"region_relative", "gravity"=>"adv_eyes", "overlay"=>"glasses", "width"=>"1.7"))
Python:
CloudinaryImage("coupled.jpg").image(flags="region_relative", gravity="adv_eyes", overlay="glasses", width="1.7")
Node.js:
cloudinary.image("coupled.jpg", {flags: "region_relative", gravity: "adv_eyes", overlay: "glasses", width: "1.7"})
Java:
cloudinary.url().transformation(new Transformation().flags("region_relative").gravity("adv_eyes").overlay(new Layer().publicId("glasses")).width(1.7)).imageTag("coupled.jpg");
JS:
cloudinary.imageTag('coupled.jpg', {flags: "region_relative", gravity: "adv_eyes", overlay: new cloudinary.Layer().publicId("glasses"), width: "1.7"}).toHtml();
jQuery:
$.cloudinary.image("coupled.jpg", {flags: "region_relative", gravity: "adv_eyes", overlay: new cloudinary.Layer().publicId("glasses"), width: "1.7"})
React:
<Image publicId="coupled.jpg" >
<Transformation flags="region_relative" gravity="adv_eyes" overlay="glasses" width="1.7" />
</Image>
Vue.js:
<cld-image publicId="coupled.jpg" >
<cld-transformation flags="region_relative" gravity="adv_eyes" overlay="glasses" width="1.7" />
</cld-image>
Angular:
<cl-image public-id="coupled.jpg" >
<cl-transformation flags="region_relative" gravity="adv_eyes" overlay="glasses" width="1.7">
</cl-transformation>
</cl-image>
.NET:
cloudinary.Api.UrlImgUp.Transform(new Transformation().Flags("region_relative").Gravity("adv_eyes").Overlay(new Layer().PublicId("glasses")).Width(1.7)).BuildImageTag("coupled.jpg")
Android:
MediaManager.get().url().transformation(new Transformation().flags("region_relative").gravity("adv_eyes").overlay(new Layer().publicId("glasses")).width(1.7)).generate("coupled.jpg");
iOS:
imageView.cldSetImage(cloudinary.createUrl().setTransformation(CLDTransformation().setFlags("region_relative").setGravity("adv_eyes").setOverlay("glasses").setWidth(1.7)).generate("coupled.jpg")!, cloudinary: cloudinary)
See the Advanced Facial Attributes Detection documentation for more information and examples on using the add-on.
When using either the crop or thumb cropping modes and setting the gravity parameter to one of the face detection values, the resulting image is delivered at a default zoom level. To control how much of the original image surrounding the face to keep, use the zoom
parameter (z
for URLs). This parameter accepts a decimal value that sets the new zoom level as a multiplier of the default zoom setting: a value less than 1.0 zooms out and a value greater than 1.0 zooms in. For example, z_0.5
halves the default zoom to 50% and zooms out to include more of the background around the face, while z_2.0
doubles the default zoom to 200% and zooms in to include less of the background around the face.
Examples with the uploaded image called woman
:
- Original image (scaled down):
Ruby:
cl_image_tag("woman.jpg")
PHP:
cl_image_tag("woman.jpg")
Python:
CloudinaryImage("woman.jpg").image()
Node.js:
cloudinary.image("woman.jpg")
Java:
cloudinary.url().imageTag("woman.jpg");
JS:
cloudinary.imageTag('woman.jpg').toHtml();
jQuery:
$.cloudinary.image("woman.jpg")
React:
<Image publicId="woman.jpg" >
</Image>
Vue.js:
<cld-image publicId="woman.jpg" >
</cld-image>
Angular:
<cl-image public-id="woman.jpg" >
</cl-image>
.NET:
cloudinary.Api.UrlImgUp.BuildImageTag("woman.jpg")
Android:
MediaManager.get().url().generate("woman.jpg");
iOS:
imageView.cldSetImage(cloudinary.createUrl().generate("woman.jpg")!, cloudinary: cloudinary)
- Cropped with face detection and default zoom:
Ruby:
cl_image_tag("woman.jpg", :gravity=>"face", :crop=>"crop")
PHP:
cl_image_tag("woman.jpg", array("gravity"=>"face", "crop"=>"crop"))
Python:
CloudinaryImage("woman.jpg").image(gravity="face", crop="crop")
Node.js:
cloudinary.image("woman.jpg", {gravity: "face", crop: "crop"})
Java:
cloudinary.url().transformation(new Transformation().gravity("face").crop("crop")).imageTag("woman.jpg");
JS:
cloudinary.imageTag('woman.jpg', {gravity: "face", crop: "crop"}).toHtml();
jQuery:
$.cloudinary.image("woman.jpg", {gravity: "face", crop: "crop"})
React:
<Image publicId="woman.jpg" >
<Transformation gravity="face" crop="crop" />
</Image>
Vue.js:
<cld-image publicId="woman.jpg" >
<cld-transformation gravity="face" crop="crop" />
</cld-image>
Angular:
<cl-image public-id="woman.jpg" >
<cl-transformation gravity="face" crop="crop">
</cl-transformation>
</cl-image>
.NET:
cloudinary.Api.UrlImgUp.Transform(new Transformation().Gravity("face").Crop("crop")).BuildImageTag("woman.jpg")
Android:
MediaManager.get().url().transformation(new Transformation().gravity("face").crop("crop")).generate("woman.jpg");
iOS:
imageView.cldSetImage(cloudinary.createUrl().setTransformation(CLDTransformation().setGravity("face").setCrop("crop")).generate("woman.jpg")!, cloudinary: cloudinary)
- Cropped with face detection and zoom set to 130%:
Ruby:
cl_image_tag("woman.jpg", :gravity=>"face", :zoom=>1.3, :crop=>"crop")
PHP:
cl_image_tag("woman.jpg", array("gravity"=>"face", "zoom"=>"1.3", "crop"=>"crop"))
Python:
CloudinaryImage("woman.jpg").image(gravity="face", zoom="1.3", crop="crop")
Node.js:
cloudinary.image("woman.jpg", {gravity: "face", zoom: "1.3", crop: "crop"})
Java:
cloudinary.url().transformation(new Transformation().gravity("face").zoom(1.3).crop("crop")).imageTag("woman.jpg");
JS:
cloudinary.imageTag('woman.jpg', {gravity: "face", zoom: "1.3", crop: "crop"}).toHtml();
jQuery:
$.cloudinary.image("woman.jpg", {gravity: "face", zoom: "1.3", crop: "crop"})
React:
<Image publicId="woman.jpg" >
<Transformation gravity="face" zoom="1.3" crop="crop" />
</Image>
Vue.js:
<cld-image publicId="woman.jpg" >
<cld-transformation gravity="face" zoom="1.3" crop="crop" />
</cld-image>
Angular:
<cl-image public-id="woman.jpg" >
<cl-transformation gravity="face" zoom="1.3" crop="crop">
</cl-transformation>
</cl-image>
.NET:
cloudinary.Api.UrlImgUp.Transform(new Transformation().Gravity("face").Zoom(1.3).Crop("crop")).BuildImageTag("woman.jpg")
Android:
MediaManager.get().url().transformation(new Transformation().gravity("face").zoom(1.3).crop("crop")).generate("woman.jpg");
iOS:
imageView.cldSetImage(cloudinary.createUrl().setTransformation(CLDTransformation().setGravity("face").setZoom(1.3).setCrop("crop")).generate("woman.jpg")!, cloudinary: cloudinary)
- 150x150 thumbnail with face detection and default zoom:
Ruby:
cl_image_tag("woman.jpg", :gravity=>"face", :width=>150, :height=>150, :crop=>"thumb")
PHP:
cl_image_tag("woman.jpg", array("gravity"=>"face", "width"=>150, "height"=>150, "crop"=>"thumb"))
Python:
CloudinaryImage("woman.jpg").image(gravity="face", width=150, height=150, crop="thumb")
Node.js:
cloudinary.image("woman.jpg", {gravity: "face", width: 150, height: 150, crop: "thumb"})
Java:
cloudinary.url().transformation(new Transformation().gravity("face").width(150).height(150).crop("thumb")).imageTag("woman.jpg");
JS:
cloudinary.imageTag('woman.jpg', {gravity: "face", width: 150, height: 150, crop: "thumb"}).toHtml();
jQuery:
$.cloudinary.image("woman.jpg", {gravity: "face", width: 150, height: 150, crop: "thumb"})
React:
<Image publicId="woman.jpg" >
<Transformation gravity="face" width="150" height="150" crop="thumb" />
</Image>
Vue.js:
<cld-image publicId="woman.jpg" >
<cld-transformation gravity="face" width="150" height="150" crop="thumb" />
</cld-image>
Angular:
<cl-image public-id="woman.jpg" >
<cl-transformation gravity="face" width="150" height="150" crop="thumb">
</cl-transformation>
</cl-image>
.NET:
cloudinary.Api.UrlImgUp.Transform(new Transformation().Gravity("face").Width(150).Height(150).Crop("thumb")).BuildImageTag("woman.jpg")
Android:
MediaManager.get().url().transformation(new Transformation().gravity("face").width(150).height(150).crop("thumb")).generate("woman.jpg");
iOS:
imageView.cldSetImage(cloudinary.createUrl().setTransformation(CLDTransformation().setGravity("face").setWidth(150).setHeight(150).setCrop("thumb")).generate("woman.jpg")!, cloudinary: cloudinary)
- 150x150 thumbnail with face detection and zoom set to 70%:
Ruby:
cl_image_tag("woman.jpg", :gravity=>"face", :width=>150, :height=>150, :zoom=>0.7, :crop=>"thumb")
PHP:
cl_image_tag("woman.jpg", array("gravity"=>"face", "width"=>150, "height"=>150, "zoom"=>"0.7", "crop"=>"thumb"))
Python:
CloudinaryImage("woman.jpg").image(gravity="face", width=150, height=150, zoom="0.7", crop="thumb")
Node.js:
cloudinary.image("woman.jpg", {gravity: "face", width: 150, height: 150, zoom: "0.7", crop: "thumb"})
Java:
cloudinary.url().transformation(new Transformation().gravity("face").width(150).height(150).zoom(0.7).crop("thumb")).imageTag("woman.jpg");
JS:
cloudinary.imageTag('woman.jpg', {gravity: "face", width: 150, height: 150, zoom: "0.7", crop: "thumb"}).toHtml();
jQuery:
$.cloudinary.image("woman.jpg", {gravity: "face", width: 150, height: 150, zoom: "0.7", crop: "thumb"})
React:
<Image publicId="woman.jpg" >
<Transformation gravity="face" width="150" height="150" zoom="0.7" crop="thumb" />
</Image>
Vue.js:
<cld-image publicId="woman.jpg" >
<cld-transformation gravity="face" width="150" height="150" zoom="0.7" crop="thumb" />
</cld-image>
Angular:
<cl-image public-id="woman.jpg" >
<cl-transformation gravity="face" width="150" height="150" zoom="0.7" crop="thumb">
</cl-transformation>
</cl-image>
.NET:
cloudinary.Api.UrlImgUp.Transform(new Transformation().Gravity("face").Width(150).Height(150).Zoom(0.7).Crop("thumb")).BuildImageTag("woman.jpg")
Android:
MediaManager.get().url().transformation(new Transformation().gravity("face").width(150).height(150).zoom(0.7).crop("thumb")).generate("woman.jpg");
iOS:
imageView.cldSetImage(cloudinary.createUrl().setTransformation(CLDTransformation().setGravity("face").setWidth(150).setHeight(150).setZoom(0.7).setCrop("thumb")).generate("woman.jpg")!, cloudinary: cloudinary)
For more examples on using the zoom parameter see the article on How to control the zoom level with automatic face detection based image cropping.