Overlay an image over detected faces

Overlay another image of your choice on top of the faces which are automatically detected in your image. This is done by setting the overlay parameter (l in URLs) to the overlay image's public ID while setting the gravity parameter to faces (g_faces in URLs).

Cloudinary automatically detects and searches for faces within an image. There are various Cloudinary tools that you can use with the detected faces' coordinates, such as Faces-based cropping, Faces-based blurring and pixelating and more.

Here's an example of an image automatically fetched from Wikimedia Commons :

Ruby:
cl_image_tag("http://upload.wikimedia.org/wikipedia/commons/4/45/Spain_national_football_team_Euro_2012_final.jpg", :type=>"fetch")
PHP:
cl_image_tag("http://upload.wikimedia.org/wikipedia/commons/4/45/Spain_national_football_team_Euro_2012_final.jpg", array("type"=>"fetch"))
Python:
CloudinaryImage("http://upload.wikimedia.org/wikipedia/commons/4/45/Spain_national_football_team_Euro_2012_final.jpg").image(type="fetch")
Node.js:
cloudinary.image("http://upload.wikimedia.org/wikipedia/commons/4/45/Spain_national_football_team_Euro_2012_final.jpg", {type: "fetch"})
Java:
cloudinary.url().type("fetch").imageTag("http://upload.wikimedia.org/wikipedia/commons/4/45/Spain_national_football_team_Euro_2012_final.jpg")
JS:
cl.imageTag('http://upload.wikimedia.org/wikipedia/commons/4/45/Spain_national_football_team_Euro_2012_final.jpg', {type: "fetch"}).toHtml();
jQuery:
$.cloudinary.image("http://upload.wikimedia.org/wikipedia/commons/4/45/Spain_national_football_team_Euro_2012_final.jpg", {type: "fetch"})
React:
<Image publicId="http://upload.wikimedia.org/wikipedia/commons/4/45/Spain_national_football_team_Euro_2012_final.jpg" type="fetch">

</Image>
Angular:
<cl-image public-id="http://upload.wikimedia.org/wikipedia/commons/4/45/Spain_national_football_team_Euro_2012_final.jpg" type="fetch">

</cl-image>
.Net:
cloudinary.Api.UrlImgUp.Type("fetch").BuildImageTag("http://upload.wikimedia.org/wikipedia/commons/4/45/Spain_national_football_team_Euro_2012_final.jpg")
Original

Here's an example of taking an image with the badge public ID, resizing it to 30 pixels-wide and overlaying it on top of all detected faces in the image:

Ruby:
cl_image_tag("http://upload.wikimedia.org/wikipedia/commons/4/45/Spain_national_football_team_Euro_2012_final.jpg", :overlay=>"badge", :gravity=>"faces", :width=>30, :type=>"fetch")
PHP:
cl_image_tag("http://upload.wikimedia.org/wikipedia/commons/4/45/Spain_national_football_team_Euro_2012_final.jpg", array("overlay"=>"badge", "gravity"=>"faces", "width"=>30, "type"=>"fetch"))
Python:
CloudinaryImage("http://upload.wikimedia.org/wikipedia/commons/4/45/Spain_national_football_team_Euro_2012_final.jpg").image(overlay="badge", gravity="faces", width=30, type="fetch")
Node.js:
cloudinary.image("http://upload.wikimedia.org/wikipedia/commons/4/45/Spain_national_football_team_Euro_2012_final.jpg", {overlay: "badge", gravity: "faces", width: 30, type: "fetch"})
Java:
cloudinary.url().transformation(new Transformation().overlay("badge").gravity("faces").width(30)).type("fetch").imageTag("http://upload.wikimedia.org/wikipedia/commons/4/45/Spain_national_football_team_Euro_2012_final.jpg")
JS:
cl.imageTag('http://upload.wikimedia.org/wikipedia/commons/4/45/Spain_national_football_team_Euro_2012_final.jpg', {overlay: "badge", gravity: "faces", width: 30, type: "fetch"}).toHtml();
jQuery:
$.cloudinary.image("http://upload.wikimedia.org/wikipedia/commons/4/45/Spain_national_football_team_Euro_2012_final.jpg", {overlay: "badge", gravity: "faces", width: 30, type: "fetch"})
React:
<Image publicId="http://upload.wikimedia.org/wikipedia/commons/4/45/Spain_national_football_team_Euro_2012_final.jpg" overlay="badge" gravity="faces" width="30" type="fetch">
        <Transformation overlay="badge" gravity="faces" width=30 />
</Image>
Angular:
<cl-image public-id="http://upload.wikimedia.org/wikipedia/commons/4/45/Spain_national_football_team_Euro_2012_final.jpg" overlay="badge" gravity="faces" width="30" type="fetch">
        <cl-transformation overlay="badge" gravity="faces" width=30 />
</cl-image>
.Net:
cloudinary.Api.UrlImgUp.Transform(new Transformation().Overlay("badge").Gravity("faces").Width(30)).Type("fetch").BuildImageTag("http://upload.wikimedia.org/wikipedia/commons/4/45/Spain_national_football_team_Euro_2012_final.jpg")
Fixed badges size

Instead of specifying a fixed value for the badge image's width, you can tell Cloudinary to resize the badge's width relative to the main image. This is done by setting the width parameter to a decimal value defining the size and setting the flags parameter to relative (fl_relative in URLs). For example, positioning multiple badges while resizing them to 10% of the width of the containing image:

Ruby:
cl_image_tag("http://upload.wikimedia.org/wikipedia/commons/4/45/Spain_national_football_team_Euro_2012_final.jpg", :overlay=>"badge", :gravity=>"faces", :width=>0.1, :flags=>"relative", :type=>"fetch")
PHP:
cl_image_tag("http://upload.wikimedia.org/wikipedia/commons/4/45/Spain_national_football_team_Euro_2012_final.jpg", array("overlay"=>"badge", "gravity"=>"faces", "width"=>0.1, "flags"=>"relative", "type"=>"fetch"))
Python:
CloudinaryImage("http://upload.wikimedia.org/wikipedia/commons/4/45/Spain_national_football_team_Euro_2012_final.jpg").image(overlay="badge", gravity="faces", width=0.1, flags="relative", type="fetch")
Node.js:
cloudinary.image("http://upload.wikimedia.org/wikipedia/commons/4/45/Spain_national_football_team_Euro_2012_final.jpg", {overlay: "badge", gravity: "faces", width: 0.1, flags: "relative", type: "fetch"})
Java:
cloudinary.url().transformation(new Transformation().overlay("badge").gravity("faces").width(0.1).flags("relative")).type("fetch").imageTag("http://upload.wikimedia.org/wikipedia/commons/4/45/Spain_national_football_team_Euro_2012_final.jpg")
JS:
cl.imageTag('http://upload.wikimedia.org/wikipedia/commons/4/45/Spain_national_football_team_Euro_2012_final.jpg', {overlay: "badge", gravity: "faces", width: 0.1, flags: "relative", type: "fetch"}).toHtml();
jQuery:
$.cloudinary.image("http://upload.wikimedia.org/wikipedia/commons/4/45/Spain_national_football_team_Euro_2012_final.jpg", {overlay: "badge", gravity: "faces", width: 0.1, flags: "relative", type: "fetch"})
React:
<Image publicId="http://upload.wikimedia.org/wikipedia/commons/4/45/Spain_national_football_team_Euro_2012_final.jpg" overlay="badge" gravity="faces" width="0.1" flags="relative" type="fetch">
        <Transformation overlay="badge" gravity="faces" width=0.1 flags="relative" />
</Image>
Angular:
<cl-image public-id="http://upload.wikimedia.org/wikipedia/commons/4/45/Spain_national_football_team_Euro_2012_final.jpg" overlay="badge" gravity="faces" width="0.1" flags="relative" type="fetch">
        <cl-transformation overlay="badge" gravity="faces" width=0.1 flags="relative" />
</cl-image>
.Net:
cloudinary.Api.UrlImgUp.Transform(new Transformation().Overlay("badge").Gravity("faces").Width(0.1).Flags("relative")).Type("fetch").BuildImageTag("http://upload.wikimedia.org/wikipedia/commons/4/45/Spain_national_football_team_Euro_2012_final.jpg")
Faces overlay

Cloudinary can even take this one step further with the option of automatically positioning the badges and resizing them to cover 100% of the width & height of each detected face. This is done by setting the flags parameter to region_relative, fl_region_relative in URLs). By doing so, all overlays will be stretched to cover the whole face:

Ruby:
cl_image_tag("http://upload.wikimedia.org/wikipedia/commons/4/45/Spain_national_football_team_Euro_2012_final.jpg", :overlay=>"badge", :gravity=>"faces", :width=>1.0, :height=>1.0, :flags=>"region_relative", :type=>"fetch")
PHP:
cl_image_tag("http://upload.wikimedia.org/wikipedia/commons/4/45/Spain_national_football_team_Euro_2012_final.jpg", array("overlay"=>"badge", "gravity"=>"faces", "width"=>1.0, "height"=>1.0, "flags"=>"region_relative", "type"=>"fetch"))
Python:
CloudinaryImage("http://upload.wikimedia.org/wikipedia/commons/4/45/Spain_national_football_team_Euro_2012_final.jpg").image(overlay="badge", gravity="faces", width=1.0, height=1.0, flags="region_relative", type="fetch")
Node.js:
cloudinary.image("http://upload.wikimedia.org/wikipedia/commons/4/45/Spain_national_football_team_Euro_2012_final.jpg", {overlay: "badge", gravity: "faces", width: 1.0, height: 1.0, flags: "region_relative", type: "fetch"})
Java:
cloudinary.url().transformation(new Transformation().overlay("badge").gravity("faces").width(1.0).height(1.0).flags("region_relative")).type("fetch").imageTag("http://upload.wikimedia.org/wikipedia/commons/4/45/Spain_national_football_team_Euro_2012_final.jpg")
JS:
cl.imageTag('http://upload.wikimedia.org/wikipedia/commons/4/45/Spain_national_football_team_Euro_2012_final.jpg', {overlay: "badge", gravity: "faces", width: 1.0, height: 1.0, flags: "region_relative", type: "fetch"}).toHtml();
jQuery:
$.cloudinary.image("http://upload.wikimedia.org/wikipedia/commons/4/45/Spain_national_football_team_Euro_2012_final.jpg", {overlay: "badge", gravity: "faces", width: 1.0, height: 1.0, flags: "region_relative", type: "fetch"})
React:
<Image publicId="http://upload.wikimedia.org/wikipedia/commons/4/45/Spain_national_football_team_Euro_2012_final.jpg" overlay="badge" gravity="faces" width="1.0" height="1.0" flags="region_relative" type="fetch">
        <Transformation overlay="badge" gravity="faces" width=1.0 height=1.0 flags="region_relative" />
</Image>
Angular:
<cl-image public-id="http://upload.wikimedia.org/wikipedia/commons/4/45/Spain_national_football_team_Euro_2012_final.jpg" overlay="badge" gravity="faces" width="1.0" height="1.0" flags="region_relative" type="fetch">
        <cl-transformation overlay="badge" gravity="faces" width=1.0 height=1.0 flags="region_relative" />
</cl-image>
.Net:
cloudinary.Api.UrlImgUp.Transform(new Transformation().Overlay("badge").Gravity("faces").Width(1.0).Height(1.0).Flags("region_relative")).Type("fetch").BuildImageTag("http://upload.wikimedia.org/wikipedia/commons/4/45/Spain_national_football_team_Euro_2012_final.jpg")
Cover 100% of all faces

This powerful feature can be used to create some funny effects:

Ruby:
cl_image_tag("http://upload.wikimedia.org/wikipedia/commons/4/45/Spain_national_football_team_Euro_2012_final.jpg", :overlay=>"cat.png", :gravity=>"faces", :width=>100, :effect=>"vignette", :type=>"fetch")
PHP:
cl_image_tag("http://upload.wikimedia.org/wikipedia/commons/4/45/Spain_national_football_team_Euro_2012_final.jpg", array("overlay"=>"cat.png", "gravity"=>"faces", "width"=>100, "effect"=>"vignette", "type"=>"fetch"))
Python:
CloudinaryImage("http://upload.wikimedia.org/wikipedia/commons/4/45/Spain_national_football_team_Euro_2012_final.jpg").image(overlay="cat.png", gravity="faces", width=100, effect="vignette", type="fetch")
Node.js:
cloudinary.image("http://upload.wikimedia.org/wikipedia/commons/4/45/Spain_national_football_team_Euro_2012_final.jpg", {overlay: "cat.png", gravity: "faces", width: 100, effect: "vignette", type: "fetch"})
Java:
cloudinary.url().transformation(new Transformation().overlay("cat.png").gravity("faces").width(100).effect("vignette")).type("fetch").imageTag("http://upload.wikimedia.org/wikipedia/commons/4/45/Spain_national_football_team_Euro_2012_final.jpg")
JS:
cl.imageTag('http://upload.wikimedia.org/wikipedia/commons/4/45/Spain_national_football_team_Euro_2012_final.jpg', {overlay: "cat.png", gravity: "faces", width: 100, effect: "vignette", type: "fetch"}).toHtml();
jQuery:
$.cloudinary.image("http://upload.wikimedia.org/wikipedia/commons/4/45/Spain_national_football_team_Euro_2012_final.jpg", {overlay: "cat.png", gravity: "faces", width: 100, effect: "vignette", type: "fetch"})
React:
<Image publicId="http://upload.wikimedia.org/wikipedia/commons/4/45/Spain_national_football_team_Euro_2012_final.jpg" overlay="cat.png" gravity="faces" width="100" effect="vignette" type="fetch">
        <Transformation overlay="cat.png" gravity="faces" width=100 effect="vignette" />
</Image>
Angular:
<cl-image public-id="http://upload.wikimedia.org/wikipedia/commons/4/45/Spain_national_football_team_Euro_2012_final.jpg" overlay="cat.png" gravity="faces" width="100" effect="vignette" type="fetch">
        <cl-transformation overlay="cat.png" gravity="faces" width=100 effect="vignette" />
</cl-image>
.Net:
cloudinary.Api.UrlImgUp.Transform(new Transformation().Overlay("cat.png").Gravity("faces").Width(100).Effect("vignette")).Type("fetch").BuildImageTag("http://upload.wikimedia.org/wikipedia/commons/4/45/Spain_national_football_team_Euro_2012_final.jpg")
Funny overlay

by Itay Taragano