Google ML Kit を使った Android アプリへの OCR 実装
Android アプリの初回起動時から、ネットワーク接続がなくても写真を読み取るには、ML Kit の同梱型テキスト認識器を使います。この例では、既存画像の選択と、システムのカメラアプリによるフルサイズの写真撮影という二つの入力に対応する、小さな Kotlin アプリを作成します。ラテン文字の認識結果を表示し、画像が空白、読み取り不能、または操作がキャンセルされた場合にも結果を画面に表示します。
前提条件
Kotlin の基礎知識、インストール済みの Android SDK、デバイスまたはエミュレーターが必要です。この例では Android Gradle plugin 9.2.1、Gradle 9.4.1、JDK 21、SDK Platform 36、Build Tools 36.0.0 を使用します。これらは再現可能なバージョンの組み合わせであり、既存アプリのアップグレードを求めるものではありません。別のツールチェーンを使う場合は、AGP 互換性表を参照してください。
JAVA_HOME に JDK、ANDROID_HOME に SDK を設定し、Gradle と SDK の platform-tools ディレクトリを
PATH に追加してください。ビルド時には依存関係を取得するため、ネットワークアクセスが必要です。アプリの minSdk は、Google の
Text Recognition v2 のセットアップ要件に従い、23 に設定しています。以下の実行時の確認には Android 16、API 36 を使用しています。すべての旧 OS や実機のカメラでの動作を確認したものではありません。
Android プロジェクトのセットアップ
TextRecognitionApp という名前の新しい空のディレクトリで始めてください。以下のファイルを、親ディレクトリも含めて指定の相対パスに作成します。各ファイルは完全な内容なので、Android Studio のテンプレートと組み合わせたり、既存プロジェクトのファイルを置き換えたりする必要はありません。
settings.gradle:
pluginManagement {
repositories {
google()
mavenCentral()
gradlePluginPortal()
}
}
dependencyResolutionManagement {
repositories {
google()
mavenCentral()
}
}
rootProject.name = 'TextRecognitionApp'
include ':app'
build.gradle:
plugins {
id 'com.android.application' version '9.2.1' apply false
}
gradle.properties:
android.useAndroidX=true
org.gradle.jvmargs=-Xmx2g
AGP 9 には Kotlin のコンパイル機能が含まれるため、このプロジェクトでは別途 Kotlin Android プラグインを適用しません。
ML Kit の依存関係の追加
app/build.gradle を作成します。ビュー バインディングにより、後ほど追加するレイアウトから ActivityMainBinding が生成されます。
plugins {
id 'com.android.application'
}
android {
namespace 'com.example.textrecognition'
compileSdk 36
defaultConfig {
applicationId 'com.example.textrecognition'
minSdk 23
targetSdk 36
versionCode 1
versionName '1.0'
}
compileOptions {
sourceCompatibility JavaVersion.VERSION_17
targetCompatibility JavaVersion.VERSION_17
}
buildFeatures {
viewBinding true
}
}
dependencies {
implementation 'androidx.activity:activity-ktx:1.9.3'
implementation 'androidx.appcompat:appcompat:1.7.0'
implementation 'com.google.android.gms:play-services-tasks:18.2.0'
implementation 'com.google.mlkit:text-recognition:16.0.1'
}
最後の依存関係は、ラテン文字用モデルをアプリに同梱します。もう一つの選択肢である
com.google.android.gms:play-services-mlkit-text-recognition:19.0.1 は、Google Play services 経由でモデルをダウンロードします。アプリの初回ダウンロードサイズは小さくなりますが、モデルの準備ができるまで認識結果を返せません。どちらか一方を選んでください。この手順では同梱型モデルのみを使用します。それぞれの利点と制約、ダウンロードの選択肢については、Google のインストール方法の比較で説明されています。
権限の設定
Photo Pickerでは、写真ライブラリ全体への権限を求めずに、選択した画像へのアクセス権を取得できます。PickVisualMedia は、ピッカーが利用できない場合の最終フォールバックとして ACTION_OPEN_DOCUMENT を使用します。インストール済みのカメラアプリに撮影を委ねることで、カメラへの直接アクセス権限の要求も避けられます。このカメラインテントを使う方法は Android のドキュメントに記載されています。
app/src/main/AndroidManifest.xml を作成します。
<manifest xmlns:android="http://schemas.android.com/apk/res/android">
<application
android:label="Text Recognition"
android:theme="@style/Theme.AppCompat.Light.NoActionBar">
<activity android:name=".MainActivity" android:exported="true">
<intent-filter>
<action android:name="android.intent.action.MAIN" />
<category android:name="android.intent.category.LAUNCHER" />
</intent-filter>
</activity>
<provider
android:name="androidx.core.content.FileProvider"
android:authorities="${applicationId}.fileprovider"
android:exported="false"
android:grantUriPermissions="true">
<meta-data
android:name="android.support.FILE_PROVIDER_PATHS"
android:resource="@xml/file_paths" />
</provider>
</application>
</manifest>
app/src/main/res/xml/file_paths.xml を作成します。
<paths xmlns:android="http://schemas.android.com/apk/res/android">
<cache-path name="ocr_camera" path="ocr-camera/" />
</paths>
FileProviderは、この撮影用ディレクトリだけをコンテンツ URI 経由で公開します。TakePicture はカメラに URI を渡し、小さなサムネイルを返す代わりに、フルサイズの画像を書き込めるようにします。
レイアウトの作成
app/src/main/res/layout/activity_main.xml を作成します。結果は選択してコピーできます。ステータスメッセージにも同じビューを使い、操作に失敗した後も表示を維持します。
<LinearLayout xmlns:android="http://schemas.android.com/apk/res/android"
android:layout_width="match_parent"
android:layout_height="match_parent"
android:orientation="vertical"
android:padding="16dp">
<Button
android:id="@+id/btnCapture"
android:layout_width="match_parent"
android:layout_height="wrap_content"
android:text="Capture image" />
<Button
android:id="@+id/btnGallery"
android:layout_width="match_parent"
android:layout_height="wrap_content"
android:text="Choose image" />
<ScrollView
android:layout_width="match_parent"
android:layout_height="0dp"
android:layout_marginTop="16dp"
android:layout_weight="1">
<TextView
android:id="@+id/textView"
android:layout_width="match_parent"
android:layout_height="wrap_content"
android:text="Choose or capture an image."
android:textIsSelectable="true"
android:textSize="16sp" />
</ScrollView>
</LinearLayout>
OCR 機能の実装
app/src/main/java/com/example/textrecognition/MainActivity.kt を作成します。外部アクティビティまたは認識処理の完了待ちの間は、両方のボタンを無効にします。デコードはワーカースレッドで実行し、ML Kit には
InputImage.fromFilePath() を介して選択した URI を渡します。
ピッカーやカメラを開いている間に、Android がアクティビティを再生成する場合があります。ランチャーを一定の順序で登録し、操作の追加状態を保存することで、再生成後のアクティビティで結果を受け取れます。再生成前に認識中だった処理は再開しません。新しい画面では、画像をもう一度選択するよう案内します。
package com.example.textrecognition
import android.content.ActivityNotFoundException
import android.net.Uri
import android.os.Bundle
import androidx.activity.enableEdgeToEdge
import androidx.activity.result.PickVisualMediaRequest
import androidx.activity.result.contract.ActivityResultContracts
import androidx.appcompat.app.AppCompatActivity
import androidx.core.content.FileProvider
import androidx.core.view.ViewCompat
import androidx.core.view.WindowInsetsCompat
import com.example.textrecognition.databinding.ActivityMainBinding
import com.google.android.gms.tasks.TaskCompletionSource
import com.google.mlkit.vision.common.InputImage
import com.google.mlkit.vision.text.TextRecognition
import com.google.mlkit.vision.text.latin.TextRecognizerOptions
import java.io.File
import java.io.IOException
import java.util.concurrent.Executors
class MainActivity : AppCompatActivity() {
private lateinit var binding: ActivityMainBinding
private var pendingCameraName: String? = null
private var pendingPicker = false
private var recognizing = false
private val cameraDirectory: File
get() = File(cacheDir, "ocr-camera")
private val takePictureLauncher = registerForActivityResult(
ActivityResultContracts.TakePicture()
) { success ->
val name = pendingCameraName
pendingCameraName = null
if (name == null) {
setBusy(false)
showMessage("The camera result is no longer available.")
} else {
val file = File(cameraDirectory, name)
if (success && file.isFile && file.length() > 0) {
processImage(cameraUri(file), file)
} else {
file.delete()
setBusy(false)
showMessage(if (success) "The camera returned no image." else "Capture canceled.")
}
}
}
private val selectPictureLauncher = registerForActivityResult(
ActivityResultContracts.PickVisualMedia()
) { uri ->
pendingPicker = false
if (uri != null) {
processImage(uri)
} else {
setBusy(false)
showMessage("Selection canceled.")
}
}
override fun onCreate(savedInstanceState: Bundle?) {
super.onCreate(savedInstanceState)
enableEdgeToEdge()
binding = ActivityMainBinding.inflate(layoutInflater)
setContentView(binding.root)
val padding = binding.root.paddingLeft
ViewCompat.setOnApplyWindowInsetsListener(binding.root) { view, insets ->
val bars = insets.getInsets(
WindowInsetsCompat.Type.systemBars() or WindowInsetsCompat.Type.displayCutout()
)
view.setPadding(padding + bars.left, padding + bars.top,
padding + bars.right, padding + bars.bottom)
insets
}
pendingCameraName = savedInstanceState?.getString("pendingCameraName")
pendingPicker = savedInstanceState?.getBoolean("pendingPicker") ?: false
savedInstanceState?.getString("recognizedText")?.let { binding.textView.text = it }
if (savedInstanceState?.getBoolean("recognizing") == true) {
showMessage("Recognition interrupted. Select an image again.")
}
setBusy(pendingCameraName != null || pendingPicker)
// A killed process cannot run its completion listener to delete abandoned captures.
cameraDirectory.listFiles()?.filter {
it.name != pendingCameraName && it.lastModified() < System.currentTimeMillis() - 86_400_000
}?.forEach { it.delete() }
binding.btnCapture.setOnClickListener { captureImage() }
binding.btnGallery.setOnClickListener { selectImage() }
}
private fun selectImage() {
pendingPicker = true
setBusy(true)
showMessage("Waiting for an image…")
try {
selectPictureLauncher.launch(
PickVisualMediaRequest(ActivityResultContracts.PickVisualMedia.ImageOnly)
)
} catch (error: ActivityNotFoundException) {
cancelSelection()
} catch (error: SecurityException) {
cancelSelection()
}
}
private fun cancelSelection() {
pendingPicker = false
setBusy(false)
showMessage("The image picker could not be opened.")
}
private fun captureImage() {
try {
if (!cameraDirectory.isDirectory && !cameraDirectory.mkdirs()) {
throw IOException("Could not create capture directory")
}
val imageFile = File.createTempFile("IMG_", ".jpg", cameraDirectory)
pendingCameraName = imageFile.name
setBusy(true)
showMessage("Waiting for the camera…")
takePictureLauncher.launch(cameraUri(imageFile))
} catch (error: IOException) {
cancelCapture()
} catch (error: ActivityNotFoundException) {
cancelCapture()
} catch (error: SecurityException) {
cancelCapture()
}
}
private fun cameraUri(file: File): Uri =
FileProvider.getUriForFile(this, "${packageName}.fileprovider", file)
private fun cancelCapture() {
pendingCameraName?.let { File(cameraDirectory, it).delete() }
pendingCameraName = null
setBusy(false)
showMessage("The camera could not be opened.")
}
private fun processImage(uri: Uri, temporaryFile: File? = null) {
recognizing = true
setBusy(true)
showMessage("Recognizing text…")
val recognizer = TextRecognition.getClient(TextRecognizerOptions.DEFAULT_OPTIONS)
val decoded = TaskCompletionSource<InputImage>()
val executor = Executors.newSingleThreadExecutor()
executor.execute {
try {
decoded.setResult(InputImage.fromFilePath(applicationContext, uri))
} catch (error: Exception) {
decoded.setException(error)
}
}
executor.shutdown()
decoded.task.continueWithTask { task -> recognizer.process(task.result) }
.addOnSuccessListener { visionText ->
if (!isDestroyed) {
showMessage(visionText.text.ifBlank { "No text found. Try a clearer image." })
}
}
.addOnFailureListener {
if (!isDestroyed) showMessage("The image could not be read. Try another image.")
}
.addOnCompleteListener {
// Activity-scoped listeners stop on onStop; this cleanup must still run.
recognizer.close()
temporaryFile?.delete()
recognizing = false
if (!isDestroyed) setBusy(false)
}
}
private fun setBusy(value: Boolean) {
binding.btnCapture.isEnabled = !value
binding.btnGallery.isEnabled = !value
}
private fun showMessage(message: String) {
binding.textView.text = message
}
override fun onSaveInstanceState(outState: Bundle) {
outState.putString("pendingCameraName", pendingCameraName)
outState.putBoolean("pendingPicker", pendingPicker)
outState.putBoolean("recognizing", recognizing)
outState.putString("recognizedText", binding.textView.text.toString())
super.onSaveInstanceState(outState)
}
}
インセットリスナーにより、操作用の UI がシステムバーやディスプレイカットアウトに重ならないようにします。アプリは再生成後も認識済みのテキストを保持しますが、認識履歴の保存やプレビューの保持は行いません。撮影ごとに新しいキャッシュファイル名を使います。完了またはキャンセルされた撮影のファイルは削除します。放棄された撮影ファイルは、1日経過後の次回以降の起動時に削除します。カメラがまだ書き込んでいる可能性があるため、onDestroy() 内の保留中の撮影ファイルはそのままにしてください。
ピッカーで選択した画像は、その場の操作のために読み取ります。元のファイルは削除しません。認識タスクは、アクティビティが破棄されても、完了するまで認識器を所有します。そのコールバックが、新しいアクティビティインスタンスのテキストを置き換えることはありません。
OCR の精度とパフォーマンスの最適化
まずは、印刷された文字を明るい場所で鮮明に撮影した写真を使ってください。Google の入力画像のガイドラインでは、1文字あたり最低 16 × 16 ピクセルを推奨しています。約 24 × 24 を超えると、一般に文字を大きくしても精度は向上しません。文字の読みやすさを保ちながら、不要な背景を切り取ってください。
この処理は静止画像用であり、リアルタイムのカメラ解析ではありません。CameraX のプレビューには、専用の権限、フレームの回転、バックプレッシャーへの対応が必要です。中国語、デーヴァナーガリー文字、日本語、韓国語には、ここで使うラテン文字用の設定ではなく、それぞれに対応するモデルの依存関係と認識器のオプションも必要です。
アプリケーションのテスト
プロジェクトディレクトリからデバッグ APK をビルドします。再実行すると APK を含むビルド出力は置き換わりますが、ソースファイルは上書きしません。
gradle --no-daemon --max-workers=2 :app:assembleDebug
対象デバイスを接続し、YOUR_DEVICE_SERIAL を
adb devices で確認したシリアル番号に置き換えてください。-r を指定してインストールすると、アプリデータを保持したまま、このサンプルアプリを置き換えます。
adb -s YOUR_DEVICE_SERIAL install -r app/build/outputs/apk/debug/app-debug.apk &&
adb -s YOUR_DEVICE_SERIAL shell am start -n com.example.textrecognition/.MainActivity
「INVOICE 12345」などの大きな文字を含むローカル画像を選択してください。スクロール可能な結果欄にその文字が表示され、両方のボタンが再び使えることを確認します。初回起動時のオフライン動作を確認するには、アプリをインストールして起動せずに、デバイスのネットワークを切断してからアプリを開き、ローカルの写真を選択してください。クラウド上にあるピッカー項目は、画像データの取得に接続が必要な場合があります。
この例を応用する前に、以下の結果を確認してください。
| 入力または中断 | 期待される結果 |
|---|---|
| 空白の画像 | 「No text found. Try a clearer image.」 |
| 読み取り不能または存在しない画像 | 「The image could not be read. Try another image.」 |
| 選択せずにピッカーを閉じる | 「Selection canceled.」と表示され、両方のボタンが有効になる |
| 撮影をキャンセル | 「Capture canceled.」と表示され、空の撮影ファイルが削除される |
| カメラがデータを書き込まずに成功を報告 | 「The camera returned no image.」と表示され、撮影ファイルが削除される |
| ピッカーやカメラを開いた状態で回転 | 保留中の結果が引き続き元の操作に対応する |
| 認識中にアクティビティを再生成 | 「Recognition interrupted. Select an image again.」と表示され、操作用の UI が有効になる |
| 認識後に回転 | 認識済みのテキストが保持される |
この例は、同梱のラテン文字用モデルを使い、Android 16 エミュレーターで動作確認しています。フォーカス、露出、カメラアプリの互換性は実機でテストしてください。回転した JPEG には正しい向きのメタデータも必要です。エンコード時の向きが誤った画像を、端末の回転で修正できるとは考えないでください。
トラブルシューティング
文字が見つからないと表示される場合は、まず印刷された文字が大きく、より鮮明な画像を試してください。認識結果が空であることと、ファイルを読み取れないことは別の問題です。撮影しても画像が返らない場合は、カメラアプリと、FileProvider のオーソリティ、キャッシュパス、マニフェストのリソース名をまとめて確認してください。
オンラインにした後でしか認識器が動作しない場合は、非同梱型の依存関係を使っている可能性があります。この同梱型の例にモデルのダウンロード処理を追加する前に、解決済みの Gradle 依存関係を確認してください。ビルド時に ActivityMainBinding を解決できない場合は、レイアウトのファイル名とビュー バインディングの設定を確認してください。
アップロードしたファイルをサーバーで処理する別の方法については、/document/ocr のドキュメントを参照してください。
