זיהוי טקסט בתמונות באמצעות ערכת ML ב-Android

ניתן להשתמש ב-ML Kit כדי לזהות טקסט בתמונות או בסרטונים, למשל טקסט של שלט רחוב. המאפיינים העיקריים של התכונה הזו הם:

ה-API הזה זמין באמצעות ספרייה לא מקובצת שצריך להוריד לפני השימוש בה, או ספרייה בחבילה שמגדילה את גודל האפליקציה. במדריך הזה ניתן למצוא מידע נוסף על ההבדלים בין שתי אפשרויות ההתקנה.

התכונה	לא בחבילה	בחבילה
שם הספרייה	com.google.android.gms:play-services-mlkit-text-recognition com.google.android.gms:play-services-mlkit-text-recognition-chinese com.google.android.gms:play-services-mlkit-text-recognition-devanagari com.google.android.gms:play-services-mlkit-text-recognition-japanese com.google.android.gms:play-services-mlkit-text-recognition-korean	com.google.mlkit:text-recognition com.google.mlkit:text-recognition-chinese com.google.mlkit:text-recognition-devanagari com.google.mlkit:text-recognition-japanese com.google.mlkit:text-recognition-korean
הטמעה	ההורדה של המודל מתבצעת באופן דינמי דרך Google Play Services.	המודל מקושר באופן סטטי לאפליקציה בזמן ה-build.
גודל האפליקציה	הגדלה של כ-260KB לכל ארכיטקטורת סקריפטים.	הגדלה של כ-4MB לכל סקריפט לכל ארכיטקטורה.
זמן אתחול	ייתכן שיהיה צורך להמתין להורדת המודל לפני השימוש הראשון.	המודל זמין באופן מיידי.
ביצועים	זמן אמת ברוב המכשירים עבור ספריית סקריפטים לטיניים, איטי יותר עבור אחרים.	זמן אמת ברוב המכשירים עבור ספריית סקריפטים לטיניים, איטי יותר עבור אחרים.

אני רוצה לנסות

• אפשר לנסות את האפליקציה לדוגמה כדי לראות דוגמה לשימוש ב-API הזה.
• אפשר לנסות את הקוד בעצמכם באמצעות codelab.

לפני שמתחילים

כדי להשתמש ב-API הזה נדרש Android API ברמה 21 ומעלה. יש לוודא שקובץ ה-build של האפליקציה משתמש בערך minSdkVersion של 21 ומעלה.

1. בקובץ build.gradle ברמת הפרויקט, חשוב לכלול את מאגר Maven של Google בקטע buildscript וגם בקטע allprojects.

2. מוסיפים את יחסי התלות של ספריות ML Kit ל-Android לקובץ ההדרגתיות של המודול ברמת האפליקציה, שהוא בדרך כלל app/build.gradle:

   כדי לקבץ את המודל עם האפליקציה:

   dependencies {
     // To recognize Latin script
     implementation 'com.google.mlkit:text-recognition:16.0.0'
   
     // To recognize Chinese script
     implementation 'com.google.mlkit:text-recognition-chinese:16.0.0'
   
     // To recognize Devanagari script
     implementation 'com.google.mlkit:text-recognition-devanagari:16.0.0'
   
     // To recognize Japanese script
     implementation 'com.google.mlkit:text-recognition-japanese:16.0.0'
   
     // To recognize Korean script
     implementation 'com.google.mlkit:text-recognition-korean:16.0.0'
   }
   

   לשימוש במודל ב-Google Play Services:

   dependencies {
     // To recognize Latin script
     implementation 'com.google.android.gms:play-services-mlkit-text-recognition:19.0.0'
   
     // To recognize Chinese script
     implementation 'com.google.android.gms:play-services-mlkit-text-recognition-chinese:16.0.0'
   
     // To recognize Devanagari script
     implementation 'com.google.android.gms:play-services-mlkit-text-recognition-devanagari:16.0.0'
   
     // To recognize Japanese script
     implementation 'com.google.android.gms:play-services-mlkit-text-recognition-japanese:16.0.0'
   
     // To recognize Korean script
     implementation 'com.google.android.gms:play-services-mlkit-text-recognition-korean:16.0.0'
   }
   

3. אם בוחרים להשתמש במודל ב-Google Play Services, אפשר להגדיר שהאפליקציה תוריד את המודל באופן אוטומטי למכשיר אחרי שהתקנתם אותה מחנות Play. כדי לעשות זאת, צריך להוסיף את ההצהרה הבאה לקובץ AndroidManifest.xml של האפליקציה:

   <application ...>
         ...
         <meta-data
             android:name="com.google.mlkit.vision.DEPENDENCIES"
             android:value="ocr" >
         <!-- To use multiple models: android:value="ocr,ocr_chinese,ocr_devanagari,ocr_japanese,ocr_korean,..." -->
   </application>
   

   אתם יכולים גם לבדוק במפורש את זמינות המודל ולבקש הורדה באמצעות ModuleInstallClient API בשירותים של Google Play. אם לא מפעילים הורדות של מודלים בזמן ההתקנה או מבקשים הורדה מפורשת, תתבצע הורדה של המודל בפעם הראשונה שתפעילו את הסורק. בקשות שנשלחות לפני שההורדה הושלמה לא מניבות תוצאות.

1. יצירת מופע של TextRecognizer

יוצרים מופע של TextRecognizer ומעבירים את האפשרויות שקשורות לספרייה שהצהרתם עליה כתלויה:

Kotlin

// When using Latin script library
val recognizer = TextRecognition.getClient(TextRecognizerOptions.DEFAULT_OPTIONS)

// When using Chinese script library
val recognizer = TextRecognition.getClient(ChineseTextRecognizerOptions.Builder().build())

// When using Devanagari script library
val recognizer = TextRecognition.getClient(DevanagariTextRecognizerOptions.Builder().build())

// When using Japanese script library
val recognizer = TextRecognition.getClient(JapaneseTextRecognizerOptions.Builder().build())

// When using Korean script library
val recognizer = TextRecognition.getClient(KoreanTextRecognizerOptions.Builder().build())

Java

// When using Latin script library
TextRecognizer recognizer =
  TextRecognition.getClient(TextRecognizerOptions.DEFAULT_OPTIONS);

// When using Chinese script library
TextRecognizer recognizer =
  TextRecognition.getClient(new ChineseTextRecognizerOptions.Builder().build());

// When using Devanagari script library
TextRecognizer recognizer =
  TextRecognition.getClient(new DevanagariTextRecognizerOptions.Builder().build());

// When using Japanese script library
TextRecognizer recognizer =
  TextRecognition.getClient(new JapaneseTextRecognizerOptions.Builder().build());

// When using Korean script library
TextRecognizer recognizer =
  TextRecognition.getClient(new KoreanTextRecognizerOptions.Builder().build());

2. הכנת תמונת הקלט

על מנת לזהות טקסט בתמונה, צריך ליצור אובייקט InputImage ממערך של Bitmap, media.Image, ByteBuffer, בייטים או מקובץ במכשיר. לאחר מכן, מעבירים את האובייקט InputImage ל-method processImage של TextRecognizer.

ניתן ליצור אובייקט InputImage ממקורות שונים. בהמשך מוסבר על כל אחד מהם.

באמצעות media.Image

כדי ליצור אובייקט InputImage מאובייקט media.Image, למשל כשמצלמים תמונה ממצלמת המכשיר, צריך להעביר את האובייקט media.Image ואת הסיבוב של התמונה אל InputImage.fromMediaImage().

אם משתמשים בספריית CameraX, המחלקות OnImageCapturedListener ו-ImageAnalysis.Analyzer מחשבים את ערך הסיבוב בשבילכם.

Kotlin

private class YourImageAnalyzer : ImageAnalysis.Analyzer {

    override fun analyze(imageProxy: ImageProxy) {
        val mediaImage = imageProxy.image
        if (mediaImage != null) {
            val image = InputImage.fromMediaImage(mediaImage, imageProxy.imageInfo.rotationDegrees)
            // Pass image to an ML Kit Vision API
            // ...
        }
    }
}

Java

private class YourAnalyzer implements ImageAnalysis.Analyzer {

    @Override
    public void analyze(ImageProxy imageProxy) {
        Image mediaImage = imageProxy.getImage();
        if (mediaImage != null) {
          InputImage image =
                InputImage.fromMediaImage(mediaImage, imageProxy.getImageInfo().getRotationDegrees());
          // Pass image to an ML Kit Vision API
          // ...
        }
    }
}

אם לא משתמשים בספריית מצלמה כדי לקבל את מידת הסיבוב של התמונה, אפשר לחשב אותה לפי מידת הסיבוב של המכשיר והכיוון של חיישן המצלמה במכשיר:

Kotlin

private val ORIENTATIONS = SparseIntArray()

init {
    ORIENTATIONS.append(Surface.ROTATION_0, 0)
    ORIENTATIONS.append(Surface.ROTATION_90, 90)
    ORIENTATIONS.append(Surface.ROTATION_180, 180)
    ORIENTATIONS.append(Surface.ROTATION_270, 270)
}

/**
 * Get the angle by which an image must be rotated given the device's current
 * orientation.
 */
@RequiresApi(api = Build.VERSION_CODES.LOLLIPOP)
@Throws(CameraAccessException::class)
private fun getRotationCompensation(cameraId: String, activity: Activity, isFrontFacing: Boolean): Int {
    // Get the device's current rotation relative to its "native" orientation.
    // Then, from the ORIENTATIONS table, look up the angle the image must be
    // rotated to compensate for the device's rotation.
    val deviceRotation = activity.windowManager.defaultDisplay.rotation
    var rotationCompensation = ORIENTATIONS.get(deviceRotation)

    // Get the device's sensor orientation.
    val cameraManager = activity.getSystemService(CAMERA_SERVICE) as CameraManager
    val sensorOrientation = cameraManager
            .getCameraCharacteristics(cameraId)
            .get(CameraCharacteristics.SENSOR_ORIENTATION)!!

    if (isFrontFacing) {
        rotationCompensation = (sensorOrientation + rotationCompensation) % 360
    } else { // back-facing
        rotationCompensation = (sensorOrientation - rotationCompensation + 360) % 360
    }
    return rotationCompensation
}
MLKitVisionImage.kt

Java

private static final SparseIntArray ORIENTATIONS = new SparseIntArray();
static {
    ORIENTATIONS.append(Surface.ROTATION_0, 0);
    ORIENTATIONS.append(Surface.ROTATION_90, 90);
    ORIENTATIONS.append(Surface.ROTATION_180, 180);
    ORIENTATIONS.append(Surface.ROTATION_270, 270);
}

/**
 * Get the angle by which an image must be rotated given the device's current
 * orientation.
 */
@RequiresApi(api = Build.VERSION_CODES.LOLLIPOP)
private int getRotationCompensation(String cameraId, Activity activity, boolean isFrontFacing)
        throws CameraAccessException {
    // Get the device's current rotation relative to its "native" orientation.
    // Then, from the ORIENTATIONS table, look up the angle the image must be
    // rotated to compensate for the device's rotation.
    int deviceRotation = activity.getWindowManager().getDefaultDisplay().getRotation();
    int rotationCompensation = ORIENTATIONS.get(deviceRotation);

    // Get the device's sensor orientation.
    CameraManager cameraManager = (CameraManager) activity.getSystemService(CAMERA_SERVICE);
    int sensorOrientation = cameraManager
            .getCameraCharacteristics(cameraId)
            .get(CameraCharacteristics.SENSOR_ORIENTATION);

    if (isFrontFacing) {
        rotationCompensation = (sensorOrientation + rotationCompensation) % 360;
    } else { // back-facing
        rotationCompensation = (sensorOrientation - rotationCompensation + 360) % 360;
    }
    return rotationCompensation;
}

לאחר מכן מעבירים את האובייקט media.Image ואת ערך מעלה הסיבוב ל-InputImage.fromMediaImage():

Kotlin

val image = InputImage.fromMediaImage(mediaImage, rotation)
MLKitVisionImage.kt

Java

InputImage image = InputImage.fromMediaImage(mediaImage, rotation);

שימוש ב-URI של קובץ

כדי ליצור אובייקט InputImage מ-URI של קובץ, מעבירים את ההקשר של האפליקציה ואת ה-URI של הקובץ אל InputImage.fromFilePath(). האפשרות הזו שימושית כשמשתמשים ב-Intent של ACTION_GET_CONTENT כדי לבקש מהמשתמשים לבחור תמונה מאפליקציית הגלריה.

Kotlin

val image: InputImage
try {
    image = InputImage.fromFilePath(context, uri)
} catch (e: IOException) {
    e.printStackTrace()
}
MLKitVisionImage.kt

Java

InputImage image;
try {
    image = InputImage.fromFilePath(context, uri);
} catch (IOException e) {
    e.printStackTrace();
}

באמצעות ByteBuffer או ByteArray

כדי ליצור אובייקט InputImage מ-ByteBuffer או מ-ByteArray, קודם צריך לחשב את מעלות סיבוב התמונה כפי שתואר קודם עבור קלט media.Image. לאחר מכן יוצרים את האובייקט InputImage עם מאגר הנתונים הזמני או המערך, יחד עם הגובה, הרוחב, פורמט קידוד הצבע ומידת הסיבוב של התמונה:

Kotlin

val image = InputImage.fromByteBuffer(
        byteBuffer,
        /* image width */ 480,
        /* image height */ 360,
        rotationDegrees,
        InputImage.IMAGE_FORMAT_NV21 // or IMAGE_FORMAT_YV12
)
MLKitVisionImage.kt
// Or:
val image = InputImage.fromByteArray(
        byteArray,
        /* image width */ 480,
        /* image height */ 360,
        rotationDegrees,
        InputImage.IMAGE_FORMAT_NV21 // or IMAGE_FORMAT_YV12
)
MLKitVisionImage.kt

Java

InputImage image = InputImage.fromByteBuffer(byteBuffer,
        /* image width */ 480,
        /* image height */ 360,
        rotationDegrees,
        InputImage.IMAGE_FORMAT_NV21 // or IMAGE_FORMAT_YV12
);
MLKitVisionImage.java
// Or:
InputImage image = InputImage.fromByteArray(
        byteArray,
        /* image width */480,
        /* image height */360,
        rotation,
        InputImage.IMAGE_FORMAT_NV21 // or IMAGE_FORMAT_YV12
);
MLKitVisionImage.java

באמצעות Bitmap

כדי ליצור אובייקט InputImage מאובייקט Bitmap, צריך להשתמש בהצהרה הבאה:

Kotlin

val image = InputImage.fromBitmap(bitmap, 0)
MLKitVisionImage.kt

Java

InputImage image = InputImage.fromBitmap(bitmap, rotationDegree);
MLKitVisionImage.java

התמונה מיוצגת על ידי אובייקט Bitmap יחד עם מעלות סיבוב.

3. עיבוד התמונה

מעבירים את התמונה ל-method process:

Kotlin

val result = recognizer.process(image)
        .addOnSuccessListener { visionText ->
            // Task completed successfully
            // ...
        }
        .addOnFailureListener { e ->
            // Task failed with an exception
            // ...
        }
TextRecognitionActivity.kt

Java

Task<Text> result =
        recognizer.process(image)
                .addOnSuccessListener(new OnSuccessListener<Text>() {
                    @Override
                    public void onSuccess(Text visionText) {
                        // Task completed successfully
                        // ...
                    }
                })
                .addOnFailureListener(
                        new OnFailureListener() {
                            @Override
                            public void onFailure(@NonNull Exception e) {
                                // Task failed with an exception
                                // ...
                            }
                        });
TextRecognitionActivity.java

הערה: אם משתמשים ב-API של CameraX, חשוב לסגור את ה-ImageProxy בסיום השימוש, למשל על ידי הוספת OnCompleteListener ל-Task שמוחזר מ-process. כדי לראות דוגמה, אפשר לעיין בכיתה VisionProcessorBase באפליקציה לדוגמה של המדריך למתחילים.

4. חילוץ טקסט מבלוקים של טקסט מזוהה

אם פעולת זיהוי הטקסט מצליחה, אובייקט Text מועבר ל-listener. אובייקט Text מכיל את הטקסט המלא שמזוהה בתמונה, ואפס אובייקטים של TextBlock או יותר.

כל TextBlock מייצג בלוק טקסט מלבני, שמכיל אפס או יותר אובייקטים מסוג Line. כל אובייקט Line מייצג שורת טקסט, שמכילה אפס אובייקטים Element או יותר. כל אובייקט Element מייצג מילה או ישות דמוית מילה, שמכילה אפס או יותר אובייקטים מסוג Symbol. כל אובייקט Symbol מייצג תו, ספרה או ישות דמוית מילה.

לכל אובייקט TextBlock, Line, Element ו-Symbol אפשר לקבל את הטקסט שמזוהה באזור, את הקואורדינטות התוחמות של האזור ועוד מאפיינים רבים אחרים, כמו מידע על הסיבוב, דירוג הסמך וכו'.

למשל:

Kotlin

val resultText = result.text
for (block in result.textBlocks) {
    val blockText = block.text
    val blockCornerPoints = block.cornerPoints
    val blockFrame = block.boundingBox
    for (line in block.lines) {
        val lineText = line.text
        val lineCornerPoints = line.cornerPoints
        val lineFrame = line.boundingBox
        for (element in line.elements) {
            val elementText = element.text
            val elementCornerPoints = element.cornerPoints
            val elementFrame = element.boundingBox
        }
    }
}
TextRecognitionActivity.kt

Java

String resultText = result.getText();
for (Text.TextBlock block : result.getTextBlocks()) {
    String blockText = block.getText();
    Point[] blockCornerPoints = block.getCornerPoints();
    Rect blockFrame = block.getBoundingBox();
    for (Text.Line line : block.getLines()) {
        String lineText = line.getText();
        Point[] lineCornerPoints = line.getCornerPoints();
        Rect lineFrame = line.getBoundingBox();
        for (Text.Element element : line.getElements()) {
            String elementText = element.getText();
            Point[] elementCornerPoints = element.getCornerPoints();
            Rect elementFrame = element.getBoundingBox();
            for (Text.Symbol symbol : element.getSymbols()) {
                String symbolText = symbol.getText();
                Point[] symbolCornerPoints = symbol.getCornerPoints();
                Rect symbolFrame = symbol.getBoundingBox();
            }
        }
    }
}
TextRecognitionActivity.java

הנחיות לבחירת תמונה לקלט

• כדי ש-ML Kit יוכל לזהות טקסט באופן מדויק, תמונות הקלט צריכות להכיל טקסט שמיוצג על ידי כמות מספיקה של נתוני פיקסלים. רצוי שכל תו יהיה בגודל של לפחות 16x16 פיקסלים. בדרך כלל אין יתרון דיוק לגבי תווים שגדולים מ-24x24 פיקסלים.

  לדוגמה, תמונה בגודל 640x480 יכולה להתאים מאוד לסריקת כרטיס ביקור שתופס את כל רוחב התמונה. כדי לסרוק מסמך שמודפס על נייר בגודל מכתב, ייתכן שתידרש תמונה בגודל 720x1280 פיקסלים.

• מיקוד באיכות נמוכה יכול להשפיע על הדיוק של זיהוי הטקסט. אם התוצאות לא מקובלות עליך, כדאי לבקש מהמשתמש לצלם מחדש את התמונה.

• אם אתם מזהים טקסט באפליקציה בזמן אמת, כדאי שתביאו בחשבון את הממדים הכוללים של תמונות הקלט. אפשר לעבד תמונות קטנות יותר מהר יותר. כדי לקצר את זמן האחזור, יש לוודא שהטקסט תופס חלק גדול ככל האפשר מהתמונה ולצלם תמונות ברזולוציות נמוכות יותר (שימו לב לדרישות הדיוק שצוינו למעלה). מידע נוסף זמין במאמר טיפים לשיפור הביצועים.

טיפים לשיפור הביצועים

• אם משתמשים ב-API של Camera או camera2, אפשר לווסת קריאות לגלאי. אם מתפנה פריים חדש של וידאו בזמן שהמזהה פועל, צריך לשחרר אותו. כדי לראות דוגמה, אפשר לעיין בכיתה VisionProcessorBase באפליקציה לדוגמה של המדריך למתחילים.
• אם אתם משתמשים ב-CameraX API, חשוב לוודא ששיטת הלחץ הזמני מוגדרת לערך ברירת המחדל שלה ImageAnalysis.STRATEGY_KEEP_ONLY_LATEST. כך אפשר להבטיח שרק תמונה אחת תוצג לניתוח בכל פעם. אם נוצרות תמונות נוספות כשהניתוח עמוס, הן יושמטו באופן אוטומטי ולא ימתינו בתור למשלוח. לאחר סגירת התמונה שמנותחת על ידי קריאה ל-ImageProxy.close(), תוצג התמונה העדכנית ביותר הבאה.
• אם משתמשים בפלט של הגלאי כדי להציג שכבות גרפיקה על תמונת הקלט, קודם מקבלים את התוצאה מ-ML Kit ואז מבצעים רינדור של התמונה ושכבת-העל בשלב אחד. הפעולה הזו מעבדת את הנתונים על פני השטח של התצוגה פעם אחת בלבד לכל מסגרת קלט. כדי לראות דוגמה, אפשר לעיין בכיתות CameraSourcePreview ו- GraphicOverlay באפליקציה לדוגמה של המדריך למתחילים.
• אם משתמשים ב- Camera2 API, צריך לצלם תמונות בפורמט ImageFormat.YUV_420_888. אם משתמשים בגרסה הישנה של Camera API, צריך לצלם תמונות בפורמט ImageFormat.NV21.
• כדאי לצלם תמונות ברזולוציה נמוכה יותר. עם זאת, חשוב לזכור גם את הדרישות לגבי מידות התמונה של ה-API הזה.