Whether your web application supports user uploaded images, you deliver static images, or you display profile pictures from social networks, you probably need to manipulate them to fit the graphic design of your Web site or mobile application.
Cloudinary allows you to easily transform your images on-the-fly to any required format, style and dimension, and also optimizes images for minimal file size alongside high visual quality for an improved user experience and minimal bandwidth. You can do all of this by implementing dynamic image transformation and delivery URLs. You can change the required transformations at any time. All transformed images are created on-demand (lazily) and delivered to your users through a fast CDN with optimized caching.
For example, you can resize and crop images, deliver them using the image format that fits your needs, and/or apply a variety of filters and effects. You can also use our smart cropping techniques, including face-detection or auto-gravity for cropping based on the most relevant parts of uploaded photos. For complex transformations, you can use the Management Console or Admin API for defining named transformations and even run a set of chained transformations on your images. You can also use the Management Console to view delivery usage reports and optimization insights.
This page teaches you how Cloudinary transformations work and provides detailed descriptions and use‑case examples for commonly-used transformations.
Note
Your account's pricing plan is in part dependent on the total number of
transformation operations performed during a billing cycle. These are primarily counted when Cloudinary generates a new 'derived resource' from an asset based on a transformation URL. For complete details on how transformations are counted, see
Transformation Counts.
The following dynamic URL with on-the-fly image transformation crops an image to a 400x400 circular thumbnail while automatically focusing on the face, and then scales down the result to a width of 200 pixels. Below you can see the original image (scaled down) and the dynamically created face detection based thumbnail.
Ruby:
cl_image_tag("lady.jpg", :transformation=>[
{:width=>400, :height=>400, :gravity=>"face", :radius=>"max", :crop=>"crop"},
{:width=>200, :crop=>"scale"}
])
PHP:
cl_image_tag("lady.jpg", array("transformation"=>array(
array("width"=>400, "height"=>400, "gravity"=>"face", "radius"=>"max", "crop"=>"crop"),
array("width"=>200, "crop"=>"scale")
)))
Python:
CloudinaryImage("lady.jpg").image(transformation=[
{'width': 400, 'height': 400, 'gravity': "face", 'radius': "max", 'crop': "crop"},
{'width': 200, 'crop': "scale"}
])
Node.js:
cloudinary.image("lady.jpg", {transformation: [
{width: 400, height: 400, gravity: "face", radius: "max", crop: "crop"},
{width: 200, crop: "scale"}
]})
Java:
cloudinary.url().transformation(new Transformation()
.width(400).height(400).gravity("face").radius("max").crop("crop").chain()
.width(200).crop("scale")).imageTag("lady.jpg");
JS:
cloudinary.imageTag('lady.jpg', {transformation: [
{width: 400, height: 400, gravity: "face", radius: "max", crop: "crop"},
{width: 200, crop: "scale"}
]}).toHtml();
jQuery:
$.cloudinary.image("lady.jpg", {transformation: [
{width: 400, height: 400, gravity: "face", radius: "max", crop: "crop"},
{width: 200, crop: "scale"}
]})
React:
<Image publicId="lady.jpg" >
<Transformation width="400" height="400" gravity="face" radius="max" crop="crop" />
<Transformation width="200" crop="scale" />
</Image>
Vue.js:
<cld-image publicId="lady.jpg" >
<cld-transformation width="400" height="400" gravity="face" radius="max" crop="crop" />
<cld-transformation width="200" crop="scale" />
</cld-image>
Angular:
<cl-image public-id="lady.jpg" >
<cl-transformation width="400" height="400" gravity="face" radius="max" crop="crop">
</cl-transformation>
<cl-transformation width="200" crop="scale">
</cl-transformation>
</cl-image>
.Net:
cloudinary.Api.UrlImgUp.Transform(new Transformation()
.Width(400).Height(400).Gravity("face").Radius("max").Crop("crop").Chain()
.Width(200).Crop("scale")).BuildImageTag("lady.jpg")
Android:
MediaManager.get().url().transformation(new Transformation()
.width(400).height(400).gravity("face").radius("max").crop("crop").chain()
.width(200).crop("scale")).generate("lady.jpg");
iOS:
imageView.cldSetImage(cloudinary.createUrl().setTransformation(CLDTransformation()
.setWidth(400).setHeight(400).setGravity("face").setRadius("max").setCrop("crop").chain()
.setWidth(200).setCrop("scale")).generate("lady.jpg")!, cloudinary: cloudinary)
Cloudinary's client libraries (SDKs) take care of the transformation URL building for you, and simplify the integration even further. They allow you to continue working in your preferred developer framework and provide helper methods to simplify building image tags and image transformation URLs: Rails, PHP, Django, JavaScript, jQuery, Node.js, .NET, Java, Angular, Javascript, React, Vue.js, iOS, Scala and Android.
Accessing media assets is done using simple delivery HTTP or HTTPS URLs which are then delivered to users via a worldwide fast CDN. The URL contains the Public ID of the requested asset plus any optional transformation parameters. The public ID is the unique identifier of the asset and is either specified when uploading the asset to your Cloudinary account, or automatically assigned by Cloudinary (see Upload images for more details on the various options for specifying the public ID).
The Cloudinary asset delivery URL takes the following structure:
https://res.cloudinary.com/<cloud_name>/<resource_type>/<type>/<transformations>/<version>/<public_id>.<format>
Where:
cloud_name - The name of your Cloudinary account, a unique public identifier for URL building and API access.resource_type - (optional) The type of asset to deliver. Default: image. Valid values: image, raw, or video type - (optional) The delivery type. Default: upload. For details on all possible types, see Delivery types.transformations (optional) One or more transformation parameters in a single component, or a set of chained transformations in multiple components. When the transformation URL is first accessed, the derived media file is created on-the-fly and delivered to your user. The derived file is also cached on the CDN and is immediately available to all subsequent users requesting the same asset. version - (optional) You can add the version to your delivery URL to bypass the cached version on the CDN and force delivery of the latest resource (in the case that a resource has been overwritten with a newer file). For simplicity, the version component is generally not included in the example URLs on this page. For details, see Asset versions.public_id - The unique identifier of the resource, including the folder structure if defined.format - (optional) The file extension of the requested delivery format for the resource. Default: The originally uploaded format or the format determined by f_auto, when used.
Therefore, in the most general case of delivering an image that has been uploaded to your Cloudinary account, the delivery URL is given as:
https://res.cloudinary.com/<cloud_name>/image/upload/<public_id>.<format>
For example, displaying the image with a public ID of sample uploaded to Cloudinary's demo account in jpg format:
Ruby:
cl_image_tag("sample.jpg")
PHP:
cl_image_tag("sample.jpg")
Python:
CloudinaryImage("sample.jpg").image()
Node.js:
cloudinary.image("sample.jpg")
Java:
cloudinary.url().imageTag("sample.jpg");
JS:
cloudinary.imageTag('sample.jpg').toHtml();
jQuery:
$.cloudinary.image("sample.jpg")
React:
<Image publicId="sample.jpg" >
</Image>
Vue.js:
<cld-image publicId="sample.jpg" >
</cld-image>
Angular:
<cl-image public-id="sample.jpg" >
</cl-image>
.Net:
cloudinary.Api.UrlImgUp.BuildImageTag("sample.jpg")
Android:
MediaManager.get().url().generate("sample.jpg");
iOS:
imageView.cldSetImage(cloudinary.createUrl().generate("sample.jpg")!, cloudinary: cloudinary)
Any transformation (manipulation) instructions can be added before the public ID in the delivery URL. When the URL is first accessed, the derived image is created on-the-fly and delivered to your user. The derived image is also cached on the CDN and is immediately available to all subsequent users requesting the same image.
The following shows an example of delivering an image with transformation parameters, where the image with a public ID of sample is cropped to a width of 300 pixels and a height of 200 pixels, and delivered in JPEG format:
Ruby:
cl_image_tag("sample.jpg", :width=>300, :height=>200, :crop=>"crop")
PHP:
cl_image_tag("sample.jpg", array("width"=>300, "height"=>200, "crop"=>"crop"))
Python:
CloudinaryImage("sample.jpg").image(width=300, height=200, crop="crop")
Node.js:
cloudinary.image("sample.jpg", {width: 300, height: 200, crop: "crop"})
Java:
cloudinary.url().transformation(new Transformation().width(300).height(200).crop("crop")).imageTag("sample.jpg");
JS:
cloudinary.imageTag('sample.jpg', {width: 300, height: 200, crop: "crop"}).toHtml();
jQuery:
$.cloudinary.image("sample.jpg", {width: 300, height: 200, crop: "crop"})
React:
<Image publicId="sample.jpg" >
<Transformation width="300" height="200" crop="crop" />
</Image>
Vue.js:
<cld-image publicId="sample.jpg" >
<cld-transformation width="300" height="200" crop="crop" />
</cld-image>
Angular:
<cl-image public-id="sample.jpg" >
<cl-transformation width="300" height="200" crop="crop">
</cl-transformation>
</cl-image>
.Net:
cloudinary.Api.UrlImgUp.Transform(new Transformation().Width(300).Height(200).Crop("crop")).BuildImageTag("sample.jpg")
Android:
MediaManager.get().url().transformation(new Transformation().width(300).height(200).crop("crop")).generate("sample.jpg");
iOS:
imageView.cldSetImage(cloudinary.createUrl().setTransformation(CLDTransformation().setWidth(300).setHeight(200).setCrop("crop")).generate("sample.jpg")!, cloudinary: cloudinary)
You can also use shortcut URLs when specifically delivering image files using the default upload type. With Cloudinary’s Root Path URL feature, the resource type and type parameters can be omitted from the URL (they automatically default to the values 'image' and 'upload' respectively). For example, the Root Path shortcut delivery URL for the cropped image above is:
https://res.cloudinary.com/demo/w_300,h_200,c_crop/sample.jpg
The rest of this page describes the various types of available transformation and delivery options, including many detailed use-case examples. See the Image Transformation Reference table and Video Transformation Reference for the complete list of available transformation parameters and syntax.
Cloudinary supports delivering media assets using HTTPS URLs. The process for creating HTTPS delivery URLs is identical to creating HTTP URLs, with only the URL protocol changing. When using one of Cloudinary's framework SDKs, you can generate HTTPS URLs by setting the secure parameter to true, either globally (e.g., in the CLOUDINARY_URL environment variable) or locally in each call. For example, delivering the sample image with HTTPS:
Ruby:
cl_image_tag("sample.jpg", :secure=>true)
PHP:
cl_image_tag("sample.jpg", array("secure"=>true))
Python:
CloudinaryImage("sample.jpg").image(secure=True)
Node.js:
cloudinary.image("sample.jpg", {secure: true})
Java:
cloudinary.url().secure(true).imageTag("sample.jpg");
JS:
cloudinary.imageTag('sample.jpg', {secure: true}).toHtml();
jQuery:
$.cloudinary.image("sample.jpg", {secure: true})
React:
<Image publicId="sample.jpg" secure="true">
</Image>
Vue.js:
<cld-image publicId="sample.jpg" secure="true">
</cld-image>
Angular:
<cl-image public-id="sample.jpg" secure="true">
</cl-image>
.Net:
cloudinary.Api.UrlImgUp.Secure(true).BuildImageTag("sample.jpg")
Android:
MediaManager.get().url().secure(true).generate("sample.jpg");
iOS:
imageView.cldSetImage(cloudinary.createUrl().generate("sample.jpg")!, cloudinary: cloudinary)
For more information on using HTTPS to deliver your media assets, see the article on Why isn't everyone using HTTPS and how to do it with Cloudinary.
The delivery type element of the URL provides an indication about the way the asset will be delivered, although in most cases, the delivery type value is determined at the time that the asset is stored in your account.
The following delivery type values are supported:
| Delivery type |
Description |
Learn more |
| upload |
The default delivery type for uploaded assets. In most cases, this delivery type indicates that the asset is publicly available. However, there are options you can use to restrict access to assets with an upload delivery type. This includes strict transformations and access mode settings) |
Upload API |
| private |
The URL for the original asset can be accessed only with a signed URL. Transformed versions of the asset are publicly available (unless strict transformations are also defined). |
Uploading private assets |
| authenticated |
Both original and transformed versions of the asset can be accessed only with a signed URL or an authentication token. |
Uploading authenticated assets
Delivering authenticated assets |
| fetch |
Enables transforming and delivering remote images on-the-fly. |
Fetch remote images |
facebook
twitter
twitter_name instagram
gravatar |
Fetches a profile picture from Facebook, Twitter, or other specified social delivery type based on a specified ID or name. |
Social media profile pictures |
youtube
hulu
vimeo
animoto
worldstarhiphop
dailymotion |
Delivers a thumbnail image generated from the specified video from a public video site. |
Fetching thumbnails of public videos |
| multi |
Enables you to deliver a single animated image (GIF, PNG or WebP) from all image assets that have been assigned a specified tag. |
Multi method
Creating animated images |
| text |
Enables you to generate an image in your account from a specified textual string along with style parameters for use as an image overlay. |
Text method |
| asset |
Relevant only for the Ruby on Rails SDK. Delivers files that were uploaded using the sync_static command. |
Static files |
| list |
Generates a list of resources with a specified tag.
Note: This isn't a delivery type in the classic sense, in that it doesn't relate to an individual asset. However, to use this feature, you specify list in the delivery type element of the URL. |
Client-side resource lists |
Tip
You can search for assets by delivery type using the Advanced Search in the Media Library. The most common types can be selected directly in the
Type section of the
Tags & Metadata search tab. All other types can be selected from the
More types list.
In addition to changing the appearance of your media assets by transforming them, you can also use Cloudinary URLs and a variety of parameters to control how they are delivered:
- Optimizations - Deliver your media assets with the smallest possible file size while maintaining visual quality, saving bandwidth and improving performance for your website.
- Responsive images - Deliver your images to perfectly fit any device, window size, orientation, or resolution at any pixel density (DPR). Upload a single high resolution image and let Cloudinary automatically transform it.
- Remotely fetched media - Grab media assets from anywhere on the web, including support for on-the-fly manipulation and optimized delivery via a CDN.
- Paged and layered media - Deliver content from assets with multiple pages or layers such as PDFs or Photoshop files, including options for delivering or transforming only selected pages or layers.
- Access control - Control who can access your media, both the originals and transformed assets.
Accessing uploaded images or their derived transformations is done using simple URLs that you can use as the 'src' of the 'img' tags in your HTML code or Javascript functions. URLs for accessing resources contain the resource kind, the Public ID of the resource, and optional version and transformation parameters. You can also use Cloudinary’s web framework SDKs to aid you in adding images to your web application and simplify the creation of transformation URLs and embedding HTML image tags. Cloudinary offers two main helper methods in this regard:
The Cloudinary URL helper method (e.g., cloudinary_url in Ruby on Rails) automatically generates the image source URL for use as the 'src' of the 'img' tags in your HTML code or Javascript functions. For example, using the URL helper method to return the URL of the sample image, scaled to a width of 300 pixels and a height of 100 pixels:
Ruby:
cloudinary_url("sample.jpg", :width=>300, :height=>100, :crop=>"scale")
PHP:
Cloudinary::cloudinary_url("sample.jpg", array("width"=>300, "height"=>100, "crop"=>"scale"))
Python:
cloudinary.utils.cloudinary_url("sample.jpg", width=300, height=100, crop="scale")
Node.js:
cloudinary.url("sample.jpg", {width: 300, height: 100, crop: "scale"})
Java:
cloudinary.url().transformation(new Transformation().width(300).height(100).crop("scale")).generate("sample.jpg")
JS:
cloudinary.url('sample.jpg', {width: 300, height: 100, crop: "scale"});
jQuery:
$.cloudinary.url("sample.jpg", {width: 300, height: 100, crop: "scale"})
React:
cloudinary.url('sample.jpg', {width: 300, height: 100, crop: "scale"});
Vue.js:
cloudinary.url('sample.jpg', {width: 300, height: 100, crop: "scale"});
Angular:
cloudinary.url('sample.jpg', {width: 300, height: 100, crop: "scale"});
.Net:
cloudinary.Api.UrlImgUp.Transform(new Transformation().Width(300).Height(100).Crop("scale")).BuildUrl("sample.jpg")
Android:
MediaManager.get().url().transformation(new Transformation().width(300).height(100).crop("scale")).generate("sample.jpg");
iOS:
cloudinary.createUrl().setTransformation(CLDTransformation().setWidth(300).setHeight(100).setCrop("scale")).generate("sample.jpg")
The Cloudinary Image Tag helper method (e.g., cl_image_tag in Ruby on Rails) automatically generates an HTML image tag including the image source URL. For example, using the Image Tag helper method to create an HTML image tag for the sample image, scaled to a width of 300 pixels and a height of 100 pixels:
Ruby:
cl_image_tag("sample.jpg", :width=>300, :height=>100, :crop=>"scale")
PHP:
cl_image_tag("sample.jpg", array("width"=>300, "height"=>100, "crop"=>"scale"))
Python:
CloudinaryImage("sample.jpg").image(width=300, height=100, crop="scale")
Node.js:
cloudinary.image("sample.jpg", {width: 300, height: 100, crop: "scale"})
Java:
cloudinary.url().transformation(new Transformation().width(300).height(100).crop("scale")).imageTag("sample.jpg");
JS:
cloudinary.imageTag('sample.jpg', {width: 300, height: 100, crop: "scale"}).toHtml();
jQuery:
$.cloudinary.image("sample.jpg", {width: 300, height: 100, crop: "scale"})
React:
<Image publicId="sample.jpg" >
<Transformation width="300" height="100" crop="scale" />
</Image>
Vue.js:
<cld-image publicId="sample.jpg" >
<cld-transformation width="300" height="100" crop="scale" />
</cld-image>
Angular:
<cl-image public-id="sample.jpg" >
<cl-transformation width="300" height="100" crop="scale">
</cl-transformation>
</cl-image>
.Net:
cloudinary.Api.UrlImgUp.Transform(new Transformation().Width(300).Height(100).Crop("scale")).BuildImageTag("sample.jpg")
Android:
MediaManager.get().url().transformation(new Transformation().width(300).height(100).crop("scale")).generate("sample.jpg");
iOS:
imageView.cldSetImage(cloudinary.createUrl().setTransformation(CLDTransformation().setWidth(300).setHeight(100).setCrop("scale")).generate("sample.jpg")!, cloudinary: cloudinary)
The Cloudinary Image Tag helper method allows you to not only specify any Cloudinary transformations parameters, but also to specify regular HTML image tag attributes (e.g., alt, title, width, height). For example, using the Image Tag helper method to create an HTML image tag for the sample image, with the 'alt' attribute set to "A sample photo" and the 'className' attribute set to "Samples":
Ruby:
cl_image_tag("sample.jpg", :alt=>"A sample photo", :className=>"Samples")
PHP:
cl_image_tag("sample.jpg", array("alt"=>"A sample photo", "className"=>"Samples"))
Python:
CloudinaryImage("sample.jpg").image(alt="A sample photo", className="Samples")
Node.js:
cloudinary.image("sample.jpg", {alt: "A sample photo", className: "Samples"})
Java:
cloudinary.url().imageTag("sample.jpg", ObjectUtils.asMap("alt","A sample photo","className","Samples"));
JS:
cl.imageTag('sample.jpg', {alt: "A sample photo", className: "Samples"}).toHtml();
jQuery:
$.cloudinary.image("sample.jpg", {alt: "A sample photo", className: "Samples"})
React:
<Image publicId="sample.jpg" alt="A sample photo" className="Samples">
</Image>
Vue.js:
js
<CLDImage publicId="sample.jpg" alt="A sample photo" className="Samples">
</CLDImage>
Angular:
<cl-image public-id="sample.jpg" alt="A sample photo" className="Samples">
</cl-image>
Note
In general, when using the SDK helper methods, you will probably take advantage of the SDK parameter names for improved readability and maintenance of your code. However, you can also optionally pass a
raw_transformation parameter, whose value is a literal URL transformation definition. For example, in Ruby:
cl_image_tag("flower.jpg",
:transformation=>[{:raw_transformation=> "o_90,w_1000,c_fill,g_south_east/l_my_image,fl_relative,w_1.0"}])
The string you pass as the raw_transformation value will be appended as is (with no processing or validation) to the end of any other transformation parameters passed in the same component of the transformation chain.
For more information on these SDK helper methods, see the documentation for the relevant framework: Ruby on Rails, PHP, Django, Node.js, Java, .NET, Angular, Javascript, React, Vue.js, iOS, Scala and Android.
Images can be uploaded to Cloudinary in various formats (input formats), and you can easily convert these images to other formats for displaying in your web site or application (output formats). Examples of situations where you might want to change the delivered image format:
- Delivering JPEGs for photos that you want to load quickly (or WebP if your users are on a Chrome browser or on a mobile app you control).
- Delivering a GIF if the image contains a drawing with only a few colors.
- Delivering a PNG (24 bit) for high quality illustrations with a transparent background.
- Delivering an image where the original format is not supported for delivery by the browser. For example, you could deliver a Photoshop (.psd) image as a JPG.
To deliver images in a different format simply specify the new format as the file extension of the delivery URL. When using our SDKs you can either specify the new format as an extension to the resource name or use the format parameter.
For example, to display a GIF version of the uploaded sample JPEG file:
Ruby:
cl_image_tag("sample.gif")
PHP:
cl_image_tag("sample.gif")
Python:
CloudinaryImage("sample.gif").image()
Node.js:
cloudinary.image("sample.gif")
Java:
cloudinary.url().imageTag("sample.gif");
JS:
cloudinary.imageTag('sample.gif').toHtml();
jQuery:
$.cloudinary.image("sample.gif")
React:
<Image publicId="sample.gif" >
</Image>
Vue.js:
<cld-image publicId="sample.gif" >
</cld-image>
Angular:
<cl-image public-id="sample.gif" >
</cl-image>
.Net:
cloudinary.Api.UrlImgUp.BuildImageTag("sample.gif")
Android:
MediaManager.get().url().generate("sample.gif");
iOS:
imageView.cldSetImage(cloudinary.createUrl().generate("sample.gif")!, cloudinary: cloudinary)
You can easily combine other image transformations with format conversion. Just make sure the format you use is supported for transformations, as per the table above. For example, to deliver a scaled down 150x100 GIF version of the sample image:
Ruby:
cl_image_tag("sample.gif", :width=>150, :height=>100, :crop=>"scale")
PHP:
cl_image_tag("sample.gif", array("width"=>150, "height"=>100, "crop"=>"scale"))
Python:
CloudinaryImage("sample.gif").image(width=150, height=100, crop="scale")
Node.js:
cloudinary.image("sample.gif", {width: 150, height: 100, crop: "scale"})
Java:
cloudinary.url().transformation(new Transformation().width(150).height(100).crop("scale")).imageTag("sample.gif");
JS:
cloudinary.imageTag('sample.gif', {width: 150, height: 100, crop: "scale"}).toHtml();
jQuery:
$.cloudinary.image("sample.gif", {width: 150, height: 100, crop: "scale"})
React:
<Image publicId="sample.gif" >
<Transformation width="150" height="100" crop="scale" />
</Image>
Vue.js:
<cld-image publicId="sample.gif" >
<cld-transformation width="150" height="100" crop="scale" />
</cld-image>
Angular:
<cl-image public-id="sample.gif" >
<cl-transformation width="150" height="100" crop="scale">
</cl-transformation>
</cl-image>
.Net:
cloudinary.Api.UrlImgUp.Transform(new Transformation().Width(150).Height(100).Crop("scale")).BuildImageTag("sample.gif")
Android:
MediaManager.get().url().transformation(new Transformation().width(150).height(100).crop("scale")).generate("sample.gif");
iOS:
imageView.cldSetImage(cloudinary.createUrl().setTransformation(CLDTransformation().setWidth(150).setHeight(100).setCrop("scale")).generate("sample.gif")!, cloudinary: cloudinary)
Notes
- If the file extension is omitted from the delivery URL then the file is delivered in the originally uploaded format.
- Only the first 100 pages are included in the new file when converting from one multi-page or multi-layer image format (PDF, GIF, WebP, TIFF, PSD) to another.
The table below summarizes the supported format types.
| Format |
Extensions |
Supported for Upload 1 |
Supported for Transformations 2 |
| AI (Adobe Illustrator) |
.ai |
Yes |
Yes |
| animated GIF |
.gif |
Yes |
Yes |
| animated WebP |
.webp |
Yes |
Yes |
| BMP |
.bmp |
Yes |
Yes |
| DjVu |
.djvu |
Yes |
No |
| EPS (Encapsulated PostScript) |
.ps, .ept, .eps, .eps3 |
Yes |
Yes |
| FBX (Filmbox) |
.fbx |
Yes |
Yes 6 |
| FLIF (Free Lossless Image Format) |
.flif |
Yes |
Yes |
| GIF |
.gif |
Yes |
Yes |
| glTF (GL Transmission Format) |
.gltf |
Yes |
Yes 6 |
| HEIF |
.heif, .heic |
Yes |
Yes |
| ICO |
.ico |
Yes |
Yes |
| InDesign |
.indd |
Yes |
Yes 3 |
| JPEG |
.jpg, .jpe, .jpeg |
Yes |
Yes |
| JPEG 2000 |
.jp2 4 |
Yes |
Yes |
| JPEG XR (JPEG eXtended Range) |
.wdp, .jxr, .hdp |
Yes |
Yes |
| PDF |
.pdf |
Yes |
Yes |
| PNG |
.png |
Yes |
Yes |
| PSD (PhotoShop Document) |
.psd |
Yes |
Yes 5 |
| Raw image files |
.arw, .cr2 |
Yes |
No |
| SVG |
.svg |
Yes |
Yes |
| TARGA (Truevision TGA) |
.tga |
Yes |
Yes |
| TIFF |
.tif, .tiff |
Yes |
Yes |
| WebP |
.webp |
Yes |
Yes |
Footnotes
If a format is supported only for upload, then the delivery URL enables a user to download the original file in its original format, but you cannot apply transformation parameters.
If a format is supported for transformations, but the browser doesn't support displaying that format, you can either provide the transformation URL with the original format to enable users to download the file, or you can provide the URL with a different delivery format specified. In that case, Cloudinary applies the transformation to the original format and then converts the image to the requested format for delivery. For example, you could provide a transformation URL for a PhotoShop (.psd) image stored in your account and specify jpg as the delivery format to display the resulting transformation in the browser.
You can transform an InDesign file if you deliver it as an image format, such as jpg or png, but you cannot deliver an indd file with transformations.
By default, when you request a jp2 image with a quality value less than 90, chroma sub-sampling (420) is automatically applied using Kakadu. You can also explicitly request chroma sub-sampling as part of your quality parameter. For example: q_90>:420.
All layers are flattened into a single image if no page parameter is specified.
The 3D format types are uploaded as a zip file. Some transformations, such as converting to a video or image, are supported on the bundle as a whole. No transformations are currently supported on its contained assets.
Another option for changing the format is to explicitly call the fetch_format parameter (f in URLs). This can be useful in situations where you cannot change the file extension, for example, when fetching remote images that already have a different file extension (format) as part of their URLs.
For example, to fetch a remote image from Wikimedia in JPEG format, and deliver the image in PNG format (also scaled down to a width of 400 pixels):
Ruby:
cl_image_tag("https://upload.wikimedia.org/wikipedia/commons/4/46/Jennifer_Lawrence_at_the_83rd_Academy_Awards.jpg", :width=>400, :crop=>"scale", :format=>"png", :type=>"fetch")
PHP:
cl_image_tag("https://upload.wikimedia.org/wikipedia/commons/4/46/Jennifer_Lawrence_at_the_83rd_Academy_Awards.jpg", array("width"=>400, "crop"=>"scale", "format"=>"png", "type"=>"fetch"))
Python:
CloudinaryImage("https://upload.wikimedia.org/wikipedia/commons/4/46/Jennifer_Lawrence_at_the_83rd_Academy_Awards.jpg").image(width=400, crop="scale", format="png", type="fetch")
Node.js:
cloudinary.image("https://upload.wikimedia.org/wikipedia/commons/4/46/Jennifer_Lawrence_at_the_83rd_Academy_Awards.jpg", {width: 400, crop: "scale", format: "png", type: "fetch"})
Java:
cloudinary.url().transformation(new Transformation().width(400).crop("scale")).format("png").type("fetch").imageTag("https://upload.wikimedia.org/wikipedia/commons/4/46/Jennifer_Lawrence_at_the_83rd_Academy_Awards.jpg");
JS:
cloudinary.imageTag('https://upload.wikimedia.org/wikipedia/commons/4/46/Jennifer_Lawrence_at_the_83rd_Academy_Awards.jpg', {width: 400, crop: "scale", format: "png", type: "fetch"}).toHtml();
jQuery:
$.cloudinary.image("https://upload.wikimedia.org/wikipedia/commons/4/46/Jennifer_Lawrence_at_the_83rd_Academy_Awards.jpg", {width: 400, crop: "scale", format: "png", type: "fetch"})
React:
<Image publicId="https://upload.wikimedia.org/wikipedia/commons/4/46/Jennifer_Lawrence_at_the_83rd_Academy_Awards.jpg" format="png" type="fetch">
<Transformation width="400" crop="scale" />
</Image>
Vue.js:
<cld-image publicId="https://upload.wikimedia.org/wikipedia/commons/4/46/Jennifer_Lawrence_at_the_83rd_Academy_Awards.jpg" format="png" type="fetch">
<cld-transformation width="400" crop="scale" />
</cld-image>
Angular:
<cl-image public-id="https://upload.wikimedia.org/wikipedia/commons/4/46/Jennifer_Lawrence_at_the_83rd_Academy_Awards.jpg" format="png" type="fetch">
<cl-transformation width="400" crop="scale">
</cl-transformation>
</cl-image>
.Net:
cloudinary.Api.UrlImgUp.Transform(new Transformation().Width(400).Crop("scale")).Format("png").Type("fetch").BuildImageTag("https://upload.wikimedia.org/wikipedia/commons/4/46/Jennifer_Lawrence_at_the_83rd_Academy_Awards.jpg")
Android:
MediaManager.get().url().transformation(new Transformation().width(400).crop("scale")).format("png").type("fetch").generate("https://upload.wikimedia.org/wikipedia/commons/4/46/Jennifer_Lawrence_at_the_83rd_Academy_Awards.jpg");
iOS:
imageView.cldSetImage(cloudinary.createUrl().setFormat("png").setType( "fetch").setTransformation(CLDTransformation().setWidth(400).setCrop("scale")).generate("https://upload.wikimedia.org/wikipedia/commons/4/46/Jennifer_Lawrence_at_the_83rd_Academy_Awards.jpg")!, cloudinary: cloudinary)
There are a lot of formats for encoding images, with some formats better than others at compression and reducing the file size without impairing visual quality. Since different browsers support different image formats, the best solution to save bandwidth and optimize delivery time would be to deliver the best format according to the browser used by each of your visitors.
The fetch_format parameter can be set to auto (f_auto in URLs) in order to perform automatic format selection based on the requesting browser. For example, with the automatic format feature, in most cases Chrome users would receive a WebP, Internet Explorer users would receive a JPEG-XR, and Safari users would receive a JPEG-2000. If a browser does not support any of these formats then the image is delivered in the format specified by the file extension.
For example, the uploaded jpg image named sample scaled down to a width of 500 pixels and delivered as WebP to Chrome browsers (22.4 KB), JPEG-XR to Internet Explorer browsers (48 KB), or as a regular JPEG (57.5 KB) to browsers that support neither format:
Ruby:
cl_image_tag("sample.jpg", :width=>500, :fetch_format=>:auto, :crop=>"scale")
PHP:
cl_image_tag("sample.jpg", array("width"=>500, "fetch_format"=>"auto", "crop"=>"scale"))
Python:
CloudinaryImage("sample.jpg").image(width=500, fetch_format="auto", crop="scale")
Node.js:
cloudinary.image("sample.jpg", {width: 500, fetch_format: "auto", crop: "scale"})
Java:
cloudinary.url().transformation(new Transformation().width(500).fetchFormat("auto").crop("scale")).imageTag("sample.jpg");
JS:
cloudinary.imageTag('sample.jpg', {width: 500, fetchFormat: "auto", crop: "scale"}).toHtml();
jQuery:
$.cloudinary.image("sample.jpg", {width: 500, fetch_format: "auto", crop: "scale"})
React:
<Image publicId="sample.jpg" >
<Transformation width="500" fetchFormat="auto" crop="scale" />
</Image>
Vue.js:
<cld-image publicId="sample.jpg" >
<cld-transformation width="500" fetchFormat="auto" crop="scale" />
</cld-image>
Angular:
<cl-image public-id="sample.jpg" >
<cl-transformation width="500" fetch-format="auto" crop="scale">
</cl-transformation>
</cl-image>
.Net:
cloudinary.Api.UrlImgUp.Transform(new Transformation().Width(500).FetchFormat("auto").Crop("scale")).BuildImageTag("sample.jpg")
Android:
MediaManager.get().url().transformation(new Transformation().width(500).fetchFormat("auto").crop("scale")).generate("sample.jpg");
iOS:
imageView.cldSetImage(cloudinary.createUrl().setTransformation(CLDTransformation().setWidth(500).setFetchFormat("auto").setCrop("scale")).generate("sample.jpg")!, cloudinary: cloudinary)
Notes
- When automatic format (
f_auto) is used together with automatic quality (q_auto), the PNG format may be selected when the automatic quality algorithm decides that it better fits the specific image. This allows delivering better looking and economical image files.
- JPG-2000 is included as an option for
f_auto on Cloudinary accounts created after October 2019. To enable this option for older accounts, contact support.
- When
f_auto is used together with q_auto for JPEG images and the automatic quality algorithm decides that no chroma subsampling should be performed, the JPEG format is selected instead of WebP. This behavior is needed because the lossy WebP format always performs chroma subsampling, which might result in a lower visual quality for some images.
- Setting the
any_format flag together with automatic quality (q_auto,fl_any_format) but without setting f_auto, will also allow switching to PNG8 encoding if the quality algorithm decides that it's more efficient.
- If
f_auto is used to deliver an image that contains transparency, and the requesting browser does not support WebP or JPEG-XR, then the image is delivered in PNG format instead of the JPEG format.
You can resize and crop images in order to match the graphic design of your web site or mobile application. Whether images are uploaded in your server-side code or by your users, the original hi-res images are stored in the cloud for further processing and management. You can then dynamically create multiple resized, cropped and manipulated images on-the-fly and deliver them via dynamic URLs.
To change the size of a image, use the width and height parameters (w and h in URLs) to assign new values. You can resize the image by using both the width and height parameters or with only one of them: the other dimension is automatically updated to maintain the aspect ratio.
- Using an integer value sets the new dimension to that number in pixels. For example,
w_150 sets the width to exactly 150 pixels.
- Using a decimal value sets the new dimension as a multiple of the original dimension. For example,
w_0.5 sets the width to half the original width.
- Using
ih or iw as values sets the dimension to the initial height or initial width of the original image respectively. For example, w_iw sets the width to the same value as the original width of the image. This may be useful when applying chained transformations or setting the dimensions of an overlay.
Examples of resizing the uploaded jpg image named sample:
Resizing the width to half the original width, maintaining the aspect ratio:
Ruby:
cl_image_tag("sample.jpg", :width=>0.5, :crop=>"scale")
PHP:
cl_image_tag("sample.jpg", array("width"=>0.5, "crop"=>"scale"))
Python:
CloudinaryImage("sample.jpg").image(width=0.5, crop="scale")
Node.js:
cloudinary.image("sample.jpg", {width: "0.5", crop: "scale"})
Java:
cloudinary.url().transformation(new Transformation().width(0.5).crop("scale")).imageTag("sample.jpg");
JS:
cloudinary.imageTag('sample.jpg', {width: "0.5", crop: "scale"}).toHtml();
jQuery:
$.cloudinary.image("sample.jpg", {width: "0.5", crop: "scale"})
React:
<Image publicId="sample.jpg" >
<Transformation width="0.5" crop="scale" />
</Image>
Vue.js:
<cld-image publicId="sample.jpg" >
<cld-transformation width="0.5" crop="scale" />
</cld-image>
Angular:
<cl-image public-id="sample.jpg" >
<cl-transformation width="0.5" crop="scale">
</cl-transformation>
</cl-image>
.Net:
cloudinary.Api.UrlImgUp.Transform(new Transformation().Width(0.5).Crop("scale")).BuildImageTag("sample.jpg")
Android:
MediaManager.get().url().transformation(new Transformation().width(0.5).crop("scale")).generate("sample.jpg");
iOS:
imageView.cldSetImage(cloudinary.createUrl().setTransformation(CLDTransformation().setWidth(0.5).setCrop("scale")).generate("sample.jpg")!, cloudinary: cloudinary)
Resizing the height to 200 pixels, maintaining the aspect ratio:
Ruby:
cl_image_tag("sample.jpg", :height=>200, :crop=>"scale")
PHP:
cl_image_tag("sample.jpg", array("height"=>200, "crop"=>"scale"))
Python:
CloudinaryImage("sample.jpg").image(height=200, crop="scale")
Node.js:
cloudinary.image("sample.jpg", {height: 200, crop: "scale"})
Java:
cloudinary.url().transformation(new Transformation().height(200).crop("scale")).imageTag("sample.jpg");
JS:
cloudinary.imageTag('sample.jpg', {height: 200, crop: "scale"}).toHtml();
jQuery:
$.cloudinary.image("sample.jpg", {height: 200, crop: "scale"})
React:
<Image publicId="sample.jpg" >
<Transformation height="200" crop="scale" />
</Image>
Vue.js:
<cld-image publicId="sample.jpg" >
<cld-transformation height="200" crop="scale" />
</cld-image>
Angular:
<cl-image public-id="sample.jpg" >
<cl-transformation height="200" crop="scale">
</cl-transformation>
</cl-image>
.Net:
cloudinary.Api.UrlImgUp.Transform(new Transformation().Height(200).Crop("scale")).BuildImageTag("sample.jpg")
Android:
MediaManager.get().url().transformation(new Transformation().height(200).crop("scale")).generate("sample.jpg");
iOS:
imageView.cldSetImage(cloudinary.createUrl().setTransformation(CLDTransformation().setHeight(200).setCrop("scale")).generate("sample.jpg")!, cloudinary: cloudinary)
Resizing to a width of 200 pixels and a height of 100 pixels:
Ruby:
cl_image_tag("sample.jpg", :width=>200, :height=>100, :crop=>"scale")
PHP:
cl_image_tag("sample.jpg", array("width"=>200, "height"=>100, "crop"=>"scale"))
Python:
CloudinaryImage("sample.jpg").image(width=200, height=100, crop="scale")
Node.js:
cloudinary.image("sample.jpg", {width: 200, height: 100, crop: "scale"})
Java:
cloudinary.url().transformation(new Transformation().width(200).height(100).crop("scale")).imageTag("sample.jpg");
JS:
cloudinary.imageTag('sample.jpg', {width: 200, height: 100, crop: "scale"}).toHtml();
jQuery:
$.cloudinary.image("sample.jpg", {width: 200, height: 100, crop: "scale"})
React:
<Image publicId="sample.jpg" >
<Transformation width="200" height="100" crop="scale" />
</Image>
Vue.js:
<cld-image publicId="sample.jpg" >
<cld-transformation width="200" height="100" crop="scale" />
</cld-image>
Angular:
<cl-image public-id="sample.jpg" >
<cl-transformation width="200" height="100" crop="scale">
</cl-transformation>
</cl-image>
.Net:
cloudinary.Api.UrlImgUp.Transform(new Transformation().Width(200).Height(100).Crop("scale")).BuildImageTag("sample.jpg")
Android:
MediaManager.get().url().transformation(new Transformation().width(200).height(100).crop("scale")).generate("sample.jpg");
iOS:
imageView.cldSetImage(cloudinary.createUrl().setTransformation(CLDTransformation().setWidth(200).setHeight(100).setCrop("scale")).generate("sample.jpg")!, cloudinary: cloudinary)
When changing the dimensions of an uploaded image by manipulating the image's height and/or width, you need to decide how to adapt or "crop" the image to fit into the requested size. Use the crop parameter for selecting the crop mode (c in URLs). Cloudinary supports the following image cropping modes: scale, fit, mfit, fill, lfill, limit, pad, lpad, mpad, crop, thumb, imagga_crop and imagga_scale.
Note
When creating dynamic delivery URLs, the image is
scaled to the new dimensions by default (as in the examples above), unless a different cropping mode is selected. However, there is no default value when using the Cloudinary SDK helper methods (see
Embedding images in web pages), and a cropping mode must be explicitly selected.
Change the size of the image exactly to the given width and height without necessarily retaining the original aspect ratio: all original image parts are visible but might be stretched or shrunk. If only the width or height is given, then the image is scaled to the new dimension while retaining the original aspect ratio, unless you also include the ignore_aspect_ratio flag).
Examples of scaling the uploaded image named sample:
Scaled to a width of 150 pixels (maintains the aspect ratio by default):
Ruby:
cl_image_tag("sample.jpg", :width=>150, :crop=>"scale")
PHP:
cl_image_tag("sample.jpg", array("width"=>150, "crop"=>"scale"))
Python:
CloudinaryImage("sample.jpg").image(width=150, crop="scale")
Node.js:
cloudinary.image("sample.jpg", {width: 150, crop: "scale"})
Java:
cloudinary.url().transformation(new Transformation().width(150).crop("scale")).imageTag("sample.jpg");
JS:
cloudinary.imageTag('sample.jpg', {width: 150, crop: "scale"}).toHtml();
jQuery:
$.cloudinary.image("sample.jpg", {width: 150, crop: "scale"})
React:
<Image publicId="sample.jpg" >
<Transformation width="150" crop="scale" />
</Image>
Vue.js:
<cld-image publicId="sample.jpg" >
<cld-transformation width="150" crop="scale" />
</cld-image>
Angular:
<cl-image public-id="sample.jpg" >
<cl-transformation width="150" crop="scale">
</cl-transformation>
</cl-image>
.Net:
cloudinary.Api.UrlImgUp.Transform(new Transformation().Width(150).Crop("scale")).BuildImageTag("sample.jpg")
Android:
MediaManager.get().url().transformation(new Transformation().width(150).crop("scale")).generate("sample.jpg");
iOS:
imageView.cldSetImage(cloudinary.createUrl().setTransformation(CLDTransformation().setWidth(150).setCrop("scale")).generate("sample.jpg")!, cloudinary: cloudinary)
Scaled to a width and height of 150 pixels without maintaining the aspect ratio:
Ruby:
cl_image_tag("sample.jpg", :width=>150, :height=>150, :crop=>"scale")
PHP:
cl_image_tag("sample.jpg", array("width"=>150, "height"=>150, "crop"=>"scale"))
Python:
CloudinaryImage("sample.jpg").image(width=150, height=150, crop="scale")
Node.js:
cloudinary.image("sample.jpg", {width: 150, height: 150, crop: "scale"})
Java:
cloudinary.url().transformation(new Transformation().width(150).height(150).crop("scale")).imageTag("sample.jpg");
JS:
cloudinary.imageTag('sample.jpg', {width: 150, height: 150, crop: "scale"}).toHtml();
jQuery:
$.cloudinary.image("sample.jpg", {width: 150, height: 150, crop: "scale"})
React:
<Image publicId="sample.jpg" >
<Transformation width="150" height="150" crop="scale" />
</Image>
Vue.js:
<cld-image publicId="sample.jpg" >
<cld-transformation width="150" height="150" crop="scale" />
</cld-image>
Angular:
<cl-image public-id="sample.jpg" >
<cl-transformation width="150" height="150" crop="scale">
</cl-transformation>
</cl-image>
.Net:
cloudinary.Api.UrlImgUp.Transform(new Transformation().Width(150).Height(150).Crop("scale")).BuildImageTag("sample.jpg")
Android:
MediaManager.get().url().transformation(new Transformation().width(150).height(150).crop("scale")).generate("sample.jpg");
iOS:
imageView.cldSetImage(cloudinary.createUrl().setTransformation(CLDTransformation().setWidth(150).setHeight(150).setCrop("scale")).generate("sample.jpg")!, cloudinary: cloudinary)
Scaled to a width of 25% (maintains the aspect ratio by default):
Ruby:
cl_image_tag("sample.jpg", :width=>0.25, :crop=>"scale")
PHP:
cl_image_tag("sample.jpg", array("width"=>0.25, "crop"=>"scale"))
Python:
CloudinaryImage("sample.jpg").image(width=0.25, crop="scale")
Node.js:
cloudinary.image("sample.jpg", {width: "0.25", crop: "scale"})
Java:
cloudinary.url().transformation(new Transformation().width(0.25).crop("scale")).imageTag("sample.jpg");
JS:
cloudinary.imageTag('sample.jpg', {width: "0.25", crop: "scale"}).toHtml();
jQuery:
$.cloudinary.image("sample.jpg", {width: "0.25", crop: "scale"})
React:
<Image publicId="sample.jpg" >
<Transformation width="0.25" crop="scale" />
</Image>
Vue.js:
<cld-image publicId="sample.jpg" >
<cld-transformation width="0.25" crop="scale" />
</cld-image>
Angular:
<cl-image public-id="sample.jpg" >
<cl-transformation width="0.25" crop="scale">
</cl-transformation>
</cl-image>
.Net:
cloudinary.Api.UrlImgUp.Transform(new Transformation().Width(0.25).Crop("scale")).BuildImageTag("sample.jpg")
Android:
MediaManager.get().url().transformation(new Transformation().width(0.25).crop("scale")).generate("sample.jpg");
iOS:
imageView.cldSetImage(cloudinary.createUrl().setTransformation(CLDTransformation().setWidth(0.25).setCrop("scale")).generate("sample.jpg")!, cloudinary: cloudinary)
The image is resized so that it takes up as much space as possible within a bounding box defined by the given width and height parameters. The original aspect ratio is retained and all of the original image is visible.
For example, the uploaded image named sample is resized to fit within a width and height of 250 pixels while retaining the aspect ratio:
Ruby:
cl_image_tag("sample.jpg", :width=>250, :height=>250, :crop=>"fit")
PHP:
cl_image_tag("sample.jpg", array("width"=>250, "height"=>250, "crop"=>"fit"))
Python:
CloudinaryImage("sample.jpg").image(width=250, height=250, crop="fit")
Node.js:
cloudinary.image("sample.jpg", {width: 250, height: 250, crop: "fit"})
Java:
cloudinary.url().transformation(new Transformation().width(250).height(250).crop("fit")).imageTag("sample.jpg");
JS:
cloudinary.imageTag('sample.jpg', {width: 250, height: 250, crop: "fit"}).toHtml();
jQuery:
$.cloudinary.image("sample.jpg", {width: 250, height: 250, crop: "fit"})
React:
<Image publicId="sample.jpg" >
<Transformation width="250" height="250" crop="fit" />
</Image>
Vue.js:
<cld-image publicId="sample.jpg" >
<cld-transformation width="250" height="250" crop="fit" />
</cld-image>
Angular:
<cl-image public-id="sample.jpg" >
<cl-transformation width="250" height="250" crop="fit">
</cl-transformation>
</cl-image>
.Net:
cloudinary.Api.UrlImgUp.Transform(new Transformation().Width(250).Height(250).Crop("fit")).BuildImageTag("sample.jpg")
Android:
MediaManager.get().url().transformation(new Transformation().width(250).height(250).crop("fit")).generate("sample.jpg");
iOS:
imageView.cldSetImage(cloudinary.createUrl().setTransformation(CLDTransformation().setWidth(250).setHeight(250).setCrop("fit")).generate("sample.jpg")!, cloudinary: cloudinary)
Same as the fit mode but only if the original image is larger than the given limit (width and height), in which case the image is scaled down so that it takes up as much space as possible within a bounding box defined by the given width and height parameters. The original aspect ratio is retained and all of the original image is visible. This mode doesn't scale up the image if your requested dimensions are larger than the original image's.
For example, the uploaded jpg image named sample limited to a width and height of 250 pixels while retaining the aspect ratio:
Ruby:
cl_image_tag("sample.jpg", :width=>250, :height=>250, :crop=>"limit")
PHP:
cl_image_tag("sample.jpg", array("width"=>250, "height"=>250, "crop"=>"limit"))
Python:
CloudinaryImage("sample.jpg").image(width=250, height=250, crop="limit")
Node.js:
cloudinary.image("sample.jpg", {width: 250, height: 250, crop: "limit"})
Java:
cloudinary.url().transformation(new Transformation().width(250).height(250).crop("limit")).imageTag("sample.jpg");
JS:
cloudinary.imageTag('sample.jpg', {width: 250, height: 250, crop: "limit"}).toHtml();
jQuery:
$.cloudinary.image("sample.jpg", {width: 250, height: 250, crop: "limit"})
React:
<Image publicId="sample.jpg" >
<Transformation width="250" height="250" crop="limit" />
</Image>
Vue.js:
<cld-image publicId="sample.jpg" >
<cld-transformation width="250" height="250" crop="limit" />
</cld-image>
Angular:
<cl-image public-id="sample.jpg" >
<cl-transformation width="250" height="250" crop="limit">
</cl-transformation>
</cl-image>
.Net:
cloudinary.Api.UrlImgUp.Transform(new Transformation().Width(250).Height(250).Crop("limit")).BuildImageTag("sample.jpg")
Android:
MediaManager.get().url().transformation(new Transformation().width(250).height(250).crop("limit")).generate("sample.jpg");
iOS:
imageView.cldSetImage(cloudinary.createUrl().setTransformation(CLDTransformation().setWidth(250).setHeight(250).setCrop("limit")).generate("sample.jpg")!, cloudinary: cloudinary)
Same as the fit mode but only if the original image is smaller than the given minimum (width and height), in which case the image is scaled up so that it takes up as much space as possible within a bounding box defined by the given width and height parameters. The original aspect ratio is retained and all of the original image is visible. This mode doesn't scale down the image if your requested dimensions are smaller than the original image's.
For example, attempting to fit the uploaded image named sample to a minimum width and height of 250 pixels while retaining the aspect ratio, results in delivering the original larger image:
Ruby:
cl_image_tag("sample.jpg", :width=>250, :height=>250, :crop=>"mfit")
PHP:
cl_image_tag("sample.jpg", array("width"=>250, "height"=>250, "crop"=>"mfit"))
Python:
CloudinaryImage("sample.jpg").image(width=250, height=250, crop="mfit")
Node.js:
cloudinary.image("sample.jpg", {width: 250, height: 250, crop: "mfit"})
Java:
cloudinary.url().transformation(new Transformation().width(250).height(250).crop("mfit")).imageTag("sample.jpg");
JS:
cloudinary.imageTag('sample.jpg', {width: 250, height: 250, crop: "mfit"}).toHtml();
jQuery:
$.cloudinary.image("sample.jpg", {width: 250, height: 250, crop: "mfit"})
React:
<Image publicId="sample.jpg" >
<Transformation width="250" height="250" crop="mfit" />
</Image>
Vue.js:
<cld-image publicId="sample.jpg" >
<cld-transformation width="250" height="250" crop="mfit" />
</cld-image>
Angular:
<cl-image public-id="sample.jpg" >
<cl-transformation width="250" height="250" crop="mfit">
</cl-transformation>
</cl-image>
.Net:
cloudinary.Api.UrlImgUp.Transform(new Transformation().Width(250).Height(250).Crop("mfit")).BuildImageTag("sample.jpg")
Android:
MediaManager.get().url().transformation(new Transformation().width(250).height(250).crop("mfit")).generate("sample.jpg");
iOS:
imageView.cldSetImage(cloudinary.createUrl().setTransformation(CLDTransformation().setWidth(250).setHeight(250).setCrop("mfit")).generate("sample.jpg")!, cloudinary: cloudinary)
Create an image with the exact given width and height without distorting the image. This option first scales up or down as much as needed to at least fill both of the given dimensions. If the requested aspect ratio is different than the original, cropping will occur on the dimension that exceeds the requested size after scaling. You can specify which part of the original image you want to keep if cropping occurs using the gravity parameter (set to center by default).
Examples of fill used with the uploaded jpg image named sample:
Filled to a width and height of 250 pixels:
Ruby:
cl_image_tag("sample.jpg", :width=>250, :height=>250, :crop=>"fill")
PHP:
cl_image_tag("sample.jpg", array("width"=>250, "height"=>250, "crop"=>"fill"))
Python:
CloudinaryImage("sample.jpg").image(width=250, height=250, crop="fill")
Node.js:
cloudinary.image("sample.jpg", {width: 250, height: 250, crop: "fill"})
Java:
cloudinary.url().transformation(new Transformation().width(250).height(250).crop("fill")).imageTag("sample.jpg");
JS:
cloudinary.imageTag('sample.jpg', {width: 250, height: 250, crop: "fill"}).toHtml();
jQuery:
$.cloudinary.image("sample.jpg", {width: 250, height: 250, crop: "fill"})
React:
<Image publicId="sample.jpg" >
<Transformation width="250" height="250" crop="fill" />
</Image>
Vue.js:
<cld-image publicId="sample.jpg" >
<cld-transformation width="250" height="250" crop="fill" />
</cld-image>
Angular:
<cl-image public-id="sample.jpg" >
<cl-transformation width="250" height="250" crop="fill">
</cl-transformation>
</cl-image>
.Net:
cloudinary.Api.UrlImgUp.Transform(new Transformation().Width(250).Height(250).Crop("fill")).BuildImageTag("sample.jpg")
Android:
MediaManager.get().url().transformation(new Transformation().width(250).height(250).crop("fill")).generate("sample.jpg");
iOS:
imageView.cldSetImage(cloudinary.createUrl().setTransformation(CLDTransformation().setWidth(250).setHeight(250).setCrop("fill")).generate("sample.jpg")!, cloudinary: cloudinary)
Filled to a width and height of 250 pixels with east gravity:
Ruby:
cl_image_tag("sample.jpg", :width=>250, :height=>250, :gravity=>"east", :crop=>"fill")
PHP:
cl_image_tag("sample.jpg", array("width"=>250, "height"=>250, "gravity"=>"east", "crop"=>"fill"))
Python:
CloudinaryImage("sample.jpg").image(width=250, height=250, gravity="east", crop="fill")
Node.js:
cloudinary.image("sample.jpg", {width: 250, height: 250, gravity: "east", crop: "fill"})
Java:
cloudinary.url().transformation(new Transformation().width(250).height(250).gravity("east").crop("fill")).imageTag("sample.jpg");
JS:
cloudinary.imageTag('sample.jpg', {width: 250, height: 250, gravity: "east", crop: "fill"}).toHtml();
jQuery:
$.cloudinary.image("sample.jpg", {width: 250, height: 250, gravity: "east", crop: "fill"})
React:
<Image publicId="sample.jpg" >
<Transformation width="250" height="250" gravity="east" crop="fill" />
</Image>
Vue.js:
<cld-image publicId="sample.jpg" >
<cld-transformation width="250" height="250" gravity="east" crop="fill" />
</cld-image>
Angular:
<cl-image public-id="sample.jpg" >
<cl-transformation width="250" height="250" gravity="east" crop="fill">
</cl-transformation>
</cl-image>
.Net:
cloudinary.Api.UrlImgUp.Transform(new Transformation().Width(250).Height(250).Gravity("east").Crop("fill")).BuildImageTag("sample.jpg")
Android:
MediaManager.get().url().transformation(new Transformation().width(250).height(250).gravity("east").crop("fill")).generate("sample.jpg");
iOS:
imageView.cldSetImage(cloudinary.createUrl().setTransformation(CLDTransformation().setWidth(250).setHeight(250).setGravity("east").setCrop("fill")).generate("sample.jpg")!, cloudinary: cloudinary)
Same as the 'fill' mode, but only if the original image is larger than the specified resolution limits, in which case the image is scaled down to fill the given width and height without distorting the image, and then the dimension that exceeds the request is cropped. If the original dimensions are smaller than the requested size, it is not resized at all. This prevents upscaling. You can specify which part of the original image you want to keep if cropping occurs using the gravity parameter (set to center by default).
For example, the uploaded image named sample limit filled to a width of 150 pixels and a height of 200 pixels and limiting the size to no larger than the original image:
Ruby:
cl_image_tag("sample.jpg", :width=>150, :height=>200, :crop=>"lfill")
PHP:
cl_image_tag("sample.jpg", array("width"=>150, "height"=>200, "crop"=>"lfill"))
Python:
CloudinaryImage("sample.jpg").image(width=150, height=200, crop="lfill")
Node.js:
cloudinary.image("sample.jpg", {width: 150, height: 200, crop: "lfill"})
Java:
cloudinary.url().transformation(new Transformation().width(150).height(200).crop("lfill")).imageTag("sample.jpg");
JS:
cloudinary.imageTag('sample.jpg', {width: 150, height: 200, crop: "lfill"}).toHtml();
jQuery:
$.cloudinary.image("sample.jpg", {width: 150, height: 200, crop: "lfill"})
React:
<Image publicId="sample.jpg" >
<Transformation width="150" height="200" crop="lfill" />
</Image>
Vue.js:
<cld-image publicId="sample.jpg" >
<cld-transformation width="150" height="200" crop="lfill" />
</cld-image>
Angular:
<cl-image public-id="sample.jpg" >
<cl-transformation width="150" height="200" crop="lfill">
</cl-transformation>
</cl-image>
.Net:
cloudinary.Api.UrlImgUp.Transform(new Transformation().Width(150).Height(200).Crop("lfill")).BuildImageTag("sample.jpg")
Android:
MediaManager.get().url().transformation(new Transformation().width(150).height(200).crop("lfill")).generate("sample.jpg");
iOS:
imageView.cldSetImage(cloudinary.createUrl().setTransformation(CLDTransformation().setWidth(150).setHeight(200).setCrop("lfill")).generate("sample.jpg")!, cloudinary: cloudinary)
Resize the image to fill the given width and height while retaining the original aspect ratio and with all of the original image visible. If the proportions of the original image do not match the given width and height, padding is added to the image to reach the required size. You can also specify where the original image is placed by using the gravity parameter (set to center by default), and specify the color of the background in the case that padding is added.
For example, the uploaded jpg image named sample padded with a black background to a width and height of 250 pixels:
Ruby:
cl_image_tag("sample.jpg", :width=>250, :height=>250, :background=>"black", :crop=>"pad")
PHP:
cl_image_tag("sample.jpg", array("width"=>250, "height"=>250, "background"=>"black", "crop"=>"pad"))
Python:
CloudinaryImage("sample.jpg").image(width=250, height=250, background="black", crop="pad")
Node.js:
cloudinary.image("sample.jpg", {width: 250, height: 250, background: "black", crop: "pad"})
Java:
cloudinary.url().transformation(new Transformation().width(250).height(250).background("black").crop("pad")).imageTag("sample.jpg");
JS:
cloudinary.imageTag('sample.jpg', {width: 250, height: 250, background: "black", crop: "pad"}).toHtml();
jQuery:
$.cloudinary.image("sample.jpg", {width: 250, height: 250, background: "black", crop: "pad"})
React:
<Image publicId="sample.jpg" >
<Transformation width="250" height="250" background="black" crop="pad" />
</Image>
Vue.js:
<cld-image publicId="sample.jpg" >
<cld-transformation width="250" height="250" background="black" crop="pad" />
</cld-image>
Angular:
<cl-image public-id="sample.jpg" >
<cl-transformation width="250" height="250" background="black" crop="pad">
</cl-transformation>
</cl-image>
.Net:
cloudinary.Api.UrlImgUp.Transform(new Transformation().Width(250).Height(250).Background("black").Crop("pad")).BuildImageTag("sample.jpg")
Android:
MediaManager.get().url().transformation(new Transformation().width(250).height(250).background("black").crop("pad")).generate("sample.jpg");
iOS:
imageView.cldSetImage(cloudinary.createUrl().setTransformation(CLDTransformation().setWidth(250).setHeight(250).setBackground("black").setCrop("pad")).generate("sample.jpg")!, cloudinary: cloudinary)
Same as the pad mode but only if the original image is larger than the given limit (width and height), in which case the image is scaled down to fill the given width and height while retaining the original aspect ratio and with all of the original image visible. This mode doesn't scale up the image if your requested dimensions are bigger than the original image's. If the proportions of the original image do not match the given width and height, padding is added to the image to reach the required size. You can also specify where the original image is placed by using the gravity parameter (set to center by default), and specify the color of the background in the case that padding is added.
For example, the uploaded jpg image named sample limit padded with a green background to a width of 400 pixels and a height of 150 pixels:
Ruby:
cl_image_tag("sample.jpg", :width=>400, :height=>150, :background=>"green", :crop=>"lpad")
PHP:
cl_image_tag("sample.jpg", array("width"=>400, "height"=>150, "background"=>"green", "crop"=>"lpad"))
Python:
CloudinaryImage("sample.jpg").image(width=400, height=150, background="green", crop="lpad")
Node.js:
cloudinary.image("sample.jpg", {width: 400, height: 150, background: "green", crop: "lpad"})
Java:
cloudinary.url().transformation(new Transformation().width(400).height(150).background("green").crop("lpad")).imageTag("sample.jpg");
JS:
cloudinary.imageTag('sample.jpg', {width: 400, height: 150, background: "green", crop: "lpad"}).toHtml();
jQuery:
$.cloudinary.image("sample.jpg", {width: 400, height: 150, background: "green", crop: "lpad"})
React:
<Image publicId="sample.jpg" >
<Transformation width="400" height="150" background="green" crop="lpad" />
</Image>
Vue.js:
<cld-image publicId="sample.jpg" >
<cld-transformation width="400" height="150" background="green" crop="lpad" />
</cld-image>
Angular:
<cl-image public-id="sample.jpg" >
<cl-transformation width="400" height="150" background="green" crop="lpad">
</cl-transformation>
</cl-image>
.Net:
cloudinary.Api.UrlImgUp.Transform(new Transformation().Width(400).Height(150).Background("green").Crop("lpad")).BuildImageTag("sample.jpg")
Android:
MediaManager.get().url().transformation(new Transformation().width(400).height(150).background("green").crop("lpad")).generate("sample.jpg");
iOS:
imageView.cldSetImage(cloudinary.createUrl().setTransformation(CLDTransformation().setWidth(400).setHeight(150).setBackground("green").setCrop("lpad")).generate("sample.jpg")!, cloudinary: cloudinary)
Same as the pad mode but only if the original image is smaller than the given minimum (width and height), in which case the image is scaled up to fill the given width and height while retaining the original aspect ratio and with all of the original image visible. This mode doesn't scale down the image if your requested dimensions are smaller than the original image's. If the proportions of the original image do not match the given width and height, padding is added to the image to reach the required size. You can also specify where the original image is placed by using the gravity parameter (set to center by default), and specify the color of the background in the case that padding is added.
For example, attempting to minimum pad the uploaded image named sample to a width and height of 250 pixels while retaining the aspect ratio, results in delivering the original larger image:
Ruby:
cl_image_tag("sample.jpg", :width=>250, :height=>250, :crop=>"mpad")
PHP:
cl_image_tag("sample.jpg", array("width"=>250, "height"=>250, "crop"=>"mpad"))
Python:
CloudinaryImage("sample.jpg").image(width=250, height=250, crop="mpad")
Node.js:
cloudinary.image("sample.jpg", {width: 250, height: 250, crop: "mpad"})
Java:
cloudinary.url().transformation(new Transformation().width(250).height(250).crop("mpad")).imageTag("sample.jpg");
JS:
cloudinary.imageTag('sample.jpg', {width: 250, height: 250, crop: "mpad"}).toHtml();
jQuery:
$.cloudinary.image("sample.jpg", {width: 250, height: 250, crop: "mpad"})
React:
<Image publicId="sample.jpg" >
<Transformation width="250" height="250" crop="mpad" />
</Image>
Vue.js:
<cld-image publicId="sample.jpg" >
<cld-transformation width="250" height="250" crop="mpad" />
</cld-image>
Angular:
<cl-image public-id="sample.jpg" >
<cl-transformation width="250" height="250" crop="mpad">
</cl-transformation>
</cl-image>
.Net:
cloudinary.Api.UrlImgUp.Transform(new Transformation().Width(250).Height(250).Crop("mpad")).BuildImageTag("sample.jpg")
Android:
MediaManager.get().url().transformation(new Transformation().width(250).height(250).crop("mpad")).generate("sample.jpg");
iOS:
imageView.cldSetImage(cloudinary.createUrl().setTransformation(CLDTransformation().setWidth(250).setHeight(250).setCrop("mpad")).generate("sample.jpg")!, cloudinary: cloudinary)
Tries to prevent a "bad crop" by first attempting to use the fill mode, but adding padding if it is determined that more of the original image needs to be included in the final image. Especially useful if the aspect ratio of the delivered image is considerably different from the original's aspect ratio. Only supported in conjunction with Automatic cropping (g_auto).
For example, the uploaded jpg image named lady delivered as a 80x400 image using the fill mode on the left, and the fill_pad mode on the right:
fill
fill_pad
Ruby:
cl_image_tag("lady.jpg", :width=>80, :height=>400, :gravity=>"auto", :background=>"auto", :crop=>"fill_pad")
PHP:
cl_image_tag("lady.jpg", array("width"=>80, "height"=>400, "gravity"=>"auto", "background"=>"auto", "crop"=>"fill_pad"))
Python:
CloudinaryImage("lady.jpg").image(width=80, height=400, gravity="auto", background="auto", crop="fill_pad")
Node.js:
cloudinary.image("lady.jpg", {width: 80, height: 400, gravity: "auto", background: "auto", crop: "fill_pad"})
Java:
cloudinary.url().transformation(new Transformation().width(80).height(400).gravity("auto").background("auto").crop("fill_pad")).imageTag("lady.jpg");
JS:
cloudinary.imageTag('lady.jpg', {width: 80, height: 400, gravity: "auto", background: "auto", crop: "fill_pad"}).toHtml();
jQuery:
$.cloudinary.image("lady.jpg", {width: 80, height: 400, gravity: "auto", background: "auto", crop: "fill_pad"})
React:
<Image publicId="lady.jpg" >
<Transformation width="80" height="400" gravity="auto" background="auto" crop="fill_pad" />
</Image>
Vue.js:
<cld-image publicId="lady.jpg" >
<cld-transformation width="80" height="400" gravity="auto" background="auto" crop="fill_pad" />
</cld-image>
Angular:
<cl-image public-id="lady.jpg" >
<cl-transformation width="80" height="400" gravity="auto" background="auto" crop="fill_pad">
</cl-transformation>
</cl-image>
.Net:
cloudinary.Api.UrlImgUp.Transform(new Transformation().Width(80).Height(400).Gravity("auto").Background("auto").Crop("fill_pad")).BuildImageTag("lady.jpg")
Android:
MediaManager.get().url().transformation(new Transformation().width(80).height(400).gravity("auto").background("auto").crop("fill_pad")).generate("lady.jpg");
iOS:
imageView.cldSetImage(cloudinary.createUrl().setTransformation(CLDTransformation().setWidth(80).setHeight(400).setGravity("auto").setBackground("auto").setCrop("fill_pad")).generate("lady.jpg")!, cloudinary: cloudinary)
Extract a region of the given width and height out of the original image. The original proportions are retained and so is the size of the graphics. You can specify the gravity parameter to select which part of the image to extract, or use fixed coordinates cropping.
For example, the uploaded jpg image named sample cropped to a width of 200 pixels, a height of 150 pixels, with northwest gravity:
Ruby:
cl_image_tag("sample.jpg", :width=>200, :height=>150, :gravity=>"north_west", :crop=>"crop")
PHP:
cl_image_tag("sample.jpg", array("width"=>200, "height"=>150, "gravity"=>"north_west", "crop"=>"crop"))
Python:
CloudinaryImage("sample.jpg").image(width=200, height=150, gravity="north_west", crop="crop")
Node.js:
cloudinary.image("sample.jpg", {width: 200, height: 150, gravity: "north_west", crop: "crop"})
Java:
cloudinary.url().transformation(new Transformation().width(200).height(150).gravity("north_west").crop("crop")).imageTag("sample.jpg");
JS:
cloudinary.imageTag('sample.jpg', {width: 200, height: 150, gravity: "north_west", crop: "crop"}).toHtml();
jQuery:
$.cloudinary.image("sample.jpg", {width: 200, height: 150, gravity: "north_west", crop: "crop"})
React:
<Image publicId="sample.jpg" >
<Transformation width="200" height="150" gravity="north_west" crop="crop" />
</Image>
Vue.js:
<cld-image publicId="sample.jpg" >
<cld-transformation width="200" height="150" gravity="north_west" crop="crop" />
</cld-image>
Angular:
<cl-image public-id="sample.jpg" >
<cl-transformation width="200" height="150" gravity="north_west" crop="crop">
</cl-transformation>
</cl-image>
.Net:
cloudinary.Api.UrlImgUp.Transform(new Transformation().Width(200).Height(150).Gravity("north_west").Crop("crop")).BuildImageTag("sample.jpg")
Android:
MediaManager.get().url().transformation(new Transformation().width(200).height(150).gravity("north_west").crop("crop")).generate("sample.jpg");
iOS:
imageView.cldSetImage(cloudinary.createUrl().setTransformation(CLDTransformation().setWidth(200).setHeight(150).setGravity("north_west").setCrop("crop")).generate("sample.jpg")!, cloudinary: cloudinary)
You can specify a region of the original image to crop by giving the x and y coordinates of the top left corner of the region together with the width and height of the region. You can also use percentage based numbers instead of the exact coordinates for x, y, w and h (e.g., 0.5 for 50%) . Use this method when you know beforehand what the correct absolute cropping coordinates are, as in when your users manually select the region to crop out of the original image.
For example, the following image shows many white sheep and one brown sheep.
Ruby:
cl_image_tag("brown_sheep.jpg")
PHP:
cl_image_tag("brown_sheep.jpg")
Python:
CloudinaryImage("brown_sheep.jpg").image()
Node.js:
cloudinary.image("brown_sheep.jpg")
Java:
cloudinary.url().imageTag("brown_sheep.jpg");
JS:
cloudinary.imageTag('brown_sheep.jpg').toHtml();
jQuery:
$.cloudinary.image("brown_sheep.jpg")
React:
<Image publicId="brown_sheep.jpg" >
</Image>
Vue.js:
<cld-image publicId="brown_sheep.jpg" >
</cld-image>
Angular:
<cl-image public-id="brown_sheep.jpg" >
</cl-image>
.Net:
cloudinary.Api.UrlImgUp.BuildImageTag("brown_sheep.jpg")
Android:
MediaManager.get().url().generate("brown_sheep.jpg");
iOS:
imageView.cldSetImage(cloudinary.createUrl().generate("brown_sheep.jpg")!, cloudinary: cloudinary)
To manipulate the picture so that only the brown sheep is visible, the image is cropped to a 300x200 region starting at the coordinate x = 355 and y = 410:
Ruby:
cl_image_tag("brown_sheep.jpg", :x=>355, :y=>410, :width=>300, :height=>200, :crop=>"crop")
PHP:
cl_image_tag("brown_sheep.jpg", array("x"=>355, "y"=>410, "width"=>300, "height"=>200, "crop"=>"crop"))
Python:
CloudinaryImage("brown_sheep.jpg").image(x=355, y=410, width=300, height=200, crop="crop")
Node.js:
cloudinary.image("brown_sheep.jpg", {x: 355, y: 410, width: 300, height: 200, crop: "crop"})
Java:
cloudinary.url().transformation(new Transformation().x(355).y(410).width(300).height(200).crop("crop")).imageTag("brown_sheep.jpg");
JS:
cloudinary.imageTag('brown_sheep.jpg', {x: 355, y: 410, width: 300, height: 200, crop: "crop"}).toHtml();
jQuery:
$.cloudinary.image("brown_sheep.jpg", {x: 355, y: 410, width: 300, height: 200, crop: "crop"})
React:
<Image publicId="brown_sheep.jpg" >
<Transformation x="355" y="410" width="300" height="200" crop="crop" />
</Image>
Vue.js:
<cld-image publicId="brown_sheep.jpg" >
<cld-transformation x="355" y="410" width="300" height="200" crop="crop" />
</cld-image>
Angular:
<cl-image public-id="brown_sheep.jpg" >
<cl-transformation x="355" y="410" width="300" height="200" crop="crop">
</cl-transformation>
</cl-image>
.Net:
cloudinary.Api.UrlImgUp.Transform(new Transformation().X(355).Y(410).Width(300).Height(200).Crop("crop")).BuildImageTag("brown_sheep.jpg")
Android:
MediaManager.get().url().transformation(new Transformation().x(355).y(410).width(300).height(200).crop("crop")).generate("brown_sheep.jpg");
iOS:
imageView.cldSetImage(cloudinary.createUrl().setTransformation(CLDTransformation().setX(355).setY(410).setWidth(300).setHeight(200).setCrop("crop")).generate("brown_sheep.jpg")!, cloudinary: cloudinary)
The image can be further manipulated with chained transformations. For example, the 300x200 cropped version above, also scaled down to 150x100:
Ruby:
cl_image_tag("brown_sheep.jpg", :transformation=>[
{:x=>355, :y=>410, :width=>300, :height=>200, :crop=>"crop"},
{:width=>150, :height=>100, :crop=>"scale"}
])
PHP:
cl_image_tag("brown_sheep.jpg", array("transformation"=>array(
array("x"=>355, "y"=>410, "width"=>300, "height"=>200, "crop"=>"crop"),
array("width"=>150, "height"=>100, "crop"=>"scale")
)))
Python:
CloudinaryImage("brown_sheep.jpg").image(transformation=[
{'x': 355, 'y': 410, 'width': 300, 'height': 200, 'crop': "crop"},
{'width': 150, 'height': 100, 'crop': "scale"}
])
Node.js:
cloudinary.image("brown_sheep.jpg", {transformation: [
{x: 355, y: 410, width: 300, height: 200, crop: "crop"},
{width: 150, height: 100, crop: "scale"}
]})
Java:
cloudinary.url().transformation(new Transformation()
.x(355).y(410).width(300).height(200).crop("crop").chain()
.width(150).height(100).crop("scale")).imageTag("brown_sheep.jpg");
JS:
cloudinary.imageTag('brown_sheep.jpg', {transformation: [
{x: 355, y: 410, width: 300, height: 200, crop: "crop"},
{width: 150, height: 100, crop: "scale"}
]}).toHtml();
jQuery:
$.cloudinary.image("brown_sheep.jpg", {transformation: [
{x: 355, y: 410, width: 300, height: 200, crop: "crop"},
{width: 150, height: 100, crop: "scale"}
]})
React:
<Image publicId="brown_sheep.jpg" >
<Transformation x="355" y="410" width="300" height="200" crop="crop" />
<Transformation width="150" height="100" crop="scale" />
</Image>
Vue.js:
<cld-image publicId="brown_sheep.jpg" >
<cld-transformation x="355" y="410" width="300" height="200" crop="crop" />
<cld-transformation width="150" height="100" crop="scale" />
</cld-image>
Angular:
<cl-image public-id="brown_sheep.jpg" >
<cl-transformation x="355" y="410" width="300" height="200" crop="crop">
</cl-transformation>
<cl-transformation width="150" height="100" crop="scale">
</cl-transformation>
</cl-image>
.Net:
cloudinary.Api.UrlImgUp.Transform(new Transformation()
.X(355).Y(410).Width(300).Height(200).Crop("crop").Chain()
.Width(150).Height(100).Crop("scale")).BuildImageTag("brown_sheep.jpg")
Android:
MediaManager.get().url().transformation(new Transformation()
.x(355).y(410).width(300).height(200).crop("crop").chain()
.width(150).height(100).crop("scale")).generate("brown_sheep.jpg");
iOS:
imageView.cldSetImage(cloudinary.createUrl().setTransformation(CLDTransformation()
.setX(355).setY(410).setWidth(300).setHeight(200).setCrop("crop").chain()
.setWidth(150).setHeight(100).setCrop("scale")).generate("brown_sheep.jpg")!, cloudinary: cloudinary)
The thumb cropping mode is specifically used for creating image thumbnails from either face or custom coordinates, and must always be accompanied by the gravity parameter set to one of the face detection or custom values. This cropping mode generates a thumbnail of an image with the exact given width and height dimensions and with the original proportions retained, but the resulting image might be scaled to fit in the given dimensions. You can specify the zoom parameter to determine how much to scale the resulting image within the given width and height.
For example, creating a 150x150 thumbnail with face detection, of the uploaded image called woman. Below you can see the original image as well as the face detection based thumbnail:
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)
The Imagga Crop and Scale add-on can be used to smartly scale and crop your images based on automatically calculated areas of interest within each specific photo. See the Imagga Crop and Scale add-on documentation for more information.
For example, the original image:
Ruby:
cl_image_tag("family_bench.jpg")
PHP:
cl_image_tag("family_bench.jpg")
Python:
CloudinaryImage("family_bench.jpg").image()
Node.js:
cloudinary.image("family_bench.jpg")
Java:
cloudinary.url().imageTag("family_bench.jpg");
JS:
cloudinary.imageTag('family_bench.jpg').toHtml();
jQuery:
$.cloudinary.image("family_bench.jpg")
React:
<Image publicId="family_bench.jpg" >
</Image>
Vue.js:
<cld-image publicId="family_bench.jpg" >
</cld-image>
Angular:
<cl-image public-id="family_bench.jpg" >
</cl-image>
.Net:
cloudinary.Api.UrlImgUp.BuildImageTag("family_bench.jpg")
Android:
MediaManager.get().url().generate("family_bench.jpg");
iOS:
imageView.cldSetImage(cloudinary.createUrl().generate("family_bench.jpg")!, cloudinary: cloudinary)
Image with Imagga cropping:
Ruby:
cl_image_tag("family_bench.jpg", :crop=>"imagga_crop")
PHP:
cl_image_tag("family_bench.jpg", array("crop"=>"imagga_crop"))
Python:
CloudinaryImage("family_bench.jpg").image(crop="imagga_crop")
Node.js:
cloudinary.image("family_bench.jpg", {crop: "imagga_crop"})
Java:
cloudinary.url().transformation(new Transformation().crop("imagga_crop")).imageTag("family_bench.jpg");
JS:
cloudinary.imageTag('family_bench.jpg', {crop: "imagga_crop"}).toHtml();
jQuery:
$.cloudinary.image("family_bench.jpg", {crop: "imagga_crop"})
React:
<Image publicId="family_bench.jpg" >
<Transformation crop="imagga_crop" />
</Image>
Vue.js:
<cld-image publicId="family_bench.jpg" >
<cld-transformation crop="imagga_crop" />
</cld-image>
Angular:
<cl-image public-id="family_bench.jpg" >
<cl-transformation crop="imagga_crop">
</cl-transformation>
</cl-image>
.Net:
cloudinary.Api.UrlImgUp.Transform(new Transformation().Crop("imagga_crop")).BuildImageTag("family_bench.jpg")
Android:
MediaManager.get().url().transformation(new Transformation().crop("imagga_crop")).generate("family_bench.jpg");
iOS:
imageView.cldSetImage(cloudinary.createUrl().setTransformation(CLDTransformation().setCrop("imagga_crop")).generate("family_bench.jpg")!, cloudinary: cloudinary)
Use the aspect_ratio parameter (ar in URLs) to resize or crop the image to a new aspect ratio. This parameter is used together with a specified crop mode (scale, fill, lfill, pad, lpad, mpad or crop), that determines how the image is adjusted to the new dimensions. This parameter can also be used when changing the dimensions of an image with only the width or height parameters (w and h in URLs) - the other dimension is then automatically updated to maintain the given aspect ratio.
The aspect_ratio parameter accepts a value in one of the following forms:
a:b where a signifies the relative width and b the relative height (e.g., 4:3 or 16:9).- a decimal value representing the ratio of the width divided by the height (e.g., 1.33 or 2.5).
Examples with the uploaded image named sample:
- Cropped to an aspect ratio of 2.5:
Ruby:
cl_image_tag("sample.jpg", :aspect_ratio=>"2.5", :crop=>"crop")
PHP:
cl_image_tag("sample.jpg", array("aspect_ratio"=>"2.5", "crop"=>"crop"))
Python:
CloudinaryImage("sample.jpg").image(aspect_ratio="2.5", crop="crop")
Node.js:
cloudinary.image("sample.jpg", {aspect_ratio: "2.5", crop: "crop"})
Java:
cloudinary.url().transformation(new Transformation().aspectRatio("2.5").crop("crop")).imageTag("sample.jpg");
JS:
cloudinary.imageTag('sample.jpg', {aspectRatio: "2.5", crop: "crop"}).toHtml();
jQuery:
$.cloudinary.image("sample.jpg", {aspect_ratio: "2.5", crop: "crop"})
React:
<Image publicId="sample.jpg" >
<Transformation aspectRatio="2.5" crop="crop" />
</Image>
Vue.js:
<cld-image publicId="sample.jpg" >
<cld-transformation aspectRatio="2.5" crop="crop" />
</cld-image>
Angular:
<cl-image public-id="sample.jpg" >
<cl-transformation aspect-ratio="2.5" crop="crop">
</cl-transformation>
</cl-image>
.Net:
cloudinary.Api.UrlImgUp.Transform(new Transformation().AspectRatio("2.5").Crop("crop")).BuildImageTag("sample.jpg")
Android:
MediaManager.get().url().transformation(new Transformation().aspectRatio("2.5").crop("crop")).generate("sample.jpg");
iOS:
imageView.cldSetImage(cloudinary.createUrl().setTransformation(CLDTransformation().setAspectRatio("2.5").setCrop("crop")).generate("sample.jpg")!, cloudinary: cloudinary)
- Filled to an aspect ratio of 16:9:
Ruby:
cl_image_tag("sample.jpg", :aspect_ratio=>"16:9", :crop=>"fill")
PHP:
cl_image_tag("sample.jpg", array("aspect_ratio"=>"16:9", "crop"=>"fill"))
Python:
CloudinaryImage("sample.jpg").image(aspect_ratio="16:9", crop="fill")
Node.js:
cloudinary.image("sample.jpg", {aspect_ratio: "16:9", crop: "fill"})
Java:
cloudinary.url().transformation(new Transformation().aspectRatio("16:9").crop("fill")).imageTag("sample.jpg");
JS:
cloudinary.imageTag('sample.jpg', {aspectRatio: "16:9", crop: "fill"}).toHtml();
jQuery:
$.cloudinary.image("sample.jpg", {aspect_ratio: "16:9", crop: "fill"})
React:
<Image publicId="sample.jpg" >
<Transformation aspectRatio="16:9" crop="fill" />
</Image>
Vue.js:
<cld-image publicId="sample.jpg" >
<cld-transformation aspectRatio="16:9" crop="fill" />
</cld-image>
Angular:
<cl-image public-id="sample.jpg" >
<cl-transformation aspect-ratio="16:9" crop="fill">
</cl-transformation>
</cl-image>
.Net:
cloudinary.Api.UrlImgUp.Transform(new Transformation().AspectRatio("16:9").Crop("fill")).BuildImageTag("sample.jpg")
Android:
MediaManager.get().url().transformation(new Transformation().aspectRatio("16:9").crop("fill")).generate("sample.jpg");
iOS:
imageView.cldSetImage(cloudinary.createUrl().setTransformation(CLDTransformation().setAspectRatio("16:9").setCrop("fill")).generate("sample.jpg")!, cloudinary: cloudinary)
- Filled to a width of 400 pixels with an aspect ratio of 4:3:
Ruby:
cl_image_tag("sample.jpg", :width=>400, :aspect_ratio=>"4:3", :crop=>"fill")
PHP:
cl_image_tag("sample.jpg", array("width"=>400, "aspect_ratio"=>"4:3", "crop"=>"fill"))
Python:
CloudinaryImage("sample.jpg").image(width=400, aspect_ratio="4:3", crop="fill")
Node.js:
cloudinary.image("sample.jpg", {width: 400, aspect_ratio: "4:3", crop: "fill"})
Java:
cloudinary.url().transformation(new Transformation().width(400).aspectRatio("4:3").crop("fill")).imageTag("sample.jpg");
JS:
cloudinary.imageTag('sample.jpg', {width: 400, aspectRatio: "4:3", crop: "fill"}).toHtml();
jQuery:
$.cloudinary.image("sample.jpg", {width: 400, aspect_ratio: "4:3", crop: "fill"})
React:
<Image publicId="sample.jpg" >
<Transformation width="400" aspectRatio="4:3" crop="fill" />
</Image>
Vue.js:
<cld-image publicId="sample.jpg" >
<cld-transformation width="400" aspectRatio="4:3" crop="fill" />
</cld-image>
Angular:
<cl-image public-id="sample.jpg" >
<cl-transformation width="400" aspect-ratio="4:3" crop="fill">
</cl-transformation>
</cl-image>
.Net:
cloudinary.Api.UrlImgUp.Transform(new Transformation().Width(400).AspectRatio("4:3").Crop("fill")).BuildImageTag("sample.jpg")
Android:
MediaManager.get().url().transformation(new Transformation().width(400).aspectRatio("4:3").crop("fill")).generate("sample.jpg");
iOS:
imageView.cldSetImage(cloudinary.createUrl().setTransformation(CLDTransformation().setWidth(400).setAspectRatio("4:3").setCrop("fill")).generate("sample.jpg")!, cloudinary: cloudinary)
Different devices support different DPR values, which is defined as the ratio between physical pixels and logical pixels. This means that a device with support for a higher DPR uses more physical pixels for displaying an image, resulting in a clearer, sharper image.
Use the dpr parameter to set the DPR value of the delivered image. The parameter accepts a numeric value specifying the DPR multiplier.
The dpr parameter is especially useful when adding overlays, as you need the overlay image to be correctly resized according to the required pixel density of the device (along with the containing image). Setting the dpr transformation parameter applies the same resizing rules both to the containing image, and the included overlay.
For example, the following URL dynamically generates a 100x100 face-detection-based circular thumbnail of an image named lady, and adds another image named cloudinary_icon as a semi-transparent watermark with a width of 50 pixels. Setting the dpr value to 1.0, 2.0 (as in the code example) or 3.0 generates the following images, while resizing both the containing image and the overlay to match the required DPR.
Ruby:
cl_image_tag("lady.jpg", :transformation=>[
{:width=>100, :height=>100, :gravity=>"face", :radius=>"max", :crop=>"thumb"},
{:overlay=>"cloudinary_icon", :effect=>"brightness:200", :flags=>"relative", :width=>0.5, :opacity=>60},
{:dpr=>2.0}
])
PHP:
cl_image_tag("lady.jpg", array("transformation"=>array(
array("width"=>100, "height"=>100, "gravity"=>"face", "radius"=>"max", "crop"=>"thumb"),
array("overlay"=>"cloudinary_icon", "effect"=>"brightness:200", "flags"=>"relative", "width"=>0.5, "opacity"=>60),
array("dpr"=>2.0)
)))
Python:
CloudinaryImage("lady.jpg").image(transformation=[
{'width': 100, 'height': 100, 'gravity': "face", 'radius': "max", 'crop': "thumb"},
{'overlay': "cloudinary_icon", 'effect': "brightness:200", 'flags': "relative", 'width': 0.5, 'opacity': 60},
{'dpr': 2.0}
])
Node.js:
cloudinary.image("lady.jpg", {transformation: [
{width: 100, height: 100, gravity: "face", radius: "max", crop: "thumb"},
{overlay: "cloudinary_icon", effect: "brightness:200", flags: "relative", width: "0.5", opacity: 60},
{dpr: "2.0"}
]})
Java:
cloudinary.url().transformation(new Transformation()
.width(100).height(100).gravity("face").radius("max").crop("thumb").chain()
.overlay(new Layer().publicId("cloudinary_icon")).effect("brightness:200").flags("relative").width(0.5).opacity(60).chain()
.dpr(2.0)).imageTag("lady.jpg");
JS:
cloudinary.imageTag('lady.jpg', {transformation: [
{width: 100, height: 100, gravity: "face", radius: "max", crop: "thumb"},
{overlay: new cloudinary.Layer().publicId("cloudinary_icon"), effect: "brightness:200", flags: "relative", width: "0.5", opacity: 60},
{dpr: "2.0"}
]}).toHtml();
jQuery:
$.cloudinary.image("lady.jpg", {transformation: [
{width: 100, height: 100, gravity: "face", radius: "max", crop: "thumb"},
{overlay: new cloudinary.Layer().publicId("cloudinary_icon"), effect: "brightness:200", flags: "relative", width: "0.5", opacity: 60},
{dpr: "2.0"}
]})
React:
<Image publicId="lady.jpg" >
<Transformation width="100" height="100" gravity="face" radius="max" crop="thumb" />
<Transformation overlay="cloudinary_icon" effect="brightness:200" flags="relative" width="0.5" opacity="60" />
<Transformation dpr="2.0" />
</Image>
Vue.js:
<cld-image publicId="lady.jpg" >
<cld-transformation width="100" height="100" gravity="face" radius="max" crop="thumb" />
<cld-transformation overlay="cloudinary_icon" effect="brightness:200" flags="relative" width="0.5" opacity="60" />
<cld-transformation dpr="2.0" />
</cld-image>
Angular:
<cl-image public-id="lady.jpg" >
<cl-transformation width="100" height="100" gravity="face" radius="max" crop="thumb">
</cl-transformation>
<cl-transformation overlay="cloudinary_icon" effect="brightness:200" flags="relative" width="0.5" opacity="60">
</cl-transformation>
<cl-transformation dpr="2.0">
</cl-transformation>
</cl-image>
.Net:
cloudinary.Api.UrlImgUp.Transform(new Transformation()
.Width(100).Height(100).Gravity("face").Radius("max").Crop("thumb").Chain()
.Overlay(new Layer().PublicId("cloudinary_icon")).Effect("brightness:200").Flags("relative").Width(0.5).Opacity(60).Chain()
.Dpr(2.0)).BuildImageTag("lady.jpg")
Android:
MediaManager.get().url().transformation(new Transformation()
.width(100).height(100).gravity("face").radius("max").crop("thumb").chain()
.overlay(new Layer().publicId("cloudinary_icon")).effect("brightness:200").flags("relative").width(0.5).opacity(60).chain()
.dpr(2.0)).generate("lady.jpg");
iOS:
imageView.cldSetImage(cloudinary.createUrl().setTransformation(CLDTransformation()
.setWidth(100).setHeight(100).setGravity("face").setRadius("max").setCrop("thumb").chain()
.setOverlay("cloudinary_icon").setEffect("brightness:200").setFlags("relative").setWidth(0.5).setOpacity(60).chain()
.setDpr(2.0)).generate("lady.jpg")!, cloudinary: cloudinary)
DPR 1.0 DPR 2.0 DPR 3.0
Now you can create a 100x100 HTML image tag and deliver an image with the resolution that best matches the specified pixel density of your users' devices. The three images below are all displayed within a 100x100 logical square using the <img> tag width and height attributes, while you see more details and a better visual result for the last two images if you view this documentation using a device that supports a higher DPR.
<img
src="https://res.cloudinary.com/demo/image/upload/c_thumb,w_100,h_100,g_face,r_max/l_cloudinary_icon,e_brightness:200,w_50,o_60/dpr_2.0/lady.jpg"
height=100
width=100 />
DPR 1.0 (100x100, 4.1KB) DPR 2.0 (200x200, 10.1KB) DPR 3.0 (300x300, 22.3KB)
You can alternatively use dpr_auto to automatically deliver the best image, depending on the requesting device's support for DPR. For details, see the Responsive images documentation.
The gravity parameter (g in URLs) is used to specify a location in the image that is used as the focus for another transformation:
- For certain cropping modes, gravity specifies which part of the original image to include when the resulting image is smaller than the original or the proportions do not match.
- For placing underlays, overlays or text captions, gravity specifies where to place them in relation to the original image.
The basic gravity value is specified by giving a compass direction to incude: north_east, north, north_west, west, south_west, south, south_east, east, or center (the default value). The compass direction represents a location in the image, for example, north_east represents the top right corner.
For example, the uploaded jpg image named sample filled to a width and height of 250 pixels while retaining the aspect ratio:
- Original image:
Ruby:
cl_image_tag("sample.jpg")
PHP:
cl_image_tag("sample.jpg")
Python:
CloudinaryImage("sample.jpg").image()
Node.js:
cloudinary.image("sample.jpg")
Java:
cloudinary.url().imageTag("sample.jpg");
JS:
cloudinary.imageTag('sample.jpg').toHtml();
jQuery:
$.cloudinary.image("sample.jpg")
React:
<Image publicId="sample.jpg" >
</Image>
Vue.js:
<cld-image publicId="sample.jpg" >
</cld-image>
Angular:
<cl-image public-id="sample.jpg" >
</cl-image>
.Net:
cloudinary.Api.UrlImgUp.BuildImageTag("sample.jpg")
Android:
MediaManager.get().url().generate("sample.jpg");
iOS:
imageView.cldSetImage(cloudinary.createUrl().generate("sample.jpg")!, cloudinary: cloudinary)
- With gravity set to north:
Ruby:
cl_image_tag("sample.jpg", :width=>250, :height=>250, :gravity=>"north", :crop=>"fill")
PHP:
cl_image_tag("sample.jpg", array("width"=>250, "height"=>250, "gravity"=>"north", "crop"=>"fill"))
Python:
CloudinaryImage("sample.jpg").image(width=250, height=250, gravity="north", crop="fill")
Node.js:
cloudinary.image("sample.jpg", {width: 250, height: 250, gravity: "north", crop: "fill"})
Java:
cloudinary.url().transformation(new Transformation().width(250).height(250).gravity("north").crop("fill")).imageTag("sample.jpg");
JS:
cloudinary.imageTag('sample.jpg', {width: 250, height: 250, gravity: "north", crop: "fill"}).toHtml();
jQuery:
$.cloudinary.image("sample.jpg", {width: 250, height: 250, gravity: "north", crop: "fill"})
React:
<Image publicId="sample.jpg" >
<Transformation width="250" height="250" gravity="north" crop="fill" />
</Image>
Vue.js:
<cld-image publicId="sample.jpg" >
<cld-transformation width="250" height="250" gravity="north" crop="fill" />
</cld-image>
Angular:
<cl-image public-id="sample.jpg" >
<cl-transformation width="250" height="250" gravity="north" crop="fill">
</cl-transformation>
</cl-image>
.Net:
cloudinary.Api.UrlImgUp.Transform(new Transformation().Width(250).Height(250).Gravity("north").Crop("fill")).BuildImageTag("sample.jpg")
Android:
MediaManager.get().url().transformation(new Transformation().width(250).height(250).gravity("north").crop("fill")).generate("sample.jpg");
iOS:
imageView.cldSetImage(cloudinary.createUrl().setTransformation(CLDTransformation().setWidth(250).setHeight(250).setGravity("north").setCrop("fill")).generate("sample.jpg")!, cloudinary: cloudinary)
- With gravity set to south_east:
Ruby:
cl_image_tag("sample.jpg", :width=>250, :height=>250, :gravity=>"south_east", :crop=>"fill")
PHP:
cl_image_tag("sample.jpg", array("width"=>250, "height"=>250, "gravity"=>"south_east", "crop"=>"fill"))
Python:
CloudinaryImage("sample.jpg").image(width=250, height=250, gravity="south_east", crop="fill")
Node.js:
cloudinary.image("sample.jpg", {width: 250, height: 250, gravity: "south_east", crop: "fill"})
Java:
cloudinary.url().transformation(new Transformation().width(250).height(250).gravity("south_east").crop("fill")).imageTag("sample.jpg");
JS:
cloudinary.imageTag('sample.jpg', {width: 250, height: 250, gravity: "south_east", crop: "fill"}).toHtml();
jQuery:
$.cloudinary.image("sample.jpg", {width: 250, height: 250, gravity: "south_east", crop: "fill"})
React:
<Image publicId="sample.jpg" >
<Transformation width="250" height="250" gravity="south_east" crop="fill" />
</Image>
Vue.js:
<cld-image publicId="sample.jpg" >
<cld-transformation width="250" height="250" gravity="south_east" crop="fill" />
</cld-image>
Angular:
<cl-image public-id="sample.jpg" >
<cl-transformation width="250" height="250" gravity="south_east" crop="fill">
</cl-transformation>
</cl-image>
.Net:
cloudinary.Api.UrlImgUp.Transform(new Transformation().Width(250).Height(250).Gravity("south_east").Crop("fill")).BuildImageTag("sample.jpg")
Android:
MediaManager.get().url().transformation(new Transformation().width(250).height(250).gravity("south_east").crop("fill")).generate("sample.jpg");
iOS:
imageView.cldSetImage(cloudinary.createUrl().setTransformation(CLDTransformation().setWidth(250).setHeight(250).setGravity("south_east").setCrop("fill")).generate("sample.jpg")!, cloudinary: cloudinary)
More advanced gravity parameters include:
xy_center - Set the center of gravity to the given x & y coordinates.face - Automatically detect the largest face in an image and make it the focus of the transformation. Any previously specified face coordinates (during upload, with the Admin API, or via the Management Console) override the automatically detected faces and are used instead. Defaults to north gravity if no face is detected or previously specified. You can also use face:auto or face:center so that the gravity will default to auto or center if no face is detected or specified. faces - Same as face gravity, but detects all the faces in an image and uses the rectangle containing all face coordinates as the basis of the transformation. Any previously specified face coordinates (during upload, with the Admin API, or via the Management Console) override the automatically detected faces and are used instead. Defaults to north gravity if no faces are detected or previously specified. You can also use faces:auto or faces:center so that the gravity will default to auto or center if no faces are detected or specified. face:center - Same as face gravity, but defaults to center gravity if no face is detected.faces:center - Same as faces gravity, but defaults to center gravity if no face is detected.
liquid - Enables content-aware liquid rescaling (also sometimes known as 'seam carving'), which can be useful when changing the aspect ratio of an image. Normal scaling retains all image content even when aspect ratios change, so important elements of an image can be distorted. Liquid rescaling intelligently removes or duplicates 'seams' of pixels that may zig zag horizontally or vertically through the picture. The seams are determined using an algorithm that selects pixels with the least importance (least color change on either side of the seam). The result is an image where the most 'important' elements of the image are retained and generally do not appear distorted although the relative height or width of items in an image may change, especially if you significantly change the aspect ratio. Tips and guideines:
- This gravity can be used only in conjunction with
c_scale (the default crop method).
- The
liquid gravity works best when applied to scenic images with large 'unbusy' sections such as sky, grass, or water.
- It also works best when applied to larger images. Thus, it is recommended to use this gravity to change aspect ratio using relative widths and heights, where one of the two dimensions remains at or close to
1.0. If you also want to resize the image, apply the resize on a different component of a chained transformation.
- In some cases, over-aggressive liquid rescaling can result in significant artifacts.
- Example:
w_1.0,ar_1.0,g_liquid/w_500,h_500 uses liquid scaling to change an image to a square (aspect ratio of 1:1) based on the original image width, and then resizes the result to 500x500.
auto - An intelligent algorithm analyzes and prioritizes the most prominent elements of the image to include. For details, see Automatic croppingocr_text - Detect all text elements in an image using the OCR Text Detection and Extraction add-on and use the detected bounding box coordinates as the basis of the transformation.adv_face - Automatically detect the largest face in an image with the Advanced Facial Attribute Detection add-on and make it the focus of the transformation.adv_faces - Automatically detect all faces in an image with the Advanced Facial Attribute Detection add-on and make them the focus of the transformation.adv_eyes - Automatically detect all eyes in an image with the Advanced Facial Attribute Detection add-on and make them the focus of the transformation.custom - Use custom coordinates that were previously specified (e.g., as part of the image upload method) and make them the focus of the transformation. Defaults to 'center' gravity if no custom coordinates have been specified.custom:face - Same as custom gravity, but defaults to face gravity if no custom coordinates have been specified.custom:faces - Same as custom gravity, but defaults to faces gravity if no custom coordinates have been specified.custom:adv_face - Same as custom gravity, but defaults to adv_face gravity if no custom coordinates have been specified.custom:adv_faces - Same as custom gravity, but defaults to adv_faces gravity if no custom coordinates have been specified.
Note
The fallback (default) values are only relevant when setting gravity for
cropping modes and not when setting gravity for
placing overlays. For example, if gravity is set to 'face' for placing an overlay, and no face is detected in the image, then the overlay is ignored.
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, and automatically detected faces (or other elements) are given higher priority while analyzing the image content (although any custom coordinates defined will override the detection algorithm).
You apply automatic content-aware gravity by setting the gravity transformation parameter to auto (g_auto in URLs).
Automatic cropping is supported for the fill, lfill, fill_pad, thumb and crop modes.
Notes and Tips:
- If custom coordinates have been specified for an image (using the Upload API or the Management Console), the cropping or overlay will be based on that definition, taking the custom coordinates as-is and overriding the detection algorithm (the same as
g_custom). This applies to all focal_gravity options except for g_auto:custom_no_override and g_auto:none.
- You can add the getinfo flag (
fl_getinfo in URLs) in your transformation to return the proposed g_auto cropping results in JSON instead of delivering the transformed image. You can then integrate the g_auto results into an external workflow, for example to display the proposed g_auto crop as the initial cropping suggestion in an external editing tool.
- By default,
g_auto applies an optimal combination of our AI and saliency-based algorithms to capture the best region to include in your cropped image. However, in certain situations you may want to explicitly request only one of the auto-cropping algorithms and/or adjust the default focal preference of the chosen 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.
But 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 instead explicitly request your preferred algorithm by specifying auto:subject or auto:classic as the gravity value (g_auto:subject or g_auto:classic in URLs), with or without an additional focal gravity option.
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 include the tree against the bright blue and white sky, while the subject algorithm focuses on the subjects that the AI-engine predicts are most likely to capture human attention, primarily the boat, lake and mountains.
Original image
Default crop
(Center gravity)
Auto-gravity
Saliency (classic) method
Auto-gravity
AI-based subject method
By default, both the saliency and subject auto-cropping algorithms give increased priority to detected faces. To adjust the focal preference of the automatic cropping algorithm, you can specify a different focal_gravity option.
For example, you can specify adv_face, adv_faces, or adv_eyes to instruct the algorithm to give priority to the eyes or faces detected by the Advanced Facial Attributes Detection add-on (as opposed to the coordinates selected by the built-in face-detection mechanism). Alternatively, you can use the value none if you don't want the algorithm to give special preference to any detected item, including faces.
If you are registered to the Cloudinary Object-Aware Cropping Add-on, you can also instruct the gravity algorithm to give top priority to one or more specific objects or categories from an extensive list.
Additionally, the OCR Text Detection and Extraction Add-on lets you give a higher priority to text by setting the gravity parameter to auto:ocr_text, while also giving priority to faces and other very prominent elements of an image.
For a complete list of all focal_gravity options, see the auto section of the gravity parameter in the Image Transformation Reference.
Keeping the most of the original image according to the requested dimensions of the derived image. Ensuring that as much as possible of the most interesting regions of the original image is included in the resulting image.
Example of portrait aspect ratio cropping, regular vs. automatic:
Original
w_200,h_300,c_fill,g_centerRegular fill
w_200,h_300,c_fill,g_autoAutomatic fill
Ruby:
cl_image_tag("basketball_in_net.jpg", :width=>200, :height=>300, :gravity=>"auto", :crop=>"fill")
PHP:
cl_image_tag("basketball_in_net.jpg", array("width"=>200, "height"=>300, "gravity"=>"auto", "crop"=>"fill"))
Python:
CloudinaryImage("basketball_in_net.jpg").image(width=200, height=300, gravity="auto", crop="fill")
Node.js:
cloudinary.image("basketball_in_net.jpg", {width: 200, height: 300, gravity: "auto", crop: "fill"})
Java:
cloudinary.url().transformation(new Transformation().width(200).height(300).gravity("auto").crop("fill")).imageTag("basketball_in_net.jpg");
JS:
cloudinary.imageTag('basketball_in_net.jpg', {width: 200, height: 300, gravity: "auto", crop: "fill"}).toHtml();
jQuery:
$.cloudinary.image("basketball_in_net.jpg", {width: 200, height: 300, gravity: "auto", crop: "fill"})
React:
<Image publicId="basketball_in_net.jpg" >
<Transformation width="200" height="300" gravity="auto" crop="fill" />
</Image>
Vue.js:
<cld-image publicId="basketball_in_net.jpg" >
<cld-transformation width="200" height="300" gravity="auto" crop="fill" />
</cld-image>
Angular:
<cl-image public-id="basketball_in_net.jpg" >
<cl-transformation width="200" height="300" gravity="auto" crop="fill">
</cl-transformation>
</cl-image>
.Net:
cloudinary.Api.UrlImgUp.Transform(new Transformation().Width(200).Height(300).Gravity("auto").Crop("fill")).BuildImageTag("basketball_in_net.jpg")
Android:
MediaManager.get().url().transformation(new Transformation().width(200).height(300).gravity("auto").crop("fill")).generate("basketball_in_net.jpg");
iOS:
imageView.cldSetImage(cloudinary.createUrl().setTransformation(CLDTransformation().setWidth(200).setHeight(300).setGravity("auto").setCrop("fill")).generate("basketball_in_net.jpg")!, cloudinary: cloudinary)
Example of square aspect ratio cropping, regular vs. automatic:
Original
w_200,h_200,c_fill,g_centerRegular fill
w_200,h_200,c_fill,g_autoAutomatic fill
Ruby:
cl_image_tag("face_left.jpg", :width=>200, :height=>200, :gravity=>"auto", :crop=>"fill")
PHP:
cl_image_tag("face_left.jpg", array("width"=>200, "height"=>200, "gravity"=>"auto", "crop"=>"fill"))
Python:
CloudinaryImage("face_left.jpg").image(width=200, height=200, gravity="auto", crop="fill")
Node.js:
cloudinary.image("face_left.jpg", {width: 200, height: 200, gravity: "auto", crop: "fill"})
Java:
cloudinary.url().transformation(new Transformation().width(200).height(200).gravity("auto").crop("fill")).imageTag("face_left.jpg");
JS:
cloudinary.imageTag('face_left.jpg', {width: 200, height: 200, gravity: "auto", crop: "fill"}).toHtml();
jQuery:
$.cloudinary.image("face_left.jpg", {width: 200, height: 200, gravity: "auto", crop: "fill"})
React:
<Image publicId="face_left.jpg" >
<Transformation width="200" height="200" gravity="auto" crop="fill" />
</Image>
Vue.js:
<cld-image publicId="face_left.jpg" >
<cld-transformation width="200" height="200" gravity="auto" crop="fill" />
</cld-image>
Angular:
<cl-image public-id="face_left.jpg" >
<cl-transformation width="200" height="200" gravity="auto" crop="fill">
</cl-transformation>
</cl-image>
.Net:
cloudinary.Api.UrlImgUp.Transform(new Transformation().Width(200).Height(200).Gravity("auto").Crop("fill")).BuildImageTag("face_left.jpg")
Android:
MediaManager.get().url().transformation(new Transformation().width(200).height(200).gravity("auto").crop("fill")).generate("face_left.jpg");
iOS:
imageView.cldSetImage(cloudinary.createUrl().setTransformation(CLDTransformation().setWidth(200).setHeight(200).setGravity("auto").setCrop("fill")).generate("face_left.jpg")!, cloudinary: cloudinary)
Same as the fill mode, but only if the original image is larger than the given limit (width and height). This mode doesn't scale up the image if your requested dimensions are bigger than the original image's.
Makes possible 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
Ruby:
cl_image_tag("sunset_shoes.jpg", :width=>150, :height=>150, :gravity=>"auto:0", :crop=>"thumb")
PHP:
cl_image_tag("sunset_shoes.jpg", array("width"=>150, "height"=>150, "gravity"=>"auto:0", "crop"=>"thumb"))
Python:
CloudinaryImage("sunset_shoes.jpg").image(width=150, height=150, gravity="auto:0", crop="thumb")
Node.js:
cloudinary.image("sunset_shoes.jpg", {width: 150, height: 150, gravity: "auto:0", crop: "thumb"})
Java:
cloudinary.url().transformation(new Transformation().width(150).height(150).gravity("auto:0").crop("thumb")).imageTag("sunset_shoes.jpg");
JS:
cloudinary.imageTag('sunset_shoes.jpg', {width: 150, height: 150, gravity: "auto:0", crop: "thumb"}).toHtml();
jQuery:
$.cloudinary.image("sunset_shoes.jpg", {width: 150, height: 150, gravity: "auto:0", crop: "thumb"})
React:
<Image publicId="sunset_shoes.jpg" >
<Transformation width="150" height="150" gravity="auto:0" crop="thumb" />
</Image>
Vue.js:
<cld-image publicId="sunset_shoes.jpg" >
<cld-transformation width="150" height="150" gravity="auto:0" crop="thumb" />
</cld-image>
Angular:
<cl-image public-id="sunset_shoes.jpg" >
<cl-transformation width="150" height="150" gravity="auto:0" crop="thumb">
</cl-transformation>
</cl-image>
.Net:
cloudinary.Api.UrlImgUp.Transform(new Transformation().Width(150).Height(150).Gravity("auto:0").Crop("thumb")).BuildImageTag("sunset_shoes.jpg")
Android:
MediaManager.get().url().transformation(new Transformation().width(150).height(150).gravity("auto:0").crop("thumb")).generate("sunset_shoes.jpg");
iOS:
imageView.cldSetImage(cloudinary.createUrl().setTransformation(CLDTransformation().setWidth(150).setHeight(150).setGravity("auto:0").setCrop("thumb")).generate("sunset_shoes.jpg")!, cloudinary: cloudinary)
Note
The numeric value supplied for
auto gravity together with
thumb cropping indicates your preference for more or less aggressive zooming and the algorithm takes that preference into account. However, the automatic gravity algorithm may still determine that for a particular image and aspect ratio, its default zoom selection is the appropriate zoom for this image. In such a case, you may not see a difference between the default
g_auto and
g_auto with a specific agressiveness level.
Crop a region of exactly the given width and height 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
Ruby:
cl_image_tag("fat_cat.jpg", :width=>200, :height=>200, :gravity=>"auto", :crop=>"crop")
PHP:
cl_image_tag("fat_cat.jpg", array("width"=>200, "height"=>200, "gravity"=>"auto", "crop"=>"crop"))
Python:
CloudinaryImage("fat_cat.jpg").image(width=200, height=200, gravity="auto", crop="crop")
Node.js:
cloudinary.image("fat_cat.jpg", {width: 200, height: 200, gravity: "auto", crop: "crop"})
Java:
cloudinary.url().transformation(new Transformation().width(200).height(200).gravity("auto").crop("crop")).imageTag("fat_cat.jpg");
JS:
cloudinary.imageTag('fat_cat.jpg', {width: 200, height: 200, gravity: "auto", crop: "crop"}).toHtml();
jQuery:
$.cloudinary.image("fat_cat.jpg", {width: 200, height: 200, gravity: "auto", crop: "crop"})
React:
<Image publicId="fat_cat.jpg" >
<Transformation width="200" height="200" gravity="auto" crop="crop" />
</Image>
Vue.js:
<cld-image publicId="fat_cat.jpg" >
<cld-transformation width="200" height="200" gravity="auto" crop="crop" />
</cld-image>
Angular:
<cl-image public-id="fat_cat.jpg" >
<cl-transformation width="200" height="200" gravity="auto" crop="crop">
</cl-transformation>
</cl-image>
.Net:
cloudinary.Api.UrlImgUp.Transform(new Transformation().Width(200).Height(200).Gravity("auto").Crop("crop")).BuildImageTag("fat_cat.jpg")
Android:
MediaManager.get().url().transformation(new Transformation().width(200).height(200).gravity("auto").crop("crop")).generate("fat_cat.jpg");
iOS:
imageView.cldSetImage(cloudinary.createUrl().setTransformation(CLDTransformation().setWidth(200).setHeight(200).setGravity("auto").setCrop("crop")).generate("fat_cat.jpg")!, cloudinary: cloudinary)
Control the visual quality and compression level of JPEG, JPEG 2000, JPEG XR, WebP and GIF images with the quality parameter (q in URLs). This parameter represents the compression level to apply to an image as a value between 1 (smallest file size possible) and 100 (best visual quality). Reducing the quality is a tradeoff between visual quality and file size: the lower the quality value, the more the file is compressed to a smaller file size, the more data is lost in the process, and the result is a loss of visual quality. The loss of visual quality is barely noticeable to the human eye at the higher quality levels, and final visual quality also depends on other factors such as the size of the image and the resolution of the user's monitor or mobile screen.
For example, reducing the quality of the uploaded JPEG image named sample to 60 results in a file size of 73 KB compared to the original file size of 245 KB with a barely noticeable reduction in visual quality:
Ruby:
cl_image_tag("sample.jpg", :quality=>60)
PHP:
cl_image_tag("sample.jpg", array("quality"=>60))
Python:
CloudinaryImage("sample.jpg").image(quality=60)
Node.js:
cloudinary.image("sample.jpg", {quality: 60})
Java:
cloudinary.url().transformation(new Transformation().quality(60)).imageTag("sample.jpg");
JS:
cloudinary.imageTag('sample.jpg', {quality: 60}).toHtml();
jQuery:
$.cloudinary.image("sample.jpg", {quality: 60})
React:
<Image publicId="sample.jpg" >
<Transformation quality="60" />
</Image>
Vue.js:
<cld-image publicId="sample.jpg" >
<cld-transformation quality="60" />
</cld-image>
Angular:
<cl-image public-id="sample.jpg" >
<cl-transformation quality="60">
</cl-transformation>
</cl-image>
.Net:
cloudinary.Api.UrlImgUp.Transform(new Transformation().Quality(60)).BuildImageTag("sample.jpg")
Android:
MediaManager.get().url().transformation(new Transformation().quality(60)).generate("sample.jpg");
iOS:
imageView.cldSetImage(cloudinary.createUrl().setTransformation(CLDTransformation().setQuality(60)).generate("sample.jpg")!, cloudinary: cloudinary)
The quality parameter is also automatically applied when delivering images with any other transformation applied. That is, unless the original uploaded image is requested, then a default quality value of 80 is also automatically applied to the transformed image.
Notes
- Images in the WebP format are lossless when specifying a quality of 100, and lossy when specifying a quality less than 100. See the How to support WebP images, save bandwidth and improve user experience article for more information on the WebP format.
- Images in the WebP format are lossless if the quality isn't specified and the original image's format is lossless (e.g., PNG).
- Animated GIFs ignore the quality setting unless the
lossy flag is added. See the Lossy compression for optimizing animated GIFs article for more information.
- The JPEGmini add-on automatically applies the best compression possible to JPEG images while maintaining a high visual quality.
Cloudinary's intelligent quality and encoding algorithm analyzes an image to find the best quality compression level and optimal encoding settings based on the image content and the viewing browser, in order to produce an image with good visual quality while minimizing the file size. Cloudinary automates the file size versus quality trade-off decision, on the fly, by using perceptual metrics and heuristics that tune the quality settings based on the specific image content and format. Analyzing every image individually to find the optimal compression level and image encoding settings allows for precise adjustment of the compression level complemented by fine tuning of the encoding settings, and can significantly reduce the file size without any degradation noticeable to the human eye.
The quality transformation parameter can be set to auto (q_auto in URLs) in order to perform automatic quality selection and image encoding adjustments. Further control of the automatic quality selection is supported as follows:
q_auto - The optimal balance between file size and visual quality. By default, this is the same as q_auto:good, while it can automatically switch to the more aggressive q_auto:eco mode (see the note on Save-data support below).q_auto:best - Less aggressive algorithm. Generates bigger files with potentially better visual quality. Example of a target audience: photography sites that display images with a high visual quality.q_auto:good - Ensuring a relatively small file size with good visual quality.q_auto:eco - More aggressive algorithm, which results in smaller files of slightly lower visual quality. Example of a target audience: popular sites and social networks with a huge amount of traffic.q_auto:low - Most aggressive algorithm, which results in the smallest files of low visual quality. Example of a target audience: sites using thumbnail images that link to higher quality images.
Examples of the resulting file size when encoding a photograph, using various regular and automatic quality parameter values:
Original (569KB)
q_80 (80.3KB)
q_auto:best (65.9KB)
q_auto:good (56.9KB)
q_auto:eco (45.0KB)
q_auto:low (35.0KB)
Ruby:
cl_image_tag("woman.jpg", :quality=>"auto")
PHP:
cl_image_tag("woman.jpg", array("quality"=>"auto"))
Python:
CloudinaryImage("woman.jpg").image(quality="auto")
Node.js:
cloudinary.image("woman.jpg", {quality: "auto"})
Java:
cloudinary.url().transformation(new Transformation().quality("auto")).imageTag("woman.jpg");
JS:
cloudinary.imageTag('woman.jpg', {quality: "auto"}).toHtml();
jQuery:
$.cloudinary.image("woman.jpg", {quality: "auto"})
React:
<Image publicId="woman.jpg" >
<Transformation quality="auto" />
</Image>
Vue.js:
<cld-image publicId="woman.jpg" >
<cld-transformation quality="auto" />
</cld-image>
Angular:
<cl-image public-id="woman.jpg" >
<cl-transformation quality="auto">
</cl-transformation>
</cl-image>
.Net:
cloudinary.Api.UrlImgUp.Transform(new Transformation().Quality("auto")).BuildImageTag("woman.jpg")
Android:
MediaManager.get().url().transformation(new Transformation().quality("auto")).generate("woman.jpg");
iOS:
imageView.cldSetImage(cloudinary.createUrl().setTransformation(CLDTransformation().setQuality("auto")).generate("woman.jpg")!, cloudinary: cloudinary)
Examples of the resulting file size when encoding a drawing, using regular and automatic quality values:
Original (296KB)
q_80 (223KB)
q_auto:best (226KB)
q_auto:good (156KB)
q_auto:eco (97.5KB)
q_auto:low (87.5KB)
Ruby:
cl_image_tag("robot.jpg", :quality=>"auto")
PHP:
cl_image_tag("robot.jpg", array("quality"=>"auto"))
Python:
CloudinaryImage("robot.jpg").image(quality="auto")
Node.js:
cloudinary.image("robot.jpg", {quality: "auto"})
Java:
cloudinary.url().transformation(new Transformation().quality("auto")).imageTag("robot.jpg");
JS:
cloudinary.imageTag('robot.jpg', {quality: "auto"}).toHtml();
jQuery:
$.cloudinary.image("robot.jpg", {quality: "auto"})
React:
<Image publicId="robot.jpg" >
<Transformation quality="auto" />
</Image>
Vue.js:
<cld-image publicId="robot.jpg" >
<cld-transformation quality="auto" />
</cld-image>
Angular:
<cl-image public-id="robot.jpg" >
<cl-transformation quality="auto">
</cl-transformation>
</cl-image>
.Net:
cloudinary.Api.UrlImgUp.Transform(new Transformation().Quality("auto")).BuildImageTag("robot.jpg")
Android:
MediaManager.get().url().transformation(new Transformation().quality("auto")).generate("robot.jpg");
iOS:
imageView.cldSetImage(cloudinary.createUrl().setTransformation(CLDTransformation().setQuality("auto")).generate("robot.jpg")!, cloudinary: cloudinary)
Notes
q_auto cannot be used within named transformations, however q_auto:[Mode] (e.g., q_auto:good) is supported within named transformations.- Save-Data support is a feature included in the Client-Hints standard, which is already supported by Chrome and Opera browsers. The browsers send a special request header named 'Save-Data' if the user has enabled data saving mode. When
q_auto is specified and the 'Save-Data: on' header reaches the CDN layer of Cloudinary, image compression and encoding will automatically switch to the eco mode (q_auto:eco) instead of the default good quality mode (q_auto:good).
- Override automatic quality: you can override the automatic quality algorithm and set a fixed quality value for a specific image in the media library.
Chroma subsampling is a method of encoding images by implementing less resolution for chroma information (colors) than for luma information (luminance), taking advantage of the human visual system's lower acuity for color differences than for luminance. To override the default behavior of whether to perform chroma subsampling, a separate value can be added to the quality parameter as follows:
444 can be added to prevent subsampling. For example: q_80:444420 can be added to force subsampling. For example: q_95:420.
Note
Chroma subsampling is not performed on images that include a text overlay unless specifically requested.
Cloudinary supports various transformations for modifying the shape and style of images. This section contains information on the following topics:
Many website designs need images with rounded corners, while some websites require images with a complete circular or oval (ellipse) crop. Twitter, for example, uses rounded corners for its users' profile pictures.
Programmatically, rounded corners can be achieved using the original rectangular images combined with modern CSS properties or image masking overlays. However, it is sometimes useful to deliver images with rounded corners in the first place. This is particularly helpful when you want to embed images inside an email (most mail clients can't add CSS based rounded corners), a PDF or a mobile application. Delivering images with already rounded corners is also useful if you want to simplify your CSS and markup or when you need to support older browsers.
Transforming an image to a rounded version is done using the radius parameter (r in URLs). You can manually specify the amount to round various corners, or you can set it to automatically round to an exact ellipse or circle.
Note
To deliver a rounded image with a transparent background, deliver as PNG. Formats that do not support transparency will be delivered by default with a white background, which can be adjusted with the
background transformation parameter. Keep in mind that the PNG format produces larger files than the JPEG format. For more information, see the article on
PNG optimization - saving bandwidth on transparent PNGs with dynamic underlay.
To manually control the rounding, use the radius parameter with between 1 and 4 values defining the rounding amount (in pixels, separated by colons), following the same concept as the border-radius CSS property. When specifying multiple values, keep a corner untouched by specifying '0'.
- One value: Symmetrical. All four corners are rounded equally according to the specified value.
- Two values: Opposites are symmetrical. The first value applies to the top-left and bottom-right corners. The second value applies to the top-right and bottom-left corners.
- Three values: One set of corners is symmetrical. The first value applies to the top-left. The second value applies to the top-right and bottom-left corners. The third value applies to the bottom-right.
- Four values: The rounding for each corner is specified separately, in clockwise order, starting with the top-left.
For example:
r_20
r_25:0
r_10:40:25
r_30:0:30:30
Ruby:
cl_image_tag("Pi.png", :width=>150, :height=>100, :radius=>"25:0", :crop=>"fill")
PHP:
cl_image_tag("Pi.png", array("width"=>150, "height"=>100, "radius"=>"25:0", "crop"=>"fill"))
Python:
CloudinaryImage("Pi.png").image(width=150, height=100, radius="25:0", crop="fill")
Node.js:
cloudinary.image("Pi.png", {width: 150, height: 100, radius: "25:0", crop: "fill"})
Java:
cloudinary.url().transformation(new Transformation().width(150).height(100).radius("25:0").crop("fill")).imageTag("Pi.png");
JS:
cloudinary.imageTag('Pi.png', {width: 150, height: 100, radius: "25:0", crop: "fill"}).toHtml();
jQuery:
$.cloudinary.image("Pi.png", {width: 150, height: 100, radius: "25:0", crop: "fill"})
React:
<Image publicId="Pi.png" >
<Transformation width="150" height="100" radius="25:0" crop="fill" />
</Image>
Vue.js:
<cld-image publicId="Pi.png" >
<cld-transformation width="150" height="100" radius="25:0" crop="fill" />
</cld-image>
Angular:
<cl-image public-id="Pi.png" >
<cl-transformation width="150" height="100" radius="25:0" crop="fill">
</cl-transformation>
</cl-image>
.Net:
cloudinary.Api.UrlImgUp.Transform(new Transformation().Width(150).Height(100).Radius("25:0").Crop("fill")).BuildImageTag("Pi.png")
Android:
MediaManager.get().url().transformation(new Transformation().width(150).height(100).radius("25:0").crop("fill")).generate("Pi.png");
iOS:
imageView.cldSetImage(cloudinary.createUrl().setTransformation(CLDTransformation().setWidth(150).setHeight(100).setRadius("25:0").setCrop("fill")).generate("Pi.png")!, cloudinary: cloudinary)
Rather than specifying specific rounding values, you can automatically crop images to the shape of an ellipse (if the requested image size is a rectangle) or a circle (if the requested image size is a square). Simply pass max as the value of the radius parameter instead of numeric values.
The following example transforms an uploaded JPEG to a 250x150 PNG with maximum radius cropping, which generates the ellipse shape with a transparent background:
Ruby:
cl_image_tag("pi.png", :width=>250, :height=>150, :radius=>"max", :crop=>"fill")
PHP:
cl_image_tag("pi.png", array("width"=>250, "height"=>150, "radius"=>"max", "crop"=>"fill"))
Python:
CloudinaryImage("pi.png").image(width=250, height=150, radius="max", crop="fill")
Node.js:
cloudinary.image("pi.png", {width: 250, height: 150, radius: "max", crop: "fill"})
Java:
cloudinary.url().transformation(new Transformation().width(250).height(150).radius("max").crop("fill")).imageTag("pi.png");
JS:
cloudinary.imageTag('pi.png', {width: 250, height: 150, radius: "max", crop: "fill"}).toHtml();
jQuery:
$.cloudinary.image("pi.png", {width: 250, height: 150, radius: "max", crop: "fill"})
React:
<Image publicId="pi.png" >
<Transformation width="250" height="150" radius="max" crop="fill" />
</Image>
Vue.js:
<cld-image publicId="pi.png" >
<cld-transformation width="250" height="150" radius="max" crop="fill" />
</cld-image>
Angular:
<cl-image public-id="pi.png" >
<cl-transformation width="250" height="150" radius="max" crop="fill">
</cl-transformation>
</cl-image>
.Net:
cloudinary.Api.UrlImgUp.Transform(new Transformation().Width(250).Height(150).Radius("max").Crop("fill")).BuildImageTag("pi.png")
Android:
MediaManager.get().url().transformation(new Transformation().width(250).height(150).radius("max").crop("fill")).generate("pi.png");
iOS:
imageView.cldSetImage(cloudinary.createUrl().setTransformation(CLDTransformation().setWidth(250).setHeight(150).setRadius("max").setCrop("fill")).generate("pi.png")!, cloudinary: cloudinary)
As the following example shows, displaying pictures of your web site's users as circle headshots is very easy to achieve with Cloudinary using face gravity with max radius:
Ruby:
cl_image_tag("face_left.png", :width=>200, :height=>200, :gravity=>"face", :radius=>"max", :crop=>"thumb")
PHP:
cl_image_tag("face_left.png", array("width"=>200, "height"=>200, "gravity"=>"face", "radius"=>"max", "crop"=>"thumb"))
Python:
CloudinaryImage("face_left.png").image(width=200, height=200, gravity="face", radius="max", crop="thumb")
Node.js:
cloudinary.image("face_left.png", {width: 200, height: 200, gravity: "face", radius: "max", crop: "thumb"})
Java:
cloudinary.url().transformation(new Transformation().width(200).height(200).gravity("face").radius("max").crop("thumb")).imageTag("face_left.png");
JS:
cloudinary.imageTag('face_left.png', {width: 200, height: 200, gravity: "face", radius: "max", crop: "thumb"}).toHtml();
jQuery:
$.cloudinary.image("face_left.png", {width: 200, height: 200, gravity: "face", radius: "max", crop: "thumb"})
React:
<Image publicId="face_left.png" >
<Transformation width="200" height="200" gravity="face" radius="max" crop="thumb" />
</Image>
Vue.js:
<cld-image publicId="face_left.png" >
<cld-transformation width="200" height="200" gravity="face" radius="max" crop="thumb" />
</cld-image>
Angular:
<cl-image public-id="face_left.png" >
<cl-transformation width="200" height="200" gravity="face" radius="max" crop="thumb">
</cl-transformation>
</cl-image>
.Net:
cloudinary.Api.UrlImgUp.Transform(new Transformation().Width(200).Height(200).Gravity("face").Radius("max").Crop("thumb")).BuildImageTag("face_left.png")
Android:
MediaManager.get().url().transformation(new Transformation().width(200).height(200).gravity("face").radius("max").crop("thumb")).generate("face_left.png");
iOS:
imageView.cldSetImage(cloudinary.createUrl().setTransformation(CLDTransformation().setWidth(200).setHeight(200).setGravity("face").setRadius("max").setCrop("thumb")).generate("face_left.png")!, cloudinary: cloudinary)
You can also overlay circular pictures of your users on other images using the layer_apply flag that tells Cloudinary to apply the rounding (and other transformations) to the overlay image and not to the base image:
Ruby:
cl_image_tag("flower.jpg", :transformation=>[
{:width=>200, :height=>200, :gravity=>"face", :radius=>"max", :overlay=>"face_left", :crop=>"thumb"},
{:flags=>"layer_apply", :gravity=>"north_east"}
])
PHP:
cl_image_tag("flower.jpg", array("transformation"=>array(
array("width"=>200, "height"=>200, "gravity"=>"face", "radius"=>"max", "overlay"=>"face_left", "crop"=>"thumb"),
array("flags"=>"layer_apply", "gravity"=>"north_east")
)))
Python:
CloudinaryImage("flower.jpg").image(transformation=[
{'width': 200, 'height': 200, 'gravity': "face", 'radius': "max", 'overlay': "face_left", 'crop': "thumb"},
{'flags': "layer_apply", 'gravity': "north_east"}
])
Node.js:
cloudinary.image("flower.jpg", {transformation: [
{width: 200, height: 200, gravity: "face", radius: "max", overlay: "face_left", crop: "thumb"},
{flags: "layer_apply", gravity: "north_east"}
]})
Java:
cloudinary.url().transformation(new Transformation()
.width(200).height(200).gravity("face").radius("max").overlay(new Layer().publicId("face_left")).crop("thumb").chain()
.flags("layer_apply").gravity("north_east")).imageTag("flower.jpg");
JS:
cloudinary.imageTag('flower.jpg', {transformation: [
{width: 200, height: 200, gravity: "face", radius: "max", overlay: new cloudinary.Layer().publicId("face_left"), crop: "thumb"},
{flags: "layer_apply", gravity: "north_east"}
]}).toHtml();
jQuery:
$.cloudinary.image("flower.jpg", {transformation: [
{width: 200, height: 200, gravity: "face", radius: "max", overlay: new cloudinary.Layer().publicId("face_left"), crop: "thumb"},
{flags: "layer_apply", gravity: "north_east"}
]})
React:
<Image publicId="flower.jpg" >
<Transformation width="200" height="200" gravity="face" radius="max" overlay="face_left" crop="thumb" />
<Transformation flags="layer_apply" gravity="north_east" />
</Image>
Vue.js:
<cld-image publicId="flower.jpg" >
<cld-transformation width="200" height="200" gravity="face" radius="max" overlay="face_left" crop="thumb" />
<cld-transformation flags="layer_apply" gravity="north_east" />
</cld-image>
Angular:
<cl-image public-id="flower.jpg" >
<cl-transformation width="200" height="200" gravity="face" radius="max" overlay="face_left" crop="thumb">
</cl-transformation>
<cl-transformation flags="layer_apply" gravity="north_east">
</cl-transformation>
</cl-image>
.Net:
cloudinary.Api.UrlImgUp.Transform(new Transformation()
.Width(200).Height(200).Gravity("face").Radius("max").Overlay(new Layer().PublicId("face_left")).Crop("thumb").Chain()
.Flags("layer_apply").Gravity("north_east")).BuildImageTag("flower.jpg")
Android:
MediaManager.get().url().transformation(new Transformation()
.width(200).height(200).gravity("face").radius("max").overlay(new Layer().publicId("face_left")).crop("thumb").chain()
.flags("layer_apply").gravity("north_east")).generate("flower.jpg");
iOS:
imageView.cldSetImage(cloudinary.createUrl().setTransformation(CLDTransformation()
.setWidth(200).setHeight(200).setGravity("face").setRadius("max").setOverlay("face_left").setCrop("thumb").chain()
.setFlags("layer_apply").setGravity("north_east")).generate("flower.jpg")!, cloudinary: cloudinary)
Rotate an image by any arbitrary angle in degrees with the angle parameter (a in URLs). A positive integer value rotates the image clockwise, and a negative integer value rotates the image counterclockwise. If the angle is not a multiple of 90 then a rectangular bounding box is added containing the rotated image and empty space.
Other possible rotation values instead of an integer value include:
auto_right - Rotate the image 90 degrees clockwise only if the requested aspect ratio does not match the image's aspect ratio. auto_left - Rotate the image 90 degrees counterclockwise only if the requested aspect ratio does not match the image's aspect ratio.vflip - Vertical mirror flip of the image.hflip - Horizontal mirror flip of the image.ignore - By default, the image is automatically rotated according to the EXIF data stored by the camera when the image was taken. Set the rotation to 'ignore' if you do not want the image to be automatically rotated.
Note
To apply multiple values, separate each value with a dot (
.). For example to horizontally flip the image and rotate it by 45 degrees:
angle: hflip.45Examples with the uploaded image named sample (all images are also scaled down to a width of 100 pixels):
- Rotate the image by 90 degrees:
Ruby:
cl_image_tag("sample.jpg", :transformation=>[
{:width=>100, :crop=>"scale"},
{:angle=>90}
])
PHP:
cl_image_tag("sample.jpg", array("transformation"=>array(
array("width"=>100, "crop"=>"scale"),
array("angle"=>90)
)))
Python:
CloudinaryImage("sample.jpg").image(transformation=[
{'width': 100, 'crop': "scale"},
{'angle': 90}
])
Node.js:
cloudinary.image("sample.jpg", {transformation: [
{width: 100, crop: "scale"},
{angle: 90}
]})
Java:
cloudinary.url().transformation(new Transformation()
.width(100).crop("scale").chain()
.angle(90)).imageTag("sample.jpg");
JS:
cloudinary.imageTag('sample.jpg', {transformation: [
{width: 100, crop: "scale"},
{angle: 90}
]}).toHtml();
jQuery:
$.cloudinary.image("sample.jpg", {transformation: [
{width: 100, crop: "scale"},
{angle: 90}
]})
React:
<Image publicId="sample.jpg" >
<Transformation width="100" crop="scale" />
<Transformation angle="90" />
</Image>
Vue.js:
<cld-image publicId="sample.jpg" >
<cld-transformation width="100" crop="scale" />
<cld-transformation angle="90" />
</cld-image>
Angular:
<cl-image public-id="sample.jpg" >
<cl-transformation width="100" crop="scale">
</cl-transformation>
<cl-transformation angle="90">
</cl-transformation>
</cl-image>
.Net:
cloudinary.Api.UrlImgUp.Transform(new Transformation()
.Width(100).Crop("scale").Chain()
.Angle(90)).BuildImageTag("sample.jpg")
Android:
MediaManager.get().url().transformation(new Transformation()
.width(100).crop("scale").chain()
.angle(90)).generate("sample.jpg");
iOS:
imageView.cldSetImage(cloudinary.createUrl().setTransformation(CLDTransformation()
.setWidth(100).setCrop("scale").chain()
.setAngle(90)).generate("sample.jpg")!, cloudinary: cloudinary)
- Rotate the image by -20 degrees (automatically adds a bounding box):
Ruby:
cl_image_tag("sample.jpg", :transformation=>[
{:width=>100, :crop=>"scale"},
{:angle=>-20}
])
PHP:
cl_image_tag("sample.jpg", array("transformation"=>array(
array("width"=>100, "crop"=>"scale"),
array("angle"=>-20)
)))
Python:
CloudinaryImage("sample.jpg").image(transformation=[
{'width': 100, 'crop': "scale"},
{'angle': -20}
])
Node.js:
cloudinary.image("sample.jpg", {transformation: [
{width: 100, crop: "scale"},
{angle: -20}
]})
Java:
cloudinary.url().transformation(new Transformation()
.width(100).crop("scale").chain()
.angle(-20)).imageTag("sample.jpg");
JS:
cloudinary.imageTag('sample.jpg', {transformation: [
{width: 100, crop: "scale"},
{angle: -20}
]}).toHtml();
jQuery:
$.cloudinary.image("sample.jpg", {transformation: [
{width: 100, crop: "scale"},
{angle: -20}
]})
React:
<Image publicId="sample.jpg" >
<Transformation width="100" crop="scale" />
<Transformation angle="-20" />
</Image>
Vue.js:
<cld-image publicId="sample.jpg" >
<cld-transformation width="100" crop="scale" />
<cld-transformation angle="-20" />
</cld-image>
Angular:
<cl-image public-id="sample.jpg" >
<cl-transformation width="100" crop="scale">
</cl-transformation>
<cl-transformation angle="-20">
</cl-transformation>
</cl-image>
.Net:
cloudinary.Api.UrlImgUp.Transform(new Transformation()
.Width(100).Crop("scale").Chain()
.Angle(-20)).BuildImageTag("sample.jpg")
Android:
MediaManager.get().url().transformation(new Transformation()
.width(100).crop("scale").chain()
.angle(-20)).generate("sample.jpg");
iOS:
imageView.cldSetImage(cloudinary.createUrl().setTransformation(CLDTransformation()
.setWidth(100).setCrop("scale").chain()
.setAngle(-20)).generate("sample.jpg")!, cloudinary: cloudinary)
- Vertically mirror flip the image and rotate by 70 degrees (automatically adds a bounding box):
Ruby:
cl_image_tag("sample.jpg", :transformation=>[
{:width=>100, :crop=>"scale"},
{:angle=>["vflip", 45]}
])
PHP:
cl_image_tag("sample.jpg", array("transformation"=>array(
array("width"=>100, "crop"=>"scale"),
array("angle"=>array("vflip", 45))
)))
Python:
CloudinaryImage("sample.jpg").image(transformation=[
{'width': 100, 'crop': "scale"},
{'angle': ["vflip", 45]}
])
Node.js:
cloudinary.image("sample.jpg", {transformation: [
{width: 100, crop: "scale"},
{angle: ["vflip", 45]}
]})
Java:
cloudinary.url().transformation(new Transformation()
.width(100).crop("scale").chain()
.angle("vflip", "45")).imageTag("sample.jpg");
JS:
cloudinary.imageTag('sample.jpg', {transformation: [
{width: 100, crop: "scale"},
{angle: ["vflip", 45]}
]}).toHtml();
jQuery:
$.cloudinary.image("sample.jpg", {transformation: [
{width: 100, crop: "scale"},
{angle: ["vflip", 45]}
]})
React:
<Image publicId="sample.jpg" >
<Transformation width="100" crop="scale" />
<Transformation angle={["vflip", 45]} />
</Image>
Vue.js:
<cld-image publicId="sample.jpg" >
<cld-transformation width="100" crop="scale" />
<cld-transformation angle={["vflip", 45]} />
</cld-image>
Angular:
<cl-image public-id="sample.jpg" >
<cl-transformation width="100" crop="scale">
</cl-transformation>
<cl-transformation angle={{["vflip", 45]}}>
</cl-transformation>
</cl-image>
.Net:
cloudinary.Api.UrlImgUp.Transform(new Transformation()
.Width(100).Crop("scale").Chain()
.Angle("vflip", "45")).BuildImageTag("sample.jpg")
Android:
MediaManager.get().url().transformation(new Transformation()
.width(100).crop("scale").chain()
.angle("vflip", "45")).generate("sample.jpg");
iOS:
imageView.cldSetImage(cloudinary.createUrl().setTransformation(CLDTransformation()
.setWidth(100).setCrop("scale").chain()
.setAngle("vflip", "45")).generate("sample.jpg")!, cloudinary: cloudinary)
- Crop the image to a 200x200 circle, then rotate the image by 30 degrees (automatically adds a bounding box) and finally trim the extra whitespace added:
Ruby:
cl_image_tag("sample.jpg", :transformation=>[
{:width=>200, :height=>200, :radius=>"max", :crop=>"fill"},
{:angle=>30},
{:effect=>"trim"}
])
PHP:
cl_image_tag("sample.jpg", array("transformation"=>array(
array("width"=>200, "height"=>200, "radius"=>"max", "crop"=>"fill"),
array("angle"=>30),
array("effect"=>"trim")
)))
Python:
CloudinaryImage("sample.jpg").image(transformation=[
{'width': 200, 'height': 200, 'radius': "max", 'crop': "fill"},
{'angle': 30},
{'effect': "trim"}
])
Node.js:
cloudinary.image("sample.jpg", {transformation: [
{width: 200, height: 200, radius: "max", crop: "fill"},
{angle: 30},
{effect: "trim"}
]})
Java:
cloudinary.url().transformation(new Transformation()
.width(200).height(200).radius("max").crop("fill").chain()
.angle(30).chain()
.effect("trim")).imageTag("sample.jpg");
JS:
cloudinary.imageTag('sample.jpg', {transformation: [
{width: 200, height: 200, radius: "max", crop: "fill"},
{angle: 30},
{effect: "trim"}
]}).toHtml();
jQuery:
$.cloudinary.image("sample.jpg", {transformation: [
{width: 200, height: 200, radius: "max", crop: "fill"},
{angle: 30},
{effect: "trim"}
]})
React:
<Image publicId="sample.jpg" >
<Transformation width="200" height="200" radius="max" crop="fill" />
<Transformation angle="30" />
<Transformation effect="trim" />
</Image>
Vue.js:
<cld-image publicId="sample.jpg" >
<cld-transformation width="200" height="200" radius="max" crop="fill" />
<cld-transformation angle="30" />
<cld-transformation effect="trim" />
</cld-image>
Angular:
<cl-image public-id="sample.jpg" >
<cl-transformation width="200" height="200" radius="max" crop="fill">
</cl-transformation>
<cl-transformation angle="30">
</cl-transformation>
<cl-transformation effect="trim">
</cl-transformation>
</cl-image>
.Net:
cloudinary.Api.UrlImgUp.Transform(new Transformation()
.Width(200).Height(200).Radius("max").Crop("fill").Chain()
.Angle(30).Chain()
.Effect("trim")).BuildImageTag("sample.jpg")
Android:
MediaManager.get().url().transformation(new Transformation()
.width(200).height(200).radius("max").crop("fill").chain()
.angle(30).chain()
.effect("trim")).generate("sample.jpg");
iOS:
imageView.cldSetImage(cloudinary.createUrl().setTransformation(CLDTransformation()
.setWidth(200).setHeight(200).setRadius("max").setCrop("fill").chain()
.setAngle(30).chain()
.setEffect("trim")).generate("sample.jpg")!, cloudinary: cloudinary)
Adjust the opacity of an image with the opacity parameter (o in URLs). The parameter accepts a value between 0-100 representing the percentage of transparency, where 100 means completely opaque and 0 is completely transparent.
Note
If the image format does not support transparency, the background color is used instead as a base (white by default). The color can be changed with the
background parameter.
For example, the uploaded image named sample delivered with 30% opacity:
Ruby:
cl_image_tag("sample.jpg", :opacity=>30)
PHP:
cl_image_tag("sample.jpg", array("opacity"=>30))
Python:
CloudinaryImage("sample.jpg").image(opacity=30)
Node.js:
cloudinary.image("sample.jpg", {opacity: 30})
Java:
cloudinary.url().transformation(new Transformation().opacity(30)).imageTag("sample.jpg");
JS:
cloudinary.imageTag('sample.jpg', {opacity: 30}).toHtml();
jQuery:
$.cloudinary.image("sample.jpg", {opacity: 30})
React:
<Image publicId="sample.jpg" >
<Transformation opacity="30" />
</Image>
Vue.js:
<cld-image publicId="sample.jpg" >
<cld-transformation opacity="30" />
</cld-image>
Angular:
<cl-image public-id="sample.jpg" >
<cl-transformation opacity="30">
</cl-transformation>
</cl-image>
.Net:
cloudinary.Api.UrlImgUp.Transform(new Transformation().Opacity(30)).BuildImageTag("sample.jpg")
Android:
MediaManager.get().url().transformation(new Transformation().opacity(30)).generate("sample.jpg");
iOS:
imageView.cldSetImage(cloudinary.createUrl().setTransformation(CLDTransformation().setOpacity(30)).generate("sample.jpg")!, cloudinary: cloudinary)
Controlling the opacity is especially useful when placing other images as overlays. For example, an overlay of cloudinary_icon added with 60% opacity:
Ruby:
cl_image_tag("sample.jpg", :overlay=>"cloudinary_icon", :width=>300, :gravity=>"north_east", :opacity=>60)
PHP:
cl_image_tag("sample.jpg", array("overlay"=>"cloudinary_icon", "width"=>300, "gravity"=>"north_east", "opacity"=>60))
Python:
CloudinaryImage("sample.jpg").image(overlay="cloudinary_icon", width=300, gravity="north_east", opacity=60)
Node.js:
cloudinary.image("sample.jpg", {overlay: "cloudinary_icon", width: 300, gravity: "north_east", opacity: 60})
Java:
cloudinary.url().transformation(new Transformation().overlay(new Layer().publicId("cloudinary_icon")).width(300).gravity("north_east").opacity(60)).imageTag("sample.jpg");
JS:
cloudinary.imageTag('sample.jpg', {overlay: new cloudinary.Layer().publicId("cloudinary_icon"), width: 300, gravity: "north_east", opacity: 60}).toHtml();
jQuery:
$.cloudinary.image("sample.jpg", {overlay: new cloudinary.Layer().publicId("cloudinary_icon"), width: 300, gravity: "north_east", opacity: 60})
React:
<Image publicId="sample.jpg" >
<Transformation overlay="cloudinary_icon" width="300" gravity="north_east" opacity="60" />
</Image>
Vue.js:
<cld-image publicId="sample.jpg" >
<cld-transformation overlay="cloudinary_icon" width="300" gravity="north_east" opacity="60" />
</cld-image>
Angular:
<cl-image public-id="sample.jpg" >
<cl-transformation overlay="cloudinary_icon" width="300" gravity="north_east" opacity="60">
</cl-transformation>
</cl-image>
.Net:
cloudinary.Api.UrlImgUp.Transform(new Transformation().Overlay(new Layer().PublicId("cloudinary_icon")).Width(300).Gravity("north_east").Opacity(60)).BuildImageTag("sample.jpg")
Android:
MediaManager.get().url().transformation(new Transformation().overlay(new Layer().publicId("cloudinary_icon")).width(300).gravity("north_east").opacity(60)).generate("sample.jpg");
iOS:
imageView.cldSetImage(cloudinary.createUrl().setTransformation(CLDTransformation().setOverlay("cloudinary_icon").setWidth(300).setGravity("north_east").setOpacity(60)).generate("sample.jpg")!, cloudinary: cloudinary)
Add a solid border around the image with the border parameter (bo in URLs). The parameter accepts a value with a CSS-like format: width_style_color (e.g., 3px_solid_black).
An opaque color can be set as an RGB hex triplet (e.g., rgb:3e2222), a 3-digit RGB hex (e.g., rgb:777) or a named color (e.g., green).
You can also use a 4-digit or 8-digit RGBA hex quadruplet for the color, where the 4th hex value represents the alpha (opacity) value (e.g., co_rgb:3e222240 results in 25% opacity).
Additionally, Cloudinary's client libraries also support a # shortcut for RGB (e.g., setting color to #3e2222 which is then translated to rgb:3e2222), and when using Cloudinary's client libraries, you can optionally set the border values programmatically instead of as a single string (e.g., :border => { :width => 4, :color => 'black' }).
Note
Currently only the 'solid' border style is supported.
For example, the uploaded jpg image named sample delivered with a 5 pixel red border:
Ruby:
cl_image_tag("sample.jpg", :border=>"5px_solid_red")
PHP:
cl_image_tag("sample.jpg", array("border"=>"5px_solid_red"))
Python:
CloudinaryImage("sample.jpg").image(border="5px_solid_red")
Node.js:
cloudinary.image("sample.jpg", {border: "5px_solid_red"})
Java:
cloudinary.url().transformation(new Transformation().border("5px_solid_red")).imageTag("sample.jpg");
JS:
cloudinary.imageTag('sample.jpg', {border: "5px_solid_red"}).toHtml();
jQuery:
$.cloudinary.image("sample.jpg", {border: "5px_solid_red"})
React:
<Image publicId="sample.jpg" >
<Transformation border="5px_solid_red" />
</Image>
Vue.js:
<cld-image publicId="sample.jpg" >
<cld-transformation border="5px_solid_red" />
</cld-image>
Angular:
<cl-image public-id="sample.jpg" >
<cl-transformation border="5px_solid_red">
</cl-transformation>
</cl-image>
.Net:
cloudinary.Api.UrlImgUp.Transform(new Transformation().Border("5px_solid_red")).BuildImageTag("sample.jpg")
Android:
MediaManager.get().url().transformation(new Transformation().border("5px_solid_red")).generate("sample.jpg");
iOS:
imageView.cldSetImage(cloudinary.createUrl().setTransformation(CLDTransformation().setBorder("5px_solid_red")).generate("sample.jpg")!, cloudinary: cloudinary)
Borders are also useful for adding to overlays to clearly define the overlaying image, and also automatically adapt to any rounded corner transformations. For example, an image of lady cropped with face detection and given rounded corners with a 10 pixel grey border, and an overlay of the image of young_couple resized to a 150x150 circular thumbnail with face detection and a black 3 pixel border, added to the northeast corner:
URL:
https://res.cloudinary.com/demo/image/upload/c_crop,g_face,r_75,bo_10px_solid_grey/l_young_couple,w_150,h_150,c_thumb,r_max,g_faces,bo_3px_solid_black/fl_layer_apply,g_north_east/lady.jpg Ruby:
cl_image_tag("lady.jpg", :transformation=>[
{:gravity=>"face", :radius=>75, :border=>"10px_solid_grey", :crop=>"crop"},
{:overlay=>"young_couple", :width=>150, :height=>150, :radius=>"max", :gravity=>"faces", :border=>"3px_solid_black", :crop=>"thumb"},
{:flags=>"layer_apply", :gravity=>"north_east"}
])
PHP:
cl_image_tag("lady.jpg", array("transformation"=>array(
array("gravity"=>"face", "radius"=>75, "border"=>"10px_solid_grey", "crop"=>"crop"),
array("overlay"=>"young_couple", "width"=>150, "height"=>150, "radius"=>"max", "gravity"=>"faces", "border"=>"3px_solid_black", "crop"=>"thumb"),
array("flags"=>"layer_apply", "gravity"=>"north_east")
)))
Python:
CloudinaryImage("lady.jpg").image(transformation=[
{'gravity': "face", 'radius': 75, 'border': "10px_solid_grey", 'crop': "crop"},
{'overlay': "young_couple", 'width': 150, 'height': 150, 'radius': "max", 'gravity': "faces", 'border': "3px_solid_black", 'crop': "thumb"},
{'flags': "layer_apply", 'gravity': "north_east"}
])
Node.js:
cloudinary.image("lady.jpg", {transformation: [
{gravity: "face", radius: 75, border: "10px_solid_grey", crop: "crop"},
{overlay: "young_couple", width: 150, height: 150, radius: "max", gravity: "faces", border: "3px_solid_black", crop: "thumb"},
{flags: "layer_apply", gravity: "north_east"}
]})
Java:
cloudinary.url().transformation(new Transformation()
.gravity("face").radius(75).border("10px_solid_grey").crop("crop").chain()
.overlay(new Layer().publicId("young_couple")).width(150).height(150).radius("max").gravity("faces").border("3px_solid_black").crop("thumb").chain()
.flags("layer_apply").gravity("north_east")).imageTag("lady.jpg");
JS:
cloudinary.imageTag('lady.jpg', {transformation: [
{gravity: "face", radius: 75, border: "10px_solid_grey", crop: "crop"},
{overlay: new cloudinary.Layer().publicId("young_couple"), width: 150, height: 150, radius: "max", gravity: "faces", border: "3px_solid_black", crop: "thumb"},
{flags: "layer_apply", gravity: "north_east"}
]}).toHtml();
jQuery:
$.cloudinary.image("lady.jpg", {transformation: [
{gravity: "face", radius: 75, border: "10px_solid_grey", crop: "crop"},
{overlay: new cloudinary.Layer().publicId("young_couple"), width: 150, height: 150, radius: "max", gravity: "faces", border: "3px_solid_black", crop: "thumb"},
{flags: "layer_apply", gravity: "north_east"}
]})
React:
<Image publicId="lady.jpg" >
<Transformation gravity="face" radius="75" border="10px_solid_grey" crop="crop" />
<Transformation overlay="young_couple" width="150" height="150" radius="max" gravity="faces" border="3px_solid_black" crop="thumb" />
<Transformation flags="layer_apply" gravity="north_east" />
</Image>
Vue.js:
<cld-image publicId="lady.jpg" >
<cld-transformation gravity="face" radius="75" border="10px_solid_grey" crop="crop" />
<cld-transformation overlay="young_couple" width="150" height="150" radius="max" gravity="faces" border="3px_solid_black" crop="thumb" />
<cld-transformation flags="layer_apply" gravity="north_east" />
</cld-image>
Angular:
<cl-image public-id="lady.jpg" >
<cl-transformation gravity="face" radius="75" border="10px_solid_grey" crop="crop">
</cl-transformation>
<cl-transformation overlay="young_couple" width="150" height="150" radius="max" gravity="faces" border="3px_solid_black" crop="thumb">
</cl-transformation>
<cl-transformation flags="layer_apply" gravity="north_east">
</cl-transformation>
</cl-image>
.Net:
cloudinary.Api.UrlImgUp.Transform(new Transformation()
.Gravity("face").Radius(75).Border("10px_solid_grey").Crop("crop").Chain()
.Overlay(new Layer().PublicId("young_couple")).Width(150).Height(150).Radius("max").Gravity("faces").Border("3px_solid_black").Crop("thumb").Chain()
.Flags("layer_apply").Gravity("north_east")).BuildImageTag("lady.jpg")
Android:
MediaManager.get().url().transformation(new Transformation()
.gravity("face").radius(75).border("10px_solid_grey").crop("crop").chain()
.overlay(new Layer().publicId("young_couple")).width(150).height(150).radius("max").gravity("faces").border("3px_solid_black").crop("thumb").chain()
.flags("layer_apply").gravity("north_east")).generate("lady.jpg");
iOS:
imageView.cldSetImage(cloudinary.createUrl().setTransformation(CLDTransformation()
.setGravity("face").setRadius(75).setBorder("10px_solid_grey").setCrop("crop").chain()
.setOverlay("young_couple").setWidth(150).setHeight(150).setRadius("max").setGravity("faces").setBorder("3px_solid_black").setCrop("thumb").chain()
.setFlags("layer_apply").setGravity("north_east")).generate("lady.jpg")!, cloudinary: cloudinary)
Note
When using the border parameter to set the border color of a text overlay, you can also set the color to
predominant_contrast. This selects the strongest contrasting color to the predominant color while taking all pixels in the image into account. For example,
l_text:Arial_30:foo,bo_3px_solid_predominant_contrastUse the background parameter (b in URLs) to set the background color of the image. The image background is visible when padding is added with one of the padding crop modes, when rounding corners, when adding overlays, and with semi-transparent PNGs and GIFs.
An opaque color can be set as an RGB hex triplet (e.g., b_rgb:3e2222), a 3-digit RGB hex (e.g., b_rgb:777) or a named color (e.g., b_green). Cloudinary's client libraries also support a # shortcut for RGB (e.g., setting background to #3e2222 which is then translated to rgb:3e2222).
For example, the uploaded image named sample padded to a width and height of 300 pixels with a green background:
Ruby:
cl_image_tag("sample.jpg", :width=>300, :height=>300, :background=>"green", :crop=>"pad")
PHP:
cl_image_tag("sample.jpg", array("width"=>300, "height"=>300, "background"=>"green", "crop"=>"pad"))
Python:
CloudinaryImage("sample.jpg").image(width=300, height=300, background="green", crop="pad")
Node.js:
cloudinary.image("sample.jpg", {width: 300, height: 300, background: "green", crop: "pad"})
Java:
cloudinary.url().transformation(new Transformation().width(300).height(300).background("green").crop("pad")).imageTag("sample.jpg");
JS:
cloudinary.imageTag('sample.jpg', {width: 300, height: 300, background: "green", crop: "pad"}).toHtml();
jQuery:
$.cloudinary.image("sample.jpg", {width: 300, height: 300, background: "green", crop: "pad"})
React:
<Image publicId="sample.jpg" >
<Transformation width="300" height="300" background="green" crop="pad" />
</Image>
Vue.js:
<cld-image publicId="sample.jpg" >
<cld-transformation width="300" height="300" background="green" crop="pad" />
</cld-image>
Angular:
<cl-image public-id="sample.jpg" >
<cl-transformation width="300" height="300" background="green" crop="pad">
</cl-transformation>
</cl-image>
.Net:
cloudinary.Api.UrlImgUp.Transform(new Transformation().Width(300).Height(300).Background("green").Crop("pad")).BuildImageTag("sample.jpg")
Android:
MediaManager.get().url().transformation(new Transformation().width(300).height(300).background("green").crop("pad")).generate("sample.jpg");
iOS:
imageView.cldSetImage(cloudinary.createUrl().setTransformation(CLDTransformation().setWidth(300).setHeight(300).setBackground("green").setCrop("pad")).generate("sample.jpg")!, cloudinary: cloudinary)
You can also use a 4-digit or 8-digit RGBA hex quadruplet for the background color, where the 4th hex value represents the alpha (opacity) value (e.g., co_rgb:3e222240 results in 25% opacity).
Note
When using the background parameter to set the background color of a text overlay, you can also set the color to
predominant_contrast. This selects the strongest contrasting color to the predominant color while taking all pixels in the image into account. For example,
l_text:Arial_30:foo,b_predominant_contrast.
You can automatically set the background color to the most prominent color in the image when applying one of the padding crop modes (pad, lpad, or mpad) by setting the background parameter to auto (b_auto in URLs). The parameter can also accept an additional value as follows:
b_auto:border - selects the predominant color while taking only the image border pixels into account. This is the default option for b_auto.b_auto:predominant - selects the predominant color while taking all pixels in the image into account.b_auto:border_contrast - selects the strongest contrasting color to the predominant color while taking only the image border pixels into account.b_auto:predominant_contrast - selects the strongest contrasting color to the predominant color while taking all pixels in the image into account.
b_auto:border
b_auto:predominant
b_auto:border_contrast
b_auto:predominant_contrast
For example, padding the sample image to a width and height of 300 pixels, and with the background color set to the predominant color in the image:
Ruby:
cl_image_tag("sample.jpg", :height=>300, :width=>300, :background=>"auto:predominant", :crop=>"pad")
PHP:
cl_image_tag("sample.jpg", array("height"=>300, "width"=>300, "background"=>"auto:predominant", "crop"=>"pad"))
Python:
CloudinaryImage("sample.jpg").image(height=300, width=300, background="auto:predominant", crop="pad")
Node.js:
cloudinary.image("sample.jpg", {height: 300, width: 300, background: "auto:predominant", crop: "pad"})
Java:
cloudinary.url().transformation(new Transformation().height(300).width(300).background("auto:predominant").crop("pad")).imageTag("sample.jpg");
JS:
cloudinary.imageTag('sample.jpg', {height: 300, width: 300, background: "auto:predominant", crop: "pad"}).toHtml();
jQuery:
$.cloudinary.image("sample.jpg", {height: 300, width: 300, background: "auto:predominant", crop: "pad"})
React:
<Image publicId="sample.jpg" >
<Transformation height="300" width="300" background="auto:predominant" crop="pad" />
</Image>
Vue.js:
<cld-image publicId="sample.jpg" >
<cld-transformation height="300" width="300" background="auto:predominant" crop="pad" />
</cld-image>
Angular:
<cl-image public-id="sample.jpg" >
<cl-transformation height="300" width="300" background="auto:predominant" crop="pad">
</cl-transformation>
</cl-image>
.Net:
cloudinary.Api.UrlImgUp.Transform(new Transformation().Height(300).Width(300).Background("auto:predominant").Crop("pad")).BuildImageTag("sample.jpg")
Android:
MediaManager.get().url().transformation(new Transformation().height(300).width(300).background("auto:predominant").crop("pad")).generate("sample.jpg");
iOS:
imageView.cldSetImage(cloudinary.createUrl().setTransformation(CLDTransformation().setHeight(300).setWidth(300).setBackground("auto:predominant").setCrop("pad")).generate("sample.jpg")!, cloudinary: cloudinary)
Gradient fade
You can also apply a padding gradient fade effect with the predominant colors in the image by adjusting the value of the b_auto parameter as follows:
b_auto:[gradient_type]:[number]:[direction]
Where:
gradient_type - one of the following values:
predominant_gradient - base the gradient fade effect on the predominant colors in the imagepredominant_gradient_contrast - base the effect on the colors that contrast the predominant colors in the imageborder_gradient - base the gradient fade effect on the predominant colors in the border pixels of the imageborder_gradient_contrast - base the effect on the colors that contrast the predominant colors in the border pixels of the image
number - the number of predominant colors to select. Possible values: 2 or 4. Default: 2direction - if 2 colors are selected, this parameter specifies the direction to blend the 2 colors together (if 4 colors are selected each gets interpolated between the four corners). Possible values: horizontal, vertical, diagonal_desc, and diagonal_asc. Default: horizontal
predominant_gradient:2:diagonal_desc
predominant_gradient_contrast:4
Ruby:
cl_image_tag("horse.jpg", :height=>300, :width=>300, :background=>"auto:predominant_gradient_contrast:4", :crop=>"pad")
PHP:
cl_image_tag("horse.jpg", array("height"=>300, "width"=>300, "background"=>"auto:predominant_gradient_contrast:4", "crop"=>"pad"))
Python:
CloudinaryImage("horse.jpg").image(height=300, width=300, background="auto:predominant_gradient_contrast:4", crop="pad")
Node.js:
cloudinary.image("horse.jpg", {height: 300, width: 300, background: "auto:predominant_gradient_contrast:4", crop: "pad"})
Java:
cloudinary.url().transformation(new Transformation().height(300).width(300).background("auto:predominant_gradient_contrast:4").crop("pad")).imageTag("horse.jpg");
JS:
cloudinary.imageTag('horse.jpg', {height: 300, width: 300, background: "auto:predominant_gradient_contrast:4", crop: "pad"}).toHtml();
jQuery:
$.cloudinary.image("horse.jpg", {height: 300, width: 300, background: "auto:predominant_gradient_contrast:4", crop: "pad"})
React:
<Image publicId="horse.jpg" >
<Transformation height="300" width="300" background="auto:predominant_gradient_contrast:4" crop="pad" />
</Image>
Vue.js:
<cld-image publicId="horse.jpg" >
<cld-transformation height="300" width="300" background="auto:predominant_gradient_contrast:4" crop="pad" />
</cld-image>
Angular:
<cl-image public-id="horse.jpg" >
<cl-transformation height="300" width="300" background="auto:predominant_gradient_contrast:4" crop="pad">
</cl-transformation>
</cl-image>
.Net:
cloudinary.Api.UrlImgUp.Transform(new Transformation().Height(300).Width(300).Background("auto:predominant_gradient_contrast:4").Crop("pad")).BuildImageTag("horse.jpg")
Android:
MediaManager.get().url().transformation(new Transformation().height(300).width(300).background("auto:predominant_gradient_contrast:4").crop("pad")).generate("horse.jpg");
iOS:
imageView.cldSetImage(cloudinary.createUrl().setTransformation(CLDTransformation().setHeight(300).setWidth(300).setBackground("auto:predominant_gradient_contrast:4").setCrop("pad")).generate("horse.jpg")!, cloudinary: cloudinary)
Custom color palette
Add a custom palette to limit the selected color to one of the colors in the palette that you provide. Once the predominant color has been calculated then the closest color from the available palette is selected. Append a colon and then the value palette followed by a list of colors, each separated by an underscore. For example, to automatically add padding and a palette that limits the possible choices to green, red and blue: b_auto:palette_red_green_blue
The palette can be used in combination with any of the various values for b_auto, and the same color in the palette can be selected more than once when requesting multiple predominant colors. For example, padding to a width and height of 300 pixels, with a 4 color gradient fade in the auto colored padding, and limiting the possible colors to red, green, blue, and orange:
Ruby:
cl_image_tag("horse.jpg", :height=>300, :width=>300, :background=>"auto:predominant_gradient:4:palette_red_green_blue_orange", :crop=>"pad")
PHP:
cl_image_tag("horse.jpg", array("height"=>300, "width"=>300, "background"=>"auto:predominant_gradient:4:palette_red_green_blue_orange", "crop"=>"pad"))
Python:
CloudinaryImage("horse.jpg").image(height=300, width=300, background="auto:predominant_gradient:4:palette_red_green_blue_orange", crop="pad")
Node.js:
cloudinary.image("horse.jpg", {height: 300, width: 300, background: "auto:predominant_gradient:4:palette_red_green_blue_orange", crop: "pad"})
Java:
cloudinary.url().transformation(new Transformation().height(300).width(300).background("auto:predominant_gradient:4:palette_red_green_blue_orange").crop("pad")).imageTag("horse.jpg");
JS:
cloudinary.imageTag('horse.jpg', {height: 300, width: 300, background: "auto:predominant_gradient:4:palette_red_green_blue_orange", crop: "pad"}).toHtml();
jQuery:
$.cloudinary.image("horse.jpg", {height: 300, width: 300, background: "auto:predominant_gradient:4:palette_red_green_blue_orange", crop: "pad"})
React:
<Image publicId="horse.jpg" >
<Transformation height="300" width="300" background="auto:predominant_gradient:4:palette_red_green_blue_orange" crop="pad" />
</Image>
Vue.js:
<cld-image publicId="horse.jpg" >
<cld-transformation height="300" width="300" background="auto:predominant_gradient:4:palette_red_green_blue_orange" crop="pad" />
</cld-image>
Angular:
<cl-image public-id="horse.jpg" >
<cl-transformation height="300" width="300" background="auto:predominant_gradient:4:palette_red_green_blue_orange" crop="pad">
</cl-transformation>
</cl-image>
.Net:
cloudinary.Api.UrlImgUp.Transform(new Transformation().Height(300).Width(300).Background("auto:predominant_gradient:4:palette_red_green_blue_orange").Crop("pad")).BuildImageTag("horse.jpg")
Android:
MediaManager.get().url().transformation(new Transformation().height(300).width(300).background("auto:predominant_gradient:4:palette_red_green_blue_orange").crop("pad")).generate("horse.jpg");
iOS:
imageView.cldSetImage(cloudinary.createUrl().setTransformation(CLDTransformation().setHeight(300).setWidth(300).setBackground("auto:predominant_gradient:4:palette_red_green_blue_orange").setCrop("pad")).generate("horse.jpg")!, cloudinary: cloudinary)
Gradient fade into padding
Fade the image into the added padding by adding the gradient_fade effect with a value of symmetric_pad (e_gradient_fade:symmetric_pad in URLs). The padding blends into the edge of the image with a strength indicated by an additional value, separated by a colon (Range: 0 to 100, Default: 20). Values for x and y can also be specified as a percentage (range: 0.0 to 1.0), or in pixels (integer values) to indicate how far into the image to apply the gradient effect. By default, the gradient is applied 30% into the image (x_0.3).
For example, padding the sample image to a width and height of 300 pixels, with the background color set to the predominant color, and with a gradient fade effect, between the added padding and 50% into the image.
Ruby:
cl_image_tag("sample.jpg", :transformation=>[
{:height=>300, :width=>300, :background=>"auto:predominant", :crop=>"pad"},
{:effect=>"gradient_fade:symmetric_pad", :x=>0.5}
])
PHP:
cl_image_tag("sample.jpg", array("transformation"=>array(
array("height"=>300, "width"=>300, "background"=>"auto:predominant", "crop"=>"pad"),
array("effect"=>"gradient_fade:symmetric_pad", "x"=>0.5)
)))
Python:
CloudinaryImage("sample.jpg").image(transformation=[
{'height': 300, 'width': 300, 'background': "auto:predominant", 'crop': "pad"},
{'effect': "gradient_fade:symmetric_pad", 'x': 0.5}
])
Node.js:
cloudinary.image("sample.jpg", {transformation: [
{height: 300, width: 300, background: "auto:predominant", crop: "pad"},
{effect: "gradient_fade:symmetric_pad", x: "0.5"}
]})
Java:
cloudinary.url().transformation(new Transformation()
.height(300).width(300).background("auto:predominant").crop("pad").chain()
.effect("gradient_fade:symmetric_pad").x(0.5)).imageTag("sample.jpg");
JS:
cloudinary.imageTag('sample.jpg', {transformation: [
{height: 300, width: 300, background: "auto:predominant", crop: "pad"},
{effect: "gradient_fade:symmetric_pad", x: "0.5"}
]}).toHtml();
jQuery:
$.cloudinary.image("sample.jpg", {transformation: [
{height: 300, width: 300, background: "auto:predominant", crop: "pad"},
{effect: "gradient_fade:symmetric_pad", x: "0.5"}
]})
React:
<Image publicId="sample.jpg" >
<Transformation height="300" width="300" background="auto:predominant" crop="pad" />
<Transformation effect="gradient_fade:symmetric_pad" x="0.5" />
</Image>
Vue.js:
<cld-image publicId="sample.jpg" >
<cld-transformation height="300" width="300" background="auto:predominant" crop="pad" />
<cld-transformation effect="gradient_fade:symmetric_pad" x="0.5" />
</cld-image>
Angular:
<cl-image public-id="sample.jpg" >
<cl-transformation height="300" width="300" background="auto:predominant" crop="pad">
</cl-transformation>
<cl-transformation effect="gradient_fade:symmetric_pad" x="0.5">
</cl-transformation>
</cl-image>
.Net:
cloudinary.Api.UrlImgUp.Transform(new Transformation()
.Height(300).Width(300).Background("auto:predominant").Crop("pad").Chain()
.Effect("gradient_fade:symmetric_pad").X(0.5)).BuildImageTag("sample.jpg")
Android:
MediaManager.get().url().transformation(new Transformation()
.height(300).width(300).background("auto:predominant").crop("pad").chain()
.effect("gradient_fade:symmetric_pad").x(0.5)).generate("sample.jpg");
iOS:
imageView.cldSetImage(cloudinary.createUrl().setTransformation(CLDTransformation()
.setHeight(300).setWidth(300).setBackground("auto:predominant").setCrop("pad").chain()
.setEffect("gradient_fade:symmetric_pad").setX(0.5)).generate("sample.jpg")!, cloudinary: cloudinary)
Apply a filter or an effect on an image with the effect parameter (e in URLs). The value of the parameter includes the name of the effect and sometimes an additional value that controls the behavior of the specific effect. Cloudinary supports a large number of effects that can be applied to change the visual appearance of delivered images. You can also apply multiple effects to an image by applying each effect as a separate chained transformation.
There are a large number of effects and filters available, which can be roughly divided into the following type of effects:
For a full list of all the supported effects, see the Image transformations reference table. For more information on using effects see the following articles:
Tip
In addition to the various image effects and filters described here, you can also apply a
3D LUT file as an image overlay to achieve desired effects.
Effects: hue, red, green, blue, negate, brightness, auto_brightness, brightness_hsb, sepia, grayscale, blackwhite, saturation, colorize, assist_colorblind, simulate_colorblind, replace_color, recolor, tint, contrast, auto_contrast, vibrance, auto_color,
These effects are useful for changing the intensities of colors in an image, correcting color imbalance, applying colorization filters, removing or replacing colors, and addressing issues relating to colorblind accessibility.
- Convert the
sample image to grayscale:
Ruby:
cl_image_tag("sample.jpg", :effect=>"grayscale")
PHP:
cl_image_tag("sample.jpg", array("effect"=>"grayscale"))
Python:
CloudinaryImage("sample.jpg").image(effect="grayscale")
Node.js:
cloudinary.image("sample.jpg", {effect: "grayscale"})
Java:
cloudinary.url().transformation(new Transformation().effect("grayscale")).imageTag("sample.jpg");
JS:
cloudinary.imageTag('sample.jpg', {effect: "grayscale"}).toHtml();
jQuery:
$.cloudinary.image("sample.jpg", {effect: "grayscale"})
React:
<Image publicId="sample.jpg" >
<Transformation effect="grayscale" />
</Image>
Vue.js:
<cld-image publicId="sample.jpg" >
<cld-transformation effect="grayscale" />
</cld-image>
Angular:
<cl-image public-id="sample.jpg" >
<cl-transformation effect="grayscale">
</cl-transformation>
</cl-image>
.Net:
cloudinary.Api.UrlImgUp.Transform(new Transformation().Effect("grayscale")).BuildImageTag("sample.jpg")
Android:
MediaManager.get().url().transformation(new Transformation().effect("grayscale")).generate("sample.jpg");
iOS:
imageView.cldSetImage(cloudinary.createUrl().setTransformation(CLDTransformation().setEffect("grayscale")).generate("sample.jpg")!, cloudinary: cloudinary)
- Increase saturation of the
sample image to 50:
Ruby:
cl_image_tag("sample.jpg", :effect=>"saturation:50")
PHP:
cl_image_tag("sample.jpg", array("effect"=>"saturation:50"))
Python:
CloudinaryImage("sample.jpg").image(effect="saturation:50")
Node.js:
cloudinary.image("sample.jpg", {effect: "saturation:50"})
Java:
cloudinary.url().transformation(new Transformation().effect("saturation:50")).imageTag("sample.jpg");
JS:
cloudinary.imageTag('sample.jpg', {effect: "saturation:50"}).toHtml();
jQuery:
$.cloudinary.image("sample.jpg", {effect: "saturation:50"})
React:
<Image publicId="sample.jpg" >
<Transformation effect="saturation:50" />
</Image>
Vue.js:
<cld-image publicId="sample.jpg" >
<cld-transformation effect="saturation:50" />
</cld-image>
Angular:
<cl-image public-id="sample.jpg" >
<cl-transformation effect="saturation:50">
</cl-transformation>
</cl-image>
.Net:
cloudinary.Api.UrlImgUp.Transform(new Transformation().Effect("saturation:50")).BuildImageTag("sample.jpg")
Android:
MediaManager.get().url().transformation(new Transformation().effect("saturation:50")).generate("sample.jpg");
iOS:
imageView.cldSetImage(cloudinary.createUrl().setTransformation(CLDTransformation().setEffect("saturation:50")).generate("sample.jpg")!, cloudinary: cloudinary)
- Apply color blind accessibility effects:
- Simulate the way an image would appear to someone with deuteranopia (most common form of) color blindness:
Ruby:
cl_image_tag("docs/colorblind_green_red.jpg", :effect=>"simulate_colorblind:deuteranopia")
PHP:
cl_image_tag("docs/colorblind_green_red.jpg", array("effect"=>"simulate_colorblind:deuteranopia"))
Python:
CloudinaryImage("docs/colorblind_green_red.jpg").image(effect="simulate_colorblind:deuteranopia")
Node.js:
cloudinary.image("docs/colorblind_green_red.jpg", {effect: "simulate_colorblind:deuteranopia"})
Java:
cloudinary.url().transformation(new Transformation().effect("simulate_colorblind:deuteranopia")).imageTag("docs/colorblind_green_red.jpg");
JS:
cloudinary.imageTag('docs/colorblind_green_red.jpg', {effect: "simulate_colorblind:deuteranopia"}).toHtml();
jQuery:
$.cloudinary.image("docs/colorblind_green_red.jpg", {effect: "simulate_colorblind:deuteranopia"})
React:
<Image publicId="docs/colorblind_green_red.jpg" >
<Transformation effect="simulate_colorblind:deuteranopia" />
</Image>
Vue.js:
<cld-image publicId="docs/colorblind_green_red.jpg" >
<cld-transformation effect="simulate_colorblind:deuteranopia" />
</cld-image>
Angular:
<cl-image public-id="docs/colorblind_green_red.jpg" >
<cl-transformation effect="simulate_colorblind:deuteranopia">
</cl-transformation>
</cl-image>
.Net:
cloudinary.Api.UrlImgUp.Transform(new Transformation().Effect("simulate_colorblind:deuteranopia")).BuildImageTag("docs/colorblind_green_red.jpg")
Android:
MediaManager.get().url().transformation(new Transformation().effect("simulate_colorblind:deuteranopia")).generate("docs/colorblind_green_red.jpg");
iOS:
imageView.cldSetImage(cloudinary.createUrl().setTransformation(CLDTransformation().setEffect("simulate_colorblind:deuteranopia")).generate("docs/colorblind_green_red.jpg")!, cloudinary: cloudinary)
You can simulate a number of different color-blind conditions. For all options, see the simulate_colorblind option of the effect parameter in the Image Transformation Reference.
- Add stripes in different directions and thicknesses to assist people with common colorblind conditions to differentiate between colors:
Ruby:
cl_image_tag("docs/colorblind_green_red.jpg", :effect=>"assist_colorblind:8")
PHP:
cl_image_tag("docs/colorblind_green_red.jpg", array("effect"=>"assist_colorblind:8"))
Python:
CloudinaryImage("docs/colorblind_green_red.jpg").image(effect="assist_colorblind:8")
Node.js:
cloudinary.image("docs/colorblind_green_red.jpg", {effect: "assist_colorblind:8"})
Java:
cloudinary.url().transformation(new Transformation().effect("assist_colorblind:8")).imageTag("docs/colorblind_green_red.jpg");
JS:
cloudinary.imageTag('docs/colorblind_green_red.jpg', {effect: "assist_colorblind:8"}).toHtml();
jQuery:
$.cloudinary.image("docs/colorblind_green_red.jpg", {effect: "assist_colorblind:8"})
React:
<Image publicId="docs/colorblind_green_red.jpg" >
<Transformation effect="assist_colorblind:8" />
</Image>
Vue.js:
<cld-image publicId="docs/colorblind_green_red.jpg" >
<cld-transformation effect="assist_colorblind:8" />
</cld-image>
Angular:
<cl-image public-id="docs/colorblind_green_red.jpg" >
<cl-transformation effect="assist_colorblind:8">
</cl-transformation>
</cl-image>
.Net:
cloudinary.Api.UrlImgUp.Transform(new Transformation().Effect("assist_colorblind:8")).BuildImageTag("docs/colorblind_green_red.jpg")
Android:
MediaManager.get().url().transformation(new Transformation().effect("assist_colorblind:8")).generate("docs/colorblind_green_red.jpg");
iOS:
imageView.cldSetImage(cloudinary.createUrl().setTransformation(CLDTransformation().setEffect("assist_colorblind:8")).generate("docs/colorblind_green_red.jpg")!, cloudinary: cloudinary)
A colorblind person would see the stripes like this:
- Use color shifts to assist people with common colorblind conditions to differentiate between colors:
Ruby:
cl_image_tag("docs/colorblind_green_red.jpg", :effect=>"assist_colorblind:xray")
PHP:
cl_image_tag("docs/colorblind_green_red.jpg", array("effect"=>"assist_colorblind:xray"))
Python:
CloudinaryImage("docs/colorblind_green_red.jpg").image(effect="assist_colorblind:xray")
Node.js:
cloudinary.image("docs/colorblind_green_red.jpg", {effect: "assist_colorblind:xray"})
Java:
cloudinary.url().transformation(new Transformation().effect("assist_colorblind:xray")).imageTag("docs/colorblind_green_red.jpg");
JS:
cloudinary.imageTag('docs/colorblind_green_red.jpg', {effect: "assist_colorblind:xray"}).toHtml();
jQuery:
$.cloudinary.image("docs/colorblind_green_red.jpg", {effect: "assist_colorblind:xray"})
React:
<Image publicId="docs/colorblind_green_red.jpg" >
<Transformation effect="assist_colorblind:xray" />
</Image>
Vue.js:
<cld-image publicId="docs/colorblind_green_red.jpg" >
<cld-transformation effect="assist_colorblind:xray" />
</cld-image>
Angular:
<cl-image public-id="docs/colorblind_green_red.jpg" >
<cl-transformation effect="assist_colorblind:xray">
</cl-transformation>
</cl-image>
.Net:
cloudinary.Api.UrlImgUp.Transform(new Transformation().Effect("assist_colorblind:xray")).BuildImageTag("docs/colorblind_green_red.jpg")
Android:
MediaManager.get().url().transformation(new Transformation().effect("assist_colorblind:xray")).generate("docs/colorblind_green_red.jpg");
iOS:
imageView.cldSetImage(cloudinary.createUrl().setTransformation(CLDTransformation().setEffect("assist_colorblind:xray")).generate("docs/colorblind_green_red.jpg")!, cloudinary: cloudinary)
- Recolor an image by finding the blue colors (to a tolerance of 80 from the color #2b38aa) and replacing them with parallel shades of maroon, taking into account shadows, lighting, etc:
Ruby:
cl_image_tag("blue_burlap.png", :effect=>"replace_color:maroon:80:2b38aa")
PHP:
cl_image_tag("blue_burlap.png", array("effect"=>"replace_color:maroon:80:2b38aa"))
Python:
CloudinaryImage("blue_burlap.png").image(effect="replace_color:maroon:80:2b38aa")
Node.js:
cloudinary.image("blue_burlap.png", {effect: "replace_color:maroon:80:2b38aa"})
Java:
cloudinary.url().transformation(new Transformation().effect("replace_color:maroon:80:2b38aa")).imageTag("blue_burlap.png");
JS:
cloudinary.imageTag('blue_burlap.png', {effect: "replace_color:maroon:80:2b38aa"}).toHtml();
jQuery:
$.cloudinary.image("blue_burlap.png", {effect: "replace_color:maroon:80:2b38aa"})
React:
<Image publicId="blue_burlap.png" >
<Transformation effect="replace_color:maroon:80:2b38aa" />
</Image>
Vue.js:
<cld-image publicId="blue_burlap.png" >
<cld-transformation effect="replace_color:maroon:80:2b38aa" />
</cld-image>
Angular:
<cl-image public-id="blue_burlap.png" >
<cl-transformation effect="replace_color:maroon:80:2b38aa">
</cl-transformation>
</cl-image>
.Net:
cloudinary.Api.UrlImgUp.Transform(new Transformation().Effect("replace_color:maroon:80:2b38aa")).BuildImageTag("blue_burlap.png")
Android:
MediaManager.get().url().transformation(new Transformation().effect("replace_color:maroon:80:2b38aa")).generate("blue_burlap.png");
iOS:
imageView.cldSetImage(cloudinary.createUrl().setTransformation(CLDTransformation().setEffect("replace_color:maroon:80:2b38aa")).generate("blue_burlap.png")!, cloudinary: cloudinary)
Original blue bag
Blues recolored to maroon shades
The outline effect (e_outline in URLs) enables you to add an outline to your transparent images. The parameter can also be passed additional values as follows:
outline:[mode]:[width]:[blur]
- mode - how to apply the outline effect which can be one of the following values:
inner, inner_fill, outer, fill. Default value: inner and outer.
- width - the first integer supplied applies to the thickness of the outline in pixels. Default value:
5. Range: 1 - 100
- blur - the second integer supplied applies to the level of blur of the outline. Default value:
0. Range: 0 - 2000
Original
e_outline
e_outline:inner
e_outline:inner_fill
e_outline:outer
e_outline:fill
Use the color parameter (co in URLs) to define a new color for the outline (the default is black). The color can be specified as an RGB hex triplet (e.g., rgb:3e2222), a 3-digit RGB hex (e.g., rgb:777) or a named color (e.g., green). For example, to add an orange outline:
Ruby:
cl_image_tag("balloon.png", :transformation=>[
{:height=>200, :crop=>"scale"},
{:effect=>"outline:15:200", :color=>"orange"}
])
PHP:
cl_image_tag("balloon.png", array("transformation"=>array(
array("height"=>200, "crop"=>"scale"),
array("effect"=>"outline:15:200", "color"=>"orange")
)))
Python:
CloudinaryImage("balloon.png").image(transformation=[
{'height': 200, 'crop': "scale"},
{'effect': "outline:15:200", 'color': "orange"}
])
Node.js:
cloudinary.image("balloon.png", {transformation: [
{height: 200, crop: "scale"},
{effect: "outline:15:200", color: "orange"}
]})
Java:
cloudinary.url().transformation(new Transformation()
.height(200).crop("scale").chain()
.effect("outline:15:200").color("orange")).imageTag("balloon.png");
JS:
cloudinary.imageTag('balloon.png', {transformation: [
{height: 200, crop: "scale"},
{effect: "outline:15:200", color: "orange"}
]}).toHtml();
jQuery:
$.cloudinary.image("balloon.png", {transformation: [
{height: 200, crop: "scale"},
{effect: "outline:15:200", color: "orange"}
]})
React:
<Image publicId="balloon.png" >
<Transformation height="200" crop="scale" />
<Transformation effect="outline:15:200" color="orange" />
</Image>
Vue.js:
<cld-image publicId="balloon.png" >
<cld-transformation height="200" crop="scale" />
<cld-transformation effect="outline:15:200" color="orange" />
</cld-image>
Angular:
<cl-image public-id="balloon.png" >
<cl-transformation height="200" crop="scale">
</cl-transformation>
<cl-transformation effect="outline:15:200" color="orange">
</cl-transformation>
</cl-image>
.Net:
cloudinary.Api.UrlImgUp.Transform(new Transformation()
.Height(200).Crop("scale").Chain()
.Effect("outline:15:200").Color("orange")).BuildImageTag("balloon.png")
Android:
MediaManager.get().url().transformation(new Transformation()
.height(200).crop("scale").chain()
.effect("outline:15:200").color("orange")).generate("balloon.png");
iOS:
imageView.cldSetImage(cloudinary.createUrl().setTransformation(CLDTransformation()
.setHeight(200).setCrop("scale").chain()
.setEffect("outline:15:200").setColor("orange")).generate("balloon.png")!, cloudinary: cloudinary)
You can also add a multi-colored outline by creating successive outline effect components. For example:
Ruby:
cl_image_tag("shoes.png", :transformation=>[
{:width=>200, :crop=>"scale"},
{:effect=>"outline:20:200", :color=>"red"},
{:effect=>"outline:15:200", :color=>"orange"},
{:effect=>"outline:10:200", :color=>"yellow"}
])
PHP:
cl_image_tag("shoes.png", array("transformation"=>array(
array("width"=>200, "crop"=>"scale"),
array("effect"=>"outline:20:200", "color"=>"red"),
array("effect"=>"outline:15:200", "color"=>"orange"),
array("effect"=>"outline:10:200", "color"=>"yellow")
)))
Python:
CloudinaryImage("shoes.png").image(transformation=[
{'width': 200, 'crop': "scale"},
{'effect': "outline:20:200", 'color': "red"},
{'effect': "outline:15:200", 'color': "orange"},
{'effect': "outline:10:200", 'color': "yellow"}
])
Node.js:
cloudinary.image("shoes.png", {transformation: [
{width: 200, crop: "scale"},
{effect: "outline:20:200", color: "red"},
{effect: "outline:15:200", color: "orange"},
{effect: "outline:10:200", color: "yellow"}
]})
Java:
cloudinary.url().transformation(new Transformation()
.width(200).crop("scale").chain()
.effect("outline:20:200").color("red").chain()
.effect("outline:15:200").color("orange").chain()
.effect("outline:10:200").color("yellow")).imageTag("shoes.png");
JS:
cloudinary.imageTag('shoes.png', {transformation: [
{width: 200, crop: "scale"},
{effect: "outline:20:200", color: "red"},
{effect: "outline:15:200", color: "orange"},
{effect: "outline:10:200", color: "yellow"}
]}).toHtml();
jQuery:
$.cloudinary.image("shoes.png", {transformation: [
{width: 200, crop: "scale"},
{effect: "outline:20:200", color: "red"},
{effect: "outline:15:200", color: "orange"},
{effect: "outline:10:200", color: "yellow"}
]})
React:
<Image publicId="shoes.png" >
<Transformation width="200" crop="scale" />
<Transformation effect="outline:20:200" color="red" />
<Transformation effect="outline:15:200" color="orange" />
<Transformation effect="outline:10:200" color="yellow" />
</Image>
Vue.js:
<cld-image publicId="shoes.png" >
<cld-transformation width="200" crop="scale" />
<cld-transformation effect="outline:20:200" color="red" />
<cld-transformation effect="outline:15:200" color="orange" />
<cld-transformation effect="outline:10:200" color="yellow" />
</cld-image>
Angular:
<cl-image public-id="shoes.png" >
<cl-transformation width="200" crop="scale">
</cl-transformation>
<cl-transformation effect="outline:20:200" color="red">
</cl-transformation>
<cl-transformation effect="outline:15:200" color="orange">
</cl-transformation>
<cl-transformation effect="outline:10:200" color="yellow">
</cl-transformation>
</cl-image>
.Net:
cloudinary.Api.UrlImgUp.Transform(new Transformation()
.Width(200).Crop("scale").Chain()
.Effect("outline:20:200").Color("red").Chain()
.Effect("outline:15:200").Color("orange").Chain()
.Effect("outline:10:200").Color("yellow")).BuildImageTag("shoes.png")
Android:
MediaManager.get().url().transformation(new Transformation()
.width(200).crop("scale").chain()
.effect("outline:20:200").color("red").chain()
.effect("outline:15:200").color("orange").chain()
.effect("outline:10:200").color("yellow")).generate("shoes.png");
iOS:
imageView.cldSetImage(cloudinary.createUrl().setTransformation(CLDTransformation()
.setWidth(200).setCrop("scale").chain()
.setEffect("outline:20:200").setColor("red").chain()
.setEffect("outline:15:200").setColor("orange").chain()
.setEffect("outline:10:200").setColor("yellow")).generate("shoes.png")!, cloudinary: cloudinary)
The tint:<options> effect enables you to blend your images with one or more colors and specify the blend strength. Advanced users can also equalize the image for increased contrast and specify the positioning of the gradient blend for each color.
By default, e_tint applies a red color at 60% blend strength.
Specify the colors and blend strength amount in the format:
e_tint:[amount]:[color1]:[color2]:...:[color10].
amount is a value from 0-100, where 0 keeps the original color and 100 blends the specified colors completely.
The color can be specified as an RGB hex triplet (e.g., rgb:3e2222), a 3-digit RGB hex (e.g., rgb:777) or a named color (e.g., green).
For example:
Ruby:
cl_image_tag("greece_landscape.jpg", :effect=>"tint:100:red:blue:yellow")
PHP:
cl_image_tag("greece_landscape.jpg", array("effect"=>"tint:100:red:blue:yellow"))
Python:
CloudinaryImage("greece_landscape.jpg").image(effect="tint:100:red:blue:yellow")
Node.js:
cloudinary.image("greece_landscape.jpg", {effect: "tint:100:red:blue:yellow"})
Java:
cloudinary.url().transformation(new Transformation().effect("tint:100:red:blue:yellow")).imageTag("greece_landscape.jpg");
JS:
cloudinary.imageTag('greece_landscape.jpg', {effect: "tint:100:red:blue:yellow"}).toHtml();
jQuery:
$.cloudinary.image("greece_landscape.jpg", {effect: "tint:100:red:blue:yellow"})
React:
<Image publicId="greece_landscape.jpg" >
<Transformation effect="tint:100:red:blue:yellow" />
</Image>
Vue.js:
<cld-image publicId="greece_landscape.jpg" >
<cld-transformation effect="tint:100:red:blue:yellow" />
</cld-image>
Angular:
<cl-image public-id="greece_landscape.jpg" >
<cl-transformation effect="tint:100:red:blue:yellow">
</cl-transformation>
</cl-image>
.Net:
cloudinary.Api.UrlImgUp.Transform(new Transformation().Effect("tint:100:red:blue:yellow")).BuildImageTag("greece_landscape.jpg")
Android:
MediaManager.get().url().transformation(new Transformation().effect("tint:100:red:blue:yellow")).generate("greece_landscape.jpg");
iOS:
imageView.cldSetImage(cloudinary.createUrl().setTransformation(CLDTransformation().setEffect("tint:100:red:blue:yellow")).generate("greece_landscape.jpg")!, cloudinary: cloudinary)
To equalize the colors in your image before tinting, set equalize to true (false by default). For example:
Ruby:
cl_image_tag("greece_landscape.jpg", :effect=>"tint:equalize:80:red:blue:yellow")
PHP:
cl_image_tag("greece_landscape.jpg", array("effect"=>"tint:equalize:80:red:blue:yellow"))
Python:
CloudinaryImage("greece_landscape.jpg").image(effect="tint:equalize:80:red:blue:yellow")
Node.js:
cloudinary.image("greece_landscape.jpg", {effect: "tint:equalize:80:red:blue:yellow"})
Java:
cloudinary.url().transformation(new Transformation().effect("tint:equalize:80:red:blue:yellow")).imageTag("greece_landscape.jpg");
JS:
cloudinary.imageTag('greece_landscape.jpg', {effect: "tint:equalize:80:red:blue:yellow"}).toHtml();
jQuery:
$.cloudinary.image("greece_landscape.jpg", {effect: "tint:equalize:80:red:blue:yellow"})
React:
<Image publicId="greece_landscape.jpg" >
<Transformation effect="tint:equalize:80:red:blue:yellow" />
</Image>
Vue.js:
<cld-image publicId="greece_landscape.jpg" >
<cld-transformation effect="tint:equalize:80:red:blue:yellow" />
</cld-image>
Angular:
<cl-image public-id="greece_landscape.jpg" >
<cl-transformation effect="tint:equalize:80:red:blue:yellow">
</cl-transformation>
</cl-image>
.Net:
cloudinary.Api.UrlImgUp.Transform(new Transformation().Effect("tint:equalize:80:red:blue:yellow")).BuildImageTag("greece_landscape.jpg")
Android:
MediaManager.get().url().transformation(new Transformation().effect("tint:equalize:80:red:blue:yellow")).generate("greece_landscape.jpg");
iOS:
imageView.cldSetImage(cloudinary.createUrl().setTransformation(CLDTransformation().setEffect("tint:equalize:80:red:blue:yellow")).generate("greece_landscape.jpg")!, cloudinary: cloudinary)
By default, the specified colors are distributed evenly. To adjust the positioning of the gradient blend, specify a position value between 0p-100p. If specifying positioning, you must specify a position value for all colors. For example:
Ruby:
cl_image_tag("greece_landscape.jpg", :effect=>"tint:equalize:80:red:50p:blue:60p:yellow:40p")
PHP:
cl_image_tag("greece_landscape.jpg", array("effect"=>"tint:equalize:80:red:50p:blue:60p:yellow:40p"))
Python:
CloudinaryImage("greece_landscape.jpg").image(effect="tint:equalize:80:red:50p:blue:60p:yellow:40p")
Node.js:
cloudinary.image("greece_landscape.jpg", {effect: "tint:equalize:80:red:50p:blue:60p:yellow:40p"})
Java:
cloudinary.url().transformation(new Transformation().effect("tint:equalize:80:red:50p:blue:60p:yellow:40p")).imageTag("greece_landscape.jpg");
JS:
cloudinary.imageTag('greece_landscape.jpg', {effect: "tint:equalize:80:red:50p:blue:60p:yellow:40p"}).toHtml();
jQuery:
$.cloudinary.image("greece_landscape.jpg", {effect: "tint:equalize:80:red:50p:blue:60p:yellow:40p"})
React:
<Image publicId="greece_landscape.jpg" >
<Transformation effect="tint:equalize:80:red:50p:blue:60p:yellow:40p" />
</Image>
Vue.js:
<cld-image publicId="greece_landscape.jpg" >
<cld-transformation effect="tint:equalize:80:red:50p:blue:60p:yellow:40p" />
</cld-image>
Angular:
<cl-image public-id="greece_landscape.jpg" >
<cl-transformation effect="tint:equalize:80:red:50p:blue:60p:yellow:40p">
</cl-transformation>
</cl-image>
.Net:
cloudinary.Api.UrlImgUp.Transform(new Transformation().Effect("tint:equalize:80:red:50p:blue:60p:yellow:40p")).BuildImageTag("greece_landscape.jpg")
Android:
MediaManager.get().url().transformation(new Transformation().effect("tint:equalize:80:red:50p:blue:60p:yellow:40p")).generate("greece_landscape.jpg");
iOS:
imageView.cldSetImage(cloudinary.createUrl().setTransformation(CLDTransformation().setEffect("tint:equalize:80:red:50p:blue:60p:yellow:40p")).generate("greece_landscape.jpg")!, cloudinary: cloudinary)
Original
default red color at 20% strength
red, blue, yellow at 100% strength
equalized, mutli-color, 80%, adjusted gradients
1Equalizing colors redistributes the pixels in your image so that they are equally balanced across the entire range of brightness values, which increases the overall contrast in the image. The lightest area is remapped to pure white, and the darkest area is remapped to pure black.
Effects: blur, blur_region, blur_faces, sharpen, unsharp_mask, pixelate, pixelate_region, pixelate_faces, ordered_dither, noise, vignette, gradient_fade, tilt_shift
These effects are used to either visually distort or visually enhance an image.
Examples:
- To apply a strong blurring filter (300) to the
sample image:
Ruby:
cl_image_tag("sample.jpg", :effect=>"blur:300")
PHP:
cl_image_tag("sample.jpg", array("effect"=>"blur:300"))
Python:
CloudinaryImage("sample.jpg").image(effect="blur:300")
Node.js:
cloudinary.image("sample.jpg", {effect: "blur:300"})
Java:
cloudinary.url().transformation(new Transformation().effect("blur:300")).imageTag("sample.jpg");
JS:
cloudinary.imageTag('sample.jpg', {effect: "blur:300"}).toHtml();
jQuery:
$.cloudinary.image("sample.jpg", {effect: "blur:300"})
React:
<Image publicId="sample.jpg" >
<Transformation effect="blur:300" />
</Image>
Vue.js:
<cld-image publicId="sample.jpg" >
<cld-transformation effect="blur:300" />
</cld-image>
Angular:
<cl-image public-id="sample.jpg" >
<cl-transformation effect="blur:300">
</cl-transformation>
</cl-image>
.Net:
cloudinary.Api.UrlImgUp.Transform(new Transformation().Effect("blur:300")).BuildImageTag("sample.jpg")
Android:
MediaManager.get().url().transformation(new Transformation().effect("blur:300")).generate("sample.jpg");
iOS:
imageView.cldSetImage(cloudinary.createUrl().setTransformation(CLDTransformation().setEffect("blur:300")).generate("sample.jpg")!, cloudinary: cloudinary)
- To apply a sharpen filter to the
sample image:
Ruby:
cl_image_tag("sample.jpg", :effect=>"sharpen")
PHP:
cl_image_tag("sample.jpg", array("effect"=>"sharpen"))
Python:
CloudinaryImage("sample.jpg").image(effect="sharpen")
Node.js:
cloudinary.image("sample.jpg", {effect: "sharpen"})
Java:
cloudinary.url().transformation(new Transformation().effect("sharpen")).imageTag("sample.jpg");
JS:
cloudinary.imageTag('sample.jpg', {effect: "sharpen"}).toHtml();
jQuery:
$.cloudinary.image("sample.jpg", {effect: "sharpen"})
React:
<Image publicId="sample.jpg" >
<Transformation effect="sharpen" />
</Image>
Vue.js:
<cld-image publicId="sample.jpg" >
<cld-transformation effect="sharpen" />
</cld-image>
Angular:
<cl-image public-id="sample.jpg" >
<cl-transformation effect="sharpen">
</cl-transformation>
</cl-image>
.Net:
cloudinary.Api.UrlImgUp.Transform(new Transformation().Effect("sharpen")).BuildImageTag("sample.jpg")
Android:
MediaManager.get().url().transformation(new Transformation().effect("sharpen")).generate("sample.jpg");
iOS:
imageView.cldSetImage(cloudinary.createUrl().setTransformation(CLDTransformation().setEffect("sharpen")).generate("sample.jpg")!, cloudinary: cloudinary)
Effects: screen, multiply, overlay, mask, anti_removal
These effects are used for blending an overlay with an image.
For example, to make each pixel of the sample image brighter according to the pixel value of the overlaid cloudinary_icon image:
Ruby:
cl_image_tag("sample.jpg", :effect=>"screen", :overlay=>"cloudinary_icon")
PHP:
cl_image_tag("sample.jpg", array("effect"=>"screen", "overlay"=>"cloudinary_icon"))
Python:
CloudinaryImage("sample.jpg").image(effect="screen", overlay="cloudinary_icon")
Node.js:
cloudinary.image("sample.jpg", {effect: "screen", overlay: "cloudinary_icon"})
Java:
cloudinary.url().transformation(new Transformation().effect("screen").overlay(new Layer().publicId("cloudinary_icon"))).imageTag("sample.jpg");
JS:
cloudinary.imageTag('sample.jpg', {effect: "screen", overlay: new cloudinary.Layer().publicId("cloudinary_icon")}).toHtml();
jQuery:
$.cloudinary.image("sample.jpg", {effect: "screen", overlay: new cloudinary.Layer().publicId("cloudinary_icon")})
React:
<Image publicId="sample.jpg" >
<Transformation effect="screen" overlay="cloudinary_icon" />
</Image>
Vue.js:
<cld-image publicId="sample.jpg" >
<cld-transformation effect="screen" overlay="cloudinary_icon" />
</cld-image>
Angular:
<cl-image public-id="sample.jpg" >
<cl-transformation effect="screen" overlay="cloudinary_icon">
</cl-transformation>
</cl-image>
.Net:
cloudinary.Api.UrlImgUp.Transform(new Transformation().Effect("screen").Overlay(new Layer().PublicId("cloudinary_icon"))).BuildImageTag("sample.jpg")
Android:
MediaManager.get().url().transformation(new Transformation().effect("screen").overlay(new Layer().publicId("cloudinary_icon"))).generate("sample.jpg");
iOS:
imageView.cldSetImage(cloudinary.createUrl().setTransformation(CLDTransformation().setEffect("screen").setOverlay("cloudinary_icon")).generate("sample.jpg")!, cloudinary: cloudinary)
Effects: shadow, make_transparent, trim, distort, shear, displace
These effects are used to morph an image's visual dimensions.
Examples:
- To add a custom green shadow to the
sample image:
Ruby:
cl_image_tag("sample.jpg", :color=>"#009900", :effect=>"shadow:50", :x=>10, :y=>10)
PHP:
cl_image_tag("sample.jpg", array("color"=>"#009900", "effect"=>"shadow:50", "x"=>10, "y"=>10))
Python:
CloudinaryImage("sample.jpg").image(color="#009900", effect="shadow:50", x=10, y=10)
Node.js:
cloudinary.image("sample.jpg", {color: "#009900", effect: "shadow:50", x: 10, y: 10})
Java:
cloudinary.url().transformation(new Transformation().color("#009900").effect("shadow:50").x(10).y(10)).imageTag("sample.jpg");
JS:
cloudinary.imageTag('sample.jpg', {color: "#009900", effect: "shadow:50", x: 10, y: 10}).toHtml();
jQuery:
$.cloudinary.image("sample.jpg", {color: "#009900", effect: "shadow:50", x: 10, y: 10})
React:
<Image publicId="sample.jpg" >
<Transformation color="#009900" effect="shadow:50" x="10" y="10" />
</Image>
Vue.js:
<cld-image publicId="sample.jpg" >
<cld-transformation color="#009900" effect="shadow:50" x="10" y="10" />
</cld-image>
Angular:
<cl-image public-id="sample.jpg" >
<cl-transformation color="#009900" effect="shadow:50" x="10" y="10">
</cl-transformation>
</cl-image>
.Net:
cloudinary.Api.UrlImgUp.Transform(new Transformation().Color("#009900").Effect("shadow:50").X(10).Y(10)).BuildImageTag("sample.jpg")
Android:
MediaManager.get().url().transformation(new Transformation().color("#009900").effect("shadow:50").x(10).y(10)).generate("sample.jpg");
iOS:
imageView.cldSetImage(cloudinary.createUrl().setTransformation(CLDTransformation().setColor("#009900").setEffect("shadow:50").setX(10).setY(10)).generate("sample.jpg")!, cloudinary: cloudinary)
- To add curved (
e_distort:arc) text to the frisbee image:
Ruby:
cl_image_tag("frisbee.jpg", :overlay=>{:font_family=>"impact", :font_size=>150, :text=>"Your%20Brand%20Name%20or%20Logo%20Here"}, :effect=>"distort:arc:-120", :color=>"white", :gravity=>"south", :y=>840, :opacity=>60)
PHP:
cl_image_tag("frisbee.jpg", array("overlay"=>array("font_family"=>"impact", "font_size"=>150, "text"=>"Your%20Brand%20Name%20or%20Logo%20Here"), "effect"=>"distort:arc:-120", "color"=>"white", "gravity"=>"south", "y"=>840, "opacity"=>60))
Python:
CloudinaryImage("frisbee.jpg").image(overlay={'font_family': "impact", 'font_size': 150, 'text': "Your%20Brand%20Name%20or%20Logo%20Here"}, effect="distort:arc:-120", color="white", gravity="south", y=840, opacity=60)
Node.js:
cloudinary.image("frisbee.jpg", {overlay: {font_family: "impact", font_size: 150, text: "Your%20Brand%20Name%20or%20Logo%20Here"}, effect: "distort:arc:-120", color: "white", gravity: "south", y: 840, opacity: 60})
Java:
cloudinary.url().transformation(new Transformation().overlay(new TextLayer().fontFamily("impact").fontSize(150).text("Your%20Brand%20Name%20or%20Logo%20Here")).effect("distort:arc:-120").color("white").gravity("south").y(840).opacity(60)).imageTag("frisbee.jpg");
JS:
cloudinary.imageTag('frisbee.jpg', {overlay: new cloudinary.TextLayer().fontFamily("impact").fontSize(150).text("Your%20Brand%20Name%20or%20Logo%20Here"), effect: "distort:arc:-120", color: "white", gravity: "south", y: 840, opacity: 60}).toHtml();
jQuery:
$.cloudinary.image("frisbee.jpg", {overlay: new cloudinary.TextLayer().fontFamily("impact").fontSize(150).text("Your%20Brand%20Name%20or%20Logo%20Here"), effect: "distort:arc:-120", color: "white", gravity: "south", y: 840, opacity: 60})
React:
<Image publicId="frisbee.jpg" >
<Transformation overlay={{fontFamily: "impact", fontSize: 150, text: "Your%20Brand%20Name%20or%20Logo%20Here"}} effect="distort:arc:-120" color="white" gravity="south" y="840" opacity="60" />
</Image>
Vue.js:
<cld-image publicId="frisbee.jpg" >
<cld-transformation overlay={{fontFamily: "impact", fontSize: 150, text: "Your%20Brand%20Name%20or%20Logo%20Here"}} effect="distort:arc:-120" color="white" gravity="south" y="840" opacity="60" />
</cld-image>
Angular:
<cl-image public-id="frisbee.jpg" >
<cl-transformation overlay="text:impact_150:Your%20Brand%20Name%20or%20Logo%20Here" effect="distort:arc:-120" color="white" gravity="south" y="840" opacity="60">
</cl-transformation>
</cl-image>
.Net:
cloudinary.Api.UrlImgUp.Transform(new Transformation().Overlay(new TextLayer().FontFamily("impact").FontSize(150).Text("Your%20Brand%20Name%20or%20Logo%20Here")).Effect("distort:arc:-120").Color("white").Gravity("south").Y(840).Opacity(60)).BuildImageTag("frisbee.jpg")
Android:
MediaManager.get().url().transformation(new Transformation().overlay(new TextLayer().fontFamily("impact").fontSize(150).text("Your%20Brand%20Name%20or%20Logo%20Here")).effect("distort:arc:-120").color("white").gravity("south").y(840).opacity(60)).generate("frisbee.jpg");
iOS:
imageView.cldSetImage(cloudinary.createUrl().setTransformation(CLDTransformation().setOverlay("text:impact_150:Your%20Brand%20Name%20or%20Logo%20Here").setEffect("distort:arc:-120").setColor("white").setGravity("south").setY(840).setOpacity(60)).generate("frisbee.jpg")!, cloudinary: cloudinary)
- To distort the
sample image to a new shape with the following coordinates (clockwise from top-left):
Ruby:
cl_image_tag("sample.jpg", :width=>300, :effect=>"distort:40:25:280:60:260:155:35:165", :crop=>"scale")
PHP:
cl_image_tag("sample.jpg", array("width"=>300, "effect"=>"distort:40:25:280:60:260:155:35:165", "crop"=>"scale"))
Python:
CloudinaryImage("sample.jpg").image(width=300, effect="distort:40:25:280:60:260:155:35:165", crop="scale")
Node.js:
cloudinary.image("sample.jpg", {width: 300, effect: "distort:40:25:280:60:260:155:35:165", crop: "scale"})
Java:
cloudinary.url().transformation(new Transformation().width(300).effect("distort:40:25:280:60:260:155:35:165").crop("scale")).imageTag("sample.jpg");
JS:
cloudinary.imageTag('sample.jpg', {width: 300, effect: "distort:40:25:280:60:260:155:35:165", crop: "scale"}).toHtml();
jQuery:
$.cloudinary.image("sample.jpg", {width: 300, effect: "distort:40:25:280:60:260:155:35:165", crop: "scale"})
React:
<Image publicId="sample.jpg" >
<Transformation width="300" effect="distort:40:25:280:60:260:155:35:165" crop="scale" />
</Image>
Vue.js:
<cld-image publicId="sample.jpg" >
<cld-transformation width="300" effect="distort:40:25:280:60:260:155:35:165" crop="scale" />
</cld-image>
Angular:
<cl-image public-id="sample.jpg" >
<cl-transformation width="300" effect="distort:40:25:280:60:260:155:35:165" crop="scale">
</cl-transformation>
</cl-image>
.Net:
cloudinary.Api.UrlImgUp.Transform(new Transformation().Width(300).Effect("distort:40:25:280:60:260:155:35:165").Crop("scale")).BuildImageTag("sample.jpg")
Android:
MediaManager.get().url().transformation(new Transformation().width(300).effect("distort:40:25:280:60:260:155:35:165").crop("scale")).generate("sample.jpg");
iOS:
imageView.cldSetImage(cloudinary.createUrl().setTransformation(CLDTransformation().setWidth(300).setEffect("distort:40:25:280:60:260:155:35:165").setCrop("scale")).generate("sample.jpg")!, cloudinary: cloudinary)
distort effect, see the article on How to dynamically distort images to fit your graphic design.
Effects: improve, gamma, auto_brightness, auto_contrast, auto_color, fill_light, vibrance, contrast, viesus_correct
These effects are used for manually adjusting the visual quality of an image, or applying automatic visual enhancements.
Examples:
- To
improve an image by automatically adjusting image colors, contrast and lightness:
Ruby:
cl_image_tag("sample.jpg", :effect=>"improve:outdoor")
PHP:
cl_image_tag("sample.jpg", array("effect"=>"improve:outdoor"))
Python:
CloudinaryImage("sample.jpg").image(effect="improve:outdoor")
Node.js:
cloudinary.image("sample.jpg", {effect: "improve:outdoor"})
Java:
cloudinary.url().transformation(new Transformation().effect("improve:outdoor")).imageTag("sample.jpg");
JS:
cloudinary.imageTag('sample.jpg', {effect: "improve:outdoor"}).toHtml();
jQuery:
$.cloudinary.image("sample.jpg", {effect: "improve:outdoor"})
React:
<Image publicId="sample.jpg" >
<Transformation effect="improve:outdoor" />
</Image>
Vue.js:
<cld-image publicId="sample.jpg" >
<cld-transformation effect="improve:outdoor" />
</cld-image>
Angular:
<cl-image public-id="sample.jpg" >
<cl-transformation effect="improve:outdoor">
</cl-transformation>
</cl-image>
.Net:
cloudinary.Api.UrlImgUp.Transform(new Transformation().Effect("improve:outdoor")).BuildImageTag("sample.jpg")
Android:
MediaManager.get().url().transformation(new Transformation().effect("improve:outdoor")).generate("sample.jpg");
iOS:
imageView.cldSetImage(cloudinary.createUrl().setTransformation(CLDTransformation().setEffect("improve:outdoor")).generate("sample.jpg")!, cloudinary: cloudinary)
- To automatically enhance an image using the Viesus automatic enhancement add-on:
Ruby:
cl_image_tag("beach.jpg", :effect=>"viesus_correct")
PHP:
cl_image_tag("beach.jpg", array("effect"=>"viesus_correct"))
Python:
CloudinaryImage("beach.jpg").image(effect="viesus_correct")
Node.js:
cloudinary.image("beach.jpg", {effect: "viesus_correct"})
Java:
cloudinary.url().transformation(new Transformation().effect("viesus_correct")).imageTag("beach.jpg");
JS:
cloudinary.imageTag('beach.jpg', {effect: "viesus_correct"}).toHtml();
jQuery:
$.cloudinary.image("beach.jpg", {effect: "viesus_correct"})
React:
<Image publicId="beach.jpg" >
<Transformation effect="viesus_correct" />
</Image>
Vue.js:
<cld-image publicId="beach.jpg" >
<cld-transformation effect="viesus_correct" />
</cld-image>
Angular:
<cl-image public-id="beach.jpg" >
<cl-transformation effect="viesus_correct">
</cl-transformation>
</cl-image>
.Net:
cloudinary.Api.UrlImgUp.Transform(new Transformation().Effect("viesus_correct")).BuildImageTag("beach.jpg")
Android:
MediaManager.get().url().transformation(new Transformation().effect("viesus_correct")).generate("beach.jpg");
iOS:
imageView.cldSetImage(cloudinary.createUrl().setTransformation(CLDTransformation().setEffect("viesus_correct")).generate("beach.jpg")!, cloudinary: cloudinary)
The art:<filter> effects brighten highlights, intensify shadows, apply sepia-like filters, add vignetting, and more.
Original image:
Filters:
al_dente
athena
audrey
aurora
daguerre
eucalyptus
fes
frost
hairspray
hokusai
incognito
linen
peacock
primavera
quartz
red_rock
refresh
sizzle
sonnet
ukulele
zorro
Ruby:
cl_image_tag("horses.jpg", :effect=>"art:zorro")
PHP:
cl_image_tag("horses.jpg", array("effect"=>"art:zorro"))
Python:
CloudinaryImage("horses.jpg").image(effect="art:zorro")
Node.js:
cloudinary.image("horses.jpg", {effect: "art:zorro"})
Java:
cloudinary.url().transformation(new Transformation().effect("art:zorro")).imageTag("horses.jpg");
JS:
cloudinary.imageTag('horses.jpg', {effect: "art:zorro"}).toHtml();
jQuery:
$.cloudinary.image("horses.jpg", {effect: "art:zorro"})
React:
<Image publicId="horses.jpg" >
<Transformation effect="art:zorro" />
</Image>
Vue.js:
<cld-image publicId="horses.jpg" >
<cld-transformation effect="art:zorro" />
</cld-image>
Angular:
<cl-image public-id="horses.jpg" >
<cl-transformation effect="art:zorro">
</cl-transformation>
</cl-image>
.Net:
cloudinary.Api.UrlImgUp.Transform(new Transformation().Effect("art:zorro")).BuildImageTag("horses.jpg")
Android:
MediaManager.get().url().transformation(new Transformation().effect("art:zorro")).generate("horses.jpg");
iOS:
imageView.cldSetImage(cloudinary.createUrl().setTransformation(CLDTransformation().setEffect("art:zorro")).generate("horses.jpg")!, cloudinary: cloudinary)
Effects: style_transfer, oil_paint, cartoonify, red_eye, adv_redeye, vectorize
This category includes other effects that don't fall under one of the other categories.
For example, to apply an oil-painting filter to the sample image:
Ruby:
cl_image_tag("sample.jpg", :effect=>"oil_paint:70")
PHP:
cl_image_tag("sample.jpg", array("effect"=>"oil_paint:70"))
Python:
CloudinaryImage("sample.jpg").image(effect="oil_paint:70")
Node.js:
cloudinary.image("sample.jpg", {effect: "oil_paint:70"})
Java:
cloudinary.url().transformation(new Transformation().effect("oil_paint:70")).imageTag("sample.jpg");
JS:
cloudinary.imageTag('sample.jpg', {effect: "oil_paint:70"}).toHtml();
jQuery:
$.cloudinary.image("sample.jpg", {effect: "oil_paint:70"})
React:
<Image publicId="sample.jpg" >
<Transformation effect="oil_paint:70" />
</Image>
Vue.js:
<cld-image publicId="sample.jpg" >
<cld-transformation effect="oil_paint:70" />
</cld-image>
Angular:
<cl-image public-id="sample.jpg" >
<cl-transformation effect="oil_paint:70">
</cl-transformation>
</cl-image>
.Net:
cloudinary.Api.UrlImgUp.Transform(new Transformation().Effect("oil_paint:70")).BuildImageTag("sample.jpg")
Android:
MediaManager.get().url().transformation(new Transformation().effect("oil_paint:70")).generate("sample.jpg");
iOS:
imageView.cldSetImage(cloudinary.createUrl().setTransformation(CLDTransformation().setEffect("oil_paint:70")).generate("sample.jpg")!, cloudinary: cloudinary)
You can dynamically add overlays, underlays and text captions to specific locations within your images, while easily manipulating and transforming them to suit your needs. This section is divided into the following topics:
Add an image over the base image with the overlay parameter (l in URLs) and the public ID of a previously uploaded image (e.g., l_watermark for an image with the public ID of watermark). For example, adding an overlay of the image called cloudinary_icon to the jpg image named sample.
Ruby:
cl_image_tag("sample.jpg", :overlay=>"cloudinary_icon")
PHP:
cl_image_tag("sample.jpg", array("overlay"=>"cloudinary_icon"))
Python:
CloudinaryImage("sample.jpg").image(overlay="cloudinary_icon")
Node.js:
cloudinary.image("sample.jpg", {overlay: "cloudinary_icon"})
Java:
cloudinary.url().transformation(new Transformation().overlay(new Layer().publicId("cloudinary_icon"))).imageTag("sample.jpg");
JS:
cloudinary.imageTag('sample.jpg', {overlay: new cloudinary.Layer().publicId("cloudinary_icon")}).toHtml();
jQuery:
$.cloudinary.image("sample.jpg", {overlay: new cloudinary.Layer().publicId("cloudinary_icon")})
React:
<Image publicId="sample.jpg" >
<Transformation overlay="cloudinary_icon" />
</Image>
Vue.js:
<cld-image publicId="sample.jpg" >
<cld-transformation overlay="cloudinary_icon" />
</cld-image>
Angular:
<cl-image public-id="sample.jpg" >
<cl-transformation overlay="cloudinary_icon">
</cl-transformation>
</cl-image>
.Net:
cloudinary.Api.UrlImgUp.Transform(new Transformation().Overlay(new Layer().PublicId("cloudinary_icon"))).BuildImageTag("sample.jpg")
Android:
MediaManager.get().url().transformation(new Transformation().overlay(new Layer().publicId("cloudinary_icon"))).generate("sample.jpg");
iOS:
imageView.cldSetImage(cloudinary.createUrl().setTransformation(CLDTransformation().setOverlay("cloudinary_icon")).generate("sample.jpg")!, cloudinary: cloudinary)
Important
If the public ID of an image includes a folder component (e.g., the public ID of an image is
animals/dog) then replace the slash with a colon when using the image as an overlay (e.g., the public ID of the image becomes
animals:dog when used as an overlay).
You can also use a remote image as an overlay by adding the fetch (or url) property of the overlay parameter ( l_fetch: in URLs) and the base64 encoded URL of the remote image. For example, adding an overlay of the remote image https://cloudinary.com/images/old_logo.png to the jpg image named sample.
Ruby:
cl_image_tag("sample.jpg", :overlay=>{:url=>"http://cloudinary.com/images/old_logo.png7"})
PHP:
cl_image_tag("sample.jpg", array("overlay"=>array("url"=>"http://cloudinary.com/images/old_logo.png7")))
Python:
CloudinaryImage("sample.jpg").image(overlay={'url': "http://cloudinary.com/images/old_logo.png7"})
Node.js:
cloudinary.image("sample.jpg", {overlay: {url: "http://cloudinary.com/images/old_logo.png7"}})
Java:
cloudinary.url().transformation(new Transformation().overlay(new FetchLayer().url("http://cloudinary.com/images/old_logo.png7"))).imageTag("sample.jpg");
JS:
cloudinary.imageTag('sample.jpg', {overlay: new cloudinary.FetchLayer().url("http://cloudinary.com/images/old_logo.png7")}).toHtml();
jQuery:
$.cloudinary.image("sample.jpg", {overlay: new cloudinary.FetchLayer().url("http://cloudinary.com/images/old_logo.png7")})
React:
<Image publicId="sample.jpg" >
<Transformation overlay={{url: "http://cloudinary.com/images/old_logo.png7"}} />
</Image>
Vue.js:
<cld-image publicId="sample.jpg" >
<cld-transformation overlay={{url: "http://cloudinary.com/images/old_logo.png7"}} />
</cld-image>
Angular:
<cl-image public-id="sample.jpg" >
<cl-transformation overlay="fetch:aHR0cDovL2Nsb3VkaW5hcnkuY29tL2ltYWdlcy9vbGRfbG9nby5wbmc%3D">
</cl-transformation>
</cl-image>
.Net:
cloudinary.Api.UrlImgUp.Transform(new Transformation().Overlay(new FetchLayer("http://cloudinary.com/images/old_logo.png7"))).BuildImageTag("sample.jpg")
Android:
MediaManager.get().url().transformation(new Transformation().overlay(new FetchLayer().url("http://cloudinary.com/images/old_logo.png7"))).generate("sample.jpg");
iOS:
imageView.cldSetImage(cloudinary.createUrl().setTransformation(CLDTransformation().setOverlay("fetch:aHR0cDovL2Nsb3VkaW5hcnkuY29tL2ltYWdlcy9vbGRfbG9nby5wbmc%3D")).generate("sample.jpg")!, cloudinary: cloudinary)
Note
The Cloudinary SDKs automatically generate a base 64 encoded URL for a given HTTP/S URL: you will need to supply the URL in base 64 encoding with padding if you generate the delivery URL in your own code.
The overlay can be resized and manipulated like any other image uploaded to Cloudinary. For example, adding an overlay of the image called cloudinary_icon to the top right corner of the sample image, where the overlay is also scaled down to 90% of its original width and made into a watermark by reducing the opacity to 70% and increasing the brightness to 50% using the brightness effect:
Ruby:
cl_image_tag("sample.jpg", :overlay=>"cloudinary_icon", :width=>0.9, :gravity=>"north_east", :opacity=>70, :effect=>"brightness:50", :crop=>"scale")
PHP:
cl_image_tag("sample.jpg", array("overlay"=>"cloudinary_icon", "width"=>0.9, "gravity"=>"north_east", "opacity"=>70, "effect"=>"brightness:50", "crop"=>"scale"))
Python:
CloudinaryImage("sample.jpg").image(overlay="cloudinary_icon", width=0.9, gravity="north_east", opacity=70, effect="brightness:50", crop="scale")
Node.js:
cloudinary.image("sample.jpg", {overlay: "cloudinary_icon", width: "0.9", gravity: "north_east", opacity: 70, effect: "brightness:50", crop: "scale"})
Java:
cloudinary.url().transformation(new Transformation().overlay(new Layer().publicId("cloudinary_icon")).width(0.9).gravity("north_east").opacity(70).effect("brightness:50").crop("scale")).imageTag("sample.jpg");
JS:
cloudinary.imageTag('sample.jpg', {overlay: new cloudinary.Layer().publicId("cloudinary_icon"), width: "0.9", gravity: "north_east", opacity: 70, effect: "brightness:50", crop: "scale"}).toHtml();
jQuery:
$.cloudinary.image("sample.jpg", {overlay: new cloudinary.Layer().publicId("cloudinary_icon"), width: "0.9", gravity: "north_east", opacity: 70, effect: "brightness:50", crop: "scale"})
React:
<Image publicId="sample.jpg" >
<Transformation overlay="cloudinary_icon" width="0.9" gravity="north_east" opacity="70" effect="brightness:50" crop="scale" />
</Image>
Vue.js:
<cld-image publicId="sample.jpg" >
<cld-transformation overlay="cloudinary_icon" width="0.9" gravity="north_east" opacity="70" effect="brightness:50" crop="scale" />
</cld-image>
Angular:
<cl-image public-id="sample.jpg" >
<cl-transformation overlay="cloudinary_icon" width="0.9" gravity="north_east" opacity="70" effect="brightness:50" crop="scale">
</cl-transformation>
</cl-image>
.Net:
cloudinary.Api.UrlImgUp.Transform(new Transformation().Overlay(new Layer().PublicId("cloudinary_icon")).Width(0.9).Gravity("north_east").Opacity(70).Effect("brightness:50").Crop("scale")).BuildImageTag("sample.jpg")
Android:
MediaManager.get().url().transformation(new Transformation().overlay(new Layer().publicId("cloudinary_icon")).width(0.9).gravity("north_east").opacity(70).effect("brightness:50").crop("scale")).generate("sample.jpg");
iOS:
imageView.cldSetImage(cloudinary.createUrl().setTransformation(CLDTransformation().setOverlay("cloudinary_icon").setWidth(0.9).setGravity("north_east").setOpacity(70).setEffect("brightness:50").setCrop("scale")).generate("sample.jpg")!, cloudinary: cloudinary)
You can also add the relative flag (fl_relative in URLs) to specify that percentage-based width & height parameters of overlays (e.g., w_0.5) are relative to the size of the base image instead of the original size of the overlaying image itself. For example, adding an overlay of the image called cloudinary_icon to the jpg image named sample, where the overlay is resized to 80% of the width of the base image:
Ruby:
cl_image_tag("sample.jpg", :overlay=>"cloudinary_icon", :width=>0.8, :flags=>"relative")
PHP:
cl_image_tag("sample.jpg", array("overlay"=>"cloudinary_icon", "width"=>0.8, "flags"=>"relative"))
Python:
CloudinaryImage("sample.jpg").image(overlay="cloudinary_icon", width=0.8, flags="relative")
Node.js:
cloudinary.image("sample.jpg", {overlay: "cloudinary_icon", width: "0.8", flags: "relative"})
Java:
cloudinary.url().transformation(new Transformation().overlay(new Layer().publicId("cloudinary_icon")).width(0.8).flags("relative")).imageTag("sample.jpg");
JS:
cloudinary.imageTag('sample.jpg', {overlay: new cloudinary.Layer().publicId("cloudinary_icon"), width: "0.8", flags: "relative"}).toHtml();
jQuery:
$.cloudinary.image("sample.jpg", {overlay: new cloudinary.Layer().publicId("cloudinary_icon"), width: "0.8", flags: "relative"})
React:
<Image publicId="sample.jpg" >
<Transformation overlay="cloudinary_icon" width="0.8" flags="relative" />
</Image>
Vue.js:
<cld-image publicId="sample.jpg" >
<cld-transformation overlay="cloudinary_icon" width="0.8" flags="relative" />
</cld-image>
Angular:
<cl-image public-id="sample.jpg" >
<cl-transformation overlay="cloudinary_icon" width="0.8" flags="relative">
</cl-transformation>
</cl-image>
.Net:
cloudinary.Api.UrlImgUp.Transform(new Transformation().Overlay(new Layer().PublicId("cloudinary_icon")).Width(0.8).Flags("relative")).BuildImageTag("sample.jpg")
Android:
MediaManager.get().url().transformation(new Transformation().overlay(new Layer().publicId("cloudinary_icon")).width(0.8).flags("relative")).generate("sample.jpg");
iOS:
imageView.cldSetImage(cloudinary.createUrl().setTransformation(CLDTransformation().setOverlay("cloudinary_icon").setWidth(0.8).setFlags("relative")).generate("sample.jpg")!, cloudinary: cloudinary)
To determine the position of an overlay, add the gravity parameter to define a location within the base image ('center' by default). For fine tuning the exact location of the overlay, you can offset the overlay from the focus of gravity by also adding the x and y coordinate parameters. These parameters accept either integer values representing the number of pixels to displace the overlay in the horizontal or vertical directions, or real values representing a percentage-based offset relative to the containing image (e.g., 0.2 for an offset of 20%). For example, adding an overlay of the image called cloudinary_icon to the jpg image named sample with gravity set to northwest but with a vertical offset of 20 pixels:
Ruby:
cl_image_tag("sample.jpg", :overlay=>"cloudinary_icon", :gravity=>"north_west", :y=>20)
PHP:
cl_image_tag("sample.jpg", array("overlay"=>"cloudinary_icon", "gravity"=>"north_west", "y"=>20))
Python:
CloudinaryImage("sample.jpg").image(overlay="cloudinary_icon", gravity="north_west", y=20)
Node.js:
cloudinary.image("sample.jpg", {overlay: "cloudinary_icon", gravity: "north_west", y: 20})
Java:
cloudinary.url().transformation(new Transformation().overlay(new Layer().publicId("cloudinary_icon")).gravity("north_west").y(20)).imageTag("sample.jpg");
JS:
cloudinary.imageTag('sample.jpg', {overlay: new cloudinary.Layer().publicId("cloudinary_icon"), gravity: "north_west", y: 20}).toHtml();
jQuery:
$.cloudinary.image("sample.jpg", {overlay: new cloudinary.Layer().publicId("cloudinary_icon"), gravity: "north_west", y: 20})
React:
<Image publicId="sample.jpg" >
<Transformation overlay="cloudinary_icon" gravity="north_west" y="20" />
</Image>
Vue.js:
<cld-image publicId="sample.jpg" >
<cld-transformation overlay="cloudinary_icon" gravity="north_west" y="20" />
</cld-image>
Angular:
<cl-image public-id="sample.jpg" >
<cl-transformation overlay="cloudinary_icon" gravity="north_west" y="20">
</cl-transformation>
</cl-image>
.Net:
cloudinary.Api.UrlImgUp.Transform(new Transformation().Overlay(new Layer().PublicId("cloudinary_icon")).Gravity("north_west").Y(20)).BuildImageTag("sample.jpg")
Android:
MediaManager.get().url().transformation(new Transformation().overlay(new Layer().publicId("cloudinary_icon")).gravity("north_west").y(20)).generate("sample.jpg");
iOS:
imageView.cldSetImage(cloudinary.createUrl().setTransformation(CLDTransformation().setOverlay("cloudinary_icon").setGravity("north_west").setY(20)).generate("sample.jpg")!, cloudinary: cloudinary)
The gravity parameter can also be set to one of the facial detection modes, and the detected facial coordinates become the focus when placing the overlay. If there are multiple faces in an image, setting the gravity parameter to 'faces' will result in the overlay being placed multiple times, once for each face detected. For example, adding an overlay of the golden_star image over all faces detected in the couple image. The star image is also resized to 110% of the detected width of each face by adding the region_relative flag:
Ruby:
cl_image_tag("couple.jpg", :overlay=>"golden_star", :gravity=>"faces", :width=>1.1, :flags=>"region_relative")
PHP:
cl_image_tag("couple.jpg", array("overlay"=>"golden_star", "gravity"=>"faces", "width"=>1.1, "flags"=>"region_relative"))
Python:
CloudinaryImage("couple.jpg").image(overlay="golden_star", gravity="faces", width=1.1, flags="region_relative")
Node.js:
cloudinary.image("couple.jpg", {overlay: "golden_star", gravity: "faces", width: "1.1", flags: "region_relative"})
Java:
cloudinary.url().transformation(new Transformation().overlay(new Layer().publicId("golden_star")).gravity("faces").width(1.1).flags("region_relative")).imageTag("couple.jpg");
JS:
cloudinary.imageTag('couple.jpg', {overlay: new cloudinary.Layer().publicId("golden_star"), gravity: "faces", width: "1.1", flags: "region_relative"}).toHtml();
jQuery:
$.cloudinary.image("couple.jpg", {overlay: new cloudinary.Layer().publicId("golden_star"), gravity: "faces", width: "1.1", flags: "region_relative"})
React:
<Image publicId="couple.jpg" >
<Transformation overlay="golden_star" gravity="faces" width="1.1" flags="region_relative" />
</Image>
Vue.js:
<cld-image publicId="couple.jpg" >
<cld-transformation overlay="golden_star" gravity="faces" width="1.1" flags="region_relative" />
</cld-image>
Angular:
<cl-image public-id="couple.jpg" >
<cl-transformation overlay="golden_star" gravity="faces" width="1.1" flags="region_relative">
</cl-transformation>
</cl-image>
.Net:
cloudinary.Api.UrlImgUp.Transform(new Transformation().Overlay(new Layer().PublicId("golden_star")).Gravity("faces").Width(1.1).Flags("region_relative")).BuildImageTag("couple.jpg")
Android:
MediaManager.get().url().transformation(new Transformation().overlay(new Layer().publicId("golden_star")).gravity("faces").width(1.1).flags("region_relative")).generate("couple.jpg");
iOS:
imageView.cldSetImage(cloudinary.createUrl().setTransformation(CLDTransformation().setOverlay("golden_star").setGravity("faces").setWidth(1.1).setFlags("region_relative")).generate("couple.jpg")!, cloudinary: cloudinary)
Note
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.
Instead of adding the overlay to a single specific location, you can tile the image within the entire image by adding the tiled flag (fl_tiled in URLs). For example, tiling an overlay of the image called cloudinary_icon on to the jpg image named flowers, with the overlay's opacity set to 50% and scaled to a width of 100 pixels:
Ruby:
cl_image_tag("flowers.jpg", :transformation=>[
{:width=>500, :crop=>"scale"},
{:overlay=>"cloudinary_icon", :opacity=>50, :width=>100, :effect=>"brightness:200", :flags=>"tiled"}
])
PHP:
cl_image_tag("flowers.jpg", array("transformation"=>array(
array("width"=>500, "crop"=>"scale"),
array("overlay"=>"cloudinary_icon", "opacity"=>50, "width"=>100, "effect"=>"brightness:200", "flags"=>"tiled")
)))
Python:
CloudinaryImage("flowers.jpg").image(transformation=[
{'width': 500, 'crop': "scale"},
{'overlay': "cloudinary_icon", 'opacity': 50, 'width': 100, 'effect': "brightness:200", 'flags': "tiled"}
])
Node.js:
cloudinary.image("flowers.jpg", {transformation: [
{width: 500, crop: "scale"},
{overlay: "cloudinary_icon", opacity: 50, width: 100, effect: "brightness:200", flags: "tiled"}
]})
Java:
cloudinary.url().transformation(new Transformation()
.width(500).crop("scale").chain()
.overlay(new Layer().publicId("cloudinary_icon")).opacity(50).width(100).effect("brightness:200").flags("tiled")).imageTag("flowers.jpg");
JS:
cloudinary.imageTag('flowers.jpg', {transformation: [
{width: 500, crop: "scale"},
{overlay: new cloudinary.Layer().publicId("cloudinary_icon"), opacity: 50, width: 100, effect: "brightness:200", flags: "tiled"}
]}).toHtml();
jQuery:
$.cloudinary.image("flowers.jpg", {transformation: [
{width: 500, crop: "scale"},
{overlay: new cloudinary.Layer().publicId("cloudinary_icon"), opacity: 50, width: 100, effect: "brightness:200", flags: "tiled"}
]})
React:
<Image publicId="flowers.jpg" >
<Transformation width="500" crop="scale" />
<Transformation overlay="cloudinary_icon" opacity="50" width="100" effect="brightness:200" flags="tiled" />
</Image>
Vue.js:
<cld-image publicId="flowers.jpg" >
<cld-transformation width="500" crop="scale" />
<cld-transformation overlay="cloudinary_icon" opacity="50" width="100" effect="brightness:200" flags="tiled" />
</cld-image>
Angular:
<cl-image public-id="flowers.jpg" >
<cl-transformation width="500" crop="scale">
</cl-transformation>
<cl-transformation overlay="cloudinary_icon" opacity="50" width="100" effect="brightness:200" flags="tiled">
</cl-transformation>
</cl-image>
.Net:
cloudinary.Api.UrlImgUp.Transform(new Transformation()
.Width(500).Crop("scale").Chain()
.Overlay(new Layer().PublicId("cloudinary_icon")).Opacity(50).Width(100).Effect("brightness:200").Flags("tiled")).BuildImageTag("flowers.jpg")
Android:
MediaManager.get().url().transformation(new Transformation()
.width(500).crop("scale").chain()
.overlay(new Layer().publicId("cloudinary_icon")).opacity(50).width(100).effect("brightness:200").flags("tiled")).generate("flowers.jpg");
iOS:
imageView.cldSetImage(cloudinary.createUrl().setTransformation(CLDTransformation()
.setWidth(500).setCrop("scale").chain()
.setOverlay("cloudinary_icon").setOpacity(50).setWidth(100).setEffect("brightness:200").setFlags("tiled")).generate("flowers.jpg")!, cloudinary: cloudinary)
You can apply multiple transformations to overlays by adding the layer_apply flag to the 'last' transformation in the series. That is, the flag tells Cloudinary to apply all chained transformations, until a transformation component that includes this flag, on the last added overlay or underlay instead of applying them on the base image (it closes the layer, similar to a closing bracket).
For example, the sample image scaled to a width of 500 pixels before adding the woman image as an overlay, where the overlay image is automatically cropped to only include the detected face and then scaled to a width of 150 pixels:
Ruby:
cl_image_tag("sample.jpg", :transformation=>[
{:width=>500, :crop=>"scale"},
{:effect=>"brightness:70"},
{:overlay=>"woman", :gravity=>"face", :crop=>"crop"},
{:width=>150, :crop=>"scale"},
{:effect=>"saturation:50"},
{:effect=>"shadow"},
{:flags=>"layer_apply"}
])
PHP:
cl_image_tag("sample.jpg", array("transformation"=>array(
array("width"=>500, "crop"=>"scale"),
array("effect"=>"brightness:70"),
array("overlay"=>"woman", "gravity"=>"face", "crop"=>"crop"),
array("width"=>150, "crop"=>"scale"),
array("effect"=>"saturation:50"),
array("effect"=>"shadow"),
array("flags"=>"layer_apply")
)))
Python:
CloudinaryImage("sample.jpg").image(transformation=[
{'width': 500, 'crop': "scale"},
{'effect': "brightness:70"},
{'overlay': "woman", 'gravity': "face", 'crop': "crop"},
{'width': 150, 'crop': "scale"},
{'effect': "saturation:50"},
{'effect': "shadow"},
{'flags': "layer_apply"}
])
Node.js:
cloudinary.image("sample.jpg", {transformation: [
{width: 500, crop: "scale"},
{effect: "brightness:70"},
{overlay: "woman", gravity: "face", crop: "crop"},
{width: 150, crop: "scale"},
{effect: "saturation:50"},
{effect: "shadow"},
{flags: "layer_apply"}
]})
Java:
cloudinary.url().transformation(new Transformation()
.width(500).crop("scale").chain()
.effect("brightness:70").chain()
.overlay(new Layer().publicId("woman")).gravity("face").crop("crop").chain()
.width(150).crop("scale").chain()
.effect("saturation:50").chain()
.effect("shadow").chain()
.flags("layer_apply")).imageTag("sample.jpg");
JS:
cloudinary.imageTag('sample.jpg', {transformation: [
{width: 500, crop: "scale"},
{effect: "brightness:70"},
{overlay: new cloudinary.Layer().publicId("woman"), gravity: "face", crop: "crop"},
{width: 150, crop: "scale"},
{effect: "saturation:50"},
{effect: "shadow"},
{flags: "layer_apply"}
]}).toHtml();
jQuery:
$.cloudinary.image("sample.jpg", {transformation: [
{width: 500, crop: "scale"},
{effect: "brightness:70"},
{overlay: new cloudinary.Layer().publicId("woman"), gravity: "face", crop: "crop"},
{width: 150, crop: "scale"},
{effect: "saturation:50"},
{effect: "shadow"},
{flags: "layer_apply"}
]})
React:
<Image publicId="sample.jpg" >
<Transformation width="500" crop="scale" />
<Transformation effect="brightness:70" />
<Transformation overlay="woman" gravity="face" crop="crop" />
<Transformation width="150" crop="scale" />
<Transformation effect="saturation:50" />
<Transformation effect="shadow" />
<Transformation flags="layer_apply" />
</Image>
Vue.js:
<cld-image publicId="sample.jpg" >
<cld-transformation width="500" crop="scale" />
<cld-transformation effect="brightness:70" />
<cld-transformation overlay="woman" gravity="face" crop="crop" />
<cld-transformation width="150" crop="scale" />
<cld-transformation effect="saturation:50" />
<cld-transformation effect="shadow" />
<cld-transformation flags="layer_apply" />
</cld-image>
Angular:
<cl-image public-id="sample.jpg" >
<cl-transformation width="500" crop="scale">
</cl-transformation>
<cl-transformation effect="brightness:70">
</cl-transformation>
<cl-transformation overlay="woman" gravity="face" crop="crop">
</cl-transformation>
<cl-transformation width="150" crop="scale">
</cl-transformation>
<cl-transformation effect="saturation:50">
</cl-transformation>
<cl-transformation effect="shadow">
</cl-transformation>
<cl-transformation flags="layer_apply">
</cl-transformation>
</cl-image>
.Net:
cloudinary.Api.UrlImgUp.Transform(new Transformation()
.Width(500).Crop("scale").Chain()
.Effect("brightness:70").Chain()
.Overlay(new Layer().PublicId("woman")).Gravity("face").Crop("crop").Chain()
.Width(150).Crop("scale").Chain()
.Effect("saturation:50").Chain()
.Effect("shadow").Chain()
.Flags("layer_apply")).BuildImageTag("sample.jpg")
Android:
MediaManager.get().url().transformation(new Transformation()
.width(500).crop("scale").chain()
.effect("brightness:70").chain()
.overlay(new Layer().publicId("woman")).gravity("face").crop("crop").chain()
.width(150).crop("scale").chain()
.effect("saturation:50").chain()
.effect("shadow").chain()
.flags("layer_apply")).generate("sample.jpg");
iOS:
imageView.cldSetImage(cloudinary.createUrl().setTransformation(CLDTransformation()
.setWidth(500).setCrop("scale").chain()
.setEffect("brightness:70").chain()
.setOverlay("woman").setGravity("face").setCrop("crop").chain()
.setWidth(150).setCrop("scale").chain()
.setEffect("saturation:50").chain()
.setEffect("shadow").chain()
.setFlags("layer_apply")).generate("sample.jpg")!, cloudinary: cloudinary)
Note how the transformations were applied in the last example as chained transformations. The first width adjustment to 500 pixels was made to the base image, and the second width adjustment to 150 pixels was made to the overlay (as was the face detection based cropping) because of the layer_apply flag.
- When adding multiple layers, close all layers with the
layer_apply flag (even if they don't use multiple components) to avoid server confusion on which transformations to apply to a particular layer.
- Specify any details regarding the relationship between the overlay image and the base image (i.e., anything that is relative like gravity) in the same component as the
layer_apply flag. For example the sample image scaled to a width of 500 pixels before adding the cloudinary_icon image as an overlay, where the overlay image is scaled to a width of 150 pixels, converted to black and white, and then the entire overlay is placed in the top right corner:
Ruby:
cl_image_tag("sample.jpg", :transformation=>[
{:width=>500, :crop=>"scale"},
{:overlay=>"cloudinary_icon", :width=>150},
{:effect=>"blackwhite"},
{:flags=>"layer_apply", :gravity=>"north_east"}
])
PHP:
cl_image_tag("sample.jpg", array("transformation"=>array(
array("width"=>500, "crop"=>"scale"),
array("overlay"=>"cloudinary_icon", "width"=>150),
array("effect"=>"blackwhite"),
array("flags"=>"layer_apply", "gravity"=>"north_east")
)))
Python:
CloudinaryImage("sample.jpg").image(transformation=[
{'width': 500, 'crop': "scale"},
{'overlay': "cloudinary_icon", 'width': 150},
{'effect': "blackwhite"},
{'flags': "layer_apply", 'gravity': "north_east"}
])
Node.js:
cloudinary.image("sample.jpg", {transformation: [
{width: 500, crop: "scale"},
{overlay: "cloudinary_icon", width: 150},
{effect: "blackwhite"},
{flags: "layer_apply", gravity: "north_east"}
]})
Java:
cloudinary.url().transformation(new Transformation()
.width(500).crop("scale").chain()
.overlay(new Layer().publicId("cloudinary_icon")).width(150).chain()
.effect("blackwhite").chain()
.flags("layer_apply").gravity("north_east")).imageTag("sample.jpg");
JS:
cloudinary.imageTag('sample.jpg', {transformation: [
{width: 500, crop: "scale"},
{overlay: new cloudinary.Layer().publicId("cloudinary_icon"), width: 150},
{effect: "blackwhite"},
{flags: "layer_apply", gravity: "north_east"}
]}).toHtml();
jQuery:
$.cloudinary.image("sample.jpg", {transformation: [
{width: 500, crop: "scale"},
{overlay: new cloudinary.Layer().publicId("cloudinary_icon"), width: 150},
{effect: "blackwhite"},
{flags: "layer_apply", gravity: "north_east"}
]})
React:
<Image publicId="sample.jpg" >
<Transformation width="500" crop="scale" />
<Transformation overlay="cloudinary_icon" width="150" />
<Transformation effect="blackwhite" />
<Transformation flags="layer_apply" gravity="north_east" />
</Image>
Vue.js:
<cld-image publicId="sample.jpg" >
<cld-transformation width="500" crop="scale" />
<cld-transformation overlay="cloudinary_icon" width="150" />
<cld-transformation effect="blackwhite" />
<cld-transformation flags="layer_apply" gravity="north_east" />
</cld-image>
Angular:
<cl-image public-id="sample.jpg" >
<cl-transformation width="500" crop="scale">
</cl-transformation>
<cl-transformation overlay="cloudinary_icon" width="150">
</cl-transformation>
<cl-transformation effect="blackwhite">
</cl-transformation>
<cl-transformation flags="layer_apply" gravity="north_east">
</cl-transformation>
</cl-image>
.Net:
cloudinary.Api.UrlImgUp.Transform(new Transformation()
.Width(500).Crop("scale").Chain()
.Overlay(new Layer().PublicId("cloudinary_icon")).Width(150).Chain()
.Effect("blackwhite").Chain()
.Flags("layer_apply").Gravity("north_east")).BuildImageTag("sample.jpg")
Android:
MediaManager.get().url().transformation(new Transformation()
.width(500).crop("scale").chain()
.overlay(new Layer().publicId("cloudinary_icon")).width(150).chain()
.effect("blackwhite").chain()
.flags("layer_apply").gravity("north_east")).generate("sample.jpg");
iOS:
imageView.cldSetImage(cloudinary.createUrl().setTransformation(CLDTransformation()
.setWidth(500).setCrop("scale").chain()
.setOverlay("cloudinary_icon").setWidth(150).chain()
.setEffect("blackwhite").chain()
.setFlags("layer_apply").setGravity("north_east")).generate("sample.jpg")!, cloudinary: cloudinary)
- Layers can be nested within layers. For example, the same image as above with another
cloudinary_icon image added as an overlay to the first (black and white) cloudinay_icon overlay.
Ruby:
cl_image_tag("sample.jpg", :transformation=>[
{:width=>500, :crop=>"scale"},
{:overlay=>"cloudinary_icon", :width=>150},
{:effect=>"blackwhite"},
{:overlay=>"cloudinary_icon", :width=>50},
{:flags=>"layer_apply"},
{:flags=>"layer_apply", :gravity=>"north_east"}
])
PHP:
cl_image_tag("sample.jpg", array("transformation"=>array(
array("width"=>500, "crop"=>"scale"),
array("overlay"=>"cloudinary_icon", "width"=>150),
array("effect"=>"blackwhite"),
array("overlay"=>"cloudinary_icon", "width"=>50),
array("flags"=>"layer_apply"),
array("flags"=>"layer_apply", "gravity"=>"north_east")
)))
Python:
CloudinaryImage("sample.jpg").image(transformation=[
{'width': 500, 'crop': "scale"},
{'overlay': "cloudinary_icon", 'width': 150},
{'effect': "blackwhite"},
{'overlay': "cloudinary_icon", 'width': 50},
{'flags': "layer_apply"},
{'flags': "layer_apply", 'gravity': "north_east"}
])
Node.js:
cloudinary.image("sample.jpg", {transformation: [
{width: 500, crop: "scale"},
{overlay: "cloudinary_icon", width: 150},
{effect: "blackwhite"},
{overlay: "cloudinary_icon", width: 50},
{flags: "layer_apply"},
{flags: "layer_apply", gravity: "north_east"}
]})
Java:
cloudinary.url().transformation(new Transformation()
.width(500).crop("scale").chain()
.overlay(new Layer().publicId("cloudinary_icon")).width(150).chain()
.effect("blackwhite").chain()
.overlay(new Layer().publicId("cloudinary_icon")).width(50).chain()
.flags("layer_apply").chain()
.flags("layer_apply").gravity("north_east")).imageTag("sample.jpg");
JS:
cloudinary.imageTag('sample.jpg', {transformation: [
{width: 500, crop: "scale"},
{overlay: new cloudinary.Layer().publicId("cloudinary_icon"), width: 150},
{effect: "blackwhite"},
{overlay: new cloudinary.Layer().publicId("cloudinary_icon"), width: 50},
{flags: "layer_apply"},
{flags: "layer_apply", gravity: "north_east"}
]}).toHtml();
jQuery:
$.cloudinary.image("sample.jpg", {transformation: [
{width: 500, crop: "scale"},
{overlay: new cloudinary.Layer().publicId("cloudinary_icon"), width: 150},
{effect: "blackwhite"},
{overlay: new cloudinary.Layer().publicId("cloudinary_icon"), width: 50},
{flags: "layer_apply"},
{flags: "layer_apply", gravity: "north_east"}
]})
React:
<Image publicId="sample.jpg" >
<Transformation width="500" crop="scale" />
<Transformation overlay="cloudinary_icon" width="150" />
<Transformation effect="blackwhite" />
<Transformation overlay="cloudinary_icon" width="50" />
<Transformation flags="layer_apply" />
<Transformation flags="layer_apply" gravity="north_east" />
</Image>
Vue.js:
<cld-image publicId="sample.jpg" >
<cld-transformation width="500" crop="scale" />
<cld-transformation overlay="cloudinary_icon" width="150" />
<cld-transformation effect="blackwhite" />
<cld-transformation overlay="cloudinary_icon" width="50" />
<cld-transformation flags="layer_apply" />
<cld-transformation flags="layer_apply" gravity="north_east" />
</cld-image>
Angular:
<cl-image public-id="sample.jpg" >
<cl-transformation width="500" crop="scale">
</cl-transformation>
<cl-transformation overlay="cloudinary_icon" width="150">
</cl-transformation>
<cl-transformation effect="blackwhite">
</cl-transformation>
<cl-transformation overlay="cloudinary_icon" width="50">
</cl-transformation>
<cl-transformation flags="layer_apply">
</cl-transformation>
<cl-transformation flags="layer_apply" gravity="north_east">
</cl-transformation>
</cl-image>
.Net:
cloudinary.Api.UrlImgUp.Transform(new Transformation()
.Width(500).Crop("scale").Chain()
.Overlay(new Layer().PublicId("cloudinary_icon")).Width(150).Chain()
.Effect("blackwhite").Chain()
.Overlay(new Layer().PublicId("cloudinary_icon")).Width(50).Chain()
.Flags("layer_apply").Chain()
.Flags("layer_apply").Gravity("north_east")).BuildImageTag("sample.jpg")
Android:
MediaManager.get().url().transformation(new Transformation()
.width(500).crop("scale").chain()
.overlay(new Layer().publicId("cloudinary_icon")).width(150).chain()
.effect("blackwhite").chain()
.overlay(new Layer().publicId("cloudinary_icon")).width(50).chain()
.flags("layer_apply").chain()
.flags("layer_apply").gravity("north_east")).generate("sample.jpg");
iOS:
imageView.cldSetImage(cloudinary.createUrl().setTransformation(CLDTransformation()
.setWidth(500).setCrop("scale").chain()
.setOverlay("cloudinary_icon").setWidth(150).chain()
.setEffect("blackwhite").chain()
.setOverlay("cloudinary_icon").setWidth(50).chain()
.setFlags("layer_apply").chain()
.setFlags("layer_apply").setGravity("north_east")).generate("sample.jpg")!, cloudinary: cloudinary)
Use the anti_removal effect (e_anti_removal in URLs) to slightly modify images overlays in a random manner, thus making them much harder to remove (e.g., adding your logo as a watermark to images). The degree of modification can be controlled by adding a level parameter: e_anti_removal:[level] (Default: 50, Range 1 - 100), and generally you would want to set the value so the resulting effect is visually hard to notice (the default value should be suitable for the vast majority of cases).
For example, adding the anti-removal effect (with a high level of 90 for demonstration purposes) to an overlay of the image called cloudinary_icon added to the north-east corner of the image named flowers, with the overlay's opacity set to 50% and scaled to a width of 200 pixels:
Ruby:
cl_image_tag("flowers.jpg", :transformation=>[
{:width=>500, :crop=>"scale"},
{:overlay=>"cloudinary_icon", :gravity=>"north_east", :opacity=>50, :width=>200, :effect=>"anti_removal:90"}
])
PHP:
cl_image_tag("flowers.jpg", array("transformation"=>array(
array("width"=>500, "crop"=>"scale"),
array("overlay"=>"cloudinary_icon", "gravity"=>"north_east", "opacity"=>50, "width"=>200, "effect"=>"anti_removal:90")
)))
Python:
CloudinaryImage("flowers.jpg").image(transformation=[
{'width': 500, 'crop': "scale"},
{'overlay': "cloudinary_icon", 'gravity': "north_east", 'opacity': 50, 'width': 200, 'effect': "anti_removal:90"}
])
Node.js:
cloudinary.image("flowers.jpg", {transformation: [
{width: 500, crop: "scale"},
{overlay: "cloudinary_icon", gravity: "north_east", opacity: 50, width: 200, effect: "anti_removal:90"}
]})
Java:
cloudinary.url().transformation(new Transformation()
.width(500).crop("scale").chain()
.overlay(new Layer().publicId("cloudinary_icon")).gravity("north_east").opacity(50).width(200).effect("anti_removal:90")).imageTag("flowers.jpg");
JS:
cloudinary.imageTag('flowers.jpg', {transformation: [
{width: 500, crop: "scale"},
{overlay: new cloudinary.Layer().publicId("cloudinary_icon"), gravity: "north_east", opacity: 50, width: 200, effect: "anti_removal:90"}
]}).toHtml();
jQuery:
$.cloudinary.image("flowers.jpg", {transformation: [
{width: 500, crop: "scale"},
{overlay: new cloudinary.Layer().publicId("cloudinary_icon"), gravity: "north_east", opacity: 50, width: 200, effect: "anti_removal:90"}
]})
React:
<Image publicId="flowers.jpg" >
<Transformation width="500" crop="scale" />
<Transformation overlay="cloudinary_icon" gravity="north_east" opacity="50" width="200" effect="anti_removal:90" />
</Image>
Vue.js:
<cld-image publicId="flowers.jpg" >
<cld-transformation width="500" crop="scale" />
<cld-transformation overlay="cloudinary_icon" gravity="north_east" opacity="50" width="200" effect="anti_removal:90" />
</cld-image>
Angular:
<cl-image public-id="flowers.jpg" >
<cl-transformation width="500" crop="scale">
</cl-transformation>
<cl-transformation overlay="cloudinary_icon" gravity="north_east" opacity="50" width="200" effect="anti_removal:90">
</cl-transformation>
</cl-image>
.Net:
cloudinary.Api.UrlImgUp.Transform(new Transformation()
.Width(500).Crop("scale").Chain()
.Overlay(new Layer().PublicId("cloudinary_icon")).Gravity("north_east").Opacity(50).Width(200).Effect("anti_removal:90")).BuildImageTag("flowers.jpg")
Android:
MediaManager.get().url().transformation(new Transformation()
.width(500).crop("scale").chain()
.overlay(new Layer().publicId("cloudinary_icon")).gravity("north_east").opacity(50).width(200).effect("anti_removal:90")).generate("flowers.jpg");
iOS:
imageView.cldSetImage(cloudinary.createUrl().setTransformation(CLDTransformation()
.setWidth(500).setCrop("scale").chain()
.setOverlay("cloudinary_icon").setGravity("north_east").setOpacity(50).setWidth(200).setEffect("anti_removal:90")).generate("flowers.jpg")!, cloudinary: cloudinary)
Note
Adding this effect generates a different result for each execution, even if the transformation is the same. For example, every transformation URL including an overlay and the anti-removal effect, where only the public_id of the base image is changed, will result in a slightly different overlay.
Add an underlay image under a base partially-transparent image with the underlay parameter (u in URLs) and the public ID of a previously uploaded PNG image (e.g., u_background for an image with the public ID of background). You can determine the dimension and position of the underlay using the width, height, x, y and gravity parameters. The underlay can also be further manipulated like any other image uploaded to Cloudinary, and the underlay parameter supports the same features as for overlays.
For example, adding an underlay of an image called site_bg to the image named smartphone. The underlay and base image are both resized to the same width and height, and the brightness is increased to 100 using the brightness effect:
Ruby:
cl_image_tag("smartphone.png", :transformation=>[
{:height=>200, :width=>200, :crop=>"fill"},
{:effect=>"brightness:100", :height=>200, :underlay=>"site_bg", :width=>200}
])
PHP:
cl_image_tag("smartphone.png", array("transformation"=>array(
array("height"=>200, "width"=>200, "crop"=>"fill"),
array("effect"=>"brightness:100", "height"=>200, "underlay"=>"site_bg", "width"=>200)
)))
Python:
CloudinaryImage("smartphone.png").image(transformation=[
{'height': 200, 'width': 200, 'crop': "fill"},
{'effect': "brightness:100", 'height': 200, 'underlay': "site_bg", 'width': 200}
])
Node.js:
cloudinary.image("smartphone.png", {transformation: [
{height: 200, width: 200, crop: "fill"},
{effect: "brightness:100", height: 200, underlay: "site_bg", width: 200}
]})
Java:
cloudinary.url().transformation(new Transformation()
.height(200).width(200).crop("fill").chain()
.effect("brightness:100").height(200).underlay(new Layer().publicId("site_bg")).width(200)).imageTag("smartphone.png");
JS:
cloudinary.imageTag('smartphone.png', {transformation: [
{height: 200, width: 200, crop: "fill"},
{effect: "brightness:100", height: 200, underlay: new cloudinary.Layer().publicId("site_bg"), width: 200}
]}).toHtml();
jQuery:
$.cloudinary.image("smartphone.png", {transformation: [
{height: 200, width: 200, crop: "fill"},
{effect: "brightness:100", height: 200, underlay: new cloudinary.Layer().publicId("site_bg"), width: 200}
]})
React:
<Image publicId="smartphone.png" >
<Transformation height="200" width="200" crop="fill" />
<Transformation effect="brightness:100" height="200" underlay="site_bg" width="200" />
</Image>
Vue.js:
<cld-image publicId="smartphone.png" >
<cld-transformation height="200" width="200" crop="fill" />
<cld-transformation effect="brightness:100" height="200" underlay="site_bg" width="200" />
</cld-image>
Angular:
<cl-image public-id="smartphone.png" >
<cl-transformation height="200" width="200" crop="fill">
</cl-transformation>
<cl-transformation effect="brightness:100" height="200" underlay="site_bg" width="200">
</cl-transformation>
</cl-image>
.Net:
cloudinary.Api.UrlImgUp.Transform(new Transformation()
.Height(200).Width(200).Crop("fill").Chain()
.Effect("brightness:100").Height(200).Underlay(new Layer().PublicId("site_bg")).Width(200)).BuildImageTag("smartphone.png")
Android:
MediaManager.get().url().transformation(new Transformation()
.height(200).width(200).crop("fill").chain()
.effect("brightness:100").height(200).underlay(new Layer().publicId("site_bg")).width(200)).generate("smartphone.png");
iOS:
imageView.cldSetImage(cloudinary.createUrl().setTransformation(CLDTransformation()
.setHeight(200).setWidth(200).setCrop("fill").chain()
.setEffect("brightness:100").setHeight(200).setUnderlay("site_bg").setWidth(200)).generate("smartphone.png")!, cloudinary: cloudinary)
Note
If the public ID of an image includes a folder component (e.g., the public ID of an image is
layers/blue) then replace the slash with a colon when using the image as an underlay (e.g., the public ID of the image becomes
layers:blue when used as an underlay).
Add a text caption over the base image with the text property of the overlay parameter ( l_text: in URLs). The parameter also requires styling parameters such as font family and size (separated with an underscore and followed by a colon), and the text string to display. For example, to overlay the text string "Flowers" in the Arial font with a size of 80 pixels: l_text:Arial_80:Flowers.
Ruby:
cl_image_tag("flowers.jpg", :transformation=>[
{:width=>500, :crop=>"scale"},
{:overlay=>{:font_family=>"Arial", :font_size=>80, :text=>"Flowers"}}
])
PHP:
cl_image_tag("flowers.jpg", array("transformation"=>array(
array("width"=>500, "crop"=>"scale"),
array("overlay"=>array("font_family"=>"Arial", "font_size"=>80, "text"=>"Flowers"))
)))
Python:
CloudinaryImage("flowers.jpg").image(transformation=[
{'width': 500, 'crop': "scale"},
{'overlay': {'font_family': "Arial", 'font_size': 80, 'text': "Flowers"}}
])
Node.js:
cloudinary.image("flowers.jpg", {transformation: [
{width: 500, crop: "scale"},
{overlay: {font_family: "Arial", font_size: 80, text: "Flowers"}}
]})
Java:
cloudinary.url().transformation(new Transformation()
.width(500).crop("scale").chain()
.overlay(new TextLayer().fontFamily("Arial").fontSize(80).text("Flowers"))).imageTag("flowers.jpg");
JS:
cloudinary.imageTag('flowers.jpg', {transformation: [
{width: 500, crop: "scale"},
{overlay: new cloudinary.TextLayer().fontFamily("Arial").fontSize(80).text("Flowers")}
]}).toHtml();
jQuery:
$.cloudinary.image("flowers.jpg", {transformation: [
{width: 500, crop: "scale"},
{overlay: new cloudinary.TextLayer().fontFamily("Arial").fontSize(80).text("Flowers")}
]})
React:
<Image publicId="flowers.jpg" >
<Transformation width="500" crop="scale" />
<Transformation overlay={{fontFamily: "Arial", fontSize: 80, text: "Flowers"}} />
</Image>
Vue.js:
<cld-image publicId="flowers.jpg" >
<cld-transformation width="500" crop="scale" />
<cld-transformation overlay={{fontFamily: "Arial", fontSize: 80, text: "Flowers"}} />
</cld-image>
Angular:
<cl-image public-id="flowers.jpg" >
<cl-transformation width="500" crop="scale">
</cl-transformation>
<cl-transformation overlay="text:Arial_80:Flowers">
</cl-transformation>
</cl-image>
.Net:
cloudinary.Api.UrlImgUp.Transform(new Transformation()
.Width(500).Crop("scale").Chain()
.Overlay(new TextLayer().FontFamily("Arial").FontSize(80).Text("Flowers"))).BuildImageTag("flowers.jpg")
Android:
MediaManager.get().url().transformation(new Transformation()
.width(500).crop("scale").chain()
.overlay(new TextLayer().fontFamily("Arial").fontSize(80).text("Flowers"))).generate("flowers.jpg");
iOS:
imageView.cldSetImage(cloudinary.createUrl().setTransformation(CLDTransformation()
.setWidth(500).setCrop("scale").chain()
.setOverlay("text:Arial_80:Flowers")).generate("flowers.jpg")!, cloudinary: cloudinary)
Like with image overlays, you can also determine the dimension and position of the text caption using the width, height, x, y and gravity parameters. The resulting caption is actually an image created on the fly and can be further manipulated like any other image uploaded to Cloudinary.
For example, adding the text string "Cool image" in the Times font with a size of 60 pixels at a distance of 20 pixels from the bottom of the image named flowers:
Ruby:
cl_image_tag("flowers.jpg", :transformation=>[
{:width=>500, :crop=>"scale"},
{:overlay=>{:font_family=>"Times", :font_size=>60, :text=>"Cool%20image"}, :gravity=>"south", :y=>20}
])
PHP:
cl_image_tag("flowers.jpg", array("transformation"=>array(
array("width"=>500, "crop"=>"scale"),
array("overlay"=>array("font_family"=>"Times", "font_size"=>60, "text"=>"Cool%20image"), "gravity"=>"south", "y"=>20)
)))
Python:
CloudinaryImage("flowers.jpg").image(transformation=[
{'width': 500, 'crop': "scale"},
{'overlay': {'font_family': "Times", 'font_size': 60, 'text': "Cool%20image"}, 'gravity': "south", 'y': 20}
])
Node.js:
cloudinary.image("flowers.jpg", {transformation: [
{width: 500, crop: "scale"},
{overlay: {font_family: "Times", font_size: 60, text: "Cool%20image"}, gravity: "south", y: 20}
]})
Java:
cloudinary.url().transformation(new Transformation()
.width(500).crop("scale").chain()
.overlay(new TextLayer().fontFamily("Times").fontSize(60).text("Cool%20image")).gravity("south").y(20)).imageTag("flowers.jpg");
JS:
cloudinary.imageTag('flowers.jpg', {transformation: [
{width: 500, crop: "scale"},
{overlay: new cloudinary.TextLayer().fontFamily("Times").fontSize(60).text("Cool%20image"), gravity: "south", y: 20}
]}).toHtml();
jQuery:
$.cloudinary.image("flowers.jpg", {transformation: [
{width: 500, crop: "scale"},
{overlay: new cloudinary.TextLayer().fontFamily("Times").fontSize(60).text("Cool%20image"), gravity: "south", y: 20}
]})
React:
<Image publicId="flowers.jpg" >
<Transformation width="500" crop="scale" />
<Transformation overlay={{fontFamily: "Times", fontSize: 60, text: "Cool%20image"}} gravity="south" y="20" />
</Image>
Vue.js:
<cld-image publicId="flowers.jpg" >
<cld-transformation width="500" crop="scale" />
<cld-transformation overlay={{fontFamily: "Times", fontSize: 60, text: "Cool%20image"}} gravity="south" y="20" />
</cld-image>
Angular:
<cl-image public-id="flowers.jpg" >
<cl-transformation width="500" crop="scale">
</cl-transformation>
<cl-transformation overlay="text:Times_60:Cool%20image" gravity="south" y="20">
</cl-transformation>
</cl-image>
.Net:
cloudinary.Api.UrlImgUp.Transform(new Transformation()
.Width(500).Crop("scale").Chain()
.Overlay(new TextLayer().FontFamily("Times").FontSize(60).Text("Cool%20image")).Gravity("south").Y(20)).BuildImageTag("flowers.jpg")
Android:
MediaManager.get().url().transformation(new Transformation()
.width(500).crop("scale").chain()
.overlay(new TextLayer().fontFamily("Times").fontSize(60).text("Cool%20image")).gravity("south").y(20)).generate("flowers.jpg");
iOS:
imageView.cldSetImage(cloudinary.createUrl().setTransformation(CLDTransformation()
.setWidth(500).setCrop("scale").chain()
.setOverlay("text:Times_60:Cool%20image").setGravity("south").setY(20)).generate("flowers.jpg")!, cloudinary: cloudinary)
Possible styling parameters for text overlays include:
| In SDK |
In URL |
Possible Values |
Additional Details |
| font_family |
[fontname] |
The name of any universally available font or the public ID of a raw, authenticated font in your account. |
Required.
For details on custom fonts, see Using custom fonts for text overlays. |
| font_size |
[pixelsize] |
Any integer. |
Required. |
| font_weight |
[weightvalue] |
- normal (default)
- bold
- thin
- light |
|
| font_style |
[stylevalue] |
- normal (default)
- italic |
|
| text_decoration |
[decorationvalue] |
- normal (default)
- underline
- strikethrough |
|
| text_align |
[alignmentvalue] |
- left (default)
- center
- right
- end
- start
- justify |
|
| stroke |
[strokevalue] |
- none (default)
- stroke
|
Whether to include an outline stroke. Set the color and weight of the stroke with the border parameter (bo in URLs). |
| letter_spacing |
letter_spacing_[value] |
Positive or negative integer or decimal value. |
The spacing between the letters, in pixels. |
| line_spacing |
line_spacing_[value] |
Positive or negative integer or decimal value. |
The spacing between multiple lines in pixels. |
| font_antialias |
antialias_[value] |
- none - Use a bi-level alpha mask
- gray - Perform single-color antialiasing. For example, using shades of gray for black text on a white background.
- subpixel - Perform antialiasing by taking advantage of the order of subpixel elements on devices such as LCD panels.
- fast - Some antialiasing is performed, but speed is prioritized over quality
- good - antialiasing that balances quality and performance
- best - Renders at the highest quality, sacrificing speed if necessary. |
When this parameter is not specified, the default antialiasing for the subsystem and target device are applied. |
| font_hinting |
hinting_[value] |
- none - Do not hint outlines.
- slight - Hint outlines slightly to improve contrast while retaining good fidelity to the original shapes.
- medium - Hint outlines with medium strength, providing a compromise between fidelity to the original shapes and contrast.
- full - Hint outlines to the maximize contrast. |
When this parameter is not specified, the default hint style for the font and target device are applied. |
The Cloudinary SDK helper methods support supplying the values as an array of mapped values or as a serialized string of values. For example in Ruby (other frameworks use similar syntax):
overlay: { text: 'Hello World', font_family: 'Arial', font_size: 18, font_weight: 'bold', font_style: 'italic', letter_spacing: 4 }
For example, to overlay the text string "Flowers" in Verdana bold with a size of 75 pixels, underlined, and with 14 pixels spacing between the letters: l_text:verdana_75_bold_underline_letter_spacing_14:Flowers.
Ruby:
cl_image_tag("flowers.jpg", :transformation=>[
{:width=>500, :crop=>"scale"},
{:overlay=>{:font_family=>"Verdana", :font_size=>75, :font_weight=>"bold", :text_decoration=>"underline", :letter_spacing=>14, :text=>"Flowers"}}
])
PHP:
cl_image_tag("flowers.jpg", array("transformation"=>array(
array("width"=>500, "crop"=>"scale"),
array("overlay"=>array("font_family"=>"Verdana", "font_size"=>75, "font_weight"=>"bold", "text_decoration"=>"underline", "letter_spacing"=>14, "text"=>"Flowers"))
)))
Python:
CloudinaryImage("flowers.jpg").image(transformation=[
{'width': 500, 'crop': "scale"},
{'overlay': {'font_family': "Verdana", 'font_size': 75, 'font_weight': "bold", 'text_decoration': "underline", 'letter_spacing': 14, 'text': "Flowers"}}
])
Node.js:
cloudinary.image("flowers.jpg", {transformation: [
{width: 500, crop: "scale"},
{overlay: {font_family: "Verdana", font_size: 75, font_weight: "bold", text_decoration: "underline", letter_spacing: 14, text: "Flowers"}}
]})
Java:
cloudinary.url().transformation(new Transformation()
.width(500).crop("scale").chain()
.overlay(new TextLayer().fontFamily("Verdana").fontSize(75).fontWeight("bold").textDecoration("underline").letterSpacing(14).text("Flowers"))).imageTag("flowers.jpg");
JS:
cloudinary.imageTag('flowers.jpg', {transformation: [
{width: 500, crop: "scale"},
{overlay: new cloudinary.TextLayer().fontFamily("Verdana").fontSize(75).fontWeight("bold").textDecoration("underline").letterSpacing(14).text("Flowers")}
]}).toHtml();
jQuery:
$.cloudinary.image("flowers.jpg", {transformation: [
{width: 500, crop: "scale"},
{overlay: new cloudinary.TextLayer().fontFamily("Verdana").fontSize(75).fontWeight("bold").textDecoration("underline").letterSpacing(14).text("Flowers")}
]})
React:
<Image publicId="flowers.jpg" >
<Transformation width="500" crop="scale" />
<Transformation overlay={{fontFamily: "Verdana", fontSize: 75, fontWeight: "bold", textDecoration: "underline", letterSpacing: 14, text: "Flowers"}} />
</Image>
Vue.js:
<cld-image publicId="flowers.jpg" >
<cld-transformation width="500" crop="scale" />
<cld-transformation overlay={{fontFamily: "Verdana", fontSize: 75, fontWeight: "bold", textDecoration: "underline", letterSpacing: 14, text: "Flowers"}} />
</cld-image>
Angular:
<cl-image public-id="flowers.jpg" >
<cl-transformation width="500" crop="scale">
</cl-transformation>
<cl-transformation overlay="text:Verdana_75_bold_underline_letter_spacing_14:Flowers">
</cl-transformation>
</cl-image>
.Net:
cloudinary.Api.UrlImgUp.Transform(new Transformation()
.Width(500).Crop("scale").Chain()
.Overlay(new TextLayer().FontFamily("Verdana").FontSize(75).FontWeight("bold").TextDecoration("underline").LetterSpacing(14).Text("Flowers"))).BuildImageTag("flowers.jpg")
Android:
MediaManager.get().url().transformation(new Transformation()
.width(500).crop("scale").chain()
.overlay(new TextLayer().fontFamily("Verdana").fontSize(75).fontWeight("bold").textDecoration("underline").letterSpacing(14).text("Flowers"))).generate("flowers.jpg");
iOS:
imageView.cldSetImage(cloudinary.createUrl().setTransformation(CLDTransformation()
.setWidth(500).setCrop("scale").chain()
.setOverlay("text:Verdana_75_bold_underline_letter_spacing_14:Flowers")).generate("flowers.jpg")!, cloudinary: cloudinary)
Text strings containing special characters need to be modified (escaped) for use with the text overlay feature. This is relevant for any special characters that would not be allowed “as is” in a valid URL path, as well as other special unicode characters. These text strings should be escaped using %-based UTF-8 encoding to ensure the text string is valid (for example, replace ? with %3F and use %20 for spaces between words). This encoding is done automatically when embedding images using the Cloudinary SDK helper methods and only needs to be done when manually adding the image delivery URL.
Additionally, the special characters comma (,) and percent sign (%) need to be double-escaped. Specifically, a comma would be added to a text overlay as %252C (and not just %2C). Similarly, use %25 to escape the percent sign of another code.
For example, the escaped URL code for the sunglasses emoji is %F0%9F%98%8E. To include this emoji in a text overlay, you must use double-escaping: l_text:Arial_80:Cool%25F0%259F%2598%258E:
You can control the color of the text overlay by adding the color property (co in URLs).
Opaque colors can be set as an RGB hex triplet (e.g., co_rgb:3e2222), a 3-digit RGB hex (e.g., co_rgb:777) or a named color (e.g., co_green). Cloudinary's client libraries also support a # shortcut for RGB (e.g., setting the color to #3e2222 which is then translated to co_rgb:3e2222). By default, if the color property is omitted then the text has a black color.
For example, adding the text string "Cool image" in Times bold with a size of 90 pixels at a distance of 80 pixels from the bottom of the image named flowers, in yellow text (FFFF00):
Ruby:
cl_image_tag("flowers.jpg", :transformation=>[
{:width=>500, :crop=>"scale"},
{:overlay=>{:font_family=>"Times", :font_size=>90, :font_weight=>"bold", :text=>"Cool%20image"}, :gravity=>"south", :y=>80, :color=>"#FFFF00"}
])
PHP:
cl_image_tag("flowers.jpg", array("transformation"=>array(
array("width"=>500, "crop"=>"scale"),
array("overlay"=>array("font_family"=>"Times", "font_size"=>90, "font_weight"=>"bold", "text"=>"Cool%20image"), "gravity"=>"south", "y"=>80, "color"=>"#FFFF00")
)))
Python:
CloudinaryImage("flowers.jpg").image(transformation=[
{'width': 500, 'crop': "scale"},
{'overlay': {'font_family': "Times", 'font_size': 90, 'font_weight': "bold", 'text': "Cool%20image"}, 'gravity': "south", 'y': 80, 'color': "#FFFF00"}
])
Node.js:
cloudinary.image("flowers.jpg", {transformation: [
{width: 500, crop: "scale"},
{overlay: {font_family: "Times", font_size: 90, font_weight: "bold", text: "Cool%20image"}, gravity: "south", y: 80, color: "#FFFF00"}
]})
Java:
cloudinary.url().transformation(new Transformation()
.width(500).crop("scale").chain()
.overlay(new TextLayer().fontFamily("Times").fontSize(90).fontWeight("bold").text("Cool%20image")).gravity("south").y(80).color("#FFFF00")).imageTag("flowers.jpg");
JS:
cloudinary.imageTag('flowers.jpg', {transformation: [
{width: 500, crop: "scale"},
{overlay: new cloudinary.TextLayer().fontFamily("Times").fontSize(90).fontWeight("bold").text("Cool%20image"), gravity: "south", y: 80, color: "#FFFF00"}
]}).toHtml();
jQuery:
$.cloudinary.image("flowers.jpg", {transformation: [
{width: 500, crop: "scale"},
{overlay: new cloudinary.TextLayer().fontFamily("Times").fontSize(90).fontWeight("bold").text("Cool%20image"), gravity: "south", y: 80, color: "#FFFF00"}
]})
React:
<Image publicId="flowers.jpg" >
<Transformation width="500" crop="scale" />
<Transformation overlay={{fontFamily: "Times", fontSize: 90, fontWeight: "bold", text: "Cool%20image"}} gravity="south" y="80" color="#FFFF00" />
</Image>
Vue.js:
<cld-image publicId="flowers.jpg" >
<cld-transformation width="500" crop="scale" />
<cld-transformation overlay={{fontFamily: "Times", fontSize: 90, fontWeight: "bold", text: "Cool%20image"}} gravity="south" y="80" color="#FFFF00" />
</cld-image>
Angular:
<cl-image public-id="flowers.jpg" >
<cl-transformation width="500" crop="scale">
</cl-transformation>
<cl-transformation overlay="text:Times_90_bold:Cool%20image" gravity="south" y="80" color="#FFFF00">
</cl-transformation>
</cl-image>
.Net:
cloudinary.Api.UrlImgUp.Transform(new Transformation()
.Width(500).Crop("scale").Chain()
.Overlay(new TextLayer().FontFamily("Times").FontSize(90).FontWeight("bold").Text("Cool%20image")).Gravity("south").Y(80).Color("#FFFF00")).BuildImageTag("flowers.jpg")
Android:
MediaManager.get().url().transformation(new Transformation()
.width(500).crop("scale").chain()
.overlay(new TextLayer().fontFamily("Times").fontSize(90).fontWeight("bold").text("Cool%20image")).gravity("south").y(80).color("#FFFF00")).generate("flowers.jpg");
iOS:
imageView.cldSetImage(cloudinary.createUrl().setTransformation(CLDTransformation()
.setWidth(500).setCrop("scale").chain()
.setOverlay("text:Times_90_bold:Cool%20image").setGravity("south").setY(80).setColor("#FFFF00")).generate("flowers.jpg")!, cloudinary: cloudinary)
You can also use a 4-digit or 8-digit RGBA hex quadruplet for the color, where the 4th hex value represents the alpha (opacity) value (e.g., co_rgb:3e222240 results in 25% opacity).
The example below uses the same text string "Cool image" in Times bold with a size of 90 pixels at a distance of 80 pixels from the bottom of the image named sample, in yellow text, but this time with an opacity of 50% (FFFF0080):
Ruby:
cl_image_tag("flowers.jpg", :transformation=>[
{:width=>500, :crop=>"scale"},
{:overlay=>{:font_family=>"Times", :font_size=>90, :font_weight=>"bold", :text=>"Cool%20image"}, :gravity=>"south", :y=>80, :color=>"#FFFF0080"}
])
PHP:
cl_image_tag("flowers.jpg", array("transformation"=>array(
array("width"=>500, "crop"=>"scale"),
array("overlay"=>array("font_family"=>"Times", "font_size"=>90, "font_weight"=>"bold", "text"=>"Cool%20image"), "gravity"=>"south", "y"=>80, "color"=>"#FFFF0080")
)))
Python:
CloudinaryImage("flowers.jpg").image(transformation=[
{'width': 500, 'crop': "scale"},
{'overlay': {'font_family': "Times", 'font_size': 90, 'font_weight': "bold", 'text': "Cool%20image"}, 'gravity': "south", 'y': 80, 'color': "#FFFF0080"}
])
Node.js:
cloudinary.image("flowers.jpg", {transformation: [
{width: 500, crop: "scale"},
{overlay: {font_family: "Times", font_size: 90, font_weight: "bold", text: "Cool%20image"}, gravity: "south", y: 80, color: "#FFFF0080"}
]})
Java:
cloudinary.url().transformation(new Transformation()
.width(500).crop("scale").chain()
.overlay(new TextLayer().fontFamily("Times").fontSize(90).fontWeight("bold").text("Cool%20image")).gravity("south").y(80).color("#FFFF0080")).imageTag("flowers.jpg");
JS:
cloudinary.imageTag('flowers.jpg', {transformation: [
{width: 500, crop: "scale"},
{overlay: new cloudinary.TextLayer().fontFamily("Times").fontSize(90).fontWeight("bold").text("Cool%20image"), gravity: "south", y: 80, color: "#FFFF0080"}
]}).toHtml();
jQuery:
$.cloudinary.image("flowers.jpg", {transformation: [
{width: 500, crop: "scale"},
{overlay: new cloudinary.TextLayer().fontFamily("Times").fontSize(90).fontWeight("bold").text("Cool%20image"), gravity: "south", y: 80, color: "#FFFF0080"}
]})
React:
<Image publicId="flowers.jpg" >
<Transformation width="500" crop="scale" />
<Transformation overlay={{fontFamily: "Times", fontSize: 90, fontWeight: "bold", text: "Cool%20image"}} gravity="south" y="80" color="#FFFF0080" />
</Image>
Vue.js:
<cld-image publicId="flowers.jpg" >
<cld-transformation width="500" crop="scale" />
<cld-transformation overlay={{fontFamily: "Times", fontSize: 90, fontWeight: "bold", text: "Cool%20image"}} gravity="south" y="80" color="#FFFF0080" />
</cld-image>
Angular:
<cl-image public-id="flowers.jpg" >
<cl-transformation width="500" crop="scale">
</cl-transformation>
<cl-transformation overlay="text:Times_90_bold:Cool%20image" gravity="south" y="80" color="#FFFF0080">
</cl-transformation>
</cl-image>
.Net:
cloudinary.Api.UrlImgUp.Transform(new Transformation()
.Width(500).Crop("scale").Chain()
.Overlay(new TextLayer().FontFamily("Times").FontSize(90).FontWeight("bold").Text("Cool%20image")).Gravity("south").Y(80).Color("#FFFF0080")).BuildImageTag("flowers.jpg")
Android:
MediaManager.get().url().transformation(new Transformation()
.width(500).crop("scale").chain()
.overlay(new TextLayer().fontFamily("Times").fontSize(90).fontWeight("bold").text("Cool%20image")).gravity("south").y(80).color("#FFFF0080")).generate("flowers.jpg");
iOS:
imageView.cldSetImage(cloudinary.createUrl().setTransformation(CLDTransformation()
.setWidth(500).setCrop("scale").chain()
.setOverlay("text:Times_90_bold:Cool%20image").setGravity("south").setY(80).setColor("#FFFF0080")).generate("flowers.jpg")!, cloudinary: cloudinary)
You can manually add multiple lines of text by separating each line of text with the newline character (%0A). For example, adding the text string "Cool image" in Verdana bold with a size of 50 pixels at a distance of 10 pixels from the left border of the image named flowers, where each word appears on a new line:
Ruby:
cl_image_tag("flowers.jpg", :transformation=>[
{:width=>500, :crop=>"scale"},
{:overlay=>{:font_family=>"Verdana", :font_size=>50, :font_weight=>"bold", :text=>"Cool%0Aimage"}, :gravity=>"west", :x=>10}
])
PHP:
cl_image_tag("flowers.jpg", array("transformation"=>array(
array("width"=>500, "crop"=>"scale"),
array("overlay"=>array("font_family"=>"Verdana", "font_size"=>50, "font_weight"=>"bold", "text"=>"Cool%0Aimage"), "gravity"=>"west", "x"=>10)
)))
Python:
CloudinaryImage("flowers.jpg").image(transformation=[
{'width': 500, 'crop': "scale"},
{'overlay': {'font_family': "Verdana", 'font_size': 50, 'font_weight': "bold", 'text': "Cool%0Aimage"}, 'gravity': "west", 'x': 10}
])
Node.js:
cloudinary.image("flowers.jpg", {transformation: [
{width: 500, crop: "scale"},
{overlay: {font_family: "Verdana", font_size: 50, font_weight: "bold", text: "Cool%0Aimage"}, gravity: "west", x: 10}
]})
Java:
cloudinary.url().transformation(new Transformation()
.width(500).crop("scale").chain()
.overlay(new TextLayer().fontFamily("Verdana").fontSize(50).fontWeight("bold").text("Cool%0Aimage")).gravity("west").x(10)).imageTag("flowers.jpg");
JS:
cloudinary.imageTag('flowers.jpg', {transformation: [
{width: 500, crop: "scale"},
{overlay: new cloudinary.TextLayer().fontFamily("Verdana").fontSize(50).fontWeight("bold").text("Cool%0Aimage"), gravity: "west", x: 10}
]}).toHtml();
jQuery:
$.cloudinary.image("flowers.jpg", {transformation: [
{width: 500, crop: "scale"},
{overlay: new cloudinary.TextLayer().fontFamily("Verdana").fontSize(50).fontWeight("bold").text("Cool%0Aimage"), gravity: "west", x: 10}
]})
React:
<Image publicId="flowers.jpg" >
<Transformation width="500" crop="scale" />
<Transformation overlay={{fontFamily: "Verdana", fontSize: 50, fontWeight: "bold", text: "Cool%0Aimage"}} gravity="west" x="10" />
</Image>
Vue.js:
<cld-image publicId="flowers.jpg" >
<cld-transformation width="500" crop="scale" />
<cld-transformation overlay={{fontFamily: "Verdana", fontSize: 50, fontWeight: "bold", text: "Cool%0Aimage"}} gravity="west" x="10" />
</cld-image>
Angular:
<cl-image public-id="flowers.jpg" >
<cl-transformation width="500" crop="scale">
</cl-transformation>
<cl-transformation overlay="text:Verdana_50_bold:Cool%0Aimage" gravity="west" x="10">
</cl-transformation>
</cl-image>
.Net:
cloudinary.Api.UrlImgUp.Transform(new Transformation()
.Width(500).Crop("scale").Chain()
.Overlay(new TextLayer().FontFamily("Verdana").FontSize(50).FontWeight("bold").Text("Cool%0Aimage")).Gravity("west").X(10)).BuildImageTag("flowers.jpg")
Android:
MediaManager.get().url().transformation(new Transformation()
.width(500).crop("scale").chain()
.overlay(new TextLayer().fontFamily("Verdana").fontSize(50).fontWeight("bold").text("Cool%0Aimage")).gravity("west").x(10)).generate("flowers.jpg");
iOS:
imageView.cldSetImage(cloudinary.createUrl().setTransformation(CLDTransformation()
.setWidth(500).setCrop("scale").chain()
.setOverlay("text:Verdana_50_bold:Cool%0Aimage").setGravity("west").setX(10)).generate("flowers.jpg")!, cloudinary: cloudinary)
Cloudinary also supports automatic multi-line text by defining a maximum width for the text string and adding the fit crop mode, which tells Cloudinary to automatically wrap the actual text content onto a new line once the width is reached. For example, to add a long text string in bold Neucha font with a size of 26 pixels to the flowers image, that wraps at a width of 400 pixels:
Ruby:
cl_image_tag("flowers.jpg", :transformation=>[
{:width=>500, :crop=>"scale"},
{:width=>400, :overlay=>{:font_family=>"Neucha", :font_size=>26, :font_weight=>"bold", :text=>"Lorem%20ipsum%20dolor%20sit%20amet%20consectetur%20adipisicing%20elit%20sed%20do%20eiusmod%20tempor%20incididunt%20ut%20labore%20et%20dolore%20magna%20aliqua.%20Ut%20enim%20ad%20minim%20veniam%20quis%20nostrud%20exercitation%20ullamco%20laboris%20nisi%20ut%20aliquip%20ex%20ea%20commodo%20consequat."}, :crop=>"fit"}
])
PHP:
cl_image_tag("flowers.jpg", array("transformation"=>array(
array("width"=>500, "crop"=>"scale"),
array("width"=>400, "overlay"=>array("font_family"=>"Neucha", "font_size"=>26, "font_weight"=>"bold", "text"=>"Lorem%20ipsum%20dolor%20sit%20amet%20consectetur%20adipisicing%20elit%20sed%20do%20eiusmod%20tempor%20incididunt%20ut%20labore%20et%20dolore%20magna%20aliqua.%20Ut%20enim%20ad%20minim%20veniam%20quis%20nostrud%20exercitation%20ullamco%20laboris%20nisi%20ut%20aliquip%20ex%20ea%20commodo%20consequat."), "crop"=>"fit")
)))
Python:
CloudinaryImage("flowers.jpg").image(transformation=[
{'width': 500, 'crop': "scale"},
{'width': 400, 'overlay': {'font_family': "Neucha", 'font_size': 26, 'font_weight': "bold", 'text': "Lorem%20ipsum%20dolor%20sit%20amet%20consectetur%20adipisicing%20elit%20sed%20do%20eiusmod%20tempor%20incididunt%20ut%20labore%20et%20dolore%20magna%20aliqua.%20Ut%20enim%20ad%20minim%20veniam%20quis%20nostrud%20exercitation%20ullamco%20laboris%20nisi%20ut%20aliquip%20ex%20ea%20commodo%20consequat."}, 'crop': "fit"}
])
Node.js:
cloudinary.image("flowers.jpg", {transformation: [
{width: 500, crop: "scale"},
{width: 400, overlay: {font_family: "Neucha", font_size: 26, font_weight: "bold", text: "Lorem%20ipsum%20dolor%20sit%20amet%20consectetur%20adipisicing%20elit%20sed%20do%20eiusmod%20tempor%20incididunt%20ut%20labore%20et%20dolore%20magna%20aliqua.%20Ut%20enim%20ad%20minim%20veniam%20quis%20nostrud%20exercitation%20ullamco%20laboris%20nisi%20ut%20aliquip%20ex%20ea%20commodo%20consequat."}, crop: "fit"}
]})
Java:
cloudinary.url().transformation(new Transformation()
.width(500).crop("scale").chain()
.width(400).overlay(new TextLayer().fontFamily("Neucha").fontSize(26).fontWeight("bold").text("Lorem%20ipsum%20dolor%20sit%20amet%20consectetur%20adipisicing%20elit%20sed%20do%20eiusmod%20tempor%20incididunt%20ut%20labore%20et%20dolore%20magna%20aliqua.%20Ut%20enim%20ad%20minim%20veniam%20quis%20nostrud%20exercitation%20ullamco%20laboris%20nisi%20ut%20aliquip%20ex%20ea%20commodo%20consequat.")).crop("fit")).imageTag("flowers.jpg");
JS:
cloudinary.imageTag('flowers.jpg', {transformation: [
{width: 500, crop: "scale"},
{width: 400, overlay: new cloudinary.TextLayer().fontFamily("Neucha").fontSize(26).fontWeight("bold").text("Lorem%20ipsum%20dolor%20sit%20amet%20consectetur%20adipisicing%20elit%20sed%20do%20eiusmod%20tempor%20incididunt%20ut%20labore%20et%20dolore%20magna%20aliqua.%20Ut%20enim%20ad%20minim%20veniam%20quis%20nostrud%20exercitation%20ullamco%20laboris%20nisi%20ut%20aliquip%20ex%20ea%20commodo%20consequat."), crop: "fit"}
]}).toHtml();
jQuery:
$.cloudinary.image("flowers.jpg", {transformation: [
{width: 500, crop: "scale"},
{width: 400, overlay: new cloudinary.TextLayer().fontFamily("Neucha").fontSize(26).fontWeight("bold").text("Lorem%20ipsum%20dolor%20sit%20amet%20consectetur%20adipisicing%20elit%20sed%20do%20eiusmod%20tempor%20incididunt%20ut%20labore%20et%20dolore%20magna%20aliqua.%20Ut%20enim%20ad%20minim%20veniam%20quis%20nostrud%20exercitation%20ullamco%20laboris%20nisi%20ut%20aliquip%20ex%20ea%20commodo%20consequat."), crop: "fit"}
]})
React:
<Image publicId="flowers.jpg" >
<Transformation width="500" crop="scale" />
<Transformation width="400" overlay={{fontFamily: "Neucha", fontSize: 26, fontWeight: "bold", text: "Lorem%20ipsum%20dolor%20sit%20amet%20consectetur%20adipisicing%20elit%20sed%20do%20eiusmod%20tempor%20incididunt%20ut%20labore%20et%20dolore%20magna%20aliqua.%20Ut%20enim%20ad%20minim%20veniam%20quis%20nostrud%20exercitation%20ullamco%20laboris%20nisi%20ut%20aliquip%20ex%20ea%20commodo%20consequat."}} crop="fit" />
</Image>
Vue.js:
<cld-image publicId="flowers.jpg" >
<cld-transformation width="500" crop="scale" />
<cld-transformation width="400" overlay={{fontFamily: "Neucha", fontSize: 26, fontWeight: "bold", text: "Lorem%20ipsum%20dolor%20sit%20amet%20consectetur%20adipisicing%20elit%20sed%20do%20eiusmod%20tempor%20incididunt%20ut%20labore%20et%20dolore%20magna%20aliqua.%20Ut%20enim%20ad%20minim%20veniam%20quis%20nostrud%20exercitation%20ullamco%20laboris%20nisi%20ut%20aliquip%20ex%20ea%20commodo%20consequat."}} crop="fit" />
</cld-image>
Angular:
<cl-image public-id="flowers.jpg" >
<cl-transformation width="500" crop="scale">
</cl-transformation>
<cl-transformation width="400" overlay="text:Neucha_26_bold:Lorem%20ipsum%20dolor%20sit%20amet%20consectetur%20adipisicing%20elit%20sed%20do%20eiusmod%20tempor%20incididunt%20ut%20labore%20et%20dolore%20magna%20aliqua.%20Ut%20enim%20ad%20minim%20veniam%20quis%20nostrud%20exercitation%20ullamco%20laboris%20nisi%20ut%20aliquip%20ex%20ea%20commodo%20consequat." crop="fit">
</cl-transformation>
</cl-image>
.Net:
cloudinary.Api.UrlImgUp.Transform(new Transformation()
.Width(500).Crop("scale").Chain()
.Width(400).Overlay(new TextLayer().FontFamily("Neucha").FontSize(26).FontWeight("bold").Text("Lorem%20ipsum%20dolor%20sit%20amet%20consectetur%20adipisicing%20elit%20sed%20do%20eiusmod%20tempor%20incididunt%20ut%20labore%20et%20dolore%20magna%20aliqua.%20Ut%20enim%20ad%20minim%20veniam%20quis%20nostrud%20exercitation%20ullamco%20laboris%20nisi%20ut%20aliquip%20ex%20ea%20commodo%20consequat.")).Crop("fit")).BuildImageTag("flowers.jpg")
Android:
MediaManager.get().url().transformation(new Transformation()
.width(500).crop("scale").chain()
.width(400).overlay(new TextLayer().fontFamily("Neucha").fontSize(26).fontWeight("bold").text("Lorem%20ipsum%20dolor%20sit%20amet%20consectetur%20adipisicing%20elit%20sed%20do%20eiusmod%20tempor%20incididunt%20ut%20labore%20et%20dolore%20magna%20aliqua.%20Ut%20enim%20ad%20minim%20veniam%20quis%20nostrud%20exercitation%20ullamco%20laboris%20nisi%20ut%20aliquip%20ex%20ea%20commodo%20consequat.")).crop("fit")).generate("flowers.jpg");
iOS:
imageView.cldSetImage(cloudinary.createUrl().setTransformation(CLDTransformation()
.setWidth(500).setCrop("scale").chain()
.setWidth(400).setOverlay("text:Neucha_26_bold:Lorem%20ipsum%20dolor%20sit%20amet%20consectetur%20adipisicing%20elit%20sed%20do%20eiusmod%20tempor%20incididunt%20ut%20labore%20et%20dolore%20magna%20aliqua.%20Ut%20enim%20ad%20minim%20veniam%20quis%20nostrud%20exercitation%20ullamco%20laboris%20nisi%20ut%20aliquip%20ex%20ea%20commodo%20consequat.").setCrop("fit")).generate("flowers.jpg")!, cloudinary: cloudinary)
To define a maximum height for the multi-line text add the height parameter: any text that does not fit within the space defined is cut and an ellipsis (...) is added to the end of the text string to indicate that the text was truncated. You can also set the text alignment and line spacing values to further control the text's appearance.
For example, to add a long text string in center aligned bold Times font with a size of 14 pixels to the envelope image, that wraps at a width of 200 pixels and is limited to a height of 150 pixels. The text is also rotated by 9 degrees and set 30 pixels from the north border to better align with the underlying image:
Ruby:
cl_image_tag("envelope.jpg", :transformation=>[
{:width=>300, :crop=>"scale"},
{:width=>200, :y=>30, :angle=>9, :height=>150, :gravity=>"north", :overlay=>{:font_family=>"Times", :font_size=>18, :font_weight=>"bold", :text_align=>"center", :text=>"Lorem%20ipsum%20dolor%20sit%20amet%20consectetur%20adipisicing%20elit%20sed%20do%20eiusmod%20tempor%20incididunt%20ut%20labore%20et%20dolore%20magna%20aliqua.%20Ut%20enim%20ad%20minim%20veniam%20quis%20nostrud%20exercitation%20ullamco%20laboris%20nisi%20ut%20aliquip%20ex%20ea%20commodo%20consequat."}, :crop=>"fit"}
])
PHP:
cl_image_tag("envelope.jpg", array("transformation"=>array(
array("width"=>300, "crop"=>"scale"),
array("width"=>200, "y"=>30, "angle"=>9, "height"=>150, "gravity"=>"north", "overlay"=>array("font_family"=>"Times", "font_size"=>18, "font_weight"=>"bold", "text_align"=>"center", "text"=>"Lorem%20ipsum%20dolor%20sit%20amet%20consectetur%20adipisicing%20elit%20sed%20do%20eiusmod%20tempor%20incididunt%20ut%20labore%20et%20dolore%20magna%20aliqua.%20Ut%20enim%20ad%20minim%20veniam%20quis%20nostrud%20exercitation%20ullamco%20laboris%20nisi%20ut%20aliquip%20ex%20ea%20commodo%20consequat."), "crop"=>"fit")
)))
Python:
CloudinaryImage("envelope.jpg").image(transformation=[
{'width': 300, 'crop': "scale"},
{'width': 200, 'y': 30, 'angle': 9, 'height': 150, 'gravity': "north", 'overlay': {'font_family': "Times", 'font_size': 18, 'font_weight': "bold", 'text_align': "center", 'text': "Lorem%20ipsum%20dolor%20sit%20amet%20consectetur%20adipisicing%20elit%20sed%20do%20eiusmod%20tempor%20incididunt%20ut%20labore%20et%20dolore%20magna%20aliqua.%20Ut%20enim%20ad%20minim%20veniam%20quis%20nostrud%20exercitation%20ullamco%20laboris%20nisi%20ut%20aliquip%20ex%20ea%20commodo%20consequat."}, 'crop': "fit"}
])
Node.js:
cloudinary.image("envelope.jpg", {transformation: [
{width: 300, crop: "scale"},
{width: 200, y: 30, angle: 9, height: 150, gravity: "north", overlay: {font_family: "Times", font_size: 18, font_weight: "bold", text_align: "center", text: "Lorem%20ipsum%20dolor%20sit%20amet%20consectetur%20adipisicing%20elit%20sed%20do%20eiusmod%20tempor%20incididunt%20ut%20labore%20et%20dolore%20magna%20aliqua.%20Ut%20enim%20ad%20minim%20veniam%20quis%20nostrud%20exercitation%20ullamco%20laboris%20nisi%20ut%20aliquip%20ex%20ea%20commodo%20consequat."}, crop: "fit"}
]})
Java:
cloudinary.url().transformation(new Transformation()
.width(300).crop("scale").chain()
.width(200).y(30).angle(9).height(150).gravity("north").overlay(new TextLayer().fontFamily("Times").fontSize(18).fontWeight("bold").textAlign("center").text("Lorem%20ipsum%20dolor%20sit%20amet%20consectetur%20adipisicing%20elit%20sed%20do%20eiusmod%20tempor%20incididunt%20ut%20labore%20et%20dolore%20magna%20aliqua.%20Ut%20enim%20ad%20minim%20veniam%20quis%20nostrud%20exercitation%20ullamco%20laboris%20nisi%20ut%20aliquip%20ex%20ea%20commodo%20consequat.")).crop("fit")).imageTag("envelope.jpg");
JS:
cloudinary.imageTag('envelope.jpg', {transformation: [
{width: 300, crop: "scale"},
{width: 200, y: 30, angle: 9, height: 150, gravity: "north", overlay: new cloudinary.TextLayer().fontFamily("Times").fontSize(18).fontWeight("bold").textAlign("center").text("Lorem%20ipsum%20dolor%20sit%20amet%20consectetur%20adipisicing%20elit%20sed%20do%20eiusmod%20tempor%20incididunt%20ut%20labore%20et%20dolore%20magna%20aliqua.%20Ut%20enim%20ad%20minim%20veniam%20quis%20nostrud%20exercitation%20ullamco%20laboris%20nisi%20ut%20aliquip%20ex%20ea%20commodo%20consequat."), crop: "fit"}
]}).toHtml();
jQuery:
$.cloudinary.image("envelope.jpg", {transformation: [
{width: 300, crop: "scale"},
{width: 200, y: 30, angle: 9, height: 150, gravity: "north", overlay: new cloudinary.TextLayer().fontFamily("Times").fontSize(18).fontWeight("bold").textAlign("center").text("Lorem%20ipsum%20dolor%20sit%20amet%20consectetur%20adipisicing%20elit%20sed%20do%20eiusmod%20tempor%20incididunt%20ut%20labore%20et%20dolore%20magna%20aliqua.%20Ut%20enim%20ad%20minim%20veniam%20quis%20nostrud%20exercitation%20ullamco%20laboris%20nisi%20ut%20aliquip%20ex%20ea%20commodo%20consequat."), crop: "fit"}
]})
React:
<Image publicId="envelope.jpg" >
<Transformation width="300" crop="scale" />
<Transformation width="200" y="30" angle="9" height="150" gravity="north" overlay={{fontFamily: "Times", fontSize: 18, fontWeight: "bold", textAlign: "center", text: "Lorem%20ipsum%20dolor%20sit%20amet%20consectetur%20adipisicing%20elit%20sed%20do%20eiusmod%20tempor%20incididunt%20ut%20labore%20et%20dolore%20magna%20aliqua.%20Ut%20enim%20ad%20minim%20veniam%20quis%20nostrud%20exercitation%20ullamco%20laboris%20nisi%20ut%20aliquip%20ex%20ea%20commodo%20consequat."}} crop="fit" />
</Image>
Vue.js:
<cld-image publicId="envelope.jpg" >
<cld-transformation width="300" crop="scale" />
<cld-transformation width="200" y="30" angle="9" height="150" gravity="north" overlay={{fontFamily: "Times", fontSize: 18, fontWeight: "bold", textAlign: "center", text: "Lorem%20ipsum%20dolor%20sit%20amet%20consectetur%20adipisicing%20elit%20sed%20do%20eiusmod%20tempor%20incididunt%20ut%20labore%20et%20dolore%20magna%20aliqua.%20Ut%20enim%20ad%20minim%20veniam%20quis%20nostrud%20exercitation%20ullamco%20laboris%20nisi%20ut%20aliquip%20ex%20ea%20commodo%20consequat."}} crop="fit" />
</cld-image>
Angular:
<cl-image public-id="envelope.jpg" >
<cl-transformation width="300" crop="scale">
</cl-transformation>
<cl-transformation width="200" y="30" angle="9" height="150" gravity="north" overlay="text:Times_18_bold_center:Lorem%20ipsum%20dolor%20sit%20amet%20consectetur%20adipisicing%20elit%20sed%20do%20eiusmod%20tempor%20incididunt%20ut%20labore%20et%20dolore%20magna%20aliqua.%20Ut%20enim%20ad%20minim%20veniam%20quis%20nostrud%20exercitation%20ullamco%20laboris%20nisi%20ut%20aliquip%20ex%20ea%20commodo%20consequat." crop="fit">
</cl-transformation>
</cl-image>
.Net:
cloudinary.Api.UrlImgUp.Transform(new Transformation()
.Width(300).Crop("scale").Chain()
.Width(200).Y(30).Angle(9).Height(150).Gravity("north").Overlay(new TextLayer().FontFamily("Times").FontSize(18).FontWeight("bold").TextAlign("center").Text("Lorem%20ipsum%20dolor%20sit%20amet%20consectetur%20adipisicing%20elit%20sed%20do%20eiusmod%20tempor%20incididunt%20ut%20labore%20et%20dolore%20magna%20aliqua.%20Ut%20enim%20ad%20minim%20veniam%20quis%20nostrud%20exercitation%20ullamco%20laboris%20nisi%20ut%20aliquip%20ex%20ea%20commodo%20consequat.")).Crop("fit")).BuildImageTag("envelope.jpg")
Android:
MediaManager.get().url().transformation(new Transformation()
.width(300).crop("scale").chain()
.width(200).y(30).angle(9).height(150).gravity("north").overlay(new TextLayer().fontFamily("Times").fontSize(18).fontWeight("bold").textAlign("center").text("Lorem%20ipsum%20dolor%20sit%20amet%20consectetur%20adipisicing%20elit%20sed%20do%20eiusmod%20tempor%20incididunt%20ut%20labore%20et%20dolore%20magna%20aliqua.%20Ut%20enim%20ad%20minim%20veniam%20quis%20nostrud%20exercitation%20ullamco%20laboris%20nisi%20ut%20aliquip%20ex%20ea%20commodo%20consequat.")).crop("fit")).generate("envelope.jpg");
iOS:
imageView.cldSetImage(cloudinary.createUrl().setTransformation(CLDTransformation()
.setWidth(300).setCrop("scale").chain()
.setWidth(200).setY(30).setAngle(9).setHeight(150).setGravity("north").setOverlay("text:Times_18_bold_center:Lorem%20ipsum%20dolor%20sit%20amet%20consectetur%20adipisicing%20elit%20sed%20do%20eiusmod%20tempor%20incididunt%20ut%20labore%20et%20dolore%20magna%20aliqua.%20Ut%20enim%20ad%20minim%20veniam%20quis%20nostrud%20exercitation%20ullamco%20laboris%20nisi%20ut%20aliquip%20ex%20ea%20commodo%20consequat.").setCrop("fit")).generate("envelope.jpg")!, cloudinary: cloudinary)
Instead of specifying the styling parameters every time you need to dynamically add a text caption to an image, you can use the Public ID of a text image created with the text method of the upload API. The same styles that were used to create the text image will also be dynamically applied to the text caption. The default text string of the text image is also used unless you provide a new text string, which can be useful if you don't want the text string to appear in the URL, or if the text string is very long.
For example, adding the text string "Stylish text" using the same styling applied in creating the text image named sample_text_style (Roboto font, 82 size, bold and red):
Ruby:
cl_image_tag("flowers.jpg", :transformation=>[
{:width=>500, :crop=>"scale"},
{:overlay=>{:public_id=>"sample_text_style", :text=>"Stylish%20text"}, :gravity=>"south"}
])
PHP:
cl_image_tag("flowers.jpg", array("transformation"=>array(
array("width"=>500, "crop"=>"scale"),
array("overlay"=>array("public_id"=>"sample_text_style", "text"=>"Stylish%20text"), "gravity"=>"south")
)))
Python:
CloudinaryImage("flowers.jpg").image(transformation=[
{'width': 500, 'crop': "scale"},
{'overlay': {'public_id': "sample_text_style", 'text': "Stylish%20text"}, 'gravity': "south"}
])
Node.js:
cloudinary.image("flowers.jpg", {transformation: [
{width: 500, crop: "scale"},
{overlay: {public_id: "sample_text_style", text: "Stylish%20text"}, gravity: "south"}
]})
Java:
cloudinary.url().transformation(new Transformation()
.width(500).crop("scale").chain()
.overlay(new TextLayer().text("Stylish%20text").publicId("sample_text_style")).gravity("south")).imageTag("flowers.jpg");
JS:
cloudinary.imageTag('flowers.jpg', {transformation: [
{width: 500, crop: "scale"},
{overlay: new cloudinary.TextLayer().text("Stylish%20text").publicId("sample_text_style"), gravity: "south"}
]}).toHtml();
jQuery:
$.cloudinary.image("flowers.jpg", {transformation: [
{width: 500, crop: "scale"},
{overlay: new cloudinary.TextLayer().text("Stylish%20text").publicId("sample_text_style"), gravity: "south"}
]})
React:
<Image publicId="flowers.jpg" >
<Transformation width="500" crop="scale" />
<Transformation overlay={{text: "Stylish%20text", publicId: "sample_text_style"}} gravity="south" />
</Image>
Vue.js:
<cld-image publicId="flowers.jpg" >
<cld-transformation width="500" crop="scale" />
<cld-transformation overlay={{text: "Stylish%20text", publicId: "sample_text_style"}} gravity="south" />
</cld-image>
Angular:
<cl-image public-id="flowers.jpg" >
<cl-transformation width="500" crop="scale">
</cl-transformation>
<cl-transformation overlay="text:sample_text_style:Stylish%20text" gravity="south">
</cl-transformation>
</cl-image>
.Net:
cloudinary.Api.UrlImgUp.Transform(new Transformation()
.Width(500).Crop("scale").Chain()
.Overlay(new TextLayer().Text("Stylish%20text").PublicId("sample_text_style")).Gravity("south")).BuildImageTag("flowers.jpg")
Android:
MediaManager.get().url().transformation(new Transformation()
.width(500).crop("scale").chain()
.overlay(new TextLayer().text("Stylish%20text").publicId("sample_text_style")).gravity("south")).generate("flowers.jpg");
iOS:
imageView.cldSetImage(cloudinary.createUrl().setTransformation(CLDTransformation()
.setWidth(500).setCrop("scale").chain()
.setOverlay("text:sample_text_style:Stylish%20text").setGravity("south")).generate("flowers.jpg")!, cloudinary: cloudinary)
By default, only universally available fonts are supported for text overlays. However, if you want to use a non-standard font, you can upload it to your Cloudinary account as a raw, authenticated file and then specify the font's full public_id (including extension) as the font for your overlay:
Cloudinary::Uploader.upload("AlexBrush-Regular.ttf",
resource_type: 'raw',
type: 'authenticated',
public_id: 'AlexBrush-Regular.ttf')
Ruby:
cl_image_tag("fireworks.jpg", :overlay=>{:font_family=>"ttf", :font_size=>100, :text=>"Happy%20New%20Year%20%202017%20"}, :color=>"white", :gravity=>"north_west", :x=>30, :y=>30)
PHP:
cl_image_tag("fireworks.jpg", array("overlay"=>array("font_family"=>"ttf", "font_size"=>100, "text"=>"Happy%20New%20Year%20%202017%20"), "color"=>"white", "gravity"=>"north_west", "x"=>30, "y"=>30))
Python:
CloudinaryImage("fireworks.jpg").image(overlay={'font_family': "ttf", 'font_size': 100, 'text': "Happy%20New%20Year%20%202017%20"}, color="white", gravity="north_west", x=30, y=30)
Node.js:
cloudinary.image("fireworks.jpg", {overlay: {font_family: "ttf", font_size: 100, text: "Happy%20New%20Year%20%202017%20"}, color: "white", gravity: "north_west", x: 30, y: 30})
Java:
cloudinary.url().transformation(new Transformation().overlay(new TextLayer().fontFamily("ttf").fontSize(100).text("Happy%20New%20Year%20%202017%20")).color("white").gravity("north_west").x(30).y(30)).imageTag("fireworks.jpg");
JS:
cloudinary.imageTag('fireworks.jpg', {overlay: new cloudinary.TextLayer().fontFamily("ttf").fontSize(100).text("Happy%20New%20Year%20%202017%20"), color: "white", gravity: "north_west", x: 30, y: 30}).toHtml();
jQuery:
$.cloudinary.image("fireworks.jpg", {overlay: new cloudinary.TextLayer().fontFamily("ttf").fontSize(100).text("Happy%20New%20Year%20%202017%20"), color: "white", gravity: "north_west", x: 30, y: 30})
React:
<Image publicId="fireworks.jpg" >
<Transformation overlay={{fontFamily: "ttf", fontSize: 100, text: "Happy%20New%20Year%20%202017%20"}} color="white" gravity="north_west" x="30" y="30" />
</Image>
Vue.js:
<cld-image publicId="fireworks.jpg" >
<cld-transformation overlay={{fontFamily: "ttf", fontSize: 100, text: "Happy%20New%20Year%20%202017%20"}} color="white" gravity="north_west" x="30" y="30" />
</cld-image>
Angular:
<cl-image public-id="fireworks.jpg" >
<cl-transformation overlay="text:AlexBrush-Regular.ttf_100:Happy%20New%20Year%20%202017%20" color="white" gravity="north_west" x="30" y="30">
</cl-transformation>
</cl-image>
.Net:
cloudinary.Api.UrlImgUp.Transform(new Transformation().Overlay(new TextLayer().FontFamily("ttf").FontSize(100).Text("Happy%20New%20Year%20%202017%20")).Color("white").Gravity("north_west").X(30).Y(30)).BuildImageTag("fireworks.jpg")
Android:
MediaManager.get().url().transformation(new Transformation().overlay(new TextLayer().fontFamily("ttf").fontSize(100).text("Happy%20New%20Year%20%202017%20")).color("white").gravity("north_west").x(30).y(30)).generate("fireworks.jpg");
iOS:
imageView.cldSetImage(cloudinary.createUrl().setTransformation(CLDTransformation().setOverlay("text:AlexBrush-Regular.ttf_100:Happy%20New%20Year%20%202017%20").setColor("white").setGravity("north_west").setX(30).setY(30)).generate("fireworks.jpg")!, cloudinary: cloudinary)
Custom font guidelines:
.ttf and .otf font types are supported.- Custom fonts must be uploaded as raw, authenticated files.
- If your custom font is stored in a folder other than the root folder, specify the path using colons as separators. For example:
folder1:folder2:myfont.ttf.
- Make sure to include the file extension when referencing the
public_id of the raw file. The extension must be specified in lower-case letters.
- To make use of bold or italic font styles, upload separate font files for each emphasis style and specify the relevant file in the overlay transformation.
- A custom font is available only to the specific account or sub-account where it was uploaded.
- Underscores are not supported in custom font names. When uploading the font as a raw file, make sure the
public_id does not include an underscore.
- As with any resource you upload to Cloudinary, it is your responsibility to make sure you have the necessary license and redistribution rights for any custom fonts you use.
3D lookup tables (3D LUTs) are used to map one color space to another. They can be used to adjust colors, contrast, and/or saturation, so that you can correct contrast, fix a camera’s inability to see a particular color shade, or give a final finished look or a particular style to your image.
After uploading a .3dl file to your account as a raw file, you can apply it to any image using the lut property of the overlay parameter ( l_lut: in URLs), followed by the LUT file name (including the .3dl extension).
Below you can see the laydybug_top.jpg image file in it's original color, compared to the video with different LUT files applied. Below these is the code for applying one of the LUTs.
Original
with 'iwltbap_sedona' LUT
with 'iwltbap_aspen' LUT
Ruby:
cl_image_tag("ladybug_top.jpg", :overlay=>"lut:iwltbap_aspen.3dl")
PHP:
cl_image_tag("ladybug_top.jpg", array("overlay"=>"lut:iwltbap_aspen.3dl"))
Python:
CloudinaryImage("ladybug_top.jpg").image(overlay="lut:iwltbap_aspen.3dl")
Node.js:
cloudinary.image("ladybug_top.jpg", {overlay: "lut:iwltbap_aspen.3dl"})
Java:
cloudinary.url().transformation(new Transformation().overlay(new Layer().publicId("lut:iwltbap_aspen.3dl"))).imageTag("ladybug_top.jpg");
JS:
cloudinary.imageTag('ladybug_top.jpg', {overlay: new cloudinary.Layer().publicId("lut:iwltbap_aspen.3dl")}).toHtml();
jQuery:
$.cloudinary.image("ladybug_top.jpg", {overlay: new cloudinary.Layer().publicId("lut:iwltbap_aspen.3dl")})
React:
<Image publicId="ladybug_top.jpg" >
<Transformation overlay="lut:iwltbap_aspen.3dl" />
</Image>
Vue.js:
<cld-image publicId="ladybug_top.jpg" >
<cld-transformation overlay="lut:iwltbap_aspen.3dl" />
</cld-image>
Angular:
<cl-image public-id="ladybug_top.jpg" >
<cl-transformation overlay="lut:iwltbap_aspen.3dl">
</cl-transformation>
</cl-image>
.Net:
cloudinary.Api.UrlImgUp.Transform(new Transformation().Overlay(new Layer().PublicId("lut:iwltbap_aspen.3dl"))).BuildImageTag("ladybug_top.jpg")
Android:
MediaManager.get().url().transformation(new Transformation().overlay(new Layer().publicId("lut:iwltbap_aspen.3dl"))).generate("ladybug_top.jpg");
iOS:
imageView.cldSetImage(cloudinary.createUrl().setTransformation(CLDTransformation().setOverlay("lut:iwltbap_aspen.3dl")).generate("ladybug_top.jpg")!, cloudinary: cloudinary)
Multiple overlays, text captions and underlays can be added as chained transformations to an image. The following example adds both an image overlay and a text caption to the image named sample as follows:
- An overlay of an image called
couple, cropped to an ellipse that only includes the detected faces.
- An overlay of an image called
cloudinary_icon with a relative width of 80% of the base image and an opacity of 50% and a brightness of 100.
- The text string "Sample image" in Impact bold font with a size of 40 pixels at a distance of 20 pixels from the bottom of the base image.
URL:
https://res.cloudinary.com/demo/image/upload/l_couple/c_crop,g_faces,w_120,h_150/r_max/fl_layer_apply,g_north_east/l_cloudinary_icon,w_0.8,fl_relative,o_50,e_brightness:100/l_text:impact_40_bold:Sample image,g_south,y_20/sample.jpg Ruby:
cl_image_tag("sample.jpg", :transformation=>[
{:overlay=>"couple"},
{:gravity=>"faces", :width=>120, :height=>150, :crop=>"crop"},
{:radius=>"max"},
{:flags=>"layer_apply", :gravity=>"north_east"},
{:overlay=>"cloudinary_icon", :width=>0.8, :flags=>"relative", :opacity=>50, :effect=>"brightness:100"},
{:overlay=>{:font_family=>"impact", :font_size=>40, :font_weight=>"bold", :text=>"Sample%20image"}, :gravity=>"south", :y=>20}
])
PHP:
cl_image_tag("sample.jpg", array("transformation"=>array(
array("overlay"=>"couple"),
array("gravity"=>"faces", "width"=>120, "height"=>150, "crop"=>"crop"),
array("radius"=>"max"),
array("flags"=>"layer_apply", "gravity"=>"north_east"),
array("overlay"=>"cloudinary_icon", "width"=>0.8, "flags"=>"relative", "opacity"=>50, "effect"=>"brightness:100"),
array("overlay"=>array("font_family"=>"impact", "font_size"=>40, "font_weight"=>"bold", "text"=>"Sample%20image"), "gravity"=>"south", "y"=>20)
)))
Python:
CloudinaryImage("sample.jpg").image(transformation=[
{'overlay': "couple"},
{'gravity': "faces", 'width': 120, 'height': 150, 'crop': "crop"},
{'radius': "max"},
{'flags': "layer_apply", 'gravity': "north_east"},
{'overlay': "cloudinary_icon", 'width': 0.8, 'flags': "relative", 'opacity': 50, 'effect': "brightness:100"},
{'overlay': {'font_family': "impact", 'font_size': 40, 'font_weight': "bold", 'text': "Sample%20image"}, 'gravity': "south", 'y': 20}
])
Node.js:
cloudinary.image("sample.jpg", {transformation: [
{overlay: "couple"},
{gravity: "faces", width: 120, height: 150, crop: "crop"},
{radius: "max"},
{flags: "layer_apply", gravity: "north_east"},
{overlay: "cloudinary_icon", width: "0.8", flags: "relative", opacity: 50, effect: "brightness:100"},
{overlay: {font_family: "impact", font_size: 40, font_weight: "bold", text: "Sample%20image"}, gravity: "south", y: 20}
]})
Java:
cloudinary.url().transformation(new Transformation()
.overlay(new Layer().publicId("couple")).chain()
.gravity("faces").width(120).height(150).crop("crop").chain()
.radius("max").chain()
.flags("layer_apply").gravity("north_east").chain()
.overlay(new Layer().publicId("cloudinary_icon")).width(0.8).flags("relative").opacity(50).effect("brightness:100").chain()
.overlay(new TextLayer().fontFamily("impact").fontSize(40).fontWeight("bold").text("Sample%20image")).gravity("south").y(20)).imageTag("sample.jpg");
JS:
cloudinary.imageTag('sample.jpg', {transformation: [
{overlay: new cloudinary.Layer().publicId("couple")},
{gravity: "faces", width: 120, height: 150, crop: "crop"},
{radius: "max"},
{flags: "layer_apply", gravity: "north_east"},
{overlay: new cloudinary.Layer().publicId("cloudinary_icon"), width: "0.8", flags: "relative", opacity: 50, effect: "brightness:100"},
{overlay: new cloudinary.TextLayer().fontFamily("impact").fontSize(40).fontWeight("bold").text("Sample%20image"), gravity: "south", y: 20}
]}).toHtml();
jQuery:
$.cloudinary.image("sample.jpg", {transformation: [
{overlay: new cloudinary.Layer().publicId("couple")},
{gravity: "faces", width: 120, height: 150, crop: "crop"},
{radius: "max"},
{flags: "layer_apply", gravity: "north_east"},
{overlay: new cloudinary.Layer().publicId("cloudinary_icon"), width: "0.8", flags: "relative", opacity: 50, effect: "brightness:100"},
{overlay: new cloudinary.TextLayer().fontFamily("impact").fontSize(40).fontWeight("bold").text("Sample%20image"), gravity: "south", y: 20}
]})
React:
<Image publicId="sample.jpg" >
<Transformation overlay="couple" />
<Transformation gravity="faces" width="120" height="150" crop="crop" />
<Transformation radius="max" />
<Transformation flags="layer_apply" gravity="north_east" />
<Transformation overlay="cloudinary_icon" width="0.8" flags="relative" opacity="50" effect="brightness:100" />
<Transformation overlay={{fontFamily: "impact", fontSize: 40, fontWeight: "bold", text: "Sample%20image"}} gravity="south" y="20" />
</Image>
Vue.js:
<cld-image publicId="sample.jpg" >
<cld-transformation overlay="couple" />
<cld-transformation gravity="faces" width="120" height="150" crop="crop" />
<cld-transformation radius="max" />
<cld-transformation flags="layer_apply" gravity="north_east" />
<cld-transformation overlay="cloudinary_icon" width="0.8" flags="relative" opacity="50" effect="brightness:100" />
<cld-transformation overlay={{fontFamily: "impact", fontSize: 40, fontWeight: "bold", text: "Sample%20image"}} gravity="south" y="20" />
</cld-image>
Angular:
<cl-image public-id="sample.jpg" >
<cl-transformation overlay="couple">
</cl-transformation>
<cl-transformation gravity="faces" width="120" height="150" crop="crop">
</cl-transformation>
<cl-transformation radius="max">
</cl-transformation>
<cl-transformation flags="layer_apply" gravity="north_east">
</cl-transformation>
<cl-transformation overlay="cloudinary_icon" width="0.8" flags="relative" opacity="50" effect="brightness:100">
</cl-transformation>
<cl-transformation overlay="text:impact_40_bold:Sample%20image" gravity="south" y="20">
</cl-transformation>
</cl-image>
.Net:
cloudinary.Api.UrlImgUp.Transform(new Transformation()
.Overlay(new Layer().PublicId("couple")).Chain()
.Gravity("faces").Width(120).Height(150).Crop("crop").Chain()
.Radius("max").Chain()
.Flags("layer_apply").Gravity("north_east").Chain()
.Overlay(new Layer().PublicId("cloudinary_icon")).Width(0.8).Flags("relative").Opacity(50).Effect("brightness:100").Chain()
.Overlay(new TextLayer().FontFamily("impact").FontSize(40).FontWeight("bold").Text("Sample%20image")).Gravity("south").Y(20)).BuildImageTag("sample.jpg")
Android:
MediaManager.get().url().transformation(new Transformation()
.overlay(new Layer().publicId("couple")).chain()
.gravity("faces").width(120).height(150).crop("crop").chain()
.radius("max").chain()
.flags("layer_apply").gravity("north_east").chain()
.overlay(new Layer().publicId("cloudinary_icon")).width(0.8).flags("relative").opacity(50).effect("brightness:100").chain()
.overlay(new TextLayer().fontFamily("impact").fontSize(40).fontWeight("bold").text("Sample%20image")).gravity("south").y(20)).generate("sample.jpg");
iOS:
imageView.cldSetImage(cloudinary.createUrl().setTransformation(CLDTransformation()
.setOverlay("couple").chain()
.setGravity("faces").setWidth(120).setHeight(150).setCrop("crop").chain()
.setRadius("max").chain()
.setFlags("layer_apply").setGravity("north_east").chain()
.setOverlay("cloudinary_icon").setWidth(0.8).setFlags("relative").setOpacity(50).setEffect("brightness:100").chain()
.setOverlay("text:impact_40_bold:Sample%20image").setGravity("south").setY(20)).generate("sample.jpg")!, cloudinary: cloudinary)
Advanced transformations
In addition to the commonly used transformation options described on this page, the following pages describe a variety of advanced transformation options:
The Image Transformations Reference table provides a comprehensive list of all parameters available for manipulating images.
The Media delivery guide shows how to control the way your media is delivered with Cloudinary URLs, including optimization and responsive images.
Original image
Default crop
Auto-gravity
Auto-gravity
Original
Original
Original
Original
q_80 (80.3KB)
q_auto:best (65.9KB)
q_auto:good (56.9KB)
q_auto:eco (45.0KB)
q_auto:low (35.0KB)
Original (296KB)
q_80 (223KB)
q_auto:best (226KB)
q_auto:good (156KB)
q_auto:eco (97.5KB)
q_auto:low (87.5KB)
Original blue bag
Blues recolored to maroon shades
Original
default red color at 20% strength
red, blue, yellow at 100% strength
equalized, mutli-color, 80%, adjusted gradients
al_dente
athena
audrey
aurora
daguerre
eucalyptus
fes
frost
hairspray
hokusai
incognito
linen
peacock
primavera
quartz
red_rock
refresh
sizzle
sonnet
ukulele
zorro
Original
with 'iwltbap_sedona' LUT
with 'iwltbap_aspen' LUT
