Imagga Crop and Scale Add-on
Overview
Cloudinary is a cloud-based service that provides an end-to-end image management solution including uploads, storage, manipulations, optimizations and delivery.
Cloudinary offers a very rich set of image manipulation 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 manipulation 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.
Using Imagga
Before you start, if you haven't done so already, please sign-up to a free Cloudinary account. After signing up, you can try the Imagga add-on for free and later on subscribe to an Imagga add-on plan that best matches your usage requirements.
To simplify the add-on integration, you can use Cloudinary's client libraries for: Ruby on Rails, Python & Django, PHP, Node.js, jQuery, AngularJS, Java, .NET, iOS, Android and Scala.
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 original 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 manipulation 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, we request that you sign your image manipulation URLs or eagerly generate the requested derived images using Cloudinary's authenticated API.
The following code example generates an image tag with a signed Cloudinary URL by setting the sign_url parameter to true. This time setting the crop parameter to imagga_scale while requesting a 150x200 smartly cropped image of the same original image.
cl_image_tag("family_bench.jpg", :crop => "imagga_scale", :width => 150, :height => 200, :sign_url => true)
<?php echo cl_image_tag("family_bench.jpg", array("crop" => "imagga_scale", "width" => 150, "height" => 200, "sign_url" => true)); ?>
cloudinary.CloudinaryImage("family_bench.jpg").image( crop = "imagga_scale", width = 150, height = 200, sign_url = True)
cloudinary.image("family_bench.jpg", { crop: "imagga_scale", width: 150, height: 200, sign_url: true });
cloudinary.url().transformation( new Transformation().crop("imagga_scale"). width(150).height(200)).signed(true).imageTag("family_bench.jpg");
As you can see in the example below, the generated Cloudinary URL includes a signature component ('s--N5szE634--'). Only URLs with a valid signature that matches the requested image manipulation will be approved for on-the-fly image manipulation and delivery.
For more details regarding signed URLs, see the following blog post: On-the-fly image manipulations secured with signed 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.
Cloudinary::Uploader.upload("local_file.jpg", :public_id => "family_bench", :eager => { :crop => "imagga_scale", :width => 150, :height => 200 })
\Cloudinary\Uploader::upload("local_file.jpg", array( "public_id" => "family_bench", "eager" => array( "crop" => "imagga_scale", "width" => 150, "height" => 200 ) ));
cloudinary.uploader.upload("local_file.jpg", public_id = "family_bench", eager = { 'crop': "imagga_scale", 'width': 150, 'height': 200 })
cloudinary.uploader.upload("local_file.jpg", function(result) { console.log(result); }, { public_id: "family_bench", eager: { crop: "imagga_scale", width: 150, height: 200 }});
cloudinary.uploader().upload("local_file.jpg", ObjectUtils.asMap("public_id", "family_bench", "eager", Arrays.asList( new Transformation().crop("imagga_scale").width(150).height(200))));
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 original 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.
cloudinary_url("sample_van.jpg", :crop => "imagga_scale", :width => 260, :height => 240, :sign_url => true)
<?php echo cloudinary_url("sample_van.jpg", array("crop" => "imagga_scale", "width" => 260, "height" => 240, "sign_url" => true)); ?>
cloudinary.CloudinaryImage("sample_van.jpg").build_url( crop = "imagga_scale", width = 260, height = 240, sign_url = True)
cloudinary.url("sample_van.jpg", { crop: "imagga_scale", width: 260, height: 240, sign_url: true });
cloudinary.url().transformation( new Transformation().crop("imagga_scale"). width(260).height(240)).signed(true).generate("sample_van.jpg");
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 original 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.
The following code sample generated an HTML image tag with a Cloudinary manipulation URL of a 380x380 smartly cropped version of the original image:
cl_image_tag("family_bench.jpg", :crop => "imagga_crop", :width => 380, :height => 380, :sign_url => true)
<?php echo cl_image_tag("family_bench.jpg", array("crop" => "imagga_crop", "width" => 380, "height" => 380, "sign_url" => true)); ?>
cloudinary.CloudinaryImage("family_bench.jpg"). image(crop = "imagga_crop", width = 380, height = 380, sign_url = True)
cloudinary.image("family_bench.jpg", { crop: "imagga_crop", width: 380, height: 380, sign_url: true });
cloudinary.url().transformation( new Transformation().crop("imagga_crop"). width(380).height(380)).signed(true).imageTag("family_bench.jpg");
The generated dynamic delivery URL and the cropped image appear below. As you can see, the cropped 380x380 region was smartly selected to contain mainly the family members, rather than the large green park background.
Further image manipulations
Smart cropping and scaling using the Imagga Cloudinary add-on can be mixed with any of Cloudinary's rich set of image manipulation 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.
cl_image_tag("family_bench.jpg", :transformation => [ { :crop => "imagga_crop", :width => 450, :height => 300, :radius => 20, :effect => "saturation:50" }, { :overlay => "imagga_logo", :width => 100, :x => 10, :y => 10, :gravity => :south_west, :opacity => 80 }], :sign_url => true)
<?php echo cl_image_tag("family_bench.jpg", array( "transformation" => array( array( "crop" => "imagga_crop", "width" => 450, "height" => 300, "radius" => 20, "effect" => "saturation:50" ), array( "overlay" => "imagga_logo", "width" => 100, "x" => 10, "y" => 10, "gravity" => "south_west", "opacity" => 80 )), "sign_url" => true)); ?>
cloudinary.CloudinaryImage("family_bench.jpg").image( transformation = [ { 'crop': "imagga_crop", 'width': 450, 'height': 300, 'radius': 20, 'effect': "saturation:50" }, { 'overlay': "imagga_logo", 'width': 100, 'x': 10, 'y': 10, 'gravity': "south_west", 'opacity': 80 }], sign_url = True)
cloudinary.image("family_bench.jpg", { transformation: [ { crop: "imagga_crop", width: 450, height: 300, radius: 20, effect: "saturation:50" }, { overlay: "imagga_logo", width: 100, x: 10, y: 10, gravity: "south_west", opacity: 80 }], sign_url: true });
cloudinary.url().transformation( new Transformation().crop("imagga_crop"). width(450).height(300).radius(20).effect("saturation:50").chain(). overlay("imagga_logo").width(100).x(10).y(10).gravity("south_west").opacity(80)). signed(true).imageTag("family_bench.jpg");
The following dynamic manipulation URL generates and delivers the combined cropped and overlayed image:
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.
cl_image_tag("coast.jpg", :transformation => [ { :width => 400, :crop => :scale }, { :overlay => "family_bench.png", :crop => "imagga_scale", :width => 150, :height => 150, :radius => :max }], :sign_url => true)
<?php echo cl_image_tag("coast.jpg", array( "transformation" => array( array( "width" => 400, "crop" => "scale" ), array( "overlay" => "family_bench.png", "crop" => "imagga_scale", "width" => 150, "height" => 150, "radius" => "max" )), "sign_url" => true)); ?>
cloudinary.CloudinaryImage("coast.jpg").image( transformation = [ { 'width': 400, 'crop': "scale" }, { 'overlay': "family_bench.png", 'crop': "imagga_scale", 'width': 150, 'width': 150, 'radius': "max" }], sign_url = True)
cloudinary.image("coast.jpg", { transformation: [ { width: 400, crop: "scale" }, { overlay: "family_bench.png", crop: "imagga_scale", width: 150, width: 150, radius: "max" }], sign_url: true });
cloudinary.url().transformation( new Transformation().width(400).crop("scale").chain(). overlay("family_bench.png").crop("imagga_scale").width(150).height(150).radius("max")). signed(true).imageTag("coast.jpg");
The 'family_bench' image is converted to a circular shape with a transparent background, overlayed on top of an uploaded image named 'coast':
For a full list of additional Cloudinary's image manipulation options, see Image transformations.