הוספת תוויות למודלים עם אימון אוטומטי של Android ב-Android

אחרי שמאמנים מודל משלכם באמצעות AutoML Vision Edge, אפשר להשתמש בו באפליקציה כדי לתייג תמונות.

יש שתי דרכים לשלב מודלים שעברו אימון מ-AutoML Vision Edge: אפשר לקבץ את המודל על ידי הצבת המודל בתיקיית הנכסים של האפליקציה, או להוריד אותו באופן דינמי מ-Firebase.

אפשרויות לחבילה של מודלים
חבילה באפליקציה
  • המודל הוא חלק מחבילת ה-APK של האפליקציה
  • המודל זמין באופן מיידי, גם כשמכשיר Android במצב אופליין
  • אין צורך בפרויקט Firebase
באירוח Firebase

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

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

    לשילוב מודל עם האפליקציה:

    dependencies {
      // ...
      // Image labeling feature with bundled automl model
      implementation 'com.google.mlkit:image-labeling-custom:16.3.1'
    }
    

    כדי להוריד מודל באופן דינמי מ-Firebase, מוסיפים את התלות linkFirebase:

    dependencies {
      // ...
      // Image labeling feature with automl model downloaded
      // from firebase
      implementation 'com.google.mlkit:image-labeling-custom:16.3.1'
      implementation 'com.google.mlkit:linkfirebase:16.1.0'
    }
    
  2. אם רוצים להוריד מודל, צריך לוודא שמוסיפים את Firebase לפרויקט ב-Android, אם עדיין לא עשיתם זאת. אין צורך לעשות זאת כשמקבצים את המודל.

1. טעינת המודל

הגדרת מקור מודל מקומי

כדי לצרף את המודל לאפליקציה:

  1. מחלצים את המודל ואת המטא-נתונים שלו מארכיון ה-zip שהורדתם מהמסוף Firebase. מומלץ להשתמש בקבצים כפי שהורדת אותם, ללא שינוי (כולל שמות הקבצים).

  2. כוללים את המודל ואת קובצי המטא-נתונים שלו בחבילת האפליקציה:

    1. אם אין תיקיית נכסים בפרויקט, כדי ליצור תיקייה כזו לוחצים לחיצה ימנית על התיקייה app/ ואז לוחצים על New > Folder > Assets Folder (חדש > תיקייה > תיקיית נכסים).
    2. יוצרים תיקיית משנה בתיקיית הנכסים שתכלול את קובצי המודל.
    3. מעתיקים את הקבצים model.tflite, dict.txt ו-manifest.json לתיקיית המשנה (כל שלושת הקבצים צריכים להיות באותה תיקייה).
  3. מוסיפים את הקוד הבא לקובץ build.gradle של האפליקציה כדי לוודא ש-Gradle לא ידחוס את קובץ המודל בזמן ה-build של האפליקציה:

    android {
        // ...
        aaptOptions {
            noCompress "tflite"
        }
    }
    

    קובץ המודל ייכלל בחבילת האפליקציה ויהיה זמין ל-ML Kit כנכס גולמי.

  4. יוצרים אובייקט LocalModel, ומציינים את הנתיב לקובץ המניפסט של המודל:

    Java

    AutoMLImageLabelerLocalModel localModel =
        new AutoMLImageLabelerLocalModel.Builder()
            .setAssetFilePath("manifest.json")
            // or .setAbsoluteFilePath(absolute file path to manifest file)
            .build();
    

    Kotlin

    val localModel = LocalModel.Builder()
        .setAssetManifestFilePath("manifest.json")
        // or .setAbsoluteManifestFilePath(absolute file path to manifest file)
        .build()
    

הגדרת מקור מודל שמתארח ב-Firebase

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

Java

// Specify the name you assigned in the Firebase console.
FirebaseModelSource firebaseModelSource =
    new FirebaseModelSource.Builder("your_model_name").build();
CustomRemoteModel remoteModel =
    new CustomRemoteModel.Builder(firebaseModelSource).build();

Kotlin

// Specify the name you assigned in the Firebase console.
val firebaseModelSource = FirebaseModelSource.Builder("your_model_name")
    .build()
val remoteModel = CustomRemoteModel.Builder(firebaseModelSource).build()

לאחר מכן, מפעילים את המשימה של הורדת המודל ומציינים את התנאים שבהם רוצים לאפשר הורדה. אם המודל לא נמצא במכשיר או אם יש גרסה חדשה יותר של המודל, המשימה תוריד את המודל באופן אסינכרוני מ-Firebase:

Java

DownloadConditions downloadConditions = new DownloadConditions.Builder()
        .requireWifi()
        .build();
RemoteModelManager.getInstance().download(remoteModel, downloadConditions)
        .addOnSuccessListener(new OnSuccessListener<Void>() {
            @Override
            public void onSuccess(@NonNull Task<Void> task) {
                // Success.
            }
        });

Kotlin

val downloadConditions = DownloadConditions.Builder()
    .requireWifi()
    .build()
RemoteModelManager.getInstance().download(remoteModel, downloadConditions)
    .addOnSuccessListener {
        // Success.
    }

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

יצירת כלי לתיוג תמונות מהמודל

אחרי שמגדירים את מקורות המודלים, יוצרים אובייקט ImageLabeler מאחד מהם.

אם יש לכם רק מודל באריזה מקומית, פשוט יוצרים תווית מאובייקט CustomImageLabelerOptions ומגדירים את סף הסמך הרצוי (ראו הערכת המודל):

Java

CustomImageLabelerOptions customImageLabelerOptions = new CustomImageLabelerOptions.Builder(localModel)
    .setConfidenceThreshold(0.0f)  // Evaluate your model in the Cloud console
                                   // to determine an appropriate value.
    .build();
ImageLabeler labeler = ImageLabeling.getClient(customImageLabelerOptions);

Kotlin

val customImageLabelerOptions = CustomImageLabelerOptions.Builder(localModel)
    .setConfidenceThreshold(0.0f)  // Evaluate your model in the Cloud console
                                   // to determine an appropriate value.
    .build()
val labeler = ImageLabeling.getClient(customImageLabelerOptions)

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

למרות שצריך לוודא זאת רק לפני הפעלת המתייג, אם יש לכם גם מודל באירוח מרוחק וגם מודל בחבילה מקומית, יכול להיות שכדאי לבצע את הבדיקה הזו כשיוצרים את מתייג התמונה: ליצור תווית מהמודל המרוחק אם הוא כבר הורד, ואם לא, מהמודל המקומי.

Java

RemoteModelManager.getInstance().isModelDownloaded(remoteModel)
        .addOnSuccessListener(new OnSuccessListener<Boolean>() {
            @Override
            public void onSuccess(Boolean isDownloaded) {
                CustomImageLabelerOptions.Builder optionsBuilder;
                if (isDownloaded) {
                    optionsBuilder = new CustomImageLabelerOptions.Builder(remoteModel);
                } else {
                    optionsBuilder = new CustomImageLabelerOptions.Builder(localModel);
                }
                CustomImageLabelerOptions options = optionsBuilder
                        .setConfidenceThreshold(0.0f)  // Evaluate your model in the Cloud console
                                                       // to determine an appropriate threshold.
                        .build();

                ImageLabeler labeler = ImageLabeling.getClient(options);
            }
        });

Kotlin

RemoteModelManager.getInstance().isModelDownloaded(remoteModel)
    .addOnSuccessListener { isDownloaded ->
        val optionsBuilder =
            if (isDownloaded) {
                CustomImageLabelerOptions.Builder(remoteModel)
            } else {
                CustomImageLabelerOptions.Builder(localModel)
            }
        // Evaluate your model in the Cloud console to determine an appropriate threshold.
        val options = optionsBuilder.setConfidenceThreshold(0.0f).build()
        val labeler = ImageLabeling.getClient(options)
}

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

Java

RemoteModelManager.getInstance().download(remoteModel, conditions)
        .addOnSuccessListener(new OnSuccessListener<Void>() {
            @Override
            public void onSuccess(Void v) {
              // Download complete. Depending on your app, you could enable
              // the ML feature, or switch from the local model to the remote
              // model, etc.
            }
        });

Kotlin

RemoteModelManager.getInstance().download(remoteModel, conditions)
    .addOnSuccessListener {
        // Download complete. Depending on your app, you could enable the ML
        // feature, or switch from the local model to the remote model, etc.
    }

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

לאחר מכן, לכל תמונה שרוצים לתייג, יוצרים אובייקט InputImage מהתמונה. הכלי לתיוג תמונות פועל במהירות הגבוהה ביותר כשמשתמשים ב-Bitmap, או אם משתמשים ב-camera2 API, ב-YUV_420_888 media.Image. מומלץ להשתמש בפורמטים האלה כשהדבר אפשרי.

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

שימוש ב-media.Image

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

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

Kotlin+KTX

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) {
        if (imageProxy == null || imageProxy.getImage() == null) {
            return;
        }
        Image mediaImage = imageProxy.getImage();
        InputImage image =
                InputImage.fromMediaImage(mediaImage, imageProxy.imageInfo.rotationDegrees);
        // Pass image to an ML Kit Vision API
        // ...
    }
}

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

Kotlin+KTX

private val ORIENTATIONS = SparseIntArray()

init {
    ORIENTATIONS.append(Surface.ROTATION_0, 90)
    ORIENTATIONS.append(Surface.ROTATION_90, 0)
    ORIENTATIONS.append(Surface.ROTATION_180, 270)
    ORIENTATIONS.append(Surface.ROTATION_270, 180)
}
/**
 * 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, context: Context): 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)

    // On most devices, the sensor orientation is 90 degrees, but for some
    // devices it is 270 degrees. For devices with a sensor orientation of
    // 270, rotate the image an additional 180 ((270 + 270) % 360) degrees.
    val cameraManager = context.getSystemService(CAMERA_SERVICE) as CameraManager
    val sensorOrientation = cameraManager
        .getCameraCharacteristics(cameraId)
        .get(CameraCharacteristics.SENSOR_ORIENTATION)!!
    rotationCompensation = (rotationCompensation + sensorOrientation + 270) % 360

    // Return the corresponding FirebaseVisionImageMetadata rotation value.
    val result: Int
    when (rotationCompensation) {
        0 -> result = FirebaseVisionImageMetadata.ROTATION_0
        90 -> result = FirebaseVisionImageMetadata.ROTATION_90
        180 -> result = FirebaseVisionImageMetadata.ROTATION_180
        270 -> result = FirebaseVisionImageMetadata.ROTATION_270
        else -> {
            result = FirebaseVisionImageMetadata.ROTATION_0
            Log.e(TAG, "Bad rotation value: $rotationCompensation")
        }
    }
    return result
}

Java

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

/**
 * 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, Context context)
        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);

    // On most devices, the sensor orientation is 90 degrees, but for some
    // devices it is 270 degrees. For devices with a sensor orientation of
    // 270, rotate the image an additional 180 ((270 + 270) % 360) degrees.
    CameraManager cameraManager = (CameraManager) context.getSystemService(CAMERA_SERVICE);
    int sensorOrientation = cameraManager
            .getCameraCharacteristics(cameraId)
            .get(CameraCharacteristics.SENSOR_ORIENTATION);
    rotationCompensation = (rotationCompensation + sensorOrientation + 270) % 360;

    // Return the corresponding FirebaseVisionImageMetadata rotation value.
    int result;
    switch (rotationCompensation) {
        case 0:
            result = FirebaseVisionImageMetadata.ROTATION_0;
            break;
        case 90:
            result = FirebaseVisionImageMetadata.ROTATION_90;
            break;
        case 180:
            result = FirebaseVisionImageMetadata.ROTATION_180;
            break;
        case 270:
            result = FirebaseVisionImageMetadata.ROTATION_270;
            break;
        default:
            result = FirebaseVisionImageMetadata.ROTATION_0;
            Log.e(TAG, "Bad rotation value: " + rotationCompensation);
    }
    return result;
}

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

Kotlin+KTX

val image = InputImage.fromMediaImage(mediaImage, rotation)

Java

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

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

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

Kotlin+KTX

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

Java

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

שימוש ב-ByteBuffer או ב-ByteArray

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

Kotlin+KTX

val image = InputImage.fromByteBuffer(
        byteBuffer,
        /* image width */ 480,
        /* image height */ 360,
        rotationDegrees,
        InputImage.IMAGE_FORMAT_NV21 // or IMAGE_FORMAT_YV12
)

Java

InputImage image = InputImage.fromByteBuffer(byteBuffer,
        /* image width */ 480,
        /* image height */ 360,
        rotationDegrees,
        InputImage.IMAGE_FORMAT_NV21 // or IMAGE_FORMAT_YV12
);

באמצעות Bitmap

כדי ליצור אובייקט InputImage מאובייקט Bitmap, צריך להצהיר על כך באופן הבא:

Kotlin+KTX

val image = InputImage.fromBitmap(bitmap, 0)

Java

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

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

3. הפעלת הכלי לתיוג תמונות

כדי לתייג אובייקטים בתמונה, מעבירים את האובייקט image לשיטה process() של ImageLabeler.

Java

labeler.process(image)
        .addOnSuccessListener(new OnSuccessListener<List<ImageLabel>>() {
            @Override
            public void onSuccess(List<ImageLabel> labels) {
                // Task completed successfully
                // ...
            }
        })
        .addOnFailureListener(new OnFailureListener() {
            @Override
            public void onFailure(@NonNull Exception e) {
                // Task failed with an exception
                // ...
            }
        });

Kotlin

labeler.process(image)
        .addOnSuccessListener { labels ->
            // Task completed successfully
            // ...
        }
        .addOnFailureListener { e ->
            // Task failed with an exception
            // ...
        }

4. אחזור מידע על אובייקטים מתויגים

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

Java

for (ImageLabel label : labels) {
    String text = label.getText();
    float confidence = label.getConfidence();
    int index = label.getIndex();
}

Kotlin

for (label in labels) {
    val text = label.text
    val confidence = label.confidence
    val index = label.index
}

טיפים לשיפור הביצועים בזמן אמת

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

  • צמצום מספר הקריאות לסימון התמונות. אם פריים חדש לסרטון הופך לזמינה בזמן שמתייג התמונות פועל, צריך לשחרר את הפריים. לדוגמה, תוכלו לעיין בשיעור VisionProcessorBase באפליקציה לדוגמה של המדריך למתחילים.
  • אם אתם משתמשים בפלט של הכלי לתיוג תמונות כדי להוסיף שכבת-על של גרפיקה לתמונה של הקלט, תחילה צריך לקבל את התוצאה, ואז לבצע עיבוד (רנדור) של התמונה ושל שכבת-העל בשלב אחד. כך אפשר לעבד את משטח המסך פעם אחת בלבד עבור כל מסגרת קלט. לדוגמה, תוכלו לעיין בכיתות CameraSourcePreview ו- GraphicOverlay באפליקציה לדוגמה במדריך למתחילים.
  • אם אתם משתמשים ב-Camera2 API, כדאי לצלם תמונות בפורמט ImageFormat.YUV_420_888.

    אם משתמשים ב-Camera API הקודם, צריך לצלם תמונות בפורמט ImageFormat.NV21.