Developer

All tutorials

Using the Android OCR Component

easy

This guide will help you integrate the what3words OCR Components into your Android application, enabling users to seamlessly scan and interpret what3words addresses from images.

The what3words OCR Components for Android simplify the process of scanning images to detect and extract what3words addresses using MLKit V2. This library supports multiple sources, including user-uploaded images and live camera feeds.

Android minimum SDK support Generic badge

Features

  • Detects and extracts what3words addresses from images.
  • Supports both live and static image scanning.
  • Flexible APIs to configure scanning preferences.

GitHub Repository

Access the library and detailed documentation on
github icon white Android OCR Component.

Demo

ocr-component-demo

1Get API key
Signup to create key
2Installation

Step 1: Add the Dependency

Include the library in your project’s build.gradle file:

dependencies {
        // W3W API OCR Lib
    implementation 'com.what3words.android:ocr-components:<latest_version>'

        // mlkit
    implementation "com.google.android.gms:play-services-mlkit-text-recognition:$mlkit_core_version"
    implementation "com.google.android.gms:play-services-mlkit-text-recognition-chinese:$mlkit_languages_version"
    implementation "com.google.android.gms:play-services-mlkit-text-recognition-devanagari:$mlkit_languages_version"
    implementation "com.google.android.gms:play-services-mlkit-text-recognition-japanese:$mlkit_languages_version"
    implementation "com.google.android.gms:play-services-mlkit-text-recognition-korean:$mlkit_languages_version"
}
Copied

Replace <latest_version> with the current version of the library, available in the GitHub Repository.

Step 2: Enable Camera Permissions

Update your AndroidManifest.xml to request the necessary permissions:

<manifest xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:tools="http://schemas.android.com/tools">

    <uses-feature android:name="android.hardware.camera.any" />

    <uses-permission android:name="android.permission.CAMERA" />
    <uses-permission android:name="android.permission.INTERNET" />
Copied
3Initialisation

Initialize OCR wrapper by MLKit Language

private lateinit var ocrWrapper: W3WOcrWrapper
private val dataProvider: What3WordsAndroidWrapper by lazy {
    What3WordsV3(
        BuildConfig.W3W_API_KEY,
        this@ComposeOcrScanPopupSampleActivity
    )
}
Copied
private fun getOcrWrapper(): W3WOcrWrapper {
    return W3WOcrMLKitWrapper(
        this,
        viewModel.selectedMLKitLibrary
    )
}
Copied
4Usage

Adding a W3WOcrScanner to Your App

Integrate the W3WOcrScanner component to enable OCR scanning in your app:

W3WOcrScanner(
    ocrScanManager = ocrScanManager,
    onDismiss = {
        // Handle scanner dismissal
    },
    onSuggestionSelected = { suggestion ->
        // Handle address selection
    },
    onError = { error ->
        // Handle the error
    },
)
Copied

Creating an OcrScanManager

The OcrScanManager handles the scanner’s state and logic, utilizing W3WImageDataSource and W3WTextDataSource for scanning and validating addresses.
Note: initialize the OCR component with your API key

val w3WImageDataSource = W3WMLKitImageDataSource.create(
    context = context,
    recognizerOptions = TextRecognizerOptionsInterface.LATIN
)

val w3WTextDataSource = W3WApiTextDataSource.create(context, W3W_API_KEY)

val ocrScanManager = rememberOcrScanManager(
    w3wImageDataSource = w3WImageDataSource,
    w3wTextDataSource = w3WTextDataSource,
)
Copied

Setup Options

You can configure the OCR scanner with either Online or Offline setups depending on your app’s requirements:

  1. Online Setup: Use MLKit for scanning and W3WApiTextDataSource for online validation.
  2. Offline Setup: Use W3WTesseractImageDataSource for offline scanning and W3WSdkTextDataSource for offline validation.
    (Offline setup requires additional licensing; contact us for details.)

Using OcrScannerState for Advanced Control

For more granular control, manage the scanner’s state externally with OcrScannerState:

val ocrScannerState = remember { OcrScannerState() }

W3WOcrScanner(
    ocrScannerState = ocrScannerState,
    onError = { error ->
        // Handle the error
    },
    onDismiss = {
        // Handle scanner dismissal
    },
    onFrameCaptured = { image ->
        // Implement detection logic for what3words addresses
        CompletableDeferred<Unit>().apply {
            complete(Unit) // Signal completion when processing is done
        }
    },
    onSuggestionSelected = { suggestion ->
        // Handle address selection
    },
)
Copied

Styling W3WOcrScanner

Customise the appearance of W3WOcrScanner by overriding its default strings, colours, and text styles:

W3WOcrScanner(
    ...
    scannerStrings = W3WOcrScannerDefaults.defaultStrings(
        scanStateFoundTitle = stringResource(id = R.string.scan_state_found),
    ),
    scannerColors = W3WOcrScannerDefaults.defaultColors(
        bottomDrawerBackground = W3WTheme.colors.background
    ),
    scannerTextStyles = W3WOcrScannerDefaults.defaultTextStyles(
        stateTextStyle = W3WTheme.typography.headline
    ),
    suggestionColors = SuggestionWhat3wordsDefaults.defaultColors(
        background = W3WTheme.colors.background
    ),
    suggestionTextStyles = SuggestionWhat3wordsDefaults.defaultTextStyles(
        wordsTextStyle = W3WTheme.typography.headline
    )
)
Copied

Camera Permission

Ensure your app requests camera permissions by adding the following to your AndroidManifest.xml:

<uses-permission android:name="android.permission.CAMERA" />
Copied
5Migration to v2.0

Upgrading to v2.0 introduces streamlined APIs and integration with the Core Library.

Breaking Changes

  • Core Library Models: v1.x models replaced with Core Library equivalents; manual migration required.
  • W3WOcrMLKitWrapper Removed: Replaced by OcrScanManager for simplified API.
  • MLKitOcrScanActivity Deprecated: No longer supported; use Jetpack Compose for activity integration.

New Features

  • OcrScanManager: Encapsulates scanning logic and state for easier implementation.
  • Flexible Data Sources: Support for online (MLKit + W3WApiTextDataSource) and offline setups.
  • Improved Modularity: Enhanced customisation and integration options for Jetpack Compose.

Migration Steps

  1. Replace the old library version with the latest:
implementation 'com.what3words:w3w-android-ocr-components:$latest'
Copied

Step 2: Replace Deprecated Models

Manually update v1.x models with Core Library equivalents. Refer to the Core Library documentation for details.

Step 3: Use OcrScanManager

Replace W3WOcrMLKitWrapper with the new OcrScanManager for simplified state and logic management:

val ocrScanManager = rememberOcrScanManager(
    w3wImageDataSource = W3WMLKitImageDataSource.create(context, TextRecognizerOptionsInterface.LATIN),
    w3wTextDataSource = W3WApiTextDataSource.create(context, W3W_API_KEY),
)

W3WOcrScanner(ocrScanManager = ocrScanManager, ...)
Copied

Step 4: Remove MLKitOcrScanActivity

MLKitOcrScanActivity has been deprecated. Use Jetpack Compose for standalone scanning activities.

6Sample App

The OCR component repository includes a sample app demonstrating the usage of the what3words OCR component.

Mobile AppDetect if text looks like a 3 word addressAndroid

Related tutorials