本頁面由 Cloud Translation API 翻譯而成。

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

您可以透過 ML Kit 的數位墨水辨識功能，辨識數百種語言在數位表面上手寫的文字，還可以對草圖分類。

立即體驗

請試用範例應用程式，查看這個 API 的使用範例。

事前準備

此 API 需要 Android API 級別 19 或以上版本。請確認應用程式的建構檔案使用的 minSdkVersion 值為 19 以上。

在您的專案層級的 build.gradle 檔案中，請務必在 buildscript 和 allprojects 區段中加入 Google 的 Maven 存放區。
將 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));

以上程式碼範例假設已下載識別模型，如下一節所述。

管理模型下載

儘管數位墨水辨識 API 支援數百種語言，但每種語言都必須先下載一些資料才能識別。每種語言需要約 20MB 的儲存空間。這項操作由 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」可解決混淆，因為「argument」這個字詞比「argnment」更有可能。

預先背景資訊也有助於辨識者辨識字詞換行，以及字詞之間的空格。您可以輸入空格字元，但無法畫出字元，該如何辨識內容是否能夠判斷某個字詞何時結束？如果使用者已寫入「hello」並繼續寫入「world」，則不需預先背景資訊，辨識器會傳回「world」字串。不過，如果您指定預先內容，「hello」則會傳回模型「亦即」字串 (亦即開頭的空格)，因為「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 包含彼此相鄰的矩形和刪節號，由於辨識器無法表示兩個形狀，因此辨識器可能會傳回其中一個 (或完全不同的) 作為結果。

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

立即體驗

事前準備

建構 Ink 物件

Kotlin

Java

取得 DigitalInkRecognizer 執行個體

Kotlin

Java

處理 Ink 物件

Kotlin

Java

管理模型下載

下載新模式

Kotlin

Java

檢查是否已下載模型

Kotlin

Java

刪除已下載的模型

Kotlin

Java

改善文字辨識準確度的訣竅

書寫區域

前後脈絡

Kotlin

Java

筆觸排序

處理模稜兩可的形狀

建構 `Ink` 物件

處理 `Ink` 物件