Android-Image-Cropper

Image Cropping Library for Android, optimised for Camera / Gallery.

1,213

249

1,213

View on GitHub

Top Related Projects

uCrop

11,849

Image Cropping Library for Android

Android-Image-Cropper

6,389

Image Cropping Library for Android, optimized for Camera / Gallery.

android-crop

4,537

Android library project for cropping images

SimpleCropView

2,479

A simple image cropping library for Android.

Quick Overview

Android-Image-Cropper is an Android library for cropping images. It provides a customizable UI for selecting and cropping images within Android applications. The library offers a simple yet powerful interface for developers to integrate image cropping functionality into their apps.

Pros

Easy integration with minimal setup required
Highly customizable UI and cropping options
Supports both programmatic and XML-based implementation
Actively maintained with regular updates and bug fixes

Cons

Limited to Android platform only
May have a learning curve for complex customizations
Some users report occasional issues with specific Android versions or devices
Dependency on other libraries may increase app size

Code Examples

Basic implementation:

// Start cropping activity for result
CropImage.activity(imageUri)
    .start(this)

// Handle the result
override fun onActivityResult(requestCode: Int, resultCode: Int, data: Intent?) {
    super.onActivityResult(requestCode, resultCode, data)
    if (requestCode == CropImage.CROP_IMAGE_ACTIVITY_REQUEST_CODE) {
        val result = CropImage.getActivityResult(data)
        if (resultCode == RESULT_OK) {
            val resultUri = result.uri
            // Use the cropped image
        } else if (resultCode == CropImage.CROP_IMAGE_ACTIVITY_RESULT_ERROR_CODE) {
            val error = result.error
            // Handle the error
        }
    }
}

Customizing crop options:

CropImage.activity(imageUri)
    .setGuidelines(CropImageView.Guidelines.ON)
    .setAspectRatio(1, 1)
    .setCropShape(CropImageView.CropShape.OVAL)
    .start(this)

Using CropImageView in XML:

<com.canhub.cropper.CropImageView
    android:id="@+id/cropImageView"
    android:layout_width="match_parent"
    android:layout_height="match_parent"
    app:cropAspectRatioX="1"
    app:cropAspectRatioY="1"
    app:cropBackgroundColor="@color/crop_background"
    app:cropGuidelines="on" />

Getting Started

Add the dependency to your app's build.gradle:

dependencies {
    implementation 'com.github.CanHub:Android-Image-Cropper:4.3.2'
}

Add the following to your project's build.gradle:

allprojects {
    repositories {
        maven { url 'https://jitpack.io' }
    }
}

Initialize the cropping activity in your code:

CropImage.activity()
    .setGuidelines(CropImageView.Guidelines.ON)
    .start(this)

Handle the result in your activity:

override fun onActivityResult(requestCode: Int, resultCode: Int, data: Intent?) {
    super.onActivityResult(requestCode, resultCode, data)
    if (requestCode == CropImage.CROP_IMAGE_ACTIVITY_REQUEST_CODE) {
        val result = CropImage.getActivityResult(data)
        if (resultCode == RESULT_OK) {
            val resultUri = result.uri
            // Use the cropped image
        }
    }
}

Competitor Comparisons

uCrop

11,849

Image Cropping Library for Android

Pros of uCrop

More customizable UI with extensive theming options
Supports both rectangle and oval crop shapes
Offers gesture-based rotation and scaling

Cons of uCrop

Larger library size, potentially increasing app size
Steeper learning curve due to more complex API

Code Comparison

uCrop:

UCrop.of(sourceUri, destinationUri)
    .withAspectRatio(16f, 9f)
    .withMaxResultSize(maxWidth, maxHeight)
    .start(this)

Android-Image-Cropper:

CropImage.activity(imageUri)
    .setAspectRatio(1, 1)
    .start(this)

Both libraries offer similar basic functionality, but uCrop provides more granular control over the cropping process. Android-Image-Cropper has a simpler API, making it easier to implement for basic use cases.

uCrop excels in customization and advanced features, while Android-Image-Cropper focuses on simplicity and ease of use. The choice between the two depends on the specific requirements of your project, such as the level of customization needed and the importance of minimizing app size.

Android-Image-Cropper

6,389

Image Cropping Library for Android, optimized for Camera / Gallery.

Pros of Android-Image-Cropper

More established and widely used library with a longer history
Extensive documentation and examples available
Supports older Android versions (API 14+)

Cons of Android-Image-Cropper

No longer actively maintained (last commit in 2019)
May lack compatibility with newer Android features and versions
Uses older dependencies and build tools

Code Comparison

Android-Image-Cropper:

CropImage.activity(imageUri)
    .setGuidelines(CropImageView.Guidelines.ON)
    .setAspectRatio(1, 1)
    .start(this);

CanHub/Android-Image-Cropper:

cropImage.launch(
    options {
        setGuidelines(CropImageView.Guidelines.ON)
        setAspectRatio(1, 1)
    }
)

The main difference is that CanHub's version uses Kotlin and modern Android development practices, including the use of the Activity Result API. This makes it more compatible with recent Android versions and development patterns.

CanHub/Android-Image-Cropper is a fork of the original Android-Image-Cropper, aimed at maintaining and updating the library for modern Android development. It offers improved Kotlin support, updated dependencies, and compatibility with newer Android versions while retaining most of the original functionality.

android-crop

4,537

Android library project for cropping images

Pros of android-crop

Lightweight and simple to use
Supports both rectangular and circular crop shapes
Includes a sample app for easy implementation reference

Cons of android-crop

Less actively maintained (last update was in 2017)
Fewer customization options for the cropping interface
Limited documentation compared to Android-Image-Cropper

Code Comparison

Android-Image-Cropper:

CropImage.activity(imageUri)
    .setGuidelines(CropImageView.Guidelines.ON)
    .setCropShape(CropImageView.CropShape.RECTANGLE)
    .start(this)

android-crop:

Crop.of(sourceUri, destinationUri).asSquare().start(activity);

Android-Image-Cropper offers more configuration options in the builder pattern, while android-crop provides a more concise API for basic cropping operations.

Android-Image-Cropper is more actively maintained and feature-rich, with extensive customization options and better documentation. It supports a wider range of Android versions and has a larger community.

android-crop is simpler and lighter, which may be preferable for projects with basic cropping needs. However, its lack of recent updates and limited features may be a drawback for more complex implementations.

scissors

1,838

✂ Android image cropping library

Pros of Scissors

Written in Kotlin, offering modern language features and better null safety
Supports both bitmap and URI-based image cropping
Includes built-in image loading and caching capabilities

Cons of Scissors

Less actively maintained (last update was in 2019)
Fewer customization options for the cropping interface
Limited documentation and examples compared to Android-Image-Cropper

Code Comparison

Android-Image-Cropper:

CropImage.activity(imageUri)
    .setGuidelines(CropImageView.Guidelines.ON)
    .setAspectRatio(1, 1)
    .start(this)

Scissors:

Scissors.create()
    .load(imageUri)
    .start(this)

Both libraries offer simple APIs for initiating the cropping process, but Android-Image-Cropper provides more options for customization in the initial setup.

Android-Image-Cropper is more actively maintained and has a larger community, which may lead to better support and more frequent updates. However, Scissors benefits from being written in Kotlin and offers some additional features like built-in image loading.

The choice between these libraries depends on specific project requirements, such as the need for Kotlin support, customization options, and long-term maintenance considerations.

SimpleCropView

2,479

A simple image cropping library for Android.

Pros of SimpleCropView

Simpler API and easier to implement for basic cropping needs
Lightweight and has fewer dependencies
Supports both rectangle and oval crop shapes out of the box

Cons of SimpleCropView

Less customizable compared to Android-Image-Cropper
Fewer advanced features like handle customization or overlay options
Not as actively maintained, with less frequent updates

Code Comparison

SimpleCropView implementation:

val cropImageView = findViewById<CropImageView>(R.id.cropImageView)
cropImageView.setImageUriAsync(imageUri)
cropImageView.getCroppedImageAsync()

Android-Image-Cropper implementation:

val cropImageView = findViewById<CropImageView>(R.id.cropImageView)
cropImageView.setImageUriAsync(imageUri)
cropImageView.getCroppedImage()

Both libraries offer similar basic functionality, but Android-Image-Cropper provides more options for customization and advanced features. SimpleCropView is a good choice for simpler projects with basic cropping needs, while Android-Image-Cropper is better suited for applications requiring more complex image manipulation and customization options.

Convert designs to code with AI

Introducing Visual Copilot: A new AI model to turn Figma designs to high quality code using your components.

Try Visual Copilot

README

Android Image Cropper

Powerful (Zoom, Rotation, Multi-Source)
Customizable (Shape, Limits, Style)
Optimized (Async, Sampling, Matrix)
Simple image cropping library for Android

Crop demo

Add to your project

dependencies {
  implementation("com.vanniktech:android-image-cropper:4.6.0")
}

Using the Library

There are 3 ways of using the library. Check out the sample app for all details.

1. Calling crop directly

Note: This way is deprecated and will be removed in future versions. The path forward is to write your own Activity, handle all the Uri stuff yourself and use CropImageView.

class MainActivity : AppCompatActivity() {
  private val cropImage = registerForActivityResult(CropImageContract()) { result ->
    if (result.isSuccessful) {
      // Use the cropped image URI.
      val croppedImageUri = result.uriContent
      val croppedImageFilePath = result.getUriFilePath(this) // optional usage
      // Process the cropped image URI as needed.
    } else {
      // An error occurred.
      val exception = result.error
      // Handle the error.
    }
  }

  private fun startCrop() {
    // Start cropping activity with guidelines.
    cropImage.launch(
      CropImageContractOptions(
        cropImageOptions = CropImageOptions(
          guidelines = Guidelines.ON
        )
      )
    )

    // Start cropping activity with gallery picker only.
    cropImage.launch(
      CropImageContractOptions(
        pickImageContractOptions = PickImageContractOptions(
          includeGallery = true,
          includeCamera = false
        )
      )
    )

    // Start cropping activity for a pre-acquired image with custom settings.
    cropImage.launch(
      CropImageContractOptions(
        uri = imageUri,
        cropImageOptions = CropImageOptions(
          guidelines = Guidelines.ON,
          outputCompressFormat = Bitmap.CompressFormat.PNG
        )
      )
    )
  }

  // Call the startCrop function when needed.
}

2. Using CropView

Note: This is the only way forward, add CropImageView into your own activity and do whatever you wish. Checkout the sample for more details.

<!-- Image Cropper fill the remaining available height -->
<com.canhub.cropper.CropImageView
  android:id="@+id/cropImageView"
  android:layout_width="match_parent"
  android:layout_height="0dp"
  android:layout_weight="1"
  />

Set image to crop

cropImageView.setImageUriAsync(uri)
// Or prefer using uri for performance and better user experience.
cropImageView.setImageBitmap(bitmap)

Get cropped image

// Subscribe to async event using cropImageView.setOnCropImageCompleteListener(listener)
cropImageView.getCroppedImageAsync()
// Or.
val cropped: Bitmap = cropImageView.getCroppedImage()

3. Extend to make a custom activity

Note: This way is also deprecated and will be removed in future versions. The path forward is to write your own Activity, handle all the Uri stuff yourself and use CropImageView.

If you want to extend the CropImageActivity please be aware you will need to set up your CropImageView

Add CropImageActivity into your AndroidManifest.xml

<!-- Theme is optional and only needed if default theme has no action bar. -->
<activity
  android:name="com.canhub.cropper.CropImageActivity"
  android:theme="@style/Base.Theme.AppCompat"
  />

Set up your CropImageView after call super.onCreate(savedInstanceState)

override fun onCreate(savedInstanceState: Bundle?) {
  super.onCreate(savedInstanceState)
  setCropImageView(binding.cropImageView)
}

Custom dialog for image source pick

When calling crop directly the library will prompt a dialog for the user choose between gallery or camera (If you keep both enable). We use the Android default AlertDialog for this. If you wanna customised it with your app theme you need to override the method showImageSourceDialog(..) when extending the activity (above)

override fun showImageSourceDialog(openSource: (Source) -> Unit) {
  super.showImageSourceDialog(openCamera)
}

Posts

Android cropping image from camera or gallery

Migrating from Android Image Cropper

Start by using Version 4.3.3:

dependencies {
  implementation("com.vanniktech:android-image-cropper:4.3.3")
}

Update all imports

-import com.theartofdev.edmodo.cropper.CropImage
-import com.theartofdev.edmodo.cropper.CropImageActivity
+import com.canhub.cropper.CropImage
+import com.canhub.cropper.CropImageActivity

Update all XML references

-<com.theartofdev.edmodo.cropper.CropImageView
+<com.canhub.cropper.CropImageView

When using Activity Contracts, consult with the sample app on how to use our Activity Contracts since onActivityResult got deprecated.

Versions after 4.3.3 have changed the APIs quite a bit, it's best to upgrade to each minor version individually, remove deprecated API usages and continue upgrading. So after using 4.3.3, upgrade to 4.4.0, upgrade to 4.5.0, 4.6.0, etc.

License

Forked from ArthurHub Originally forked from edmodo/cropper.

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this work except in compliance with the License. You may obtain a copy of the License in the LICENSE file, or at:

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

Top Related Projects

Convert designs to code with AI

Introducing Visual Copilot: A new AI model to turn Figma designs to high quality code using your components.

Try Visual Copilot