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

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

有了 ML Kit 數位墨水辨識功能，您就能辨識手寫文字支援數百種語言，以及分類草圖。

立即試用

使用範例應用程式試試請查看此 API 的使用範例。

事前準備

這個 API 需要 Android API 級別 21 以上的版本。確認您應用程式的版本檔案使用 21 以上的 minSdkVersion 值。

在專案層級的 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 可以使用畫布：。您的觸控事件處理常式應呼叫 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 支援數百種語言，需要先下載一些資料才能辨識。前後每種語言需要 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));

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

文字辨識的準確度可能因語言而異。準確度也會取決於創作風格數位墨水辨識經過充分訓練，可處理多種寫作風格，每個使用者的結果都可能不同

你可以透過以下幾種方式提高文字辨識工具的準確度。請注意，這些技巧不適用於表情符號、自動繪圖和圖形的繪圖分類器。

寫作領域

許多應用程式都有明確定義的使用者輸入內容寫入區域。符號的意義是部分取決於其大小，相對於包含該元素的撰寫區域大小。例如小寫或大寫英文字母「o」還有半形逗號和 a 的。

告知辨識器能改善書寫區域的寬度和高度。不過辨識器會假設書寫區域只包含一行文字。如果撰寫區域範圍夠大，讓使用者能寫兩行以上的程式碼，結果，方法是傳入帶有高度的 WriteArea ，預估高度單行文字。您傳遞至辨識工具的 WriterArea 物件不需要對應至並且與螢幕上的實際書寫區域完全相符。以這種方式變更 WriteArea 高度某些語言的效果更好。

指定書寫區域時，請以筆劃的單位指定寬度和高度座標。x,y 座標引數沒有單位要求，API 會將所有因此，唯一重要的是，筆觸的相對大小和位置。您可以以適合您系統的方式傳遞座標。

預先背景資訊

前情境是指 Ink 中筆劃前方的文字輸入的內容您可以提供預先背景資訊，協助辨識工具。

例如：草寫字母「n」和「u」經常遭人誤解如果使用者輸入時，它們可能會繼續出現您可以辨識為「arg」的筆觸「ument」或「nment」。指定預先情境「arg」可解決模稜兩可的情況「引數」而不是「argnment」。

預先背景資訊也可協助辨識器辨識分行符號 (字詞之間的空格)。你可以輸入空格字元，但無法繪製一個，因此辨識器如何判斷該字詞的結尾下一場會議是開始的？如果使用者已經寫「hello」繼續用一個字延續下去「world」，如果沒有預先背景資訊，辨識器會傳回「world」字串。不過，如果您將預先上下文的「hello」，模型會傳回「並以開頭的空格取代 "Hello" 世界」比「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` 物件