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.

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

Gdy przekazujesz obraz do narzędzia ML Kit, wykrywa on maksymalnie 5 obiektów na obrazie wraz z pozycją każdego obiektu na obrazie. Podczas wykrywania obiektów w strumieniach wideo każdy obiekt ma niepowtarzalny identyfikator, który można śledzić między klatkami. Możesz też włączyć przybliżoną klasyfikację obiektów, co spowoduje dodanie do nich etykiet z szerokimi opisami kategorii.

Zanim zaczniesz

  1. W pliku build.gradle na poziomie projektu umieść repozytorium Maven Google i w sekcjach buildscript i allprojects.
  2. Dodaj zależności do 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 wszelkie ustawienia wzorca do wykrywania treści, które chcesz zmienić z poziomu domyślnego.

  1. Skonfiguruj wzorzec do wykrywania treści na potrzeby zastosowania za pomocą obiektu ObjectDetectorOptions. Możesz zmienić te ustawienia:

    Ustawienia wzorca do 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 w pierwszych kilku wywołaniach wzorca może zwrócić niepełne wyniki (np. nieokreślone ramki ograniczające lub etykiety kategorii). Dodatkowo w STREAM_MODE wzorzec do wykrywania obiektów zostaje przypisany do obiektów w celu ś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 SINGLE_IMAGE_MODE wzorzec do wykrywania obiektów zwraca wynik po określeniu ramki granicznej obiektu. Jeśli włączysz także klasyfikację, zwróci ona wynik po udostępnieniu ramki ograniczenia i etykiety kategorii. W rezultacie opóźnienie wykrywania może być większe. Poza tym SINGLE_IMAGE_MODE nie ma przypisanych identyfikatorów śledzenia. Użyj tego trybu, jeśli czas oczekiwania nie jest krytyczny i nie chcesz obsługiwać częściowych wyników.

    Wykrywanie i śledzenie wielu obiektów false (domyślnie) | true

    Określa, czy chcesz wykrywać i śledzić maksymalnie 5 obiektów czy tylko najbardziej wyróżniony obiekt (domyślnie).

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

    Określa, czy wykryte obiekty mają być klasyfikowane na ogólne kategorie. Po włączeniu wykrywacz obiektów klasyfikuje obiekty w te kategorie: artykuły odzieżowe, jedzenie, artykuły gospodarstwa domowego, miejsca i rośliny.

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

    • Wykrywanie na żywo i śledzenie najbardziej widocznego obiektu w wizjerze aparatu.
    • Wykrywanie wielu obiektów na podstawie obrazu statycznego.

    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. Pobieranie instancji ObjectDetector:

    Kotlin

    val objectDetector = ObjectDetection.getClient(options)

    Java

    ObjectDetector objectDetector = ObjectDetection.getClient(options);

2. Przygotowanie obrazu wejściowego

Aby wykrywać i śledzić obiekty, przekazuj obrazy do metody ObjectDetectorprocess().

Wzorzec do wykrywania obiektów działa bezpośrednio z poziomu Bitmap, NV21 ByteBuffer lub YUV_420_888 media.Image. Jeśli masz bezpośredni dostęp do jednego z nich, zalecamy utworzenie elementu InputImage z tych źródeł. Jeśli tworzysz element InputImage z innych źródeł, zajmiemy się konwersją wewnętrznie, co może obniżyć jego skuteczność.

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

Obiekt InputImage możesz utworzyć z różnych źródeł, a każde z nich opisano poniżej.

Używanie modułu media.Image

Aby utworzyć obiekt InputImage z obiektu media.Image, na przykład podczas robienia obrazu z aparatu urządzenia, przekaż obiekt media.Image, a obraz zostanie obrócony do InputImage.fromMediaImage().

Jeśli używasz biblioteki KameraX, 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 obrazu, możesz go obliczyć na podstawie stopni obrotu urządzenia i orientacji czujnika aparatu w tym 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 prześlij 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 pliku do InputImage.fromFilePath(). Ta opcja jest przydatna, gdy używasz intencji ACTION_GET_CONTENT zachęcającej użytkownika do wybrania zdjęcia 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 narzędzia 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 kodowania kolorów i stopniem obrotu:

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 modułu 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 z stopniami obrotu.

3. Przetwórz obraz

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 metody process() zakończy się powodzeniem, detektor będzie przekazywać listę DetectedObject s.

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 identyfikująca obiekt na obrazach. Brak wartości SINGLE_IMAGE_MODE.
Etykiety
Opis etykiety Opis tekstowy etykiety. Będzie to jedna z stałych ciągu znaków zdefiniowanych w PredefinedCategory.
Indeks etykiety Indeks etykiety obejmuje wszystkie etykiety obsługiwane przez klasyfikator. Będzie to jedna ze stałych liczb całkowitych zdefiniowanych 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 komfort użytkowników

Aby zadbać o wygodę użytkowników, postępuj zgodnie z tymi wskazówkami w aplikacji:

  • Pomyślne wykrywanie obiektów zależy od złożoności wizualnej obiektu. Aby można było wykryć obiekty, które mają niewielką liczbę funkcji wizualnych, może być konieczne zajęcie większej części obrazu. Należy przekazać użytkownikom wskazówki dotyczące przechwytywania danych wejściowych, które dobrze działają z rodzajami obiektów, które mają być wykrywane.
  • Jeśli używasz klasyfikacji, jeśli chcesz wykrywać obiekty, które nie należą do obsługiwanych kategorii, zaimplementuj specjalną obsługę na nieznanych obiektach.

Zobacz też aplikację ML Kit Material Design i wzór Material Design na potrzeby funkcji obsługiwanych przez systemy uczące się.

Improving performance

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

  • Gdy korzystasz z trybu strumieniowego w aplikacji w czasie rzeczywistym, nie używaj wykrywania wielu obiektów, ponieważ większość urządzeń nie jest w stanie wygenerować wystarczającej liczby klatek.

  • Wyłącz klasyfikację, jeśli nie jest potrzebna.

  • Jeśli używasz interfejsu Camera lub camera2 API, ograniczaj wywołania wzorca do wykrywania treści. Jeśli podczas działania wzorca do wykrywania treści dostępna jest nowa ramka wideo, upuść ją. Przykład znajdziesz w klasie VisionProcessorBase w przykładowej aplikacji.
  • Jeśli korzystasz z interfejsu API CameraX, upewnij się, że strategia ciśnienia wstecznego jest ustawiona na wartość domyślną ImageAnalysis.STRATEGY_KEEP_ONLY_LATEST. Zapewnia to tylko jeden obraz naraz. Jeśli w analizatorze będzie dużo więcej obrazów, to będą one automatycznie usuwane i nie będą umieszczane w kolejce. Po zamknięciu analizujemy obraz, wywołując polecenie ImageProxy.close(). Następny obraz jest wyświetlany.
  • Jeśli używasz danych wyjściowych wzorca do nakładania grafiki na obraz wejściowy, najpierw uzyskaj wynik z ML Kit, a następnie wyrenderuj obraz i nakładkę w jednym kroku. W przypadku każdej klatki wejściowej jest ona renderowana tylko raz na ekranie. Przykład znajdziesz w klasach CameraSourcePreview i GraphicOverlay w przykładowej aplikacji.
  • 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.