Wykrywaj i śledź obiekty za pomocą ML Kit na Androida

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

Kiedy przekazujesz obrazy ML Kit, ML Kit zwraca dla każdego obrazu listę maksymalnie pięciu wykrytych obiektów i ich położenie na obrazie. Podczas wykrywania obiektów w strumieniach wideo każdy obiekt ma identyfikator, którego można użyć do śledzenia obiektu na obrazach. Opcjonalnie możesz także włączyć zgrubną klasyfikację obiektów, która oznacza obiekty z szerokimi opisami kategorii.

Zanim zaczniesz

  1. Jeśli jeszcze tego nie zrobiłeś, dodaj Firebase do swojego projektu na Androida .
  2. Dodaj zależności dla bibliotek ML Kit Android do pliku Gradle modułu (na poziomie aplikacji) (zwykle app/build.gradle ): 
    apply plugin: 'com.android.application'
apply plugin: 'com.google.gms.google-services'

dependencies {
  // ...

  implementation 'com.google.firebase:firebase-ml-vision:24.0.3'
  implementation 'com.google.firebase:firebase-ml-vision-object-detection-model:19.0.6'
}

1. Skonfiguruj detektor obiektów

Aby rozpocząć wykrywanie i śledzenie obiektów, najpierw utwórz instancję FirebaseVisionObjectDetector , opcjonalnie określając ustawienia detektora, które chcesz zmienić z domyślnych.

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

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

    W trybie STREAM_MODE (domyślnie) detektor obiektów działa z małym opóźnieniem, ale może generować niekompletne wyniki (takie jak nieokreślone ramki ograniczające lub etykiety kategorii) przy kilku pierwszych wywołaniach detektora. Ponadto w STREAM_MODE detektor przypisuje obiektom identyfikatory śledzenia, których można używać do śledzenia obiektów w klatkach. 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 detektor obiektów czeka, aż ramka ograniczająca wykrytego obiektu i (jeśli włączyłeś klasyfikację) etykieta kategorii będą dostępne, zanim zwróci wynik. W rezultacie opóźnienie wykrywania jest potencjalnie większe. Ponadto w SINGLE_IMAGE_MODE identyfikatory śledzenia nie są przypisywane. Użyj tego trybu, jeśli opóźnienie nie jest krytyczne i nie chcesz mieć do czynienia z częściowymi wynikami.

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

    Określa, czy wykrywać i śledzić maksymalnie pięć obiektów, czy tylko najbardziej widoczny obiekt (domyślnie).

    Klasyfikuj obiekty false (domyślnie) | true

    Określa, czy klasyfikować wykryte obiekty do ogólnych kategorii. Po włączeniu detektor obiektów klasyfikuje obiekty w następujące kategorie: artykuły modowe, żywność, artykuły gospodarstwa domowego, miejsca, rośliny i nieznane.

    Interfejs API wykrywania i śledzenia obiektów jest zoptymalizowany pod kątem 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 dla tych przypadków użycia:

    Java

    // Live detection and tracking
FirebaseVisionObjectDetectorOptions options =
        new FirebaseVisionObjectDetectorOptions.Builder()
                .setDetectorMode(FirebaseVisionObjectDetectorOptions.STREAM_MODE)
                .enableClassification()  // Optional
                .build();

// Multiple object detection in static images
FirebaseVisionObjectDetectorOptions options =
        new FirebaseVisionObjectDetectorOptions.Builder()
                .setDetectorMode(FirebaseVisionObjectDetectorOptions.SINGLE_IMAGE_MODE)
                .enableMultipleObjects()
                .enableClassification()  // Optional
                .build();

    Kotlin+KTX

    // Live detection and tracking
val options = FirebaseVisionObjectDetectorOptions.Builder()
        .setDetectorMode(FirebaseVisionObjectDetectorOptions.STREAM_MODE)
        .enableClassification()  // Optional
        .build()

// Multiple object detection in static images
val options = FirebaseVisionObjectDetectorOptions.Builder()
        .setDetectorMode(FirebaseVisionObjectDetectorOptions.SINGLE_IMAGE_MODE)
        .enableMultipleObjects()
        .enableClassification()  // Optional
        .build()

  2. Uzyskaj instancję FirebaseVisionObjectDetector :

    Java

    FirebaseVisionObjectDetector objectDetector =
        FirebaseVision.getInstance().getOnDeviceObjectDetector();

// Or, to change the default settings:
FirebaseVisionObjectDetector objectDetector =
        FirebaseVision.getInstance().getOnDeviceObjectDetector(options);

    Kotlin+KTX

    val objectDetector = FirebaseVision.getInstance().getOnDeviceObjectDetector()

// Or, to change the default settings:
val objectDetector = FirebaseVision.getInstance().getOnDeviceObjectDetector(options)

2. Uruchom detektor obiektów

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

Dla każdej klatki wideo lub obrazu w sekwencji wykonaj następujące czynności:

  1. Utwórz obiekt FirebaseVisionImage ze swojego obrazu.

    • Aby utworzyć obiekt FirebaseVisionImage z obiektu media.Image , na przykład podczas przechwytywania obrazu z kamery urządzenia, przekaż obiekt media.Image i obrót obrazu do FirebaseVisionImage.fromMediaImage() .

      Jeśli korzystasz z biblioteki CameraX , klasy OnImageCapturedListener i ImageAnalysis.Analyzer obliczają wartość rotacji za Ciebie, więc wystarczy przekonwertować rotację na jedną ze stałych ROTATION_ ML Kit przed wywołaniem FirebaseVisionImage.fromMediaImage() :

      Java

      private class YourAnalyzer implements ImageAnalysis.Analyzer {

    private int degreesToFirebaseRotation(int degrees) {
        switch (degrees) {
            case 0:
                return FirebaseVisionImageMetadata.ROTATION_0;
            case 90:
                return FirebaseVisionImageMetadata.ROTATION_90;
            case 180:
                return FirebaseVisionImageMetadata.ROTATION_180;
            case 270:
                return FirebaseVisionImageMetadata.ROTATION_270;
            default:
                throw new IllegalArgumentException(
                        "Rotation must be 0, 90, 180, or 270.");
        }
    }

    @Override
    public void analyze(ImageProxy imageProxy, int degrees) {
        if (imageProxy == null || imageProxy.getImage() == null) {
            return;
        }
        Image mediaImage = imageProxy.getImage();
        int rotation = degreesToFirebaseRotation(degrees);
        FirebaseVisionImage image =
                FirebaseVisionImage.fromMediaImage(mediaImage, rotation);
        // Pass image to an ML Kit Vision API
        // ...
    }
}

      Kotlin+KTX

      private class YourImageAnalyzer : ImageAnalysis.Analyzer {
    private fun degreesToFirebaseRotation(degrees: Int): Int = when(degrees) {
        0 -> FirebaseVisionImageMetadata.ROTATION_0
        90 -> FirebaseVisionImageMetadata.ROTATION_90
        180 -> FirebaseVisionImageMetadata.ROTATION_180
        270 -> FirebaseVisionImageMetadata.ROTATION_270
        else -> throw Exception("Rotation must be 0, 90, 180, or 270.")
    }

    override fun analyze(imageProxy: ImageProxy?, degrees: Int) {
        val mediaImage = imageProxy?.image
        val imageRotation = degreesToFirebaseRotation(degrees)
        if (mediaImage != null) {
            val image = FirebaseVisionImage.fromMediaImage(mediaImage, imageRotation)
            // Pass image to an ML Kit Vision API
            // ...
        }
    }
}

      Jeśli nie korzystasz z biblioteki kamer, która umożliwia obrót obrazu, możesz go obliczyć na podstawie obrotu urządzenia i orientacji czujnika kamery w urządzeniu:

      Java

      private static final SparseIntArray ORIENTATIONS = new SparseIntArray();
static {
    ORIENTATIONS.append(Surface.ROTATION_0, 90);
    ORIENTATIONS.append(Surface.ROTATION_90, 0);
    ORIENTATIONS.append(Surface.ROTATION_180, 270);
    ORIENTATIONS.append(Surface.ROTATION_270, 180);
}

/**
 * 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, Context context)
        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);

    // On most devices, the sensor orientation is 90 degrees, but for some
    // devices it is 270 degrees. For devices with a sensor orientation of
    // 270, rotate the image an additional 180 ((270 + 270) % 360) degrees.
    CameraManager cameraManager = (CameraManager) context.getSystemService(CAMERA_SERVICE);
    int sensorOrientation = cameraManager
            .getCameraCharacteristics(cameraId)
            .get(CameraCharacteristics.SENSOR_ORIENTATION);
    rotationCompensation = (rotationCompensation + sensorOrientation + 270) % 360;

    // Return the corresponding FirebaseVisionImageMetadata rotation value.
    int result;
    switch (rotationCompensation) {
        case 0:
            result = FirebaseVisionImageMetadata.ROTATION_0;
            break;
        case 90:
            result = FirebaseVisionImageMetadata.ROTATION_90;
            break;
        case 180:
            result = FirebaseVisionImageMetadata.ROTATION_180;
            break;
        case 270:
            result = FirebaseVisionImageMetadata.ROTATION_270;
            break;
        default:
            result = FirebaseVisionImageMetadata.ROTATION_0;
            Log.e(TAG, "Bad rotation value: " + rotationCompensation);
    }
    return result;
}
      VisionImage.java

      Kotlin+KTX

      private val ORIENTATIONS = SparseIntArray()

init {
    ORIENTATIONS.append(Surface.ROTATION_0, 90)
    ORIENTATIONS.append(Surface.ROTATION_90, 0)
    ORIENTATIONS.append(Surface.ROTATION_180, 270)
    ORIENTATIONS.append(Surface.ROTATION_270, 180)
}
/**
 * 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, context: Context): 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)

    // On most devices, the sensor orientation is 90 degrees, but for some
    // devices it is 270 degrees. For devices with a sensor orientation of
    // 270, rotate the image an additional 180 ((270 + 270) % 360) degrees.
    val cameraManager = context.getSystemService(CAMERA_SERVICE) as CameraManager
    val sensorOrientation = cameraManager
            .getCameraCharacteristics(cameraId)
            .get(CameraCharacteristics.SENSOR_ORIENTATION)!!
    rotationCompensation = (rotationCompensation + sensorOrientation + 270) % 360

    // Return the corresponding FirebaseVisionImageMetadata rotation value.
    val result: Int
    when (rotationCompensation) {
        0 -> result = FirebaseVisionImageMetadata.ROTATION_0
        90 -> result = FirebaseVisionImageMetadata.ROTATION_90
        180 -> result = FirebaseVisionImageMetadata.ROTATION_180
        270 -> result = FirebaseVisionImageMetadata.ROTATION_270
        else -> {
            result = FirebaseVisionImageMetadata.ROTATION_0
            Log.e(TAG, "Bad rotation value: $rotationCompensation")
        }
    }
    return result
}
      VisionImage.kt

      Następnie przekaż obiekt media.Image i wartość rotacji do FirebaseVisionImage.fromMediaImage() :

      Java

      FirebaseVisionImage image = FirebaseVisionImage.fromMediaImage(mediaImage, rotation);
      VisionImage.java

      Kotlin+KTX

      val image = FirebaseVisionImage.fromMediaImage(mediaImage, rotation)
      VisionImage.kt
    • Aby utworzyć obiekt FirebaseVisionImage na podstawie identyfikatora URI pliku, przekaż kontekst aplikacji i identyfikator URI pliku do FirebaseVisionImage.fromFilePath() . Jest to przydatne, gdy używasz intencji ACTION_GET_CONTENT do monitowania użytkownika o wybranie obrazu z aplikacji galerii.

      Java

      FirebaseVisionImage image;
try {
    image = FirebaseVisionImage.fromFilePath(context, uri);
} catch (IOException e) {
    e.printStackTrace();
}
      VisionImage.java

      Kotlin+KTX

      val image: FirebaseVisionImage
try {
    image = FirebaseVisionImage.fromFilePath(context, uri)
} catch (e: IOException) {
    e.printStackTrace()
}
      VisionImage.kt
    • Aby utworzyć obiekt FirebaseVisionImage z ByteBuffer lub tablicy bajtów, najpierw oblicz obrót obrazu w sposób opisany powyżej dla wejścia media.Image .

      Następnie utwórz obiekt FirebaseVisionImageMetadata zawierający wysokość, szerokość, format kodowania kolorów i obrót obrazu:

      Java

      FirebaseVisionImageMetadata metadata = new FirebaseVisionImageMetadata.Builder()
        .setWidth(480)   // 480x360 is typically sufficient for
        .setHeight(360)  // image recognition
        .setFormat(FirebaseVisionImageMetadata.IMAGE_FORMAT_NV21)
        .setRotation(rotation)
        .build();
      VisionImage.java

      Kotlin+KTX

      val metadata = FirebaseVisionImageMetadata.Builder()
        .setWidth(480) // 480x360 is typically sufficient for
        .setHeight(360) // image recognition
        .setFormat(FirebaseVisionImageMetadata.IMAGE_FORMAT_NV21)
        .setRotation(rotation)
        .build()
      VisionImage.kt

      Użyj bufora lub tablicy oraz obiektu metadanych, aby utworzyć obiekt FirebaseVisionImage :

      Java

      FirebaseVisionImage image = FirebaseVisionImage.fromByteBuffer(buffer, metadata);
// Or: FirebaseVisionImage image = FirebaseVisionImage.fromByteArray(byteArray, metadata);
      VisionImage.java

      Kotlin+KTX

      val image = FirebaseVisionImage.fromByteBuffer(buffer, metadata)
// Or: val image = FirebaseVisionImage.fromByteArray(byteArray, metadata)
      VisionImage.kt
    • Aby utworzyć obiekt FirebaseVisionImage z obiektu Bitmap :

      Java

      FirebaseVisionImage image = FirebaseVisionImage.fromBitmap(bitmap);
      VisionImage.java

      Kotlin+KTX

      val image = FirebaseVisionImage.fromBitmap(bitmap)
      VisionImage.kt
      Obraz reprezentowany przez obiekt Bitmap musi być ustawiony pionowo i nie jest wymagany żaden dodatkowy obrót.

  2. Przekaż obraz do metody processImage() :

    Java

    objectDetector.processImage(image)
        .addOnSuccessListener(
                new OnSuccessListener<List<FirebaseVisionObject>>() {
                    @Override
                    public void onSuccess(List<FirebaseVisionObject> detectedObjects) {
                        // Task completed successfully
                        // ...
                    }
                })
        .addOnFailureListener(
                new OnFailureListener() {
                    @Override
                    public void onFailure(@NonNull Exception e) {
                        // Task failed with an exception
                        // ...
                    }
                });

    Kotlin+KTX

    objectDetector.processImage(image)
        .addOnSuccessListener { detectedObjects ->
            // Task completed successfully
            // ...
        }
        .addOnFailureListener { e ->
            // Task failed with an exception
            // ...
        }

  3. Jeśli wywołanie processImage() powiedzie się, lista FirebaseVisionObject zostanie przekazana do odbiornika powodzenia.

    Każdy FirebaseVisionObject zawiera następujące właściwości:

    Pole ograniczające Rect wskazujący położenie obiektu na obrazie.
    Identyfikator śledzenia Liczba całkowita identyfikująca obiekt na obrazach. Null w SINGLE_IMAGE_MODE.
    Kategoria Gruba kategoria obiektu. Jeśli detektor obiektów nie ma włączonej klasyfikacji, jest to zawsze FirebaseVisionObject.CATEGORY_UNKNOWN .
    Zaufanie Wartość ufności klasyfikacji obiektu. Jeśli detektor obiektów nie ma włączonej klasyfikacji lub obiekt jest sklasyfikowany jako nieznany, wartość ta wynosi null .

    Java

    // The list of detected objects contains one item if multiple object detection wasn't enabled.
for (FirebaseVisionObject obj : detectedObjects) {
    Integer id = obj.getTrackingId();
    Rect bounds = obj.getBoundingBox();

    // If classification was enabled:
    int category = obj.getClassificationCategory();
    Float confidence = obj.getClassificationConfidence();
}

    Kotlin+KTX

    // The list of detected objects contains one item if multiple object detection wasn't enabled.
for (obj in detectedObjects) {
    val id = obj.trackingId       // A number that identifies the object across images
    val bounds = obj.boundingBox  // The object's position in the image

    // If classification was enabled:
    val category = obj.classificationCategory
    val confidence = obj.classificationConfidence
}

Poprawa użyteczności i wydajności

Aby zapewnić najlepszą wygodę użytkowania, postępuj zgodnie z tymi wskazówkami w swojej aplikacji:

  • Skuteczne wykrycie obiektu zależy od jego złożoności wizualnej. Aby obiekty o niewielkiej liczbie cech wizualnych mogły zostać wykryte, konieczne może być zajęcie większej części obrazu. Powinieneś zapewnić użytkownikom wskazówki dotyczące przechwytywania danych wejściowych, które sprawdzają się w przypadku obiektów, które chcesz wykryć.
  • Jeśli podczas korzystania z klasyfikacji chcesz wykryć obiekty, które nie mieszczą się w obsługiwanych kategoriach, zaimplementuj specjalną obsługę nieznanych obiektów.

Zapoznaj się także z [aplikacją prezentacyjną ML Kit Material Design] [showcase-link]{: .external } i kolekcją Material Design Patterns na potrzeby funkcji opartych na uczeniu maszynowym .

Korzystając z trybu przesyłania strumieniowego w aplikacji czasu rzeczywistego, postępuj zgodnie z poniższymi wskazówkami, aby uzyskać najlepszą liczbę klatek na sekundę:

  • Nie używaj wykrywania wielu obiektów w trybie przesyłania strumieniowego, ponieważ większość urządzeń nie będzie w stanie wygenerować odpowiedniej liczby klatek na sekundę.

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

  • Przepustnica wzywa do detektora. Jeżeli w trakcie działania detektora pojawi się nowa klatka wideo, usuń ją.
  • Jeśli używasz wyjścia detektora 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 ten sposób renderujesz na powierzchnię wyświetlacza tylko raz dla każdej klatki wejściowej.

  • Jeśli korzystasz z interfejsu API Camera2, przechwytuj obrazy w formacie ImageFormat.YUV_420_888 .

    Jeśli używasz starszego interfejsu Camera API, przechwytuj obrazy w formacie ImageFormat.NV21 .