透過 ML Kit 的數位 ID 辨識功能，您可以辨識數百種語言的數位表面上手寫文字，以及將素描分類。
立即體驗
- 如要查看此 API 的範例，請搭配範例應用程式。
事前準備
- 在專案層級的
build.gradle檔案中，請務必將 Google 的 Maven 存放區加進buildscript和allprojects區段。 - 將 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 包含矩形且彼此相鄰的刪節號，則辨識器可能會傳回一個或另一個 (或其他完全不同的) 結果，這是因為單一辨識候選項目無法代表兩個形狀。