diff --git a/README.md b/README.md index 8e097a7f..cd91aa9f 100644 --- a/README.md +++ b/README.md @@ -1,73 +1,88 @@ # Google's ML Kit for Flutter -Google's ML Kit for Flutter is a set of [Flutter plugins](https://flutter.io/platform-plugins/) that enable [Flutter](https://flutter.dev) apps to use [Google's standalone ML Kit](https://developers.google.com/ml-kit). +Google’s ML Kit for Flutter is a set of [Flutter plugins](https://flutter.io/platform-plugins/) that enable [Flutter](https://flutter.dev) apps to use [Google’s standalone ML Kit](https://developers.google.com/ml-kit). -## Features +--- -### Vision APIs +## πŸ“Έ Features -| Feature | Plugin | Source Code | Android | iOS | -|-------------------------------------------------------------------------------------------------| -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- | --- | -| [Barcode Scanning](https://developers.google.com/ml-kit/vision/barcode-scanning) | [google_mlkit_barcode_scanning](https://pub.dev/packages/google_mlkit_barcode_scanning) [![Pub Version](https://img.shields.io/pub/v/google_mlkit_barcode_scanning)](https://pub.dev/packages/google_mlkit_barcode_scanning) | [![GitHub](https://img.shields.io/badge/github-%23121011.svg?style=for-the-badge&logo=github&logoColor=white)](https://github.com/flutter-ml/google_ml_kit_flutter/tree/master/packages/google_mlkit_barcode_scanning) | βœ… | βœ… | -| [Face Detection](https://developers.google.com/ml-kit/vision/face-detection) | [google_mlkit_face_detection](https://pub.dev/packages/google_mlkit_face_detection) [![Pub Version](https://img.shields.io/pub/v/google_mlkit_face_detection)](https://pub.dev/packages/google_mlkit_face_detection) | [![GitHub](https://img.shields.io/badge/github-%23121011.svg?style=for-the-badge&logo=github&logoColor=white)](https://github.com/flutter-ml/google_ml_kit_flutter/tree/master/packages/google_mlkit_face_detection) | βœ… | βœ… | -| [Face Mesh Detection (Beta)](https://developers.google.com/ml-kit/vision/face-mesh-detection) | [google_mlkit_face_mesh_detection](https://pub.dev/packages/google_mlkit_face_mesh_detection) [![Pub Version](https://img.shields.io/pub/v/google_mlkit_face_mesh_detection)](https://pub.dev/packages/google_mlkit_face_mesh_detection) | [![GitHub](https://img.shields.io/badge/github-%23121011.svg?style=for-the-badge&logo=github&logoColor=white)](https://github.com/flutter-ml/google_ml_kit_flutter/tree/master/packages/google_mlkit_face_mesh_detection) | βœ… | ❌ | -| [Text Recognition v2](https://developers.google.com/ml-kit/vision/text-recognition/v2) | [google_mlkit_text_recognition](https://pub.dev/packages/google_mlkit_text_recognition) [![Pub Version](https://img.shields.io/pub/v/google_mlkit_text_recognition)](https://pub.dev/packages/google_mlkit_text_recognition) | [![GitHub](https://img.shields.io/badge/github-%23121011.svg?style=for-the-badge&logo=github&logoColor=white)](https://github.com/flutter-ml/google_ml_kit_flutter/tree/master/packages/google_mlkit_text_recognition) | βœ… | βœ… | -| [Image Labeling](https://developers.google.com/ml-kit/vision/image-labeling) | [google_mlkit_image_labeling](https://pub.dev/packages/google_mlkit_image_labeling) [![Pub Version](https://img.shields.io/pub/v/google_mlkit_image_labeling)](https://pub.dev/packages/google_mlkit_image_labeling) | [![GitHub](https://img.shields.io/badge/github-%23121011.svg?style=for-the-badge&logo=github&logoColor=white)](https://github.com/flutter-ml/google_ml_kit_flutter/tree/master/packages/google_mlkit_image_labeling) | βœ… | βœ… | -| [Object Detection and Tracking](https://developers.google.com/ml-kit/vision/object-detection) | [google_mlkit_object_detection](https://pub.dev/packages/google_mlkit_object_detection) [![Pub Version](https://img.shields.io/pub/v/google_mlkit_object_detection)](https://pub.dev/packages/google_mlkit_object_detection) | [![GitHub](https://img.shields.io/badge/github-%23121011.svg?style=for-the-badge&logo=github&logoColor=white)](https://github.com/flutter-ml/google_ml_kit_flutter/tree/master/packages/google_mlkit_object_detection) | βœ… | βœ… | -| [Digital Ink Recognition](https://developers.google.com/ml-kit/vision/digital-ink-recognition) | [google_mlkit_digital_ink_recognition](https://pub.dev/packages/google_mlkit_digital_ink_recognition) [![Pub Version](https://img.shields.io/pub/v/google_mlkit_digital_ink_recognition)](https://pub.dev/packages/google_mlkit_digital_ink_recognition) | [![GitHub](https://img.shields.io/badge/github-%23121011.svg?style=for-the-badge&logo=github&logoColor=white)](https://github.com/flutter-ml/google_ml_kit_flutter/tree/master/packages/google_mlkit_digital_ink_recognition) | βœ… | βœ… | -| [Pose Detection (Beta)](https://developers.google.com/ml-kit/vision/pose-detection) | [google_mlkit_pose_detection](https://pub.dev/packages/google_mlkit_pose_detection) [![Pub Version](https://img.shields.io/pub/v/google_mlkit_pose_detection)](https://pub.dev/packages/google_mlkit_pose_detection) | [![GitHub](https://img.shields.io/badge/github-%23121011.svg?style=for-the-badge&logo=github&logoColor=white)](https://github.com/flutter-ml/google_ml_kit_flutter/tree/master/packages/google_mlkit_pose_detection) | βœ… | βœ… | -| [Selfie Segmentation (Beta)](https://developers.google.com/ml-kit/vision/selfie-segmentation) | [google_mlkit_selfie_segmentation](https://pub.dev/packages/google_mlkit_selfie_segmentation) [![Pub Version](https://img.shields.io/pub/v/google_mlkit_selfie_segmentation)](https://pub.dev/packages/google_mlkit_selfie_segmentation) | [![GitHub](https://img.shields.io/badge/github-%23121011.svg?style=for-the-badge&logo=github&logoColor=white)](https://github.com/flutter-ml/google_ml_kit_flutter/tree/master/packages/google_mlkit_selfie_segmentation) | βœ… | βœ… | -| [Subject Segmentation (Beta)](https://developers.google.com/ml-kit/vision/subject-segmentation) | [google_mlkit_subject_segmentation](https://pub.dev/packages/google_mlkit_subject_segmentation) [![Pub Version](https://img.shields.io/pub/v/google_mlkit_subject_segmentation)](https://pub.dev/packages/google_mlkit_subject_segmentation) | [![GitHub](https://img.shields.io/badge/github-%23121011.svg?style=for-the-badge&logo=github&logoColor=white)](https://github.com/flutter-ml/google_ml_kit_flutter/tree/master/packages/google_mlkit_subject_segmentation) | βœ… | ❌ | -| [Document Scanner (Beta)](https://developers.google.com/ml-kit/vision/doc-scanner) | [google_mlkit_document_scanner](https://pub.dev/packages/google_mlkit_document_scanner) [![Pub Version](https://img.shields.io/pub/v/google_mlkit_document_scanner)](https://pub.dev/packages/google_mlkit_document_scanner) | [![GitHub](https://img.shields.io/badge/github-%23121011.svg?style=for-the-badge&logo=github&logoColor=white)](https://github.com/flutter-ml/google_ml_kit_flutter/tree/master/packages/google_mlkit_document_scanner) | βœ… | ❌ | +### 🧠 Vision APIs -### Natural Language APIs +| Feature | Plugin | Source Code | Android | iOS | +|---------|--------|-------------|---------|-----| +| [Barcode Scanning](https://developers.google.com/ml-kit/vision/barcode-scanning) | [google_mlkit_barcode_scanning](https://pub.dev/packages/google_mlkit_barcode_scanning) [![Pub Version](https://img.shields.io/pub/v/google_mlkit_barcode_scanning)](https://pub.dev/packages/google_mlkit_barcode_scanning) | [Source](https://github.com/flutter-ml/google_ml_kit_flutter/tree/master/packages/google_mlkit_barcode_scanning) | βœ… | βœ… | +| [Face Detection](https://developers.google.com/ml-kit/vision/face-detection) | [google_mlkit_face_detection](https://pub.dev/packages/google_mlkit_face_detection) [![Pub Version](https://img.shields.io/pub/v/google_mlkit_face_detection)](https://pub.dev/packages/google_mlkit_face_detection) | [Source](https://github.com/flutter-ml/google_ml_kit_flutter/tree/master/packages/google_mlkit_face_detection) | βœ… | βœ… | +| [Face Mesh Detection (Beta)](https://developers.google.com/ml-kit/vision/face-mesh-detection) | [google_mlkit_face_mesh_detection](https://pub.dev/packages/google_mlkit_face_mesh_detection) [![Pub Version](https://img.shields.io/pub/v/google_mlkit_face_mesh_detection)](https://pub.dev/packages/google_mlkit_face_mesh_detection) | [Source](https://github.com/flutter-ml/google_ml_kit_flutter/tree/master/packages/google_mlkit_face_mesh_detection) | βœ… | ❌ | +| [Text Recognition v2](https://developers.google.com/ml-kit/vision/text-recognition/v2) | [google_mlkit_text_recognition](https://pub.dev/packages/google_mlkit_text_recognition) [![Pub Version](https://img.shields.io/pub/v/google_mlkit_text_recognition)](https://pub.dev/packages/google_mlkit_text_recognition) | [Source](https://github.com/flutter-ml/google_ml_kit_flutter/tree/master/packages/google_mlkit_text_recognition) | βœ… | βœ… | +| [Image Labeling](https://developers.google.com/ml-kit/vision/image-labeling) | [google_mlkit_image_labeling](https://pub.dev/packages/google_mlkit_image_labeling) [![Pub Version](https://img.shields.io/pub/v/google_mlkit_image_labeling)](https://pub.dev/packages/google_mlkit_image_labeling) | [Source](https://github.com/flutter-ml/google_ml_kit_flutter/tree/master/packages/google_mlkit_image_labeling) | βœ… | βœ… | +| [Object Detection & Tracking](https://developers.google.com/ml-kit/vision/object-detection) | [google_mlkit_object_detection](https://pub.dev/packages/google_mlkit_object_detection) [![Pub Version](https://img.shields.io/pub/v/google_mlkit_object_detection)](https://pub.dev/packages/google_mlkit_object_detection) | [Source](https://github.com/flutter-ml/google_ml_kit_flutter/tree/master/packages/google_mlkit_object_detection) | βœ… | βœ… | +| [Digital Ink Recognition](https://developers.google.com/ml-kit/vision/digital-ink-recognition) | [google_mlkit_digital_ink_recognition](https://pub.dev/packages/google_mlkit_digital_ink_recognition) [![Pub Version](https://img.shields.io/pub/v/google_mlkit_digital_ink_recognition)](https://pub.dev/packages/google_mlkit_digital_ink_recognition) | [Source](https://github.com/flutter-ml/google_ml_kit_flutter/tree/master/packages/google_mlkit_digital_ink_recognition) | βœ… | βœ… | +| [Pose Detection (Beta)](https://developers.google.com/ml-kit/vision/pose-detection) | [google_mlkit_pose_detection](https://pub.dev/packages/google_mlkit_pose_detection) [![Pub Version](https://img.shields.io/pub/v/google_mlkit_pose_detection)](https://pub.dev/packages/google_mlkit_pose_detection) | [Source](https://github.com/flutter-ml/google_ml_kit_flutter/tree/master/packages/google_mlkit_pose_detection) | βœ… | βœ… | +| [Selfie Segmentation (Beta)](https://developers.google.com/ml-kit/vision/selfie-segmentation) | [google_mlkit_selfie_segmentation](https://pub.dev/packages/google_mlkit_selfie_segmentation) [![Pub Version](https://img.shields.io/pub/v/google_mlkit_selfie_segmentation)](https://pub.dev/packages/google_mlkit_selfie_segmentation) | [Source](https://github.com/flutter-ml/google_ml_kit_flutter/tree/master/packages/google_mlkit_selfie_segmentation) | βœ… | βœ… | +| [Subject Segmentation (Beta)](https://developers.google.com/ml-kit/vision/subject-segmentation) | [google_mlkit_subject_segmentation](https://pub.dev/packages/google_mlkit_subject_segmentation) [![Pub Version](https://img.shields.io/pub/v/google_mlkit_subject_segmentation)](https://pub.dev/packages/google_mlkit_subject_segmentation) | [Source](https://github.com/flutter-ml/google_ml_kit_flutter/tree/master/packages/google_mlkit_subject_segmentation) | βœ… | ❌ | +| [Document Scanner (Beta)](https://developers.google.com/ml-kit/vision/doc-scanner) | [google_mlkit_document_scanner](https://pub.dev/packages/google_mlkit_document_scanner) [![Pub Version](https://img.shields.io/pub/v/google_mlkit_document_scanner)](https://pub.dev/packages/google_mlkit_document_scanner) | [Source](https://github.com/flutter-ml/google_ml_kit_flutter/tree/master/packages/google_mlkit_document_scanner) | βœ… | ❌ | -| Feature | Plugin | Source Code | Android | iOS | -|---------------------------------------------------------------------------------------------| -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- | --- | -| [Language Identification](https://developers.google.com/ml-kit/language/identification) | [google_mlkit_language_id](https://pub.dev/packages/google_mlkit_language_id) [![Pub Version](https://img.shields.io/pub/v/google_mlkit_language_id)](https://pub.dev/packages/google_mlkit_language_id) | [![GitHub](https://img.shields.io/badge/github-%23121011.svg?style=for-the-badge&logo=github&logoColor=white)](https://github.com/flutter-ml/google_ml_kit_flutter/tree/master/packages/google_mlkit_language_id) | βœ… | βœ… | -| [On-Device Translation](https://developers.google.com/ml-kit/language/translation) | [google_mlkit_translation](https://pub.dev/packages/google_mlkit_translation) [![Pub Version](https://img.shields.io/pub/v/google_mlkit_translation)](https://pub.dev/packages/google_mlkit_translation) | [![GitHub](https://img.shields.io/badge/github-%23121011.svg?style=for-the-badge&logo=github&logoColor=white)](https://github.com/flutter-ml/google_ml_kit_flutter/tree/master/packages/google_mlkit_translation) | βœ… | βœ… | -| [Smart Reply](https://developers.google.com/ml-kit/language/smart-reply) | [google_mlkit_smart_reply](https://pub.dev/packages/google_mlkit_smart_reply) [![Pub Version](https://img.shields.io/pub/v/google_mlkit_smart_reply)](https://pub.dev/packages/google_mlkit_smart_reply) | [![GitHub](https://img.shields.io/badge/github-%23121011.svg?style=for-the-badge&logo=github&logoColor=white)](https://github.com/flutter-ml/google_ml_kit_flutter/tree/master/packages/google_mlkit_smart_reply) | βœ… | βœ… | -| [Entity Extraction (Beta)](https://developers.google.com/ml-kit/language/entity-extraction) | [google_mlkit_entity_extraction](https://pub.dev/packages/google_mlkit_entity_extraction) [![Pub Version](https://img.shields.io/pub/v/google_mlkit_entity_extraction)](https://pub.dev/packages/google_mlkit_entity_extraction) | [![GitHub](https://img.shields.io/badge/github-%23121011.svg?style=for-the-badge&logo=github&logoColor=white)](https://github.com/flutter-ml/google_ml_kit_flutter/tree/master/packages/google_mlkit_entity_extraction) | βœ… | βœ… | +--- -**PLEASE READ THIS** before continuing or posting a [new issue](https://github.com/flutter-ml/google_ml_kit_flutter/issues): +### πŸ—£οΈ Natural Language APIs -- [Google's ML Kit](https://developers.google.com/ml-kit) was build only for mobile platforms: iOS and Android apps. Web or any other platform is not supported, you can request support for those platform to Google in [their repo](https://github.com/googlesamples/mlkit/issues). +| Feature | Plugin | Source Code | Android | iOS | +|---------|--------|-------------|---------|-----| +| [Language Identification](https://developers.google.com/ml-kit/language/identification) | [google_mlkit_language_id](https://pub.dev/packages/google_mlkit_language_id) [![Pub Version](https://img.shields.io/pub/v/google_mlkit_language_id)](https://pub.dev/packages/google_mlkit_language_id) | [Source](https://github.com/flutter-ml/google_ml_kit_flutter/tree/master/packages/google_mlkit_language_id) | βœ… | βœ… | +| [On-Device Translation](https://developers.google.com/ml-kit/language/translation) | [google_mlkit_translation](https://pub.dev/packages/google_mlkit_translation) [![Pub Version](https://img.shields.io/pub/v/google_mlkit_translation)](https://pub.dev/packages/google_mlkit_translation) | [Source](https://github.com/flutter-ml/google_ml_kit_flutter/tree/master/packages/google_mlkit_translation) | βœ… | βœ… | +| [Smart Reply](https://developers.google.com/ml-kit/language/smart-reply) | [google_mlkit_smart_reply](https://pub.dev/packages/google_mlkit_smart_reply) [![Pub Version](https://img.shields.io/pub/v/google_mlkit_smart_reply)](https://pub.dev/packages/google_mlkit_smart_reply) | [Source](https://github.com/flutter-ml/google_ml_kit_flutter/tree/master/packages/google_mlkit_smart_reply) | βœ… | βœ… | +| [Entity Extraction (Beta)](https://developers.google.com/ml-kit/language/entity-extraction) | [google_mlkit_entity_extraction](https://pub.dev/packages/google_mlkit_entity_extraction) [![Pub Version](https://img.shields.io/pub/v/google_mlkit_entity_extraction)](https://pub.dev/packages/google_mlkit_entity_extraction) | [Source](https://github.com/flutter-ml/google_ml_kit_flutter/tree/master/packages/google_mlkit_entity_extraction) | βœ… | βœ… | -- This plugin is not sponsored or maintained by Google. The [authors](https://github.com/flutter-ml/google_ml_kit_flutter/blob/master/AUTHORS) are developers excited about Machine Learning that wanted to expose Google's native APIs to Flutter. +--- -- Google's ML Kit APIs are only developed natively for iOS and Android. This plugin uses Flutter Platform Channels as explained [here](https://docs.flutter.dev/development/platform-integration/platform-channels). +## ⚠️ Important Notes - Messages are passed between the client (the app/plugin) and host (platform) using platform channels as illustrated in this diagram: +- **ML Kit** is designed **only for mobile platforms** β€” Android and iOS. Web or desktop platforms are **not supported**. If you need web support, please request it from Google via [their repo](https://github.com/googlesamples/mlkit/issues). +- This plugin **is not sponsored or maintained by Google**. The [authors](https://github.com/flutter-ml/google_ml_kit_flutter/blob/master/AUTHORS) are independent contributors who expose Google’s native ML Kit APIs to Flutter. +- All ML operations are executed **natively**, not in Dart. This plugin uses **Flutter Platform Channels** to send requests to the native platform. -

- -

+

+ +

- Messages and responses are passed asynchronously, to ensure the user interface remains responsive. To read more about platform channels go [here](https://docs.flutter.dev/development/platform-integration/platform-channels). +--- - Because this plugin uses platform channels, no Machine Learning processing is done in Flutter/Dart, all the calls are passed to the native platform using `MethodChannel` in Android and `FlutterMethodChannel` in iOS, and executed using Google's native APIs. Think of this plugin as a bridge between your app and Google's native ML Kit APIs. This plugin only passes the call to the native API and the processing is done by Google's API. It is important that you understand this concept when it comes to debugging errors for your ML model and/or app. +## 🧩 Debugging & Issues -- Since the plugin uses platform channels, you may encounter issues with the native API. Before submitting a new issue, identify the source of the issue. You can run both iOS and/or Android native [example apps by Google](https://github.com/googlesamples/mlkit) and make sure that the issue is not reproducible with their native examples. If you can reproduce the issue in their apps then report the issue to Google. The [authors](https://github.com/flutter-ml/google_ml_kit_flutter/blob/master/AUTHORS) do not have access to the source code of their native APIs, so you need to report the issue to them. If you find that their example apps are okay and still you have an issue using this plugin, then look at our [closed and open issues](https://github.com/flutter-ml/google_ml_kit_flutter/issues). If you cannot find anything that can help you then report the issue and provide enough details. Be patient, someone from the community will eventually help you. +If you encounter problems: -## Migrating from ML Kit for Firebase to the new standalone ML Kit SDK +1. Run the native ML Kit example apps from [Google Samples](https://github.com/googlesamples/mlkit) to confirm whether the issue is native. +2. If the native examples also fail, report the issue to Google. +3. If the native examples work, search the [open and closed issues](https://github.com/flutter-ml/google_ml_kit_flutter/issues). +4. If you still can’t find a solution, open a **new issue** here and provide detailed steps to reproduce. -When Migrating from ML Kit for Firebase to the new standalone ML Kit SDK read [this guide](https://developers.google.com/ml-kit/migration). +--- -For Android details read [this](https://developers.google.com/ml-kit/migration/android). +## πŸ”„ Migration -For iOS details read [this](https://developers.google.com/ml-kit/migration/ios). +If you are migrating from **ML Kit for Firebase** to the standalone **ML Kit SDK**, see: -## Example app +- [Migration guide](https://developers.google.com/ml-kit/migration) +- [Android migration](https://developers.google.com/ml-kit/migration/android) +- [iOS migration](https://developers.google.com/ml-kit/migration/ios) -Find the example app [here](https://github.com/flutter-ml/google_ml_kit_flutter/tree/master/packages/example). +--- -### Consuming image streams on Android +## πŸ“± Example App -Until https://github.com/flutter/flutter/issues/145961 is resolved, the most recent version of the camera package doesn't support the required image formats. To make things work, manually add the legacy plugin via the instructions from https://pub.dev/packages/camera_android. +A working example is available at: +`packages/example` β€” or view it online: +https://github.com/flutter-ml/google_ml_kit_flutter/tree/master/packages/example -## Contributing +### For Android image streams +Until [Flutter issue #145961](https://github.com/flutter/flutter/issues/145961) is resolved, you may need to add the **legacy camera plugin** manually. See [`camera_android`](https://pub.dev/packages/camera_android) for instructions. -Contributions are welcome. -In case of any problems look at [existing issues](https://github.com/flutter-ml/google_ml_kit_flutter/issues), if you cannot find anything related to your problem then open an issue. -Create an issue before opening a [pull request](https://github.com/flutter-ml/google_ml_kit_flutter/pulls) for non trivial fixes. -In case of trivial fixes open a [pull request](https://github.com/flutter-ml/google_ml_kit_flutter/pulls) directly. +--- + +## 🀝 Contributing + +Contributions are welcome! + +- Check existing [issues](https://github.com/flutter-ml/google_ml_kit_flutter/issues). +- For **non-trivial** changes, please open an issue first to discuss. +- For **trivial** fixes (typos, formatting), open a [pull request](https://github.com/flutter-ml/google_ml_kit_flutter/pulls) directly.