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

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

Gdy przekażesz obraz do ML Kit, wykryje on maksymalnie 5 obiektów na obrazie wraz z ich położeniem. Podczas wykrywania obiektów w strumieniach wideo każdy obiekt ma unikalny identyfikator, którego możesz używać do śledzenia obiektu w kolejnych klatkach. Opcjonalnie możesz też włączyć klasyfikację obiektów, która przypisuje do obiektów etykiety z ogólnymi opisami kategorii.

Wypróbuj

Zanim zaczniesz

  1. W pliku build.gradle na poziomie projektu dodaj repozytorium Google Maven do sekcji buildscript i allprojects.
  2. Dodaj zależności do bibliotek ML Kit na Androida do pliku Gradle na poziomie modułu, który zwykle znajduje się w app/build.gradle: 
    dependencies {
  // ...

  implementation 'com.google.mlkit:object-detection:17.0.2'

}

1. Skonfiguruj detektor obiektów

Aby wykrywać i śledzić obiekty, najpierw utwórz instancję ObjectDetector i opcjonalnie określ ustawienia detektora, które chcesz zmienić w stosunku do ustawień domyślnych.

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

    Ustawienia detektora obiektów
    Tryb wykrywania STREAM_MODE (domyślnie) | SINGLE_IMAGE_MODE

    W trybie STREAM_MODE (domyślnie) detektor obiektów działa z krótkim czasem oczekiwania, ale podczas kilku pierwszych wywołań może zwracać niepełne wyniki (np. nieokreślone ramki ograniczające lub etykiety kategorii). W trybie STREAM_MODE, detektor przypisuje też do obiektów identyfikatory śledzenia, których możesz używać do śledzenia obiektów w kolejnych klatkach. Używaj tego trybu, gdy chcesz śledzić obiekty lub gdy ważny jest krótki czas oczekiwania, np. podczas przetwarzania strumieni wideo w czasie rzeczywistym.

    W trybie SINGLE_IMAGE_MODE detektor obiektów zwraca wynik po określeniu ramki ograniczającej obiektu. Jeśli włączysz też klasyfikację, detektor zwróci wynik, gdy dostępne będą zarówno ramka ograniczająca, jak i etykieta kategorii. W rezultacie, czas oczekiwania na wykrycie może być dłuższy. W trybie SINGLE_IMAGE_MODE nie są też przypisywane identyfikatory śledzenia. Używaj tego trybu, jeśli czas oczekiwania nie jest krytyczny i nie chcesz mieć do czynienia z częściowymi wynikami.
    Wykrywanie i śledzenie wielu obiektów false (domyślnie) | true

    Czy wykrywać i śledzić maksymalnie 5 obiektów, czy tylko najbardziej widoczny obiekt (domyślnie).
    Klasyfikowanie obiektów false (domyślnie) | true

    Czy klasyfikować wykryte obiekty w ogólnych kategoriach. Gdy ta opcja jest włączona, detektor obiektów klasyfikuje obiekty w tych kategoriach: odzież, żywność, sprzęt domowy, miejsca i rośliny.

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

    • Wykrywanie i śledzenie w czasie rzeczywistym 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. Przygotuj obraz wejściowy

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

Detektor obiektów działa bezpośrednio na podstawie Bitmap, NV21 ByteBuffer lub YUV_420_888 media.Image. Jeśli masz bezpośredni dostęp do jednego z tych źródeł, zalecamy utworzenie InputImage na jego podstawie. Jeśli utworzysz an InputImage na podstawie innych źródeł, zajmiemy się konwersją wewnętrznie, ale może to być mniej wydajne.

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

Obiekt InputImage możesz utworzyć na podstawie różnych źródeł. Poniżej znajdziesz ich opis.

Używanie media.Image

Aby utworzyć obiekt InputImage na podstawie obiektu media.Image, np. gdy robisz zdjęcie aparatem urządzenia, przekaż obiekt media.Image i obrót obrazu do InputImage.fromMediaImage().

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

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 używasz biblioteki aparatu, która podaje 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
}

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)

Java

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

Używanie identyfikatora URI pliku

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

Kotlin

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

Używanie ByteBuffer lub ByteArray

Aby utworzyć obiekt InputImage na podstawie ByteBuffer lub ByteArray, najpierw oblicz stopień obrotu obrazu jak opisano wcześniej w przypadku danych wejściowych media.Image. Następnie utwórz obiekt InputImage za pomocą bufora lub tablicy oraz wysokości, szerokości, formatu kodowania kolorów i stopnia obrotu obrazu:

Kotlin

val image = InputImage.fromByteBuffer(
        byteBuffer,
        /* image width */ 480,
        /* image height */ 360,
        rotationDegrees,
        InputImage.IMAGE_FORMAT_NV21 // or IMAGE_FORMAT_YV12
)
// Or:
val image = InputImage.fromByteArray(
        byteArray,
        /* 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
);
// Or:
InputImage image = InputImage.fromByteArray(
        byteArray,
        /* image width */480,
        /* image height */360,
        rotation,
        InputImage.IMAGE_FORMAT_NV21 // or IMAGE_FORMAT_YV12
);

Używanie Bitmap

Aby utworzyć obiekt InputImage na podstawie obiektu Bitmap, użyj tej deklaracji:

Kotlin

val image = InputImage.fromBitmap(bitmap, 0)

Java

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

Obraz jest reprezentowany przez obiekt Bitmap wraz ze stopniami obrotu.

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

4. Pobieranie informacji o wykrytych obiektach

Jeśli wywołanie process() się powiedzie, do odbiornika sukcesu zostanie przekazana lista DetectedObject.

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

Ramka ograniczająca Rect, który wskazuje położenie obiektu na obrazie.
Identyfikator śledzenia Liczba całkowita, która identyfikuje obiekt na obrazach. W trybie SINGLE_IMAGE_MODE ma wartość null.
Etykiety
Opis etykiety Tekstowy opis etykiety. Będzie to jedna ze stałych typu String zdefiniowanych w PredefinedCategory.
Indeks etykiety Indeks etykiety wśród wszystkich etykiet obsługiwanych przez klasyfikator. Będzie to jedna ze stałych typu integer zdefiniowanych w PredefinedCategory.
Wiarygodność etykiety Poziom 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();
    }
}

Zapewnianie użytkownikom jak najlepszych wrażeń

Aby zapewnić użytkownikom jak najlepsze wrażenia, postępuj zgodnie z tymi wskazówkami:

  • Skuteczność wykrywania obiektów zależy od ich złożoności wizualnej. Aby można było wykryć obiekty z niewielką liczbą cech wizualnych, mogą one zajmować większą część obrazu. Powinieneś(-aś) poinformować użytkowników, jak przechwytywać dane wejściowe, które dobrze współpracują z rodzajami obiektów, które chcesz wykrywać.
  • Jeśli używasz klasyfikacji i chcesz wykrywać obiekty, które nie pasują do obsługiwanych kategorii, zaimplementuj specjalną obsługę nieznanych obiektów.

Zapoznaj się też z aplikacją demonstracyjną ML Kit Material Design i zbiorem wzorców Material Design dla funkcji opartych na uczeniu maszynowym.

Zwiększanie skuteczności

Jeśli chcesz używać 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ę:

  • Jeśli używasz trybu strumieniowego w aplikacji działającej w czasie rzeczywistym, nie używaj wykrywania wielu obiektów, ponieważ większość urządzeń nie będzie w stanie zapewnić odpowiedniej liczby klatek na sekundę.

  • Jeśli nie potrzebujesz klasyfikacji, wyłącz ją.

  • Jeśli używasz interfejsu Camera lub camera2 API, ograniczaj wywołania detektora. Jeśli podczas działania detektora pojawi się nowa klatka filmu, pomiń ją. Przykład znajdziesz w klasie VisionProcessorBase w przykładowej aplikacji z krótkim przewodnikiem.
  • Jeśli używasz interfejsu CameraX API, upewnij się, że strategia przeciwdziałania nadmiarowi danych jest ustawiona na wartość domyślną ImageAnalysis.STRATEGY_KEEP_ONLY_LATEST. Gwarantuje to, że do analizy będzie dostarczany tylko 1 obraz naraz. Jeśli podczas pracy analizatora zostanie wygenerowanych więcej obrazów, zostaną one automatycznie pominięte i nie zostaną dodane do kolejki dostarczania. Gdy obraz analizowany zostanie zamknięty przez wywołanie ImageProxy.close(), zostanie dostarczony 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 w jednym kroku wyrenderuj obraz i nałóż na niego grafikę. Dzięki temu renderowanie na powierzchni wyświetlacza odbywa się tylko raz na każdą klatkę wejściową. Przykład znajdziesz w klasach CameraSourcePreview i GraphicOverlay w przykładowej aplikacji z krótkim przewodnikiem.
  • Jeśli używasz interfejsu Camera2 API, rób zdjęcia w ImageFormat.YUV_420_888 formacie. Jeśli używasz starszego interfejsu Camera API, rób zdjęcia w ImageFormat.NV21 formacie.