flutter_quad_annotator 0.0.1

A Flutter package for quadrilateral annotation with draggable vertices and edges, featuring magnifier, grid assistance, and highly customizable styling options.

Flutter Quad Annotator

一个功能强大的Flutter四边形标注工具包，提供可拖拽的四点定位四边形组件，支持放大镜、网格辅助线、自动检测等丰富功能。

📱 预览

多平台支持展示

[Android Demo] Android	[iOS Demo] iOS
[Web Demo] Web	[macOS Demo] macOS

🌐 在线演示

点击这里体验在线演示

或者运行本地示例应用查看完整功能演示

功能特性

• ✅ 四边形顶点拖拽 - 支持拖拽四个顶点来调整四边形形状
• ✅ 四边形边线拖拽 - 支持拖拽边线来移动整个四边形
• ✅ 放大镜功能 - 拖拽时显示放大镜，便于精确定位
• ✅ 网格辅助线 - 可选的网格背景，帮助对齐
• ✅ 高度可定制 - 支持自定义颜色、大小、样式等
• ✅ 事件回调 - 提供丰富的拖拽事件回调
• ✅ 单点触控 - 智能的单点触控识别，避免多点触控干扰

📋 平台支持

平台	支持状态	备注
✅ Android	完全支持	API 16+
✅ iOS	完全支持	iOS 9.0+
✅ Web	完全支持	现代浏览器
✅ macOS	完全支持	macOS 10.11+
✅ Windows	完全支持	Windows 7+
✅ Linux	完全支持	主流发行版

快速开始

安装

在你的 pubspec.yaml 文件中添加依赖：

dependencies:
  flutter_quad_annotator: ^0.0.1

然后运行：

flutter pub get

导入

import 'package:flutter_quad_annotator/flutter_quad_annotator.dart';

基本用法

QuadAnnotatorBox(
  backgroundColor: Colors.grey[100]!,
  onVerticesChanged: (QuadAnnotation rectangle) {
    print('四边形顶点已更新: ${rectangle.vertices}');
  },
  enableMagnifier: true,
  vertexColor: Colors.blue,
  borderColor: Colors.red,
)

完整示例

查看 /example 文件夹中的完整示例应用，演示了所有功能的使用方法：

cd example
flutter pub get
flutter run

示例应用包含：

• 交互式控制面板
• 实时坐标显示
• 所有配置选项的演示
• 事件回调的使用示例

API 文档

QuadAnnotatorBox

主要的四边形标注组件。

主要参数

参数	类型	默认值	说明
image	ui.Image?	null	背景图片对象
imageProvider	ImageProvider?	null	图片提供者
width	double	必需	组件宽度
height	double	必需	组件高度
backgroundColor	Color	Colors.transparent	背景颜色
rectangle	QuadAnnotation?	null	初始四边形
onVerticesChanged	OnVerticesChanged?	null	顶点变化回调
enableMagnifier	bool	true	是否启用放大镜
vertexRadius	double	8.0	顶点半径
borderWidth	double	2.0	边框宽度
vertexColor	Color	Colors.white	顶点颜色
borderColor	Color	Colors.white	边框颜色
autoDetect	bool	true	是否自动检测矩形
preview	bool	false	是否为预览模式

QuadAnnotation

四边形标注类，用于存储和操作四个顶点坐标。

// 创建四边形
final rectangle = QuadAnnotation(
  topLeft: Offset(10, 10),
  topRight: Offset(100, 10),
  bottomRight: Offset(100, 100),
  bottomLeft: Offset(10, 100),
);

// 从顶点列表创建
final rectangle = QuadAnnotation.fromVertices([
  Offset(10, 10),
  Offset(100, 10),
  Offset(100, 100),
  Offset(10, 100),
]);

// 获取顶点列表
List<Offset> vertices = rectangle.vertices;

// 获取边界矩形
Rect bounds = rectangle.bounds;

高级配置

放大镜配置

QuadAnnotatorBox(
  enableMagnifier: true,
  magnifierRadius: 60.0,
  magnification: 2.0,
  magnifierPositionMode: MagnifierPositionMode.edge,
  magnifierBorderColor: Colors.white,
  magnifierBorderWidth: 3.0,
  magnifierCrosshairColor: Colors.white,
)

呼吸灯效果配置

QuadAnnotatorBox(
  enableBreathing: true,
  breathingColor: Colors.white,
  breathingDuration: Duration(seconds: 2),
  breathingOpacityMin: 0.2,
  breathingOpacityMax: 0.9,
)

事件回调

QuadAnnotatorBox(
  onVerticesChanged: (rectangle) {
    // 四边形顶点变化
  },
  onVertexDragStart: (vertexIndex, position) {
    // 开始拖拽顶点
  },
  onVertexDragEnd: (vertexIndex, position) {
    // 结束拖拽顶点
  },
  onEdgeDragStart: (edgeIndex, position) {
    // 开始拖拽边线
  },
  onEdgeDragEnd: (edgeIndex, position) {
    // 结束拖拽边线
  },
)

🚀 性能特性

• 高效渲染: 使用自定义 CustomPainter 实现高性能绘制
• 内存优化: 智能的状态管理，避免不必要的重建
• 流畅交互: 60fps 的拖拽体验，支持高刷新率设备
• 响应式设计: 自适应不同屏幕尺寸和像素密度

🔧 故障排除

常见问题

Q: 拖拽时出现卡顿怎么办？ A: 确保在 onVerticesChanged 回调中避免执行耗时操作，可以使用防抖或节流技术。

Q: 如何禁用某些交互功能？ A: 使用 preview: true 参数可以禁用所有交互功能。

Q: 自动检测不准确怎么办？ A: 可以设置 autoDetect: false 禁用自动检测，或者提供自定义的初始矩形 rectangle。

性能优化建议

1. 避免频繁重建: 将 QuadAnnotatorBox 包装在 const 构造函数中
2. 合理使用回调: 只监听必要的事件，避免在回调中执行重操作
3. 内存管理: 及时释放不需要的资源，特别是大图像数据

🤝 贡献指南

我们欢迎所有形式的贡献！

如何贡献

1. Fork 本仓库
2. 创建你的特性分支 (git checkout -b feature/AmazingFeature)
3. 提交你的更改 (git commit -m 'Add some AmazingFeature')
4. 推送到分支 (git push origin feature/AmazingFeature)
5. 打开一个 Pull Request

开发环境设置

# 克隆仓库
git clone https://github.com/YongTaiSin/flutter_quad_annotator.git
cd flutter_quad_annotator

# 安装依赖
flutter pub get

# 运行测试
flutter test

# 运行示例
cd example
flutter pub get
flutter run

代码规范

• 遵循 Dart Style Guide
• 使用 flutter analyze 检查代码质量
• 为新功能添加相应的测试用例
• 更新文档和示例代码

📄 许可证

本项目采用 MIT 许可证。详见 LICENSE 文件。

🙏 致谢

• 感谢 rectangle_detector 提供的自动检测功能
• 感谢所有贡献者和用户的支持

📞 联系我们

• Issues: GitHub Issues
• Discussions: GitHub Discussions
• Email: [e-mail]

---

如果这个包对你有帮助，请给我们一个 ⭐️

Made with ❤️ by Flutter Community