Android image manipulation

Overview

After you or your users have uploaded image assets to Cloudinary, you can deliver them via dynamic URLs. You can include instructions in your dynamic URLs that tell Cloudinary to manipulate your assets using a set of transformation parameters. All manipulations are performed automatically in the cloud and your transformed assets are automatically optimized before they are routed through a fast CDN to the end user for optimal user experience.

For example, you can resize and crop, add overlay images, blur or pixelate faces, apply a large variety of special effects and filters, and apply settings to optimize your images and to deliver them responsively.

Cloudinary's Android library simplifies the generation of transformation URLs, for easy embedding of assets in your Android application.

See also: Android video manipulation

Generate image URLs

Use the url method of the MediaManager class to generate an image URL.

String url = MediaManager.get().url().generate("sample.jpg")

The code above returns the following string:

https://res.cloudinary.com/demo/image/upload/sample.jpg

Add Transformations

You can add transformations to your url method by defining them with the Transformation class and then applying them with the transformation method of the MediaManager class.

Transformation tr = new Transformation();
tr.crop("fit").width(100);      // "c_fit,w_100"
String url = MediaManager.get().url().transformation(tr).generate("mypic.jpg")

Chaining Transformations

You can also chain transformations together (each transformation is applied to the result of the previous transformation):

Transformation tr = new Transformation();
tr.width(10).crop('fit').chain().angle(15)     // "c_fit,w_10/a_15"

For example, the following code crops the image to 150x150, rounds the corners, applies a sepia effect, adds text to the top center of the resized image, and then rotates the entire result by 20 degrees.

String url = MediaManager.get().url().transformation(new Transformation()
   .height(150).width(150).crop("crop").effect("sepia").radius(20).chain()
   .overlay(new TextLayer()
      .fontFamily("Arial").fontSize(60).text("This is my picture"))
   .gravity("north").y(20).chain()
   .angle(20))
   .generate("mypic.jpg")

For more information and examples of image transformations, see Applying common image transformations.

Download images

The dynamic URL returned from the url method can be easily used with most of the popular download libraries. For example:

// Glide (https://github.com/bumptech/glide): 
ImageView imageView = (ImageView) findViewById(R.id.my_image_view);
GlideApp.with(this).load(MediaManager.get().url().generate("sample.jpg")).into(imageView);

// Fresco (https://github.com/facebook/fresco):
Uri uri = Uri.parse(MediaManager.get().url().generate("sample.jpg"));
SimpleDraweeView draweeView = (SimpleDraweeView) findViewById(R.id.my_image_view);
draweeView.setImageURI(uri);

// Picasso (https://square.github.io/picasso):
ImageView imageView = (ImageView) findViewById(R.id.my_image_view);
Picasso.with(context).load(MediaManager.get().url().generate("sample.jpg")).into(imageView);

Apply common image transformations

This section provides an overview and examples of the following commonly used image transformation features, along with links to more detailed documentation on these features:

• Resizing and cropping
• Converting to another image format
• Applying image effects and filters
• Adding text and image overlays
• Image optimizations

Keep in mind that this section is only intended to introduce you to the basics of using image transformations with Android.

For comprehensive explanations of how to implement a wide variety of transformations, see Image transformations. For a full list of all supported image transformations and their usage, see the Image transformation reference.

Resizing and cropping

There are a variety of different ways to resize and/or crop your images, and to control the area of the image that is preserved during a crop.

The following example uses the fill cropping method to generate and deliver an image that completely fills the requested 250x250 size while retaining the original aspect ratio. It uses face detection gravity to ensure that all the faces in the image are retained and centered when the image is cropped:

MediaManager.get().url().transformation(new Transformation().width(250).height(250).gravity("faces").crop("fill")).generate("family_bench.jpg");

Original image Fill cropping with 'faces' gravity

For details on all resizing and cropping options, see resizing and cropping images

Converting to another image format

You can deliver any image uploaded to Cloudinary in essentially any image format. There are two main ways to convert and deliver in another format:

• Specify the image's public ID with the desired extension.
• Explicitly set the desired format using the fetchFormat parameter.

For example:

Deliver a .jpg file in .gif format by specifying the new file extension:

MediaManager.get().url().generate("sample.gif");

Deliver a .jpg file in .gif format by specifying the fetchFormat parameter:

MediaManager.get().url().transformation(new Transformation().width(350).crop("scale")).format("gif").generate("cloud_castle.jpg");

For more details see Image format conversion

Applying image effects and filters

You can select from a large selection of image effects, enhancements, and filters to apply to your images. The available effects include a variety of color balance and level effects, tinting, blurring, pixelating, sharpening, automatic improvement effects, artistic filters, image and text overlays, distortion and shape changing effects, outlines, backgrounds, shadows, and more.

For example, the code below applies a cartoonify effect, rounding corners effect, and background color effect (and then scales the image down to a height of 300 pixels).

MediaManager.get().url().transformation(new Transformation()
  .effect("cartoonify").chain()
  .radius("max").chain()
  .effect("outline:100").color("lightblue").chain()
  .background("lightblue").chain()
  .height(300).crop("scale")).generate("actor.jpg");

For more details on the available image effects and filters, see Applying image effects and filters

Adding text and image overlays

You can add images and text as overlays on your main image. You can apply the same types of transformations on your overlay images as you can with any image and you can use gravity settings or x and y coordinates to control the location of the overlays. You can also apply a variety of transformations on text, such color, font, size, rotation, and more.

For example, the code below overlays a couple's photo on a mug image. The overlay photo is cropped using face detection with adjusted color saturation and a vignette effect applied. The word love is added in a pink, fancy font and rotated to fit the design. A balloon graphic is also added. Additionally, the final image is cropped and the corners are rounded.

MediaManager.get().url().transformation(new Transformation()
  .width(400).height(250).gravity("south").crop("fill").chain()
  .overlay(new Layer().publicId("nice_couple")).width(1.3).height(1.3).gravity("faces").flags("region_relative").crop("crop").chain()
  .effect("saturation:50").chain()
  .effect("vignette").chain()
  .flags("layer_apply").width(100).radius("max").gravity("center").y(20).x(-20).crop("scale").chain()
  .overlay(new Layer().publicId("balloon")).height(55).chain()
  .effect("hue:-20").angle(5).chain()
  .flags("layer_apply").x(30).y(5).chain()
  .overlay(new TextLayer().fontFamily("Cookie").fontSize(40).fontWeight("bold").text("Love")).effect("colorize").color("#f08").chain()
  .angle(20).flags("layer_apply").x(-45).y(44).chain()
  .width(300).height(250).x(30).crop("crop").chain()
  .radius(60)).generate("coffee_cup.jpg");

Image optimizations

By default, Cloudinary automatically performs certain optimizations on all transformed images. There are also a number of additional features that enable you to further optimize the images you use in your Android application. These include optimizations to image quality, format, and size, among others.

For example, you can use the auto value for the fetchFormat and quality attributes to automatically deliver the image in the format and quality that minimize file size while meeting the required quality level. Below, these two parameters are applied, resulting in a 50% file size reduction (1.4MB vs. 784KB) with no visible change in quality.

MediaManager.get().url().transformation(new Transformation().quality("auto").fetchFormat("auto")).generate("pond_reflect.jpg");

For an in-depth review of the many ways you can optimize your images, see Image optimization

Responsive images

Responsive design is a method of providing an optimal viewing experience to users, tailored to their device, window size, orientation, and resolution. An app that is designed responsively adapts its layout to the viewing environment, resizing and moving elements dynamically and based on the properties of the device where the app is displayed.

When it comes to images, a responsively designed app should not just send the highest resolution image and then use client-side resizing to display the image on the various devices: that would be a significant waste of bandwidth for users on small, low-resolution displays. The best solution is to prepare an image in various resolutions and sizes, and then deliver the image with the most appropriate resolution, based on the device's resolution and the available dimensions to avoid wasting bandwidth or load time. Cloudinary can help reduce the complexity of this task with dynamic image transformations. You can simply build image URLs with any image width and height based on the specific device resolution and window size. This means you don't have to pre-create the images; the dynamic resizing takes place on-the-fly as needed.

Use the MediaManager's responsiveUrl method to generate a dynamic image URL based on the exact dimensions needed for the image according to a specified ImageView element. In addition to the image's PublicId, you then pass the ImageView element and a ResponsiveUrl.Callback() to the generate method. After the image URL for the specified ImageView size has been generated, you can use any image download library to fetch the image and update the element.

When the responsiveUrl method runs, it retrieves the exact available dimensions for the ImageView element and then rounds up the height and width for the image to the nearest step (100 by default). For example, if the exact width of the ImageView element is 284 pixels, the requested width is rounded up to 300 pixels. This prevents too many image versions being generated and reduces cache hits for subsequent requests from other devices. The next time any image view requiring 201-300 pixels requests the same image, the existing one is delivered directly from the CDN cache.

The responsiveUrl method accepts 4 parameters as follows:

• autoWidth: Boolean - Adjust image width according to the available ImageView width
• autoHeight: Boolean - Adjust image height according to the available ImageWidth height
• cropMode: String - The crop mode to apply when adjusting the image
• gravity: String - The location in the image to be used as the focus for the transformation

Instead of specifying the 4 parameters individually, you can also pass one of the following presets:

• AUTO_FILL: Adjusts both height and width of the image, and crops the image to fill the ImageView while retaining the aspect-ratio and using automatic gravity to determine which part of the image is kept and which is cropped, if necessary. (This is a shortcut for: true, true, "fill", "auto".)
• FIT: Adjusts both height and width of the image, and resizes the image to completely fit within the bounds of the ImageView while retaining the aspect-ratio. The whole image will be shown. (This is a shortcut for: true, true, "fit", "center".)

For example, to generate the responsiveUrl for the sample image, automatically resized to fill the available width and height:

MediaManager.get().responsiveUrl(AUTO_FILL)
    .generate("sample", imageView, new ResponsiveUrl.Callback() {
      @Override
      public void onUrlReady(Url url) {
        // Use your favorite image download library to fetch the image, picasso example:
        Picasso.with(context).load(url.generate()).into(imageView);
      }
    });

Which is equivalent to:

 MediaManager.get().responsiveUrl(true, true, "fill", "auto")
    .generate("sample", imageView, new ResponsiveUrl.Callback() {
      @Override
      public void onUrlReady(Url url) {
       // Use your favorite image download library to fetch the image, picasso example:
       Picasso.with(context).load(url.generate()).into(imageView);
      }
    });

The default values for the responsive calculation can be overridden by calling the stepSize, minDimension and/or maxDimension methods and passing the new values (default values are 100, 100 and 2000 respectively).

For example, to set the step size to every 200 pixels and limit the dimensions to between 200 and 1000 pixels:

MediaManager.get().responsiveUrl(AUTO_FILL)
    .stepSize(200)
    .minDimension(200)
    .maxDimension(1000)
    .generate("sample", imageView, new ResponsiveUrl.Callback() {
      @Override
      public void onUrlReady(Url url) {
        // Use your favorite image download library to fetch the image, picasso example:
        Picasso.with(context).load(url.generate()).into(imageView);
      }
    });

Additionally, instead of passing only the PublicId, you can pass any complex Cloudinary dynamic URL, including transformation components. The responsive transformation is chained after everything else as the last component. For example, to generate an HTTPS responsive url, including a transformation to rotate the image by 30 degrees, add a blur effect, and convert the image to WebP:

Url baseUrl = MediaManager.get().url();
baseUrl.secure(true).transformation(new Transformation().angle(30).effect("blur", 50).fetchFormat("webp"));
MediaManager.get().responsiveUrl(AUTO_FILL)
    .generate(baseUrl, imageView, new ResponsiveUrl.Callback() {
      @Override
      public void onUrlReady(Url url) {
         // Use your favorite image download library to fetch the image, picasso example:
         Picasso.with(context).load(url.generate()).into(imageView);
      }
    });