Wykrywanie i śledzenie obiektów przy użyciu ML Kit na Androidzie

Zadbaj o dobrą organizację dzięki kolekcji Zapisuj i kategoryzuj treści zgodnie ze swoimi preferencjami.

Możesz używać ML Kit do wykrywania i śledzenia obiektów w kolejnych klatkach wideo.

Gdy przekazujesz obraz do narzędzia ML Kit, wykrywa on maksymalnie 5 obiektów na obrazie wraz z jego położeniem. Podczas wykrywania obiektów w strumieniach wideo każdy obiekt ma unikalny identyfikator, którego można użyć do śledzenia obiektu między ramkami. Opcjonalnie możesz też włączyć przybliżoną klasyfikację obiektów, która oznacza obiekty etykietami z szerokimi opisami kategorii.

Wypróbuj

Zanim zaczniesz

  1. W pliku build.gradle na poziomie projektu umieść repozytorium Google Maven w sekcjach buildscript i allprojects.
  2. Dodaj zależności bibliotek ML Kit na Androida do pliku Gradle na poziomie aplikacji, który zwykle wynosi app/build.gradle:
    dependencies {
      // ...
    
      implementation 'com.google.mlkit:object-detection:17.0.0'
    
    }
    

1. Konfigurowanie wzorca do wykrywania obiektów

Aby wykrywać i śledzić obiekty, najpierw utwórz instancję ObjectDetector i opcjonalnie określ ustawienia wzorca do wykrywania, które chcesz zmienić z poziomu domyślnego.

  1. Skonfiguruj wzorzec do wykrywania obiektów w swoim przypadku użycia za pomocą obiektu ObjectDetectorOptions. Możesz zmienić te ustawienia:

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

    W STREAM_MODE (domyślnie) wzorzec do wykrywania obiektów działa z krótkim czasem oczekiwania, ale przy pierwszych wywołaniach wzorca może wykryć niepełne wyniki (takie jak nieokreślone ramki ograniczające lub etykiety kategorii). Oprócz tego w detektorze STREAM_MODE do obiektów są przypisywane identyfikatory śledzenia, których możesz używać do śledzenia obiektów w ramkach. Użyj tego trybu, jeśli chcesz śledzić obiekty lub gdy ważne jest małe opóźnienie, na przykład podczas przetwarzania strumieni wideo w czasie rzeczywistym.

    W obiekcie SINGLE_IMAGE_MODE wzorzec do wykrywania obiektów zwraca wynik po określeniu ramki ograniczającej obiekt. Jeśli włączysz także klasyfikację, wyniki będą zwracane po udostępnieniu ramki ograniczającej i etykiety kategorii. W efekcie opóźnienie wykrywania może być większe. Oprócz tego w SINGLE_IMAGE_MODE nie są przypisywane identyfikatory śledzenia. Użyj tego trybu, jeśli opóźnienie nie jest krytyczne i nie chcesz uwzględniać częściowych wyników.

    Wykrywaj i śledź wiele obiektów false (domyślnie) | true

    Określa, czy chcesz wykryć i śledzić maksymalnie 5 obiektów czy tylko najbardziej widoczny obiekt (domyślnie).

    Klasyfikowanie obiektów false (domyślnie) | true

    Określa, czy wykryte obiekty mają zostać sklasyfikowane w ramach przybliżonych kategorii. Po włączeniu tej funkcji wykrywacz obiektów klasyfikuje obiekty w te kategorie: artykuły odzieżowe, jedzenie, artykuły gospodarstwa domowego, 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 i śledzenie najsłynniejszego obiektu w wizjerze kamery.
    • Wykrywanie wielu obiektów na podstawie statycznego obrazu.

    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.

Wzorzec do wykrywania 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 elementu InputImage na podstawie tych źródeł. Jeśli utworzysz tag InputImage z innych źródeł, przeprowadzimy dla Ciebie konwersję wewnętrznie, co może obniżyć jej wydajność.

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

Obiekt InputImage możesz utworzyć z różnych źródeł. Poniżej objaśniamy poszczególne z nich.

Korzystanie z: media.Image

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

Jeśli używasz biblioteki Aparat X, klasy OnImageCapturedListener i ImageAnalysis.Analyzer obliczają wartość rotacji.

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 zdjęć, która zapewnia kąt obrotu zdjęcia, możesz obliczyć ją 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ść stopni 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 InputImage z identyfikatora URI pliku, przekaż kontekst aplikacji i identyfikator URI pliku do InputImage.fromFilePath(). Jest to przydatne, gdy użyjesz intencji ACTION_GET_CONTENT, aby poprosić użytkownika o wybranie obrazu z 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();
}

Korzystanie z ByteBuffer lub ByteArray

Aby utworzyć obiekt InputImage z 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 z buforem lub tablicą wraz z wysokością, szerokością, formatem kolorów i stopniem rotacji:

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

Korzystanie z: Bitmap

Aby utworzyć obiekt InputImage z obiektu Bitmap, złóż tę deklarację:

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. Przetwórz obraz

Przekaż obraz za pomocą 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. Uzyskaj informacje o wykrytych obiektach

Jeśli wywołanie process() zakończy się powodzeniem, do odbiornika zostanie przekazana lista DetectedObjects.

Każdy element 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 określająca obiekt na obrazach. Brak wartości SINGLE_IMAGE_MODE.
Etykiety
Opis etykiety Tekst etykiety. Będzie to jedna ze stałych ciągów znaków zdefiniowanych w zasadzie PredefinedCategory.
Indeks etykiety Indeks etykiety wśród wszystkich etykiet obsługiwanych przez klasyfikator. Będzie to jedna ze stały liczby całkowitej zdefiniowanej w PredefinedCategory.
Pewność etykiety Wartość ufności klasyfikacji obiektów.

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, zastosuj się do tych wskazówek:

  • Pomyślne wykrywanie obiektu zależy od jego złożoności wizualnej. Aby obiekt został wykryty, obiekty o małej liczbie elementów wizualnych mogą zająć większą część obrazu. Należy przekazać użytkownikom wskazówki dotyczące przechwytywania danych wejściowych, które dobrze współgrają z obiektami, które mają być wykrywane.
  • Jeśli używasz klasyfikacji, aby wykrywać obiekty, które nie należą do obsługiwanych kategorii, zaimplementuj specjalną obsługę elementów nieznanych.

Zapoznaj się także z aplikacją Material Design z prezentacją ML Kit i kolekcją wzorców dla funkcji wykorzystujących systemy uczące się.

Improving performance

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

  • Jeśli używasz trybu strumieniowego przesyłania danych w aplikacji w czasie rzeczywistym, nie używaj wykrywania wielu obiektów, ponieważ większość urządzeń nie będzie w stanie generować odpowiedniej liczby klatek.

  • Wyłącz klasyfikację, której nie potrzebujesz.

  • Jeśli używasz interfejsu API Camera lub camera2, ograniczaj wywołania do wzorca do wykrywania treści. Jeśli po uruchomieniu wzorca do wykrywania filmów dostępna będzie nowa ramka, puść ją. Przykład znajdziesz w klasie VisionProcessorBase w przykładowej aplikacji krótkiego wprowadzenia.
  • Jeśli korzystasz z interfejsu API CameraX, sprawdź, czy strategia pushpress ma ustawioną wartość domyślną ImageAnalysis.STRATEGY_KEEP_ONLY_LATEST. Gwarantuje to, że w danym momencie do analizy zostanie wysłany tylko 1 obraz. Jeśli analizator jest zajęty, więcej obrazów jest usuwanych, a następnie usuwanych automatycznie i nie znajdujących się w kolejce w celu dostarczenia. Gdy analizowany obraz zostanie zamknięty, wywołany jest obiekt ImageProxy.close(). Pojawi się następny obraz.
  • Jeśli używasz danych wyjściowych wzorca do nakładania grafiki na obrazie wejściowym, najpierw pobierz wynik z ML Kit, a następnie wyrenderuj obraz i nakładkę w jednym kroku. Renderuje się na wyświetlaczu tylko raz dla każdej klatki wejściowej. Przykład znajdziesz w klasach CameraSourcePreview i GraphicOverlay w przykładowej aplikacji krótkiego wprowadzenia.
  • Jeśli używasz interfejsu Camera2 API, zrób zdjęcia w formacie ImageFormat.YUV_420_888. Jeśli używasz starszego interfejsu API aparatu, zrób zdjęcia w formacie ImageFormat.NV21.