Objekte mit ML Kit auf Android-Geräten erkennen und verfolgen

Mit dem ML Kit können Sie in aufeinanderfolgenden Videoframes Objekte erkennen und verfolgen.

Wenn Sie ein Bild an ML Kit übergeben, werden im Objekt bis zu fünf Objekte zusammen mit der Position der einzelnen Objekte im Bild erkannt. Wenn Objekte in Videostreams erkannt werden, hat jedes Objekt eine eindeutige ID, mit der Sie das Objekt von Frame zu Frame erfassen können. Sie können optional die grobe Objektklassifizierung aktivieren, die Objekte mit Beschreibungen allgemeiner Kategorien kennzeichnet.

Diese API verwendet eine entbündelte Bibliothek, die vor der Verwendung heruntergeladen werden muss. Weitere Informationen finden Sie in diesem Leitfaden.

Testen

• Probieren Sie die Beispiel-App aus, um sich ein Anwendungsbeispiel dieser API anzusehen.
• Eine vollständige Implementierung dieser API findest du in der Material Design Showcase App.

Hinweis

Für diese API ist Android API-Level 19 oder höher erforderlich. Achten Sie darauf, dass die Build-Datei Ihrer Anwendung einen minSdkVersion-Wert von 19 oder höher verwendet.

1. Achten Sie darauf, dass Sie in der Datei build.gradle auf Projektebene das Maven-Repository von Google in die Abschnitte buildscript und allprojects aufnehmen.
2. Fügen Sie die Abhängigkeiten für die ML Kit-Android-Bibliotheken in die Gradle-Datei des Moduls auf App-Ebene ein, die normalerweise app/build.gradle ist:

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

1. Objektdetektor konfigurieren

Erstellen Sie zuerst eine Instanz von ObjectDetector, um Objekte zu erkennen und zu verfolgen, und geben Sie optional alle Detektoreinstellungen an, die Sie als Standardeinstellung ändern möchten.

1. Konfigurieren Sie den Objektdetektor für Ihren Anwendungsfall mit einem ObjectDetectorOptions-Objekt. Sie können die folgenden Einstellungen ändern:

   Einstellungen für Objektdetektoren
   Erkennungsmodus	STREAM_MODE (Standard) | SINGLE_IMAGE_MODE In STREAM_MODE (Standard) wird der Objektdetektor mit niedriger Latenz ausgeführt. Er kann jedoch bei den ersten Aufrufen des Detektors zu unvollständigen Ergebnissen (wie nicht spezifizierten Begrenzungsrahmen oder Kategorielabels) führen. Außerdem weist der Detektor in STREAM_MODE Objekten Tracking-IDs zu, mit denen Sie Objekte rahmenübergreifend verfolgen können. Verwenden Sie diesen Modus, wenn Sie Objekte erfassen möchten oder wenn eine niedrige Latenz wichtig ist, z. B. bei der Verarbeitung von Videostreams in Echtzeit. In SINGLE_IMAGE_MODE gibt der Objektdetektor das Ergebnis zurück, nachdem der Begrenzungsrahmen des Objekts festgelegt wurde. Wenn Sie auch die Klassifizierung aktivieren, wird das Ergebnis zurückgegeben, sobald der Begrenzungsrahmen und das Kategorielabel verfügbar sind. Die Erkennungslatenz ist daher potenziell höher. Außerdem werden in SINGLE_IMAGE_MODE keine Tracking-IDs zugewiesen. Verwenden Sie diesen Modus, wenn die Latenz nicht kritisch ist und Sie keine Teilergebnisse verarbeiten möchten.
   Mehrere Objekte erkennen und verfolgen	false (Standard) | true Gibt an, ob bis zu fünf Objekte oder nur das auffälligste Objekt erkannt und verfolgt werden soll (Standardeinstellung).
   Objekte klassifizieren	false (Standard) | true Gibt an, ob erkannte Objekte in groben Kategorien klassifiziert werden sollen. Wenn die Objekterkennung aktiviert ist, können Objekte in die folgenden Kategorien eingeordnet werden: Mode, Lebensmittel, Haushaltswaren, Orte und Pflanzen.

   Die Objekterkennungs- und Tracking-API ist für diese beiden Kernanwendungsfälle optimiert:

   • Live-Erkennung und -Tracking des auffälligsten Objekts im Kamerasucher
   • Die Erkennung mehrerer Objekte aus einem statischen Bild.

   So konfigurieren Sie die API für diese Anwendungsfälle:

   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. Rufen Sie eine Instanz von ObjectDetector ab:

   Kotlin

   val objectDetector = ObjectDetection.getClient(options)

   Java

   ObjectDetector objectDetector = ObjectDetection.getClient(options);

2. Eingabebild vorbereiten

Wenn Sie Objekte erkennen und verfolgen möchten, übergeben Sie Bilder an die Methode process() der Instanz ObjectDetector.

Der Objektdetektor wird direkt von Bitmap, NV21 ByteBuffer oder YUV_420_888 media.Image ausgeführt. Das Erstellen einer InputImage aus diesen Quellen wird empfohlen, wenn Sie direkten Zugriff auf eine dieser Quellen haben. Wenn Sie eine InputImage aus anderen Quellen erstellen, führen wir die Konvertierung intern für Sie durch und sie ist möglicherweise weniger effizient.

Führen Sie für jeden Video- oder Bildframe die folgenden Schritte aus:

Sie können ein InputImage-Objekt aus verschiedenen Quellen erstellen. Dies wird im Folgenden erläutert.

Mit einem media.Image

Wenn Sie ein InputImage-Objekt aus einem media.Image-Objekt erstellen möchten, z. B. wenn Sie ein Bild von der Kamera eines Geräts aufnehmen, übergeben Sie das Objekt media.Image und die Rotation des Bildes an InputImage.fromMediaImage().

Wenn Sie die KameraX-Bibliothek verwenden, berechnen die Klassen OnImageCapturedListener und ImageAnalysis.Analyzer den Rotationswert für Sie.

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
          // ...
        }
    }
}

Wenn Sie keine Kamerabibliothek verwenden, die Ihnen den Grad der Drehung des Bildes angibt, können Sie ihn anhand des Grads der Drehung und der Ausrichtung des Kamerasensors im Gerät berechnen:

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;
}

Übergeben Sie dann das Objekt media.Image und den Rotationsgradwert an InputImage.fromMediaImage():

Kotlin

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

Java

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

Datei-URI verwenden

Übergeben Sie den Anwendungskontext und den Datei-URI an InputImage.fromFilePath(), um ein InputImage-Objekt aus einem Datei-URI zu erstellen. Dies ist nützlich, wenn Sie den Intent ACTION_GET_CONTENT verwenden, um den Nutzer aufzufordern, ein Bild aus der Galerie-App auszuwählen.

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();
}

Mit ByteBuffer oder ByteArray

Berechnen Sie zum Erstellen eines InputImage-Objekts aus einem ByteBuffer oder einem ByteArray zuerst den Grad der Bilddrehung, wie zuvor für die media.Image-Eingabe beschrieben. Erstellen Sie dann das Objekt InputImage mit dem Zwischenspeicher oder Array, zusammen mit Höhe, Breite, Farbcodierungsformat und Rotationsgrad des Bildes:

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

Mit einem Bitmap

Erstellen Sie zum Anlegen eines InputImage-Objekts aus einem Bitmap-Objekt die folgende Deklaration:

Kotlin

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

Java

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

Das Bild wird durch ein Bitmap-Objekt zusammen mit einem Rotationsgrad dargestellt.

3. Bild verarbeiten

Übergeben Sie das Bild an die Methode 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
                // ...
            }
        });

Hinweis: Wenn Sie die CameraX API verwenden, müssen Sie ImageProxy schließen, wenn Sie die API nicht mehr verwenden. Fügen Sie beispielsweise OnCompleteListener zu Task hinzu, das von der Methode process zurückgegeben wird. Ein Beispiel finden Sie in der Kurzanleitungs-Beispielanwendung in der Klasse VisionProcessorBase.

4. Informationen zu erkannten Objekten abrufen

Wenn der Aufruf von process() erfolgreich ist, wird eine Liste von DetectedObjects an den Erfolgs-Listener übergeben.

Hinweis: Im Streamingmodus muss der Objektdetektor je nach Geräteleistung möglicherweise 30 oder mehr Frames verarbeiten, bevor das erste Objekt erkannt wird.

Jeder DetectedObject enthält die folgenden Attribute:

Begrenzungsrahmen	Ein Rect, der die Position des Objekts im Bild angibt.
Tracking-ID	Eine Ganzzahl, die das Objekt über Bilder hinweg identifiziert. Null in SINGLE_IMAGE_MODE.
Labels	Labelbeschreibung Die Textbeschreibung des Labels. Sie ist eine der in PredefinedCategory definierten Stringkonstanten. Label index Der Index des Labels unter allen vom Klassifikator unterstützten Labels. Sie ist eine der in PredefinedCategory definierten Ganzzahlkonstanten. Label-Konfidenz Der Konfidenzwert der Objektklassifizierung.

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();
    }
}

Nutzerfreundlichkeit optimieren

Beachten Sie für Ihre App die folgenden Richtlinien:

• Die erfolgreiche Objekterkennung hängt von der visuellen Komplexität des Objekts ab. Objekte, die nur wenige visuelle Merkmale haben, müssen möglicherweise einen größeren Teil des Bildes einnehmen, damit sie erkannt werden. Sie sollten Nutzern eine Anleitung zum Erfassen von Eingaben zur Verfügung stellen, die gut für die Art von Objekten geeignet sind, die Sie erkennen möchten.
• Wenn Sie bei der Klassifizierung Objekte erkennen möchten, die sich nicht in die von Ihnen unterstützten Kategorien einordnen lassen, implementieren Sie eine besondere Behandlung für unbekannte Objekte.

Weitere Informationen finden Sie auch in der Sammlung Material Kit Showcase Design und in der Material Design-Sammlung Muster für Machine Learning-Funktionen.

Leistung erhöhen

Wenn Sie die Objekterkennung in einer Echtzeitanwendung verwenden möchten, beachten Sie die folgenden Richtlinien, um die besten Framerates zu erzielen:

• Wenn Sie den Streamingmodus in einer Echtzeitanwendung verwenden, sollten Sie nicht die Mehrfachobjekterkennung verwenden, da die meisten Geräte keine angemessenen Frame-Raten erzeugen können.

• Deaktivieren Sie die Klassifizierung, wenn Sie sie nicht benötigen.

• Wenn Sie die Camera oder camera2 API verwenden, drosseln Sie Aufrufe an den Detektor. Wenn während der Ausführung des Detektors ein neuer Videoframe verfügbar ist, lassen Sie den Frame fallen. Ein Beispiel finden Sie in der Kurzanleitungs-Beispielanwendung in der Klasse VisionProcessorBase.
• Achten Sie bei Verwendung der CameraX API darauf, dass die Rückdruckstrategie auf den Standardwert ImageAnalysis.STRATEGY_KEEP_ONLY_LATEST festgelegt ist. Dadurch wird garantiert, dass jeweils nur ein Bild zur Analyse übermittelt wird. Wenn das Analyseprogramm ausgelastet ist, werden mehr Bilder erstellt, damit sie nicht zur Auslieferung in die Warteschlange gestellt werden. Sobald das analysierte Bild durch Aufrufen von ImageProxy.close() geschlossen wird, wird das nächste neueste Bild gesendet.
• Wenn Sie die Ausgabe des Detektors verwenden, um Grafiken auf dem Eingabebild einzublenden, rufen Sie zuerst das Ergebnis aus ML Kit ab und rendern dann das Bild und das Overlay in einem einzigen Schritt. Wird für jeden Eingabeframe nur einmal auf der Anzeigeoberfläche gerendert. Ein Beispiel findest du in den Beispielklassen CameraSourcePreview und GraphicOverlay.
• Wenn Sie die Camera2 API verwenden, nehmen Sie Bilder im Format ImageFormat.YUV_420_888 auf. Wenn Sie die ältere Camera API verwenden, nehmen Sie Bilder im Format ImageFormat.NV21 auf.