uCrop — an Android library for clipping images

We develop lots of different Android apps at Yalantis, and our experience shows that almost every application we deal with needs image cropping functionality. Image cropping can be used for various purposes, from ordinary adjustment of user profile images to more complex features that involve aspect ratio cropping and flexible image transformations.

Since we want to provide all our customers with the best set of tools for image editing functionality, we decided to create uCrop, an image cropping library for Android.

You might be wondering why we couldn’t just use one of the existing solutions for image cropping for Android. After all, you can find lots of them on Github and on the Android Arsenal. But here is the thing: none of these solutions could satisfy our requirements. Let’s take a quick look at the most popular open-source image cropping libraries and explain why they don’t quite fit the bill.

1. SoundCloud cropping library

I’ve successfully used SoundCloud’s library on several projects, but there are still a couple of issues with it that make me sad.

To start with, you operate with a crop frame and not with an image itself. This causes some pain when you need to crop a small area of an image, and it feels wrong from the user experience point of view. I was sure Instagram taught us some good UX lessons, and the movable crop frames have died out.

Also, the SoundCloud cropping library doesn’t allow us to do any rotations. Come on, guys! Everyone knows that there are hundreds of “magic” Android phones that put wrong EXIF information inside photos (thankfully, we have CWAC to clear this mess up). Furthermore, there are millions of users who want to be able to rotate images (and not only by 90°).

Last but not least, aspect ratio cannot be changed using the SoundCloud library. Of course, if you just need to get a square image for a profile photo you can do it without any problems. But there are lots of other more interesting shapes for profile pictures that you won’t be able to implement using this library.

2. Edmodo Cropper

Edmodo Cropper is quite similar to the SoundCloud library, and has some of the same drawbacks. However, this library supports dynamically changing the crop frame aspect ratio. It also has guidelines and a method for rotating images (only a method, however, so you need to figure out a gesture detection or some sort of a spinner to control the gestures on your own).

3. Scissors

Scissors is a new library, and I was so excited to see it recently in an Android Weekly issue. But my excitement dissipated within 5 minutes. Here is a quote from the blog post about Scissors:

“…we researched existing solutions. None of them fulfilled the requirements we needed so we decided to build our own.”

A praiseworthy approach, indeed. But in fact, we again have another library that cannot rotate images and change aspect ratio dynamically. Scissors, though, has integrations with popular image libraries such as Picasso, Glide, and Universal Image Loader. I hope Scissors gets more useful features in the following versions.

Scissors is a new library, and I was so excited to see it recently in an Android Weekly issue. But my excitement dissipated within 5 minutes. Here is a quote from the blog post about Scissors:

“…we researched existing solutions. None of them fulfilled the requirements we needed so we decided to build our own.”

A praiseworthy approach, indeed. But in fact, we again have another library that cannot rotate images and change aspect ratio dynamically. Scissors, though, has integrations with popular image libraries such as Picasso, Glide, and Universal Image Loader. I hope Scissors gets more useful features in the following versions.

After analysing the drawbacks of the existing libraries, we decided to create our own library with gesture support and a neat UX.

uCrop is an Android library that allows you to clip images for further use. uCrop’s key features include:

• scaling images
• rotating images
• changing crop aspect ratio
• supporting touch gestures: scroll (pan) image with one finger, rotate image with two fingers, pinch to zoom, double tap to zoom
• out-of-the-box Activity with functional design, neat widgets for more precise image rotation and scaling, and a set of pre-defined common aspect ratios (1:1, 4:3, 3:4, 2:3, 3:2, 16:9, 9:16 + aspect ratio of the original image).

uCrop has a builder-type interface for initialization and for setting a proper configuration in your app. While the library itself requires a minimum of API level 10, the sample works with API level 15+.

1. Include the uCrop library as a local project library.

compile 'com.yalantis:ucrop:[latest version]'

2. The uCrop configuration is created using the builder pattern.

UCrop.of(sourceUri, destinationUri)
   .withAspectRatio(16, 9)
   .withMaxResultSize(maxWidth, maxHeight)
   .start(context);

3. Override the onActivityResult method and handle it with uCrop.

@Override
public void onActivityResult(int requestCode, int resultCode, Intent data) {
   if (resultCode == RESULT_OK && requestCode == UCrop.REQUEST_CROP) {
       final Uri resultUri = UCrop.getOutput(data);
   } else if (resultCode == UCrop.RESULT_ERROR) {
       final Throwable cropError = UCrop.getError(data);
   }
}

How can you customize uCrop?

You can change the following settings:

• compression format (e.g. PNG, JPEG, WEBP).
• compression quality [0 – 100] (PNG, which is lossless, will ignore the quality setting)
• support for simultaneous gestures
• the maximum size for a Bitmap that is decoded from the source Uri and used within the crop view (if you want to override default behaviour).
• and more to come (e.g. color palette)

In our other article, we share our experience building uCrop.