זיהוי אובייקטים ומעקב אחריהם באמצעות ML Kit ב-Android

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

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

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

רוצה לנסות?

• מומלץ לשחק עם האפליקציה לדוגמה כדי .
• לצפייה בתצוגה של עיצוב חומרים (Material Design) אפליקציה להטמעה מקצה לקצה של ה-API הזה.

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

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

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

   dependencies {
     // ...
   
     implementation 'com.google.mlkit:object-detection:17.0.1'
   
   }
   

1. הגדרת מזהה האובייקטים

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

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

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

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

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

   כדי להגדיר את ה-API לתרחישים לדוגמה האלה:

   Kotlin

   // Live detection and tracking
   val options = ObjectDetectorOptions.Builder()
           .setDetectorMode(ObjectDetectorOptions.STREAM_MODE)
           .enableClassification()  // Optional
           .build()
   
   // Multiple object detection in static images
   val options = ObjectDetectorOptions.Builder()
           .setDetectorMode(ObjectDetectorOptions.SINGLE_IMAGE_MODE)
           .enableMultipleObjects()
           .enableClassification()  // Optional
           .build()

   Java

   // Live detection and tracking
   ObjectDetectorOptions options =
           new ObjectDetectorOptions.Builder()
                   .setDetectorMode(ObjectDetectorOptions.STREAM_MODE)
                   .enableClassification()  // Optional
                   .build();
   
   // Multiple object detection in static images
   ObjectDetectorOptions options =
           new ObjectDetectorOptions.Builder()
                   .setDetectorMode(ObjectDetectorOptions.SINGLE_IMAGE_MODE)
                   .enableMultipleObjects()
                   .enableClassification()  // Optional
                   .build();

2. מקבלים מופע של ObjectDetector:

   Kotlin

   val objectDetector = ObjectDetection.getClient(options)

   Java

   ObjectDetector objectDetector = ObjectDetection.getClient(options);

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

כדי לזהות אובייקטים ולעקוב אחריהם, צריך להעביר תמונות אל ObjectDetector באמצעות ה-method process() של המכונה.

מזהה האובייקטים פועל ישירות מ-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() זה שימושי כאשר צריך להשתמש ב-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

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

Java

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

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

4. קבלת מידע על אובייקטים שזוהו

אם הקריאה אל process() תתבצע בהצלחה, תועבר רשימה של DetectedObject אל 'המאזינים להצלחה'.

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

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

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

Kotlin

for (detectedObject in detectedObjects) {
    val boundingBox = detectedObject.boundingBox
    val trackingId = detectedObject.trackingId
    for (label in detectedObject.labels) {
        val text = label.text
        if (PredefinedCategory.FOOD == text) {
            ...
        }
        val index = label.index
        if (PredefinedCategory.FOOD_INDEX == index) {
            ...
        }
        val confidence = label.confidence
    }
}

Java

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

הבטחת חוויית משתמש מעולה

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

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

בנוסף, כדאי לעיין אפליקציית ML Kit Material Design עיצוב חומר איסוף תבניות לתכונות מבוססות-למידת מכונה.

Improving performance

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

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

• אפשר להשבית את הסיווג אם לא צריך אותו.

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