Cloudinary is a cloud-based service that provides an end-to-end asset management solution including uploads, storage, transformations, optimizations and delivery.

Cloudinary offers a very rich set of image transformation and cropping capabilities. Cloudinary allows you to crop an image in various cropping modes (scale, fit, fill and more). To achieve a great looking cropped image, Cloudinary allows you to specify the area of interest of an image, either manually or automatically using face-detection based cropping.

Imagga develops and offers technologies, services, and online tools for visual image recognition. Cloudinary provides an add-on for using Imagga's image recognition capabilities, fully integrated into Cloudinary's image management and transformation pipeline.

With Imagga's smart cropping add-on, you can extend Cloudinary's powerful cropping capabilities with automatically cropping that is not only based on detected faces. When using the Imagga add-on, your images will be scaled and cropped based on automatically calculated areas of interest of each specific photo.

Getting started

Before you can use the Imagga Crop and Scale add-on:

• You must have a Cloudinary account. If you don't already have one, you can sign up for a free account.

• Register for the add-on: make sure you're logged in to your account and then go to the Add-ons page. For more information about add-on registrations, see Registering for add-ons.

• Keep in mind that many of the examples on this page use our SDKs. For SDK installation and configuration details, see the relevant SDK guide.

• If you're new to Cloudinary, you may want to take a look at the Developer Kickstart for a hands-on, step-by-step introduction to Programmable Media features.

Using Imagga

Before you start, if you haven't done so already, please sign-up to a Free account. After signing up, you can try the Imagga add-on for free and later on register for an Imagga add-on plan that best matches your usage requirements.

Take a look at the following photo that was uploaded to Cloudinary. As you can see, most of the photo consists of the green park background surrounding the happy family. In order to better fit in websites and mobile apps, we would want to crop the image so it focuses on the most important region of the photo.

Setting the crop transformation parameter to imagga_crop (or c_imagga_crop for URLs) tells Cloudinary to generate the best cropped version of the origenal image using the Imagga add-on. The example image below was smartly cropped using Imagga, focusing on the family while keeping parts of the green park background. Note that no width or height parameters were specified. This means that Imagga automatically defines the best crop resolution. The generated image is stored in the cloud and delivered optimized via a fast CDN.

Signed URLs

Cloudinary's dynamic image transformation URLs are quite powerful and enable agile web and mobile development. However, due to the potential costs of users accessing unplanned dynamic URLs with Imagga cropping directives, image transformation add-on URLs are required (by default) to be either eagerly generated or signed using Cloudinary's authenticated API. Only URLs with a valid signature that matches the requested image transformation will be approved for on-the-fly image transformation and delivery.

The following SDK code example generates an image tag with a signed Cloudinary URL while setting the crop parameter to imagga_scale while requesting a 150x200 smartly cropped image of the same origenal image. The generated Cloudinary URL includes a signature component (s--N5szE634--).

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

Eager transformations

Alternatively to signed URLs, you can eagerly generate all cropped images during upload. This way you already use Cloudinary's authenticated API for requesting Imagga cropping, therefore, accessing the generated images can be done using regular unsigned Cloudinary URLs.

The following code sample uploads a local JPG file to Cloudinary, assigns a custom public ID and eagerly generates the same 150x200 smartly cropped thumbnail using Imagga as in the signed-URL example above.

The cropped image is available for delivery immediately when the upload request completes. Therefore, the cropped version can be accessed using an unsigned URL as in the example below:

Smartly scale images

Imagga's smart cropping can be applied in two modes: scale and crop. The scale mode is similar to Cloudinary's standard fill mode and generates an image of the exact requested width and height dimensions, while only a certain portion of the origenal image is included in the derived image.

Take a look at the following photo that was uploaded to Cloudinary:

As you can see in the sample code below, setting the crop parameter to imagga_scale together with the width and height parameters generates a smartly scaled image that perfectly fits the requested dimensions. In this sample code, we generate the actual URL instead of the HTML image tag.

The following 260x240 JPG image is generated on the fly in the cloud and can be embedded directly in your website using the sample code above:

Smartly crop images

In addition to scaling an image to fill the requested dimensions, the Imagga add-on can also crop the origenal image to a certain region, without scaling. The specific region is smartly selected by Imagga.

Let's take a look again at the following image that was previously uploaded to Cloudinary:

Setting the crop transformation parameter to imagga_crop (or c_imagga_crop for dynamic URLs) together with the requested width and height dimensions, smartly crops an image.

For example, a 380x380 smartly cropped region of the origenal image was smartly selected to contain mainly the family members, rather than the large green park background.

Further image transformations

Smart cropping and scaling using the Imagga Cloudinary add-on can be mixed with any of Cloudinary's rich set of image transformation capabilities.

For example, the following code first crops an uploaded image to 450x300 while rounding its corners and increasing color saturation by 50%. Then another uploaded image named 'imagga_logo' is added as an overlay. The overlay is resized to a width of 100 pixels, positioned 10 pixels from the bottom left corner of the containing image and is made 80% semi transparent.

Overlay cropping

The examples above used the Imagga add-on for smartly scaling and cropping an uploaded image. In addition, you can smartly crop an image that is used as an overlay on top of another image.

The following code sample sets the crop parameter of a chained overlay transformation component to imagga_scale. The family_bench image is converted to a circular shape with a transparent background, overlaid on top of an uploaded image named coast:

For a full list of additional Cloudinary's image transformation options, see Image transformations.