זיהוי, מעקב וסיווג של אובייקטים באמצעות מודל סיווג בהתאמה אישית ב-Android

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

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

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

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

מודל בחבילה	מודל מתארח
המודל הוא חלק מחבילת ה-APK של האפליקציה, ולכן הוא מגדיל את הגודל שלה.	המודל לא נכלל ב-APK. הוא מתארח על ידי העלאה ל-Cloud Storage. מומלץ להשתמש ב-Cloud Storage for Firebase.
המודל זמין באופן מיידי, גם כשמכשיר Android אופליין	האפליקציה צריכה לכלול קוד להורדת המודל לפי דרישה
אין צורך בפרויקט Firebase	נדרש פרויקט Firebase (אם משתמשים ב-Cloud Storage for Firebase).
כדי לעדכן את המודל, צריך לפרסם מחדש את האפליקציה	עדכון המודל בלי לפרסם מחדש את האפליקציה
אין בדיקות A/B מובנות	בדיקות A/B עם הגדרת תצורה מרחוק ב-Firebase

רוצה לנסות?

• אפשר לראות דוגמה לשימוש במודל החבילה באפליקציית המדריך למתחילים בנושא Vision, ודוגמה לשימוש במודל המתארח באפליקציית המדריך למתחילים בנושא AutoML.
• כדי לראות הטמעה מקצה לקצה של ה-API הזה, אפשר לעיין באפליקציית הדוגמה של Material Design.

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

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

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

   כדי לארוז מודל עם האפליקציה:

   dependencies {
     // ...
     // Object detection & tracking feature with custom bundled model
     implementation("com.google.mlkit:object-detection-custom:17.0.2")
   }
   

2. אם רוצים להוריד מודל מ-Cloud Storage for Firebase, צריך להוסיף את Firebase לפרויקט Android, אם עדיין לא עשיתם זאת. זה לא נדרש כשמצרפים את המודל לחבילה.

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

אפשר לטעון את המודל ממקור שצורף באופן מקומי או ממקור שמתארח מרחוק.

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

כדי לארוז את המודל עם האפליקציה:

1. מעתיקים את קובץ המודל (בדרך כלל מסתיים ב-.tflite או ב-.lite) לתיקייה assets/ של האפליקציה. (יכול להיות שתצטרכו ליצור את התיקייה קודם. לשם כך, לוחצים לחיצה ימנית על התיקייה app/ ואז לוחצים על חדש > תיקייה > תיקיית נכסים).

2. יוצרים אובייקט LocalModel ומציינים את הנתיב לקובץ המודל:

   Kotlin

   val localModel = LocalModel.Builder()
           .setAssetFilePath("model.tflite")
           // or .setAbsoluteFilePath(absolute path to model file)
           // or .setUri(URI to model file)
           .build()

   Java

   LocalModel localModel =
       new LocalModel.Builder()
           .setAssetFilePath("model.tflite")
           // or .setAbsoluteFilePath(absolute path to model file)
           // or .setUri(URI to model file)
           .build();

   הערה: אפליקציות שמטרגטות ל-Android 11 (רמת API 30) לא יכולות יותר לגשת לקבצים מאחסון חיצוני בגלל עדכוני אחסון ב-Android 11.
   הערה: אם יש לכם מודל שאומן באמצעות AutoML Vision Edge ב-Firebase (לא ב-Google Cloud), יכול להיות שההוראות שלמעלה לא יפעלו. הוראות מפורטות זמינות במדריך להעברת נתונים.

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

כדי להשתמש במודל שמתארח מרחוק, צריך להוריד את קובץ המודל לאחסון המקומי של המכשיר באמצעות הלוגיקה של האפליקציה, ואז לטעון אותו כמודל מקומי. מומלץ להשתמש ב-Cloud Storage for Firebase כדי לארח מודל. פרטים על ההטמעה מופיעים במדריך להעברת נתונים מ-Firebase ML ל-Cloud Storage.

2. הגדרת גלאי האובייקטים

אחרי שמגדירים את מקורות המודל, מגדירים את גלאי האובייקטים לתרחיש השימוש עם אובייקט CustomObjectDetectorOptions. אפשר לשנות את ההגדרות הבאות:

הגדרות של זיהוי אובייקטים
מצב זיהוי	‫STREAM_MODE (ברירת מחדל) | SINGLE_IMAGE_MODE במצב STREAM_MODE (ברירת מחדל), גלאי האובייקטים פועל עם זמן אחזור נמוך, אבל יכול להיות שהוא יפיק תוצאות לא מלאות (כמו תיבות תוחמות או תוויות קטגוריה לא מוגדרות) בכמה ההפעלות הראשונות של הגלאי. בנוסף, במצב STREAM_MODE, הגלאי מקצה מזהי מעקב לאובייקטים, שאפשר להשתמש בהם כדי לעקוב אחרי אובייקטים בפריים. משתמשים במצב הזה כשרוצים לעקוב אחרי אובייקטים, או כשזמן אחזור נמוך חשוב, למשל כשמעבדים סטרימינג של סרטונים בזמן אמת. ב-SINGLE_IMAGE_MODE, גלאי האובייקטים מחזיר את התוצאה אחרי שנקבע תיבת התוחמת של האובייקט. אם מפעילים גם סיווג, התוצאה מוחזרת אחרי שתיבת התוחמת ותווית הקטגוריה זמינות. כתוצאה מכך, יכול להיות שזמן האחזור של הזיהוי יהיה ארוך יותר. בנוסף, במודעות SINGLE_IMAGE_MODE לא מוקצים מזהים לצורכי מעקב. כדאי להשתמש במצב הזה אם זמן האחזור לא קריטי ואתם לא רוצים להתמודד עם תוצאות חלקיות.
זיהוי ומעקב אחרי כמה אובייקטים	‫false (ברירת מחדל) | true האם לזהות ולעקוב אחרי עד חמישה אובייקטים או רק אחרי האובייקט הבולט ביותר (ברירת מחדל).
סיווג אובייקטים	‫false (ברירת מחדל) | true האם לסווג את האובייקטים שזוהו באמצעות מודל מסווג התוכן המותאם אישית שסופק. כדי להשתמש במודל מסווג התוכן המותאם אישית, צריך להגדיר את הערך true.
סף מהימנות לסיווג	ציון המינימום של רמת הסמך של התוויות שזוהו. אם לא מגדירים ערך, המערכת תשתמש בסף של המסווג שצוין במטא-נתונים של המודל. אם המודל לא מכיל מטא-נתונים או שהמטא-נתונים לא מציינים סף לסיווג, ייעשה שימוש בסף ברירת המחדל 0.0.
מספר התוויות המקסימלי לכל אובייקט	המספר המקסימלי של תוויות לכל אובייקט שהגלאי יחזיר. אם לא מגדירים את הערך, המערכת תשתמש בערך ברירת המחדל 10.

ממשק ה-API לזיהוי אובייקטים ולמעקב מותאם לשני תרחישי השימוש העיקריים הבאים:

• זיהוי ומעקב בזמן אמת של האובייקט הבולט ביותר בעינית המצלמה.
• זיהוי של כמה אובייקטים בתמונה סטטית.

כדי להגדיר את ה-API לתרחישי השימוש האלה, עם מודל שצורף באופן מקומי:

Kotlin

// Live detection and tracking
val customObjectDetectorOptions =
        CustomObjectDetectorOptions.Builder(localModel)
        .setDetectorMode(CustomObjectDetectorOptions.STREAM_MODE)
        .enableClassification()
        .setClassificationConfidenceThreshold(0.5f)
        .setMaxPerObjectLabelCount(3)
        .build()

// Multiple object detection in static images
val customObjectDetectorOptions =
        CustomObjectDetectorOptions.Builder(localModel)
        .setDetectorMode(CustomObjectDetectorOptions.SINGLE_IMAGE_MODE)
        .enableMultipleObjects()
        .enableClassification()
        .setClassificationConfidenceThreshold(0.5f)
        .setMaxPerObjectLabelCount(3)
        .build()

val objectDetector =
        ObjectDetection.getClient(customObjectDetectorOptions)

Java

// Live detection and tracking
CustomObjectDetectorOptions customObjectDetectorOptions =
        new CustomObjectDetectorOptions.Builder(localModel)
                .setDetectorMode(CustomObjectDetectorOptions.STREAM_MODE)
                .enableClassification()
                .setClassificationConfidenceThreshold(0.5f)
                .setMaxPerObjectLabelCount(3)
                .build();

// Multiple object detection in static images
CustomObjectDetectorOptions customObjectDetectorOptions =
        new CustomObjectDetectorOptions.Builder(localModel)
                .setDetectorMode(CustomObjectDetectorOptions.SINGLE_IMAGE_MODE)
                .enableMultipleObjects()
                .enableClassification()
                .setClassificationConfidenceThreshold(0.5f)
                .setMaxPerObjectLabelCount(3)
                .build();

ObjectDetector objectDetector =
    ObjectDetection.getClient(customObjectDetectorOptions);

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

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

Kotlin

val modelFile = File(context.cacheDir, "my_remote_model.tflite")

val model = if (modelFile.exists()) {
    // Use the downloaded model if available
    LocalModel.Builder().setAbsoluteFilePath(modelFile.absolutePath).build()
} else {
    // Fall back to the bundled model
    LocalModel.Builder().setAssetFilePath("model.tflite").build()
}

val customObjectDetectorOptions =
        CustomObjectDetectorOptions.Builder(model)
        .setDetectorMode(CustomObjectDetectorOptions.SINGLE_IMAGE_MODE)
        .enableClassification()
        .setClassificationConfidenceThreshold(0.5f)
        .setMaxPerObjectLabelCount(3)
        .build()

val objectDetector =
        ObjectDetection.getClient(customObjectDetectorOptions)

Java

File modelFile = new File(context.getCacheDir(), "my_remote_model.tflite");

LocalModel model;
if (modelFile.exists()) {
    // Use the downloaded model if available
    model = new LocalModel.Builder().setAbsoluteFilePath(modelFile.getAbsolutePath()).build();
} else {
    // Fall back to the bundled model
    model = new LocalModel.Builder().setAssetFilePath("model.tflite").build();
}

CustomObjectDetectorOptions customObjectDetectorOptions =
        new CustomObjectDetectorOptions.Builder(model)
                .setDetectorMode(CustomObjectDetectorOptions.SINGLE_IMAGE_MODE)
                .enableClassification()
                .setClassificationConfidenceThreshold(0.5f)
                .setMaxPerObjectLabelCount(3)
                .build();

ObjectDetector objectDetector =
        ObjectDetection.getClient(customObjectDetectorOptions);

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

Kotlin

val localFile = File(context.cacheDir, "my_remote_model.tflite")
if (localFile.exists()) {
    // Model is already cached, initialize immediately
    initializeDetector(localFile)
} else {
    // Model is not yet available, show loading UI and start download
    showLoadingUI()
    val storage = Firebase.storage
    val modelRef = storage.getReferenceFromUrl("gs://YOUR_BUCKET/path/to/model.tflite")
    modelRef.getFile(localFile)
        .addOnSuccessListener {
            // Download complete, initialize the detector
            hideLoadingUI()
            initializeDetector(localFile)
        }
        .addOnFailureListener {
            // Handle download error
            showErrorUI()
        }
}

private fun initializeDetector(modelFile: File) {
    val localModel = LocalModel.Builder().setAbsoluteFilePath(modelFile.absolutePath).build()
    val customObjectDetectorOptions = CustomObjectDetectorOptions.Builder(localModel)
            .setDetectorMode(CustomObjectDetectorOptions.SINGLE_IMAGE_MODE)
            .enableClassification()
            .build()
    val objectDetector = ObjectDetection.getClient(customObjectDetectorOptions)
    // Enable ML-related UI features here
    enableMLFeatures(objectDetector)
}

Java

File localFile = new File(context.getCacheDir(), "my_remote_model.tflite");
if (localFile.exists()) {
    // Model is already cached, initialize immediately
    initializeDetector(localFile);
} else {
    // Model is not yet available, show loading UI and start download
    showLoadingUI();
    FirebaseStorage storage = FirebaseStorage.getInstance();
    StorageReference modelRef = storage.getReferenceFromUrl("gs://YOUR_BUCKET/path/to/model.tflite");
    modelRef.getFile(localFile)
        .addOnSuccessListener(new OnSuccessListener<FileDownloadTask.TaskSnapshot>() {
            @Override
            public void onSuccess(FileDownloadTask.TaskSnapshot taskSnapshot) {
                // Download complete, initialize the detector
                hideLoadingUI();
                initializeDetector(localFile);
            }
        })
        .addOnFailureListener(new OnFailureListener() {
            @Override
            public void onFailure(@NonNull Exception exception) {
                // Handle download error
                showErrorUI();
            }
        });
}

private void initializeDetector(File modelFile) {
    LocalModel localModel = new LocalModel.Builder().setAbsoluteFilePath(modelFile.getAbsolutePath()).build();
    CustomObjectDetectorOptions customObjectDetectorOptions =
            new CustomObjectDetectorOptions.Builder(localModel)
                    .setDetectorMode(CustomObjectDetectorOptions.SINGLE_IMAGE_MODE)
                    .enableClassification()
                    .build();
    ObjectDetector objectDetector = ObjectDetection.getClient(customObjectDetectorOptions);
    // Enable ML-related UI features here
    enableMLFeatures(objectDetector);
}

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

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

אפשר ליצור אובייקט 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(). זה שימושי כשמשתמשים ב-ACTION_GET_CONTENT intent כדי להציג למשתמש בקשה לבחור תמונה מאפליקציית הגלריה שלו.

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 יחד עם מעלות הסיבוב.

4. הפעלת זיהוי האובייקטים

Kotlin

objectDetector
    .process(image)
    .addOnFailureListener(e -> {...})
    .addOnSuccessListener(results -> {
        for (detectedObject in results) {
          // ...
        }
    });

Java

objectDetector
    .process(image)
    .addOnFailureListener(e -> {...})
    .addOnSuccessListener(results -> {
        for (DetectedObject detectedObject : results) {
          // ...
        }
    });

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

5. קבלת מידע על אובייקטים עם תוויות

אם הקריאה ל-process() מצליחה, רשימה של DetectedObjects מועברת למאזין ההצלחה.

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

כל DetectedObject מכיל את המאפיינים הבאים:

תיבה תוחמת (bounding box)	‫Rect שמציין את מיקום האובייקט בתמונה.
מזהה לצורכי מעקב	מספר שלם שמזהה את האובייקט בתמונות. ‫Null ב-SINGLE_IMAGE_MODE.
תוויות	תיאור תווית תיאור הטקסט של התווית. הערך הזה מוחזר רק אם המטא-נתונים של מודל LiteRT מכילים תיאורי תוויות. אינדקס התוויות האינדקס של התווית מבין כל התוויות שהמסווג תומך בהן. רמת הוודאות של התווית ערך מהימנות של סיווג האובייקט.

Kotlin

// The list of detected objects contains one item if multiple
// object detection wasn't enabled.
for (detectedObject in results) {
    val boundingBox = detectedObject.boundingBox
    val trackingId = detectedObject.trackingId
    for (label in detectedObject.labels) {
      val text = label.text
      val index = label.index
      val confidence = label.confidence
    }
}

Java

// The list of detected objects contains one item if multiple
// object detection wasn't enabled.
for (DetectedObject detectedObject : results) {
  Rect boundingBox = detectedObject.getBoundingBox();
  Integer trackingId = detectedObject.getTrackingId();
  for (Label label : detectedObject.getLabels()) {
    String text = label.getText();
    int index = label.getIndex();
    float confidence = label.getConfidence();
  }
}

הערה: אם משתמשים במודל LiteRT שלא תואם ל-ML Kit, מקבלים MlKitException עם קוד השגיאה MlKitException#INVALID_ARGUMENT ופרטים מסוימים לגבי הסיבה לכך שהוא לא תואם. פרטים נוספים מפורטים במאמר בנושא דרישות התאימות של מודלים בהתאמה אישית.

איך מבטיחים חוויית משתמש מעולה

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

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

כדאי גם לעיין באפליקציית התצוגה של ML Kit Material Design ובאוסף הדפוסים של תכונות מבוססות למידת מכונה של Material Design.

Improving performance

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

• כשמשתמשים במצב סטרימינג באפליקציה בזמן אמת, לא מומלץ להשתמש בכמה זיהוי אובייקטים, כי רוב המכשירים לא יוכלו להפיק קצבי פריימים מספיקים.

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