OpenCV と Tesseract による Android カメラ OCR の構築
CameraX、OpenCV、Tesseract4Android を使い、カメラのライブプレビューから印刷された文字をデバイス上で認識します。認識した英語をプレビューの下に表示し、一度に一つのフレームを処理する Java アクティビティを作成します。終了したアクティビティセッションの結果は破棄します。このオープンソース OCR SDK を使う方法では、モデルと前処理を制御できますが、カメラのフレームレートでの認識を保証するものではありません。
前提条件
- Java 対応の Android Studio、Android SDK Platform 36、Build Tools 36.0.0
- Android API 23 以降を実行するカメラ搭載 Android デバイス
- Java と Android Views の基礎知識
このサンプルでは、CameraX 1.6.2、OpenCV 4.13.0、Tesseract4Android 4.8.0 にバージョンを固定します。ビルドには Android Gradle Plugin 9.2.1、Gradle 9.4.1、JDK 21 を使い、Java 17 のソース互換性を設定します。現在の CameraX では最小要件が API 23 に引き上げられています。ライブラリのマニフェストを上書きして、この組み合わせを API 21 で無理に実行しないでください。このサンプルの実行時検証には Android 16 x86_64 エミュレーターを使っています。最小要件の OS と実機では、フォーカス、照明、継続使用時のメモリ使用量、認識速度も含め、別途テストが必要です。
Android Studio プロジェクトの設定
Android Studio で Empty Views Activity プロジェクトを作成します。Java と Groovy DSL を選択し、Minimum SDK を API 23 に設定します。レイアウトとアクティビティの置き換えで既存のアプリケーションコードを上書きしないよう、新しいプロジェクトを使ってください。パッケージ宣言、名前空間、マニフェストのランチャーアクティビティ項目、テーマはそのまま残します。
gradle.properties に android.useAndroidX=true を設定します。以下のアプリ設定では、ローカルで動かすこのサンプル用に targetSdk 34 を維持します。アプリを配布する前に、デプロイ先のターゲットを別途選択してテストしてください。
依存関係の追加:OpenCV と Tesseract
プロジェクトレベルの settings.gradle
settings.gradle の既存の dependencyResolutionManagement ブロックに、以下のリポジトリを統合します。生成済みのプラグインリポジトリとアプリモジュールの指定は残します。
dependencyResolutionManagement {
repositories {
google()
mavenCentral()
maven { url 'https://jitpack.io' }
}
}
アプリレベルの build.gradle
アプリの既存の android ブロックに以下の設定を統合し、依存関係を追加します。名前空間とアプリケーション ID はそのまま残します。公式の OpenCV Android アーティファクトは
org.opencv:opencv で、Tesseract4Android は JitPack から解決されます。
android {
compileSdk 36
defaultConfig {
minSdk 23
targetSdk 34
}
compileOptions {
sourceCompatibility JavaVersion.VERSION_17
targetCompatibility JavaVersion.VERSION_17
}
}
dependencies {
implementation 'androidx.activity:activity:1.9.3'
implementation 'androidx.camera:camera-camera2:1.6.2'
implementation 'androidx.camera:camera-lifecycle:1.6.2'
implementation 'androidx.camera:camera-view:1.6.2'
implementation 'org.opencv:opencv:4.13.0'
implementation 'cz.adaptech.tesseract4android:tesseract4android:4.8.0'
}
ネイティブ互換性は、両方のライブラリと APK のパッケージングに依存します。Tesseract4Android は、4.8.0 リリースで 16 KB 対応を追加しました。OpenCV と CameraX は、どちらも前述の固定バージョンを使ってください。OpenCV 4.9.0 と CameraX 1.3.4 には、4 KB 境界にアラインされた 64 ビットライブラリが含まれています。リリースビルドでは、推移的に依存するネイティブライブラリも含め、最終的な APK またはアプリバンドルに対して Android の 16 KB 検証手順を実施してください。
Tesseract 学習済みデータファイルのコピー
tessdata 4.0.0 の英語モデルを
app/src/main/assets/tessdata/eng.traineddata に配置し、必要に応じてアセットディレクトリを作成します。GitHub のプレビューページではなく、バイナリそのものをダウンロードしてください。SHA-256 は daa0c97d651c19fba3b25e81317cd697e9908c8208090c94c3905381c23fc047 です。以下の OCRManager.java クラス全体を、MainActivity と同じパッケージに追加します。このクラスはアセットを一時ファイルにコピーし、コピーに成功した場合にのみインストールします。また、tessdata の親ディレクトリで Tesseract を初期化し、close() を通じてネイティブリソースを解放します。
モデルは APK に同梱されるため、初回起動時もオフラインで動作します。初期化時には、デバイス上にアプリ専用のコピーも作成します。フレームと認識したテキストはメモリ内にとどまり、このサンプルではアップロードも保存もしません。アクティビティを再起動すると、新しいスキャンが始まります。
OCR マネージャーの実装
以下のクラス全体を、アプリのパッケージ内に OCRManager.java として保存します(パッケージ宣言を追加してください)。生成、使用、終了処理は、一つのバックグラウンドワーカーで行います。各ビットマップの所有権は呼び出し元が保持します。
import android.content.Context;
import android.graphics.Bitmap;
import com.googlecode.tesseract.android.TessBaseAPI;
import java.io.File;
import java.io.FileOutputStream;
import java.io.IOException;
import java.io.InputStream;
public final class OCRManager implements AutoCloseable {
private TessBaseAPI tessBaseAPI;
public OCRManager(Context context) throws IOException {
File root = new File(context.getFilesDir(), "tesseract-4.0.0");
File data = new File(root, "tessdata");
if (!data.isDirectory() && !data.mkdirs()) {
throw new IOException("Could not create tessdata directory");
}
File model = new File(data, "eng.traineddata");
if (!model.isFile() || model.length() == 0) {
File temporary = File.createTempFile("eng-", ".tmp", data);
try {
try (InputStream input = context.getAssets().open("tessdata/eng.traineddata");
FileOutputStream output = new FileOutputStream(temporary)) {
byte[] buffer = new byte[8192];
int count;
while ((count = input.read(buffer)) != -1) {
output.write(buffer, 0, count);
}
}
if (temporary.length() == 0 || !temporary.renameTo(model)) {
throw new IOException("Could not install English model");
}
} finally {
temporary.delete();
}
}
TessBaseAPI api = new TessBaseAPI();
try {
if (!api.init(root.getAbsolutePath(), "eng")) {
throw new IOException("Could not initialize Tesseract");
}
tessBaseAPI = api;
} finally {
if (tessBaseAPI == null) api.recycle();
}
}
public String extractTextFromImage(Bitmap bitmap) {
if (tessBaseAPI == null) throw new IllegalStateException("OCR manager is closed");
if (bitmap == null || bitmap.isRecycled()) {
throw new IllegalArgumentException("A readable bitmap is required");
}
try {
tessBaseAPI.setImage(bitmap);
String text = tessBaseAPI.getUTF8Text();
if (text == null) throw new IllegalStateException("Recognition failed");
return text;
} finally {
tessBaseAPI.clear();
}
}
@Override
public void close() {
if (tessBaseAPI != null) {
tessBaseAPI.recycle();
tessBaseAPI = null;
}
}
}
単一画像には try-with-resources を使います。画像を繰り返し処理する場合は、直列実行のエグゼキューターで一つのマネージャーを保持し、最後のタスクの後に
close() をキューに追加します。OCR の実行中に UI スレッドから終了処理を行わないでください。コピーに失敗したファイルがモデルとしてインストールされることはありません。異なるリリースのモデルを配布するときは、アプリ専用ディレクトリに新しい名前を使ってください。
カメラアクセスと権限の設定
AndroidManifest.xml の <manifest> 直下に、以下の要素を追加します。このファイルには、すでに android XML 名前空間が宣言されています。
<uses-permission android:name="android.permission.CAMERA" />
<uses-feature android:name="android.hardware.camera" android:required="true" />
<uses-feature android:name="android.hardware.camera.autofocus" android:required="false" />
以下のアクティビティは、カメラを開始する前に実行時権限を要求します。拒否した場合は、Android のアプリ設定でカメラへのアクセスを許可し、既存のアクティビティに戻ってください。onResume() が現在の権限を確認して初期化を開始するため、プロセスを再起動する必要はありません。Android では、保護されたデータにアクセスする前に権限を確認する必要があります。同梱モデルやアプリ専用ファイルには、ストレージ権限は不要です。
カメラのライブ映像の統合
res/layout/activity_main.xml を以下のレイアウトに置き換えます。
<?xml version="1.0" encoding="utf-8"?>
<LinearLayout xmlns:android="http://schemas.android.com/apk/res/android"
android:layout_width="match_parent"
android:layout_height="match_parent"
android:orientation="vertical">
<androidx.camera.view.PreviewView
android:id="@+id/preview_view"
android:layout_width="match_parent"
android:layout_height="0dp"
android:layout_weight="1" />
<TextView
android:id="@+id/text_result"
android:layout_width="match_parent"
android:layout_height="wrap_content"
android:maxLines="6"
android:padding="16dp"
android:textSize="16sp" />
</LinearLayout>
リアルタイム OCR 機能の実装
生成済みのパッケージ宣言を残し、MainActivity.java を以下のインポートとクラスに置き換えます。CameraX は、プレビューとアナライザーをアクティビティのライフサイクルに結び付けます。初期化、認識、Tesseract のリソース解放は、すべて同じ直列実行ワーカーで行います。CameraX の画像解析の要件に従い、スキップしたフレームや失敗した場合も含め、各フレームを
finally ブロックで閉じます。
import android.Manifest;
import android.content.pm.PackageManager;
import android.graphics.Bitmap;
import android.graphics.Matrix;
import android.os.Bundle;
import android.view.OrientationEventListener;
import android.view.Surface;
import android.widget.TextView;
import androidx.activity.ComponentActivity;
import androidx.activity.result.ActivityResultLauncher;
import androidx.activity.result.contract.ActivityResultContracts;
import androidx.camera.core.CameraSelector;
import androidx.camera.core.ImageAnalysis;
import androidx.camera.core.ImageProxy;
import androidx.camera.core.Preview;
import androidx.camera.lifecycle.ProcessCameraProvider;
import androidx.camera.view.PreviewView;
import androidx.core.content.ContextCompat;
import androidx.lifecycle.Lifecycle;
import com.google.common.util.concurrent.ListenableFuture;
import java.io.IOException;
import java.util.concurrent.ExecutionException;
import java.util.concurrent.ExecutorService;
import java.util.concurrent.Executors;
import org.opencv.android.OpenCVLoader;
import org.opencv.android.Utils;
import org.opencv.core.Mat;
import org.opencv.imgproc.Imgproc;
public class MainActivity extends ComponentActivity {
private final ExecutorService worker = Executors.newSingleThreadExecutor();
private volatile boolean stopped;
private volatile boolean active;
private volatile int session;
private boolean initializing;
private OCRManager ocr;
private PreviewView previewView;
private TextView resultText;
private ProcessCameraProvider cameraProvider;
private Preview preview;
private ImageAnalysis analysis;
private OrientationEventListener orientationListener;
private final ActivityResultLauncher<String> cameraPermission = registerForActivityResult(
new ActivityResultContracts.RequestPermission(), granted -> {
if (granted) initializeOCR();
else resultText.setText("Camera permission is required to scan text");
});
@Override
protected void onCreate(Bundle savedInstanceState) {
super.onCreate(savedInstanceState);
setContentView(R.layout.activity_main);
previewView = findViewById(R.id.preview_view);
resultText = findViewById(R.id.text_result);
if (ContextCompat.checkSelfPermission(this, Manifest.permission.CAMERA)
!= PackageManager.PERMISSION_GRANTED) {
cameraPermission.launch(Manifest.permission.CAMERA);
}
}
@Override
protected void onResume() {
super.onResume();
active = true;
if (ContextCompat.checkSelfPermission(this, Manifest.permission.CAMERA)
== PackageManager.PERMISSION_GRANTED) {
initializeOCR();
}
}
@Override
protected void onPause() {
active = false;
session++;
super.onPause();
}
private void initializeOCR() {
if (stopped || initializing) return;
initializing = true;
resultText.setText("Loading text recognition…");
worker.execute(() -> {
try {
if (!OpenCVLoader.initLocal()) throw new IOException("OpenCV did not load");
ocr = new OCRManager(getApplicationContext());
runOnUiThread(() -> {
if (!stopped) {
resultText.setText("Point the camera at printed text");
startCamera();
}
});
} catch (IOException | RuntimeException | UnsatisfiedLinkError error) {
showResult("Text recognition could not be initialized");
}
});
}
private void startCamera() {
ListenableFuture<ProcessCameraProvider> future = ProcessCameraProvider.getInstance(this);
future.addListener(() -> {
if (stopped) return;
try {
cameraProvider = future.get();
preview = new Preview.Builder().build();
preview.setSurfaceProvider(previewView.getSurfaceProvider());
analysis = new ImageAnalysis.Builder()
.setBackpressureStrategy(ImageAnalysis.STRATEGY_KEEP_ONLY_LATEST)
.build();
analysis.setAnalyzer(worker, this::analyze);
cameraProvider.bindToLifecycle(this, CameraSelector.DEFAULT_BACK_CAMERA,
preview, analysis);
orientationListener = new OrientationEventListener(this) {
@Override
public void onOrientationChanged(int degrees) {
if (degrees == ORIENTATION_UNKNOWN) return;
int rotation = degrees >= 315 || degrees < 45 ? Surface.ROTATION_0
: degrees < 135 ? Surface.ROTATION_270
: degrees < 225 ? Surface.ROTATION_180 : Surface.ROTATION_90;
analysis.setTargetRotation(rotation);
}
};
if (getLifecycle().getCurrentState().isAtLeast(Lifecycle.State.STARTED)
&& orientationListener.canDetectOrientation()) {
orientationListener.enable();
}
} catch (InterruptedException error) {
Thread.currentThread().interrupt();
showResult("The camera could not be started");
} catch (ExecutionException | RuntimeException error) {
showResult("The camera could not be started");
}
}, ContextCompat.getMainExecutor(this));
}
private void analyze(ImageProxy frame) {
int frameSession = session;
Bitmap source = null;
Bitmap upright = null;
Bitmap processed = null;
try {
if (stopped || !active) return;
source = frame.toBitmap();
Matrix rotation = new Matrix();
rotation.postRotate(frame.getImageInfo().getRotationDegrees());
upright = Bitmap.createBitmap(source, 0, 0, source.getWidth(), source.getHeight(),
rotation, true);
processed = preprocessImage(upright);
String text = ocr.extractTextFromImage(processed);
showFrameResult(text.trim().isEmpty() ? "No text found" : text, frameSession);
} catch (RuntimeException error) {
showFrameResult("This frame could not be recognized", frameSession);
} finally {
if (processed != null) processed.recycle();
if (upright != null && upright != source) upright.recycle();
if (source != null) source.recycle();
frame.close();
}
}
private Bitmap preprocessImage(Bitmap source) {
Mat rgba = new Mat();
Mat gray = new Mat();
Bitmap result = null;
try {
Utils.bitmapToMat(source, rgba);
Imgproc.cvtColor(rgba, gray, Imgproc.COLOR_RGBA2GRAY);
Imgproc.threshold(gray, gray, 0, 255, Imgproc.THRESH_BINARY | Imgproc.THRESH_OTSU);
result = Bitmap.createBitmap(gray.cols(), gray.rows(), Bitmap.Config.ARGB_8888);
Utils.matToBitmap(gray, result);
return result;
} catch (RuntimeException error) {
if (result != null) result.recycle();
throw error;
} finally {
gray.release();
rgba.release();
}
}
private void showResult(String text) {
runOnUiThread(() -> {
if (!stopped) resultText.setText(text);
});
}
private void showFrameResult(String text, int frameSession) {
runOnUiThread(() -> {
if (!stopped && active && session == frameSession) resultText.setText(text);
});
}
@Override
protected void onStart() {
super.onStart();
if (orientationListener != null && orientationListener.canDetectOrientation()) {
orientationListener.enable();
}
}
@Override
protected void onStop() {
if (orientationListener != null) orientationListener.disable();
super.onStop();
}
@Override
protected void onDestroy() {
stopped = true;
if (orientationListener != null) orientationListener.disable();
if (analysis != null) analysis.clearAnalyzer();
if (cameraProvider != null && preview != null && analysis != null) {
cameraProvider.unbind(preview, analysis);
}
// Cleanup follows any running frame; recycling on the UI thread would race with OCR.
worker.execute(() -> {
if (ocr != null) ocr.close();
});
worker.shutdown();
super.onDestroy();
}
}
パフォーマンスとメモリ使用量の最適化
STRATEGY_KEEP_ONLY_LATEST は、ビットマップのコピーをキューに蓄積せずに、処理待ちの量を制限します。アナライザーは直列実行ワーカー上で同期的に動作するため、Tesseract が二つのフレームを同時に処理することはありません。ImageProxy.toBitmap() API がカメラバッファーのレイアウトを処理し、その結果を回転させることでフレームの向きのメタデータを反映します。前処理では、Otsu 法による二値化の前に RGBA を単一のグレースケールチャンネルに変換し、失敗した場合も両方の OpenCV 行列を解放します。
遠くの文字や小さな文字には、近づくか、解析解像度を調整してください。ぼかしの追加や解像度の引き下げを行う前に、認識品質を測定してください。二値化は印刷文字に有効な場合がありますが、実際の照明条件で元の画像と比較してください。
多言語の文字認識への対応
この実行可能なサンプルは英語を認識します。Tesseract は、eng+fra+deu のような文字列で、インストール済みの複数言語を初期化できます。ただし、この引数の変更だけでは不十分です。対応する学習済みデータファイルを、それぞれ事前にインストールする必要があります。マネージャーを拡張する場合は、それらのモデルと失敗ケースを別途テストしてください。ワーカーがフレームを認識している間は、マネージャーを置き換えないでください。
テストとよくある問題のデバッグ
アプリを実行し、カメラへのアクセスを許可します。「Loading text recognition…」の表示後、鮮明に大きく印刷された英語のテキストにカメラを向けます。プレビュー下のメッセージが認識したテキストに置き換わり、何もないフレームでは「No text found」と表示されます。結果は表示中の動画フレームごとではなく、認識が完了するたびに更新されます。
「Text recognition could not be initialized」と表示された場合は、同梱モデルのパスとチェックサムを確認し、次にデバイスログでネイティブライブラリの読み込みエラーを確認してください。アセットが存在しないか空の場合はコピー中に失敗し、空でなくても破損したモデルは初期化に失敗します。空でないアプリ専用モデルは再利用されるため、インストール済みの破損したコピーを修正するには、このサンプルアプリのデータを消去するか、再インストールする必要があります。これにより、サンプルのアプリ専用モデルのコピーが削除されます。異なるモデルを配布するときは、新しいディレクトリ名を使ってください。
「The camera could not be started」は、カメラのバインドに失敗したことを示します。デバイスに使用可能な背面カメラがあるか確認してください。「This frame could not be recognized」はフレーム単位の失敗で、後続のフレームは引き続き処理できます。権限を拒否してから「設定」で許可する操作、アプリを離れて戻る操作、アクティビティの再生成をテストしてください。一時停止前から処理中だった結果で、現在のセッションのフィードバックを置き換えてはいけません。
Android 16 では、合成した「HELLO ANDROID 123」画像が、このアクティビティのアナライザーで四つすべての回転方向で処理され、空白画像では「No text found」と表示されました。エミュレーターのカメラからも、CameraX を通じて繰り返しフレームが供給されました。これらの検証は、制御された入力を使って変換とライフサイクル処理を確認するもので、実機のカメラがページをどの程度正確に読み取るかを測定するものではありません。
配布前に、対象デバイスで四つすべての向き、権限の取り消し、長時間のスキャンをテストしてください。ぼけ、照明のむら、小さな文字がある条件で、二値化画像と元の画像を比較してください。適切なフレームの解放と上限のあるキューは処理待ちの蓄積を防ぎますが、OCR の精度、許容できるバッテリー使用量、特定の認識速度を保証するものではありません。
