在 Android 上使用 ML Kit 辨識數位墨水

透過 ML Kit 的數位 ID 辨識功能，您可以辨識數百種語言的數位表面上手寫文字，以及將素描分類。

立即體驗

事前準備

  1. 在專案層級的 build.gradle 檔案中，請務必將 Google 的 Maven 存放區加進 buildscript 和 allprojects 區段。
  2. 將 ML Kit Android 程式庫的依附元件新增至模組的應用程式層級 Gradle 檔案，通常為 app/build.gradle：
dependencies {
  // ...
  implementation 'com.google.mlkit:digital-ink-recognition:18.1.0'
}

您現在可以開始辨識 Ink 物件中的文字。

建立 Ink 物件

建構 Ink 物件的主要方法是在觸控螢幕上繪製。在 Android 上，您可以使用 Canvas 來達到此目的。您的觸控事件處理常式應呼叫下列程式碼片段：addNewTouchEvent() 方法，該點會將使用者繪製到的點儲存在 Ink 物件中。

以下程式碼片段說明這個一般模式。如需更完整的範例，請參閱 ML Kit 快速入門導覽課程範例。

Kotlin

var inkBuilder = Ink.builder()
lateinit var strokeBuilder: Ink.Stroke.Builder

// Call this each time there is a new event.
fun addNewTouchEvent(event: MotionEvent) {
  val action = event.actionMasked
  val x = event.x
  val y = event.y
  var t = System.currentTimeMillis()

  // If your setup does not provide timing information, you can omit the
  // third paramater (t) in the calls to Ink.Point.create
  when (action) {
    MotionEvent.ACTION_DOWN -> {
      strokeBuilder = Ink.Stroke.builder()
      strokeBuilder.addPoint(Ink.Point.create(x, y, t))
    }
    MotionEvent.ACTION_MOVE -> strokeBuilder!!.addPoint(Ink.Point.create(x, y, t))
    MotionEvent.ACTION_UP -> {
      strokeBuilder.addPoint(Ink.Point.create(x, y, t))
      inkBuilder.addStroke(strokeBuilder.build())
    }
    else -> {
      // Action not relevant for ink construction
    }
  }
}

...

// This is what to send to the recognizer.
val ink = inkBuilder.build()

Java

Ink.Builder inkBuilder = Ink.builder();
Ink.Stroke.Builder strokeBuilder;

// Call this each time there is a new event.
public void addNewTouchEvent(MotionEvent event) {
  float x = event.getX();
  float y = event.getY();
  long t = System.currentTimeMillis();

  // If your setup does not provide timing information, you can omit the
  // third paramater (t) in the calls to Ink.Point.create
  int action = event.getActionMasked();
  switch (action) {
    case MotionEvent.ACTION_DOWN:
      strokeBuilder = Ink.Stroke.builder();
      strokeBuilder.addPoint(Ink.Point.create(x, y, t));
      break;
    case MotionEvent.ACTION_MOVE:
      strokeBuilder.addPoint(Ink.Point.create(x, y, t));
      break;
    case MotionEvent.ACTION_UP:
      strokeBuilder.addPoint(Ink.Point.create(x, y, t));
      inkBuilder.addStroke(strokeBuilder.build());
      strokeBuilder = null;
      break;
  }
}

...

// This is what to send to the recognizer.
Ink ink = inkBuilder.build();

取得 DigitalInkRecognizer 執行個體

如要執行辨識，請將 Ink 執行個體傳送至 DigitalInkRecognizer 物件。以下程式碼示範如何使用 BCP-47 標記將這類辨識器執行個體化。

Kotlin

// Specify the recognition model for a language
var modelIdentifier: DigitalInkRecognitionModelIdentifier
try {
  modelIdentifier = DigitalInkRecognitionModelIdentifier.fromLanguageTag("en-US")
} catch (e: MlKitException) {
  // language tag failed to parse, handle error.
}
if (modelIdentifier == null) {
  // no model was found, handle error.
}
var model: DigitalInkRecognitionModel =
    DigitalInkRecognitionModel.builder(modelIdentifier).build()


// Get a recognizer for the language
var recognizer: DigitalInkRecognizer =
    DigitalInkRecognition.getClient(
        DigitalInkRecognizerOptions.builder(model).build())

Java

// Specify the recognition model for a language
DigitalInkRecognitionModelIdentifier modelIdentifier;
try {
  modelIdentifier =
    DigitalInkRecognitionModelIdentifier.fromLanguageTag("en-US");
} catch (MlKitException e) {
  // language tag failed to parse, handle error.
}
if (modelIdentifier == null) {
  // no model was found, handle error.
}

DigitalInkRecognitionModel model =
    DigitalInkRecognitionModel.builder(modelIdentifier).build();

// Get a recognizer for the language
DigitalInkRecognizer recognizer =
    DigitalInkRecognition.getClient(
        DigitalInkRecognizerOptions.builder(model).build());

處理 Ink 物件

Kotlin

recognizer.recognize(ink)
    .addOnSuccessListener { result: RecognitionResult ->
      // `result` contains the recognizer's answers as a RecognitionResult.
      // Logs the text from the top candidate.
      Log.i(TAG, result.candidates[0].text)
    }
    .addOnFailureListener { e: Exception ->
      Log.e(TAG, "Error during recognition: $e")
    }

Java

recognizer.recognize(ink)
    .addOnSuccessListener(
        // `result` contains the recognizer's answers as a RecognitionResult.
        // Logs the text from the top candidate.
        result -> Log.i(TAG, result.getCandidates().get(0).getText()))
    .addOnFailureListener(
        e -> Log.e(TAG, "Error during recognition: " + e));

上方的程式碼範例假設已經下載辨識模型，如下一節所述。

管理模型下載

雖然 Digital ink Recognition API 支援數百種語言，但每種語言都必須下載部分資料才能辨識。每種語言約需要 20 MB 的儲存空間。這項操作將由 RemoteModelManager 物件處理。

下載新模型

Kotlin

import com.google.mlkit.common.model.DownloadConditions
import com.google.mlkit.common.model.RemoteModelManager

var model: DigitalInkRecognitionModel =  ...
val remoteModelManager = RemoteModelManager.getInstance()

remoteModelManager.download(model, DownloadConditions.Builder().build())
    .addOnSuccessListener {
      Log.i(TAG, "Model downloaded")
    }
    .addOnFailureListener { e: Exception ->
      Log.e(TAG, "Error while downloading a model: $e")
    }

Java

import com.google.mlkit.common.model.DownloadConditions;
import com.google.mlkit.common.model.RemoteModelManager;

DigitalInkRecognitionModel model = ...;
RemoteModelManager remoteModelManager = RemoteModelManager.getInstance();

remoteModelManager
    .download(model, new DownloadConditions.Builder().build())
    .addOnSuccessListener(aVoid -> Log.i(TAG, "Model downloaded"))
    .addOnFailureListener(
        e -> Log.e(TAG, "Error while downloading a model: " + e));

檢查模型是否已下載

Kotlin

var model: DigitalInkRecognitionModel =  ...
remoteModelManager.isModelDownloaded(model)

Java

DigitalInkRecognitionModel model = ...;
remoteModelManager.isModelDownloaded(model);

刪除已下載的模型

如果將模型從裝置的儲存空間中移除，就可以釋出空間。

Kotlin

var model: DigitalInkRecognitionModel =  ...
remoteModelManager.deleteDownloadedModel(model)
    .addOnSuccessListener {
      Log.i(TAG, "Model successfully deleted")
    }
    .addOnFailureListener { e: Exception ->
      Log.e(TAG, "Error while deleting a model: $e")
    }

Java

DigitalInkRecognitionModel model = ...;
remoteModelManager.deleteDownloadedModel(model)
                  .addOnSuccessListener(
                      aVoid -> Log.i(TAG, "Model successfully deleted"))
                  .addOnFailureListener(
                      e -> Log.e(TAG, "Error while deleting a model: " + e));

提昇文字辨識準確度的訣竅

文字辨識準確度可能因語言而異，準確率也必須仰賴寫作樣式。雖然 Digital Ink Recognition 已經過訓練，可處理多種寫入樣式，但結果會因使用者而異。

以下是提昇文字辨識器準確度的幾種方式。請注意，這些技術不適用於表情符號、自動繪製和形狀的繪圖分類器。

寫入區域

許多應用程式都有定義使用者輸入內容的寫入區域。而其中符號的意義取決於其寫入區域的大小。例如小寫或小寫英文字母「o」或「c」以及逗號與正斜線的差異。

告訴辨識區域的寬度和高度有助於提高精確度。不過，辨識器會假設寫入區域只有一行文字。如果實體寫入區域夠大，讓使用者能夠編寫兩行以上，那麼您可以寫入 WriteArea，以取得最佳結果，這是更好的單行文字高度估計值。您傳送給辨識器的 WriteArea 物件，不需要完全與螢幕上的實體寫入區域完全相同。以這種方式變更 WriteArea 高度，在部分語言中表現更佳。

指定寫入區域時，請在筆劃座標相同的單位中指定寬度和高度。x,y 座標引數沒有單位要求 - API 會將所有單位正規化，因此最重要的是筆劃的相對大小和位置。您可以依照系統需求，以任何座標傳遞座標。

結構定義

結構定義是指您要辨識的 Ink 中筆觸前的文字。你可以向前置端告知事前背景，以利對方辨識。

例如，草寫字母「n」和「u」經常被誤認為。如果使用者已輸入部分字詞「arg」，則系統可繼續進行可視為「ument」或「nment」的筆劃。指定預先結構定義「arg」可解決模稜兩可的情況，因為「引數」一詞較「引數」更可能。

情境脈絡也可協助辨識器識別出字詞間斷字元。您可以輸入空格字元，但無法繪製一個字元，那麼辨識器要如何判斷一個字詞的結尾，以及下一個字詞何時開始？假如使用者已經撰寫「hello」並繼續以書面名稱「world」來使用，則沒有背景資訊，則系統會傳回「world」字串。但是，如果指定前置結構定義「hello」，模型會傳回「world」字串加上前置空格，因為「hello world」比「helloword」更合理。

您應提供最長的最長結構定義字串，最多 20 個字元 (包括空格)。如果字串較長，辨識器只會使用最後 20 個字元。

以下程式碼範例說明如何定義撰寫區域，以及如何使用 RecognitionContext 物件指定預先結構定義。

Kotlin

var preContext : String = ...;
var width : Float = ...;
var height : Float = ...;
val recognitionContext : RecognitionContext =
    RecognitionContext.builder()
        .setPreContext(preContext)
        .setWritingArea(WritingArea(width, height))
        .build()

recognizer.recognize(ink, recognitionContext)

Java

String preContext = ...;
float width = ...;
float height = ...;
RecognitionContext recognitionContext =
    RecognitionContext.builder()
                      .setPreContext(preContext)
                      .setWritingArea(new WritingArea(width, height))
                      .build();

recognizer.recognize(ink, recognitionContext);

筆劃順序

辨識準確率與筆劃順序敏感。辨識器會預期按照自然的自然順序來筆劃，例如從左到右代表英文。從這個模式區分的任何情況 (例如從最後一個字詞開始建立英文句子)，會使結果的準確度降低。

另一個例子是，在 Ink 中間的字詞移除，並替換成其他字詞。修訂版本可能位於句子的中間，但修訂版本的筆觸位於筆劃序列結束時。在此情況下，建議您分別將新寫入的字詞傳送至 API，並使用自己的邏輯合併結果與先前的辨識。

處理模糊不清的形狀

在某些情況下，提供給辨識器的形狀意義不明確。舉例來說，如果矩形的圓角邊緣會顯示為矩形或橢圓形，

在發生這類情況時，只要使用辨識分數就能加以處理。只有形狀分類器會提供分數。如果模型非常有信心，最佳結果的分數就會優於第二種最佳結果。如果無法確定，前兩項結果的分數將會關閉。另請注意，形狀分類器會將整個 Ink 解讀為單一形狀。舉例來說，如果 Ink 包含矩形且彼此相鄰的刪節號，則辨識器可能會傳回一個或另一個 (或其他完全不同的) 結果，這是因為單一辨識候選項目無法代表兩個形狀。