Kotlin media transformations (Beta)

After you or your users have uploaded media assets to Cloudinary, you can deliver them via dynamic URLs. You can include instructions in your dynamic URLs that tell Cloudinary to transform your assets using a set of transformation actions. All transformations 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 or concatenate videos, blur or pixelate faces, apply a large variety of special effects and filters, and apply settings to optimize your media and to deliver them responsively.

Cloudinary's Kotlin SDK simplifies the generation of transformation URLs for easy embedding of assets in your Kotlin application.

Syntax Overview

The Kotlin SDK provides a simpler and more enhanced developer experience when compared with existing Cloudinary SDKs:

  • The SDK supports an action-based syntax, designed to make building delivery URLs and transformations more logical and discoverable.
  • When compiled to the final delivery URL, each action represents a different transformation component.
  • Allows discovering the available options from within your development environment, and ensures that only options that are supported can be used together.

Kotlin syntax overview

  • Action: An Action represents a directive to Cloudinary on how to transform a specific aspect of an asset (e.g., effect or resize).
  • ActionType: The ActionType defines the specific Action to apply (e.g., effect(Effect.blur{}) or resize(Resize.crop{})).
  • Qualifier: Qualifiers further define how to apply an Action (e.g., strength qualifies the effect(Effect.blur{}) Action with a value of strength(50)).

The output of each Action is a complete transformation component (separated by slashes) in the URL. For example, the syntax example above would generate a URL similar to the following:

Copy to clipboard
https://res.cloudinary.com/demo/image/upload/e_blur:100/mypic.jpg

Deliver and transform images

You can deliver your media using direct URL-building directives, and then adding them to your image or video view.

Direct URL building

To build an image or video URL, use the cloudinary.media helper method. This will generate a URL based on the media type identified by adding the resourceType parameter. You can also explicitly define the media type by using the cloudinary.image or cloudinary.video helper methods. You can pass in your transformations as shown in the examples below:

Copy to clipboard
cloudinary.media{ 
  publicId("sample")
  resize(Resize.fill {
      width(100)
      height(150)
  })
}
// Output: "https://res.cloudinary.com/demo/image/upload/c_fill,h_150,w_100/sample.jpg"
Copy to clipboard
cloudinary.media{
  publicId("sample_spreadsheet.xls")
  resourceType("raw")
}
// Output: "https://res.cloudinary.com/demo/raw/upload/sample_spreadsheet.xls"

Building transformations

Building transformations with the Cloudinary Kotlin SDK is made simpler thanks to new "builders" and Cloudinary's DSL.

Here's a simple example of creating a new transformation:

Copy to clipboard
private val myTransformation = transformation {
  resize(scale {
    width(150)
    height(150)
  })
  effect(Effect.sepia())
}

This transformation can then be applied when building a URL:

Copy to clipboard
cloudinary.media{
  publicId("sample")
  transformation(myTransformation)
}

In the above example resize and effect are "Actions", scale and Effect.sepia() are the "ActionTypes" and width(150) and height(150) are the "qualifiers".

Combining transformations

Cloudinary supports powerful transformations. You can even combine multiple transformations together as part of a single transformation request, e.g. crop an image and add a border. In certain cases you may want to perform additional transformations on the result of the previous transformation request.

To support multiple transformations in a transformation URL, you can include multiple transformation components, each separated by a '/'. Each transformation component is applied to the result of the previous one. In Kotlin, applying multiple transformations is achieved by simply adding the next action to the transformation. The following example first crops the original image to a specific set of custom coordinates and then transforms the result so it fills a 130x100 rectangle:

Copy to clipboard
cloudinary.media{
    publicId("brown_sheep")
    resize(Resize.crop{
      width(300)
      height(200)
      x(355)
      y(410)
    })
    resize(Resize.fill{
      width(130)
      height(100)
    })
}

Simple chaining example

The following example applies 4 chained transformations: custom cropping to 300x200, fill to 130x100, rotate by 20 degrees and then scale to 50%:

Copy to clipboard
cloudinary.media{
    publicId("brown_sheep")
    resize(Resize.crop {
        width(300)
        height(200)
        x(355)
        y(410)
    })
    resize(Resize.fill {
        width(130)
        height(100)
    })
    rotate(angle(20))
    resize(Resize.scale {
        width(0.5)
    })
}

More complex chaining example

For more information on image transformations, see Apply common image transformations.

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:

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

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.

Copy to clipboard
cloudinary.media(
    publicId("family_bench.jpg")
    resize(Resize.fill {
      width(750)
      height(750)
      gravity(Gravity.faces())
    })
}
Original image before face recognition cropping Original image Fill cropping with 'faces' gravity 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 three main ways to convert and deliver in another format:

  • Specifying the image's public ID with the desired extension.
  • Explicitly set the desired format using the fetch_format parameter.
  • Use the auto fetch_format to instruct Cloudinary to deliver the image in the most optimized format for each browser that requests it.

For example:

Deliver a .jpg file in .png format:

Copy to clipboard
cloudinary.media{
    publicId("sample")
    format(Format.png())
}

Let Cloudinary select the optimal format for each browser. For example, in Chrome, this image delivers in .webp format:

Copy to clipboard
cloudinary.media{
    publicId("cloud_castle")
    format(Format.auto())
}

For more details see Image format support.

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 crops and pads the image down to a height of 300 pixels).

Copy to clipboard
cloudinary.media{
    publicId("actor.jpg")
    effect(Effect.cartoonify())
    roundCorners(RoundCorners.max())
    outline{
        width(100)
        color(Color.LIGHTBLUE)
    }
    background(Color.LIGHTBLUE))
    resize(Resize.pad {
        height(300)
    })
}

An image with several transformation effects

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 as 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.

Copy to clipboard
cloudinary.media{
    publicId("coffee_cup")
    resize(Resize.fill {
        width(400)
        height(250)
        gravity(Gravity.south())
    })
    overlay(Source.image("nice_couple")) {
        transformation {
            resize(Resize.crop {
                width(1.3)
                height(1.3)
                gravity(Gravity.faces())
                resizeMode(ResizeMode.regionRelative())
            })
            adjust(Adjust.saturation(50))
            effect(Effect.vignette())
            roundCorners(RoundCorners.max())
            resize(Resize.scale {
                width(100)
            })
        }
        position {
            y(20)
            x(-20)
            gravity(Gravity.center())
        }
    }
    overlay(Source.image("balloon")) {
        transformation {
            resize(Resize.scale {
                height(55)
            })
            adjust(Adjust.hue(-20))
            angle(5)
        }
        position{
            x(30)
            y(5)
        }
    }
    overlay(Source.text("Love") {
        fontFamily("Cookie")
        fontSize(40)
        style {
            fontWeight(FontWeight.BOLD)
        }
    })
    {
        transformation {
            effect(Effect.colorize {
                color("#f08")
            })
            rotate(Rotate.angle(20))
        }
        position {
            x(-45)
            y(44)
        }

    }
    resize(Resize.crop {
        width(300)
        height(250)
        x(30)
    })
    roundCorners(RoundCorners.radius(60))
}

An image with many transformations and overlays applied

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 application. These include optimizations to image quality, format, and size, among others.

For example, you can use the auto value for the fetch_format 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.

Copy to clipboard
cloudinary.media{
    publicId("pond_reflect")
    format(Format.auto())
    quality(Quality.auto())
}

50% file size optimization using auto format and auto quality features

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

✔️ Feedback sent!