crop_your_image

A flutter plugin that provides Crop widget for cropping images.

Image Cropping Preview

Philosophy

crop_your_image provides flexible and customizable Crop widget that can be placed at anywhere in your well designed apps.

As Crop is a simple widget displaying minimum cropping UI, Crop can be placed anywhere such as, for example, occupying entire screen, at top half of the screen, or even on dialogs or bottom sheets. It's totally up to you!

Users' cropping operation is also customizable. By default, images are fixed on the screen and users can move crop rect to decide where to crop. Once configured interactive mode, images can be zoomed/panned, and crop rect can be configured as fixed.

CropController enables you to control crop rect from outside of Crop. The controller allows you to run cropping (or related actions) from anywhere on your codebase.

Enjoy building your own cropping UI with crop_your_image!

Features

Minimum UI restrictions
Flexible Crop widget that can be placed anywhere on your widget tree
CropController to control Crop
Zooming / panning images
Crop with rect or circle whichever you want
Fix aspect ratio
Configure Rect of crop rect programmatically
Detect events of users' operation
Undo / Redo operation
(advanced) Cropping backend logics are also customizable

Note that this package DON'T

read / download image data from any storages, such as gallery, internet, etc.
resize, tilt, or other conversions which can be done with image package directly.
provide UI parts other than cropping editor, such as buttons to control. Building UI is fully UP TO YOU!

Usage

Basics

Place Crop Widget wherever you want to place image cropping UI.

final _controller = CropController();

@override
Widget build(BuildContext context) {
  return Crop(
    image: _imageData, 
    controller: _controller,
    onCropped: (result) {
      switch(result) {
        case CropResult.success(:final croppedImage):
          // do something with cropped image data 
        case CropResult.error(:final error):
          // do something with error
      }
    }
  );
}

Then, Crop widget will automatically display cropping editor UI on users screen with given image.

By passing CropController instance to controller argument of Crop's constructor, you can control the Crop widget from anywhere on your source code.

For example, when you want to crop the image with the current crop rect, you can just call _controller.crop() whenever you want, such like the code below.

ElevatedButton(
  child: Text('Crop it!')
  onPressed: () => _cropController.crop(),
),

Because _controller.crop() only kicks the cropping process, this method returns immediately without any cropped image data. You can obtain the result of cropping images via onCropped callback of Crop Widget.

Undo / Redo

CropController also provides undo and redo methods.

ElevatedButton(
  child: Text('Undo')
  onPressed: () => _cropController.undo(),
),

You can also detect history of crop rect changes via onHistoryChanged callback of Crop Widget. This callback exposes History object, which contains undoCount and redoCount, that indicates how many times undo / redo operation is available.

Crop(
  onHistoryChanged: (history) {
    setState(() {
      _undoEnabled = history.undoCount > 0;
      _redoEnabled = history.redoCount > 0;
    });
  },
)

List of configurations

All the arguments of Crop and usages are below.

final _controller = CropController();

Widget build(BuildContext context) {
  return Crop(
    image: _imageData,
    controller: _controller,
    onCropped: (result) {
      switch(result) {
        case CropResult.success(:final croppedImage):
          // do something with cropped image data 
        case CropResult.error(:final error):
          // do something with error
      }
    },
    aspectRatio: 4 / 3,

    initialRectBuilder: InitialRectBuilder.withBuilder((viewportRect, imageRect) {
      return Rect.fromLTRB(
        viewportRect.left + 24,
        viewportRect.top + 32,
        viewportRect.right - 24,
        viewportRect.bottom - 32,
      );
    }),
    // initialRectBuilder: InitialRectBuilder.withArea(
    //   ImageBasedRect.fromLTWH(240, 212, 800, 600),
    // ),
    // initialRectBuilder: InitialRectBuilder.withSizeAndRatio(
    //   size: 0.5,
    //   aspectRatio: 4 / 3,
    // ),

    // withCircleUi: true,
    baseColor: Colors.blue.shade900,
    maskColor: Colors.white.withAlpha(100),
    overlayBuilder: (context, rect) {
      return CustomPaint(painter: MyPainter(rect));
    },
    progressIndicator: const CircularProgressIndicator(),
    radius: 20,
    onMoved: (newRect) {
      // do something with current crop rect.
    },
    onImageMoved: (newImageRect) {
      // do something with current image rect.
    },
    onStatusChanged: (status) {
      // do something with current CropStatus
    },
    willUpdateScale: (newScale) {
      // if returning false, scaling will be canceled
      return newScale < 5;
    },
    cornerDotBuilder: (size, edgeAlignment) => const DotControl(color: Colors.blue),
    clipBehavior: Clip.none,
    interactive: true,
    // fixCropRect: true,

    // formatDetector: (image) {},
    // imageCropper: myCustomImageCropper,
    // imageParser: (image, {format}) {},
  );
}

argument	type	description
image	Uint8List	Original image data to be cropped. The result of cropping operation can be obtained via `onCropped` callback.
onCropped	void Function(CropResult)	Callback called when cropping operation is completed. The result is exposed as `CropResult` object. `CropResult.success()` contains cropped image data, and `CropResult.error()` contains error object.
controller	CropController	Controller for managing cropping operation.
aspectRatio	double?	Initial aspect ratio of crop rect. Set `null` or just omit if you want to crop images with any aspect ratio. `aspectRatio` can be changed dynamically via setter of `CropController.aspectRatio`. (see below)
initialSize	double?	is the initial size of crop rect. `1.0` (or `null`, by default) fits the size of image, which means crop rect extends as much as possible. `0.5` would be the half. This value is also referred when `aspectRatio` changes via `CropController.aspectRatio`.
initialRectBuilder	InitialRectBuilder?	An object preserving configuration for building the initial crop rect. `InitialRectBuilder.withBuilder` enables you to configure the rect with a function to decide initial `Rect` of crop rect based on viewport of `Crop` itself. `InitialRectBuilder.withArea` enables you to configure the rect with `ImageBasedRect` which is based on actual image size. `InitialRectBuilder.withSizeAndRatio` enables you to configure the rect with `size` and `aspectRatio`.
withCircleUi	bool	Flag to decide the shape of cropping UI. If `true`, the shape of cropping UI is circle and `aspectRatio` is automatically set `1.0`. Note that this flag does NOT affect to the result of cropping image. If you want cropped images with circle shape, call `CropController.cropCircle` instead of `CropController.crop`.
maskColor	Color?	Color of the mask widget which is placed over the cropping editor.
baseColor	Color?	Color of the base color of the cropping editor.
overlayBuilder	Widget Function(BuildContext, ViewportBasedRect)?	Builder function to build Widget placed over the cropping rect. `rect` of argument is current `ViewportBasedRect` of crop rect.
radius	double?	Corner radius of crop rect.
onMoved	void Function(ViewportBasedRect)?	Callback called when crop rect is moved regardless of its reasons. `newRect` of argument is current `ViewportBasedRect` of crop rect.
onImageMoved	void Function(ViewportBasedRect)?	Callback called when image is moved regardless of its reasons. `newImageRect` of argument is current `ViewportBasedRect` of image.
onHistoryChanged	void Function(History)?	Callback called when history of crop rect is changed. This history allows you to undo / redo feature is available or not.
onStatusChanged	void Function(CropStatus)?	Callback called when status of Crop is changed.
willUpdateScale	bool Function(double)?	Callback called before scale changes on interactive mode. By returning `false` to this callback, updating scale will be canceled.
cornerDotBuilder	Widget Function(Size, EdgeAlignment)?	Builder function to build Widget placed at four corners used to move crop rect. The builder passes `size` which widget must follow and `edgeAlignment` which indicates the position.
progressIndicator	Widget?	Widget for showing preparing image is in progress. Nothing (`SizedBox.shrink()` actually) is shown by default.
interactive	bool?	Flag to enable interactive mode that users can move / zoom images. `false` by default
fixCropRect	bool?	Flag if crop rect should be fixed on interactive mode. `false` by default
clipBehavior	Clip?	Decide clipping strategy for `Crop`. `Clip.hardEdge` by default
filterQuality	FilterQuality?	Decide filter quality for `Image` showing target image. `FilterQuality.low` by default

for Web

argument	type	description
scrollZoomSensitivity	double?	Sensitivity for zoom gesture using mouse-wheel. For web applications only.

Advanced

crop_your_image also allows you to customize backend logic for

detecting the format of the image
detecting detail information (width / height) of the image
cropping

by passing the arguments below.

argument	type	description
formatDetector	ImageFormat Function(Uint8List)?	Function to detect the format of original image. By detecting the format before `imageParser` parses the original image from `Uint8List` to `ImageDetail`, `imageParser` will sufficiently parse the binary, which means the initializing operation speeds up. `defaultFormatDetector` is used by default
imageParser	ImageDetail	Function for parsing original image from `Uint8List` to `ImageDetail`, which preserve `height`, `width` and parsed `image` with generic type `<T>`. `image` is passed to `imageCropper` with `Rect` to be cropped. `defaultImageParser` is used by default
imageCropper	ImageCropper	By implementing `ImageCropper<T>` and passing its instance to this argument, you can exchange cropping logic. `defaultImageCropper` is used by default

Gallery App

The repository below is for a sample app of using crop_your_image. | chooyan-eng/crop_your_image_gallery

You can find several examples with executable source codes here.

Contact

If you have anything you want to inform me (@chooyan-eng), such as suggestions to enhance this package or functionalities you want etc, feel free to make issues on GitHub or send messages on X @tsuyoshi_chujo (Japanese @chooyan_i18n).