Wykrywanie i śledzenie obiektów za pomocą ML Kit na Androidzie

Za pomocą ML Kit możesz wykrywać i śledzić obiekty w kolejnych klatkach wideo.

Gdy przekazujesz obraz do ML Kit, wykrywa on maksymalnie 5 obiektów na obrazie wraz z położeniem każdego z nich. Podczas wykrywania obiektów w strumieniach wideo każdy z nich ma unikalny identyfikator, który umożliwia śledzenie obiektu od klatki do klatki. Możesz też opcjonalnie włączyć przybliżoną klasyfikację obiektów, która oznacza etykietami obiekty o szerokim opisie kategorii.

Ten interfejs API wykorzystuje niezgrupowaną bibliotekę, którą należy pobrać przed użyciem. Więcej informacji znajdziesz w tym przewodniku.

Wypróbuj

• Zapoznaj się z przykładową aplikacją, aby zobaczyć przykład użycia tego interfejsu API.
• Aby uzyskać kompleksową implementację tego interfejsu API, zobacz aplikację z funkcją prezentacji Material Design.

Zanim zaczniesz

Ten interfejs API wymaga interfejsu API Androida na poziomie 21 lub wyższym. Upewnij się, że plik kompilacji aplikacji używa wartości minSdkVersion o wartości 21 lub większej.

1. W pliku build.gradle na poziomie projektu dodaj repozytorium Google Maven w sekcjach buildscript i allprojects.
2. Dodaj zależności bibliotek ML Kit na Androida do pliku Gradle modułu na poziomie aplikacji, którym jest zwykle app/build.gradle:

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

1. Konfigurowanie detektora obiektów

Aby wykrywać i śledzić obiekty, najpierw utwórz instancję usługi ObjectDetector i opcjonalnie wskaż ustawienia wzorca do wykrywania, które chcesz zmienić niż domyślne.

1. Skonfiguruj detektor obiektów na potrzeby swojego przypadku użycia za pomocą obiektu ObjectDetectorOptions. Możesz zmienić następujące ustawienia:

   Ustawienia wykrywania obiektów
   Tryb wykrywania	STREAM_MODE (domyślna) | SINGLE_IMAGE_MODE W STREAM_MODE (domyślnie) detektor obiektów działa z krótkim czasem oczekiwania, ale już po kilku pierwszych wywołaniach detektora może powodować niekompletne wyniki (takie jak nieokreślone ramki ograniczające czy etykiety kategorii). Dodatkowo w STREAM_MODE detektor przypisuje do obiektów identyfikatory śledzenia, których możesz używać do śledzenia obiektów w ramkach. Używaj tego trybu, gdy chcesz śledzić obiekty lub gdy zależy Ci na krótkim czasie oczekiwania, np. przy przetwarzaniu strumieni wideo w czasie rzeczywistym. W SINGLE_IMAGE_MODE detektor obiektów zwraca wynik po określeniu ramki ograniczającej obiektu. Jeśli włączysz też klasyfikację, otrzymasz wynik, gdy ramka ograniczająca i etykieta kategorii będą dostępne. W związku z tym czas oczekiwania na wykrywanie może być dłuższy. W SINGLE_IMAGE_MODE identyfikatory śledzenia nie są przypisane. Użyj tego trybu, jeśli czas oczekiwania nie ma krytycznego znaczenia i nie chcesz mieć do czynienia z częściowymi wynikami.
   Wykrywanie i śledzenie wielu obiektów	false (domyślna) | true Określa, czy wykrywać i śledzić maksymalnie 5 obiektów czy tylko najbardziej widoczne obiekty (ustawienie domyślne).
   Klasyfikowanie obiektów	false (domyślna) | true Określa, czy należy sklasyfikować wykryte obiekty w przybliżonych kategoriach. Gdy ta opcja jest włączona, detektor obiektów klasyfikuje obiekty w następujące kategorie: artykuły modowe, żywność, AGD, miejsca i rośliny.

   Interfejs API wykrywania i śledzenia obiektów jest zoptymalizowany pod kątem tych 2 głównych przypadków użycia:

   • Wykrywanie na żywo i śledzenie najbardziej widocznego obiektu w wizjerze aparatu.
   • Wykrywanie wielu obiektów na obrazie statycznym.

   Aby skonfigurować interfejs API pod kątem tych przypadków użycia:

   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. Pobierz instancję ObjectDetector:

   Kotlin

   val objectDetector = ObjectDetection.getClient(options)

   Java

   ObjectDetector objectDetector = ObjectDetection.getClient(options);

2. Przygotowywanie obrazu wejściowego

Aby wykrywać i śledzić obiekty, przekaż obrazy do metody process() instancji ObjectDetector.

Wykrywacz obiektów działa bezpośrednio z Bitmap, NV21 ByteBuffer lub YUV_420_888 media.Image. Jeśli masz bezpośredni dostęp do jednego z nich, zalecamy utworzenie InputImage z tych źródeł. Jeśli utworzysz InputImage z innych źródeł, my zajmiemy się konwersją wewnętrznie za Ciebie i może to przynieść mniej efektu.

Dla każdej klatki filmu lub obrazu w sekwencji wykonaj te czynności:

Obiekt InputImage możesz utworzyć z różnych źródeł. Poniżej znajdziesz opis każdego z nich.

Korzystanie z: media.Image

Aby utworzyć obiekt InputImage na podstawie obiektu media.Image, na przykład podczas rejestrowania obrazu aparatem urządzenia, przekaż obiekt media.Image i obrót obrazu do InputImage.fromMediaImage().

Jeśli używasz biblioteki AparatuX, klasy OnImageCapturedListener i ImageAnalysis.Analyzer obliczają wartość obrotu za Ciebie.

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

Jeśli nie korzystasz z biblioteki aparatu, która określa stopień obrotu obrazu, możesz go obliczyć na podstawie stopnia obrotu urządzenia i orientacji czujnika aparatu w urządzeniu:

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

Następnie przekaż obiekt media.Image i wartość stopnia obrotu do InputImage.fromMediaImage():

Kotlin

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

Java

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

Za pomocą identyfikatora URI pliku

Aby utworzyć obiekt InputImage na podstawie identyfikatora URI pliku, przekaż do InputImage.fromFilePath() kontekst aplikacji i identyfikator URI pliku. Jest to przydatne, gdy używasz intencji ACTION_GET_CONTENT, aby zachęcić użytkownika do wybrania obrazu z aplikacji galerii.

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

Przy użyciu: ByteBuffer lub ByteArray

Aby utworzyć obiekt InputImage na podstawie ByteBuffer lub ByteArray, najpierw oblicz stopień obrotu obrazu zgodnie z wcześniejszym opisem dla danych wejściowych media.Image. Następnie utwórz obiekt InputImage z buforem lub tablicą i podaj wysokość, szerokość, format kodowania kolorów i stopień obrotu:

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

Korzystanie z: Bitmap

Aby utworzyć obiekt InputImage z obiektu Bitmap, wypełnij tę deklarację:

Kotlin

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

Java

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

Obraz jest reprezentowany przez obiekt Bitmap wraz z informacją o obróceniu w stopniach.

3. Przetwarzanie obrazu

Przekaż obraz do metody 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
                // ...
            }
        });

Uwaga: jeśli korzystasz z interfejsu API CameraX, zamknij ImageProxy po zakończeniu jego używania, np. dodając OnCompleteListener do obiektu Task zwróconego przez metodę process. Przykład znajdziesz w klasie VisionProcessorBase w przykładowej aplikacji z krótkim wprowadzeniem.

4. Uzyskiwanie informacji o wykrytych obiektach

Jeśli wywołanie process() się powiedzie, do detektora powodzenia zostanie przekazana lista elementów DetectedObject.

Uwaga: w trybie strumieniowania detektor obiektów może potrzebować 30 lub więcej klatek, w zależności od wydajności urządzenia, zanim wykryje pierwszy obiekt.

Każdy element DetectedObject zawiera te właściwości:

Ramka ograniczająca	Rect, który wskazuje pozycję obiektu na obrazie.
Identyfikator śledzenia	Liczba całkowita, która identyfikuje obiekt na obrazach. Wartość null w trybie SINGLE_IMAGE_MODE.
Etykiety	Opis etykiety Opis tekstowy etykiety. Będzie to jedna ze stałych ciągu znaków zdefiniowanych w polu PredefinedCategory. Indeks etykiety Indeks etykiety wśród wszystkich etykiet obsługiwanych przez klasyfikator. Będzie to jedna ze stałych liczb całkowitych zdefiniowanych w PredefinedCategory. Poziom ufności etykiet Wartość ufności klasyfikacji obiektu.

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

Dbanie o wygodę użytkowników

Aby zadbać o wygodę użytkowników, przestrzegaj tych wytycznych:

• Pomyślne wykrycie obiektu zależy od jego złożoności wizualnej. Obiekty z niewielką liczbą funkcji wizualnych mogą być wykrywane, gdy trzeba zająć większą część obrazu. Przekaż użytkownikom wskazówki dotyczące przechwytywania danych wejściowych, które będą dobrze działać w przypadku rodzaju obiektów, które chcesz wykrywać.
• Jeśli korzystasz z klasyfikacji, jeśli chcesz wykrywać obiekty, które nie trafią bezpośrednio do obsługiwanych kategorii, zastosuj specjalną obsługę nieznanych obiektów.

Zapoznaj się też z aplikacją do prezentacji ML Kit Material Design i z kolekcją Material Design Wzorce dla funkcji opartych na systemach uczących się.

Improving performance

Jeśli chcesz korzystać z wykrywania obiektów w aplikacji działającej w czasie rzeczywistym, postępuj zgodnie z tymi wskazówkami, aby uzyskać najlepszą liczbę klatek na sekundę:

• Gdy używasz trybu strumieniowania w aplikacji działającej w czasie rzeczywistym, nie używaj wykrywania wielu obiektów, ponieważ większość urządzeń nie jest w stanie wygenerować odpowiedniej liczby klatek.

• Wyłącz klasyfikację, jeśli jej nie potrzebujesz.

• Jeśli używasz interfejsu API Camera lub camera2, ograniczaj wywołania detektora. Jeśli podczas działania detektora pojawi się nowa klatka wideo, upuść ją. Przykład znajdziesz w klasie VisionProcessorBase w przykładowej aplikacji z krótkim wprowadzeniem.
• Jeśli używasz interfejsu API CameraX, upewnij się, że strategia obciążenia zwrotnego jest ustawiona na wartość domyślną ImageAnalysis.STRATEGY_KEEP_ONLY_LATEST. Gwarantuje to, że do analizy zostanie dostarczony tylko 1 obraz naraz. Jeśli zostanie utworzonych więcej obrazów, gdy analizator jest zajęty, zostaną one automatycznie usunięte i nie trafią do kolejki dostarczania. Gdy analizowany obraz zostanie zamknięty przez wywołanie metody ImageProxy.close(), zostanie wyświetlony następny najnowszy obraz.
• Jeśli używasz danych wyjściowych detektora do nakładania grafiki na obraz wejściowy, najpierw pobierz wynik z ML Kit, a potem wyrenderuj obraz i nakładkę w jednym kroku. Powoduje to renderowanie na powierzchni wyświetlania tylko raz na każdą klatkę wejściową. Przykład znajdziesz w klasach CameraSourcePreview i GraphicOverlay w przykładowej aplikacji z krótkim wprowadzeniem.
• Jeśli używasz interfejsu Camera2 API, rób zdjęcia w formacie ImageFormat.YUV_420_888. Jeśli używasz starszej wersji interfejsu Camera API, rób zdjęcia w formacie ImageFormat.NV21.