flutter_perspective_crop 1.0.1

A Flutter package for perspective image cropping with draggable corner handles, grid overlay, and homography-based perspective correction.

flutter_perspective_crop

A Flutter package for perspective image cropping with draggable corner handles, grid overlay, and homography-based perspective correction.

Features

• Perspective crop — Drag four corner handles to define an arbitrary quadrilateral crop region
• Homography-based transform — Uses projective (perspective) mapping via a subdivided triangle mesh for accurate results
• Interactive UI — Real-time preview with dark overlay, crop border, and 3×3 grid guide
• Fully customizable — Colors, handle sizes, labels, padding, and more are configurable via constructor parameters
• Simple API — Navigate to PerspectiveCropPage and receive the cropped image file path on pop

Getting started

Add the package to your pubspec.yaml:

dependencies:
  flutter_perspective_crop: ^1.0.0

Then run:

flutter pub get

Import it in your Dart code:

import 'package:flutter_perspective_crop/flutter_perspective_crop.dart';

Usage

Basic usage

import 'package:flutter/material.dart';
import 'package:flutter_perspective_crop/flutter_perspective_crop.dart';

class MyPage extends StatelessWidget {
  const MyPage({super.key});

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      body: Center(
        child: ElevatedButton(
          onPressed: () async {
            final croppedPath = await Navigator.push<String>(
              context,
              MaterialPageRoute(
                builder: (_) => PerspectiveCropPage(
                  imagePath: '/path/to/your/image.jpg',
                ),
              ),
            );

            if (croppedPath != null) {
              debugPrint('Cropped image saved at: $croppedPath');
            }
          },
          child: const Text('Crop Image'),
        ),
      ),
    );
  }
}

Customized usage

PerspectiveCropPage(
  imagePath: imagePath,
  title: 'Adjust Crop',
  backgroundColor: Colors.grey.shade900,
  appBarColor: Colors.grey.shade900,
  cropLabel: 'Apply',
  resetLabel: 'Start Over',
  handleRadius: 14.0,
  activeHandleRadius: 18.0,
  overlayColor: Colors.black54,
  borderColor: Colors.cyan,
  activeHandleColor: Colors.cyanAccent,
  gridColor: Colors.cyan.withValues(alpha: 0.3),
  touchSlop: 80.0,
  onError: (error) => debugPrint('Crop failed: $error'),
)

Using the engine directly

You can also use PerspectiveCropEngine programmatically if you need to perform a perspective crop without the UI:

import 'dart:ui' as ui;
import 'package:flutter_perspective_crop/flutter_perspective_crop.dart';

Future<ui.Image?> cropImage(ui.Image source, List<Offset> corners) {
  // corners: [topLeft, topRight, bottomRight, bottomLeft] in pixel coordinates
  return PerspectiveCropEngine.apply(source, corners);
}

API Reference

PerspectiveCropPage

Parameter	Type	Default	Description
imagePath	String	required	Path to the source image file
title	String	'Crop Image'	AppBar title
backgroundColor	Color	Colors.black	Page background color
appBarColor	Color	Colors.black	AppBar background
appBarIconColor	Color	Colors.white	AppBar icon color
appBarTextColor	Color	Colors.white	AppBar text color
padding	EdgeInsetsGeometry	EdgeInsets.all(16)	Padding around crop area
resetLabel	String	'Reset'	Reset button label
cropLabel	String	'Crop'	Crop button label
cropButtonColor	Color	Colors.white	Crop button background
cropButtonForegroundColor	Color	Colors.black	Crop button text color
handleRadius	double	12.0	Corner handle radius
activeHandleRadius	double	16.0	Active handle radius
overlayColor	Color	Color(0x99000000)	Overlay outside crop
borderColor	Color	Colors.white	Border & handle color
activeHandleColor	Color	Colors.yellow	Active handle color
gridColor	Color	Color(0x4DFFFFFF)	Grid line color
touchSlop	double	60.0	Touch grab distance
onError	void Function(Object)?	null	Error callback

PerspectiveCropEngine

Method	Description
apply(source, quadCorners)	Crops the source image using perspective transform. Returns the cropped ui.Image.
computeHomography(srcPts, dstPts)	Computes the 3×3 homography matrix for 4 point correspondences.

CropOverlayPainter

A CustomPainter that renders the image with the crop overlay. Accepts all visual customization parameters.

Additional information

• Report bugs and request features on the GitHub issue tracker
• Contributions are welcome! Please open a pull request.
• Licensed under the MIT License.