cses_ocr

On-device OCR Flutter plugin for iOS and Android using:

• iOS: Apple Vision
• Android: Google ML Kit Text Recognition

The plugin exposes a stable Dart API and returns structured OCR data including text, blocks, lines, words, normalized bounding boxes, confidence, image dimensions, and duration.

Version

1.0.0

Flutter compatibility

• Flutter >=3.44.0
• Dart >=3.4.0 <4.0.0
• iOS >=13.0
• Android minSdk 24

Flutter 3.44+ uses Swift Package Manager by default for iOS/macOS native dependencies. CocoaPods remains supported for compatibility. Flutter currently recommends that plugins support both integration paths.

iOS package management

cses_ocr supports both Swift Package Manager and CocoaPods without duplicating the Swift source.

Canonical source:

ios/cses_ocr/Sources/cses_ocr/CsesOcrPlugin.swift

SPM:

ios/cses_ocr/Package.swift

CocoaPods:

ios/cses_ocr.podspec

The podspec points to the exact same Sources/cses_ocr directory used by SPM.

Do not recreate ios/Classes.

Usage

final result = await CsesOcr.instance.recognizeFile(
  imagePath: imagePath,
);

print(result.text);

Or bytes:

final result = await CsesOcr.instance.recognizeBytes(
  bytes: imageBytes,
  options: const OcrOptions(
    language: OcrLanguage.chinese,
    recognitionLevel: OcrRecognitionLevel.accurate,
  ),
);

Long-running requests can be cancelled with a single-use token:

final token = OcrCancellationToken();
final pending = CsesOcr.instance.recognizeFile(
  imagePath: imagePath,
  cancellationToken: token,
);

await token.cancel();

recognitionLevel maps to Apple Vision on iOS. Google ML Kit chooses its own accuracy/performance behavior on Android. mode and engine are stable API extension points; the current implementation supports system text OCR only.

Architecture boundary

The plugin intentionally only provides:

Image → Native OCR → OcrResult

Camera, gallery, document scanning workflows, CSES business logic, GetX, repositories, use cases, analytics, AI, and server APIs remain outside this plugin.

See doc/architecture.md for the complete architecture.

Verification

From the plugin root:

flutter pub get
flutter analyze
flutter test

The checked-in iOS example uses Swift Package Manager. Verify it with Flutter 3.44+:

flutter config --enable-swift-package-manager
cd example
flutter run

To verify CocoaPods compatibility, use a host app created while Swift Package Manager is disabled, add this repository as a path dependency, and build that host. Do not switch the checked-in SPM example in place because its Xcode project already contains SPM package references.

For example:

flutter config --no-enable-swift-package-manager
flutter create --platforms=ios /tmp/cses_ocr_pod_host
cd /tmp/cses_ocr_pod_host
flutter pub add cses_ocr --path /absolute/path/to/cses_ocr
flutter build ios --simulator

Restore your preferred global Flutter setting afterward. Flutter's plugin-author guidance recommends verifying both integration paths while the transition to Swift Package Manager is ongoing.

Publishing

This package is structured as a public Flutter plugin and is intended to be published to pub.dev. Before the first release, run the complete validation suite with Flutter 3.44+:

flutter pub get
flutter analyze
flutter test
flutter pub publish --dry-run

flutter pub publish --dry-run performs the pub.dev validation without uploading the package.

The package metadata points to the public source repository used by this checkout.