Detecta objetos y hazles seguimiento con el Kit de AA en Android

Puedes usar el Kit de AA para detectar objetos y hacerles seguimiento en todos los fotogramas de video.

Cuando pasas imágenes del Kit de AA, este muestra, para cada imagen, una lista de hasta cinco objetos detectados y su posición en la imagen. Cuando detectas objetos en transmisiones de video por Internet, cada uno de ellos tiene un ID que puedes usar para seguirlo en las imágenes. De manera opcional, puedes habilitar la clasificación ordinaria de objetos, que etiqueta los objetos con descripciones de categorías amplias.

Antes de comenzar

  1. Si aún no lo has hecho, agrega Firebase a tu proyecto de Android.
  2. Agrega las dependencias para las bibliotecas de Android del Kit de AA al archivo Gradle (generalmente app/build.gradle) de tu módulo (nivel de app):
    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. Configura el detector de objetos

Para comenzar a detectar objetos y hacerles seguimiento, primero debes crear una instancia de FirebaseVisionObjectDetector que, de manera opcional, especifique cualquier configuración del detector que quieras cambiar de la configuración predeterminada.

  1. Configura el detector de objetos para tu caso práctico con un objeto FirebaseVisionObjectDetectorOptions. Puedes cambiar las siguientes opciones de configuración:

    Configuración del detector de objetos
    Modo de detección STREAM_MODE (predeterminado) | SINGLE_IMAGE_MODE

    En el STREAM_MODE (predeterminado), el detector de objetos se ejecuta con baja latencia, pero podría generar resultados incompletos (como cuadros de límite o etiquetas de categoría no especificados) en las primeras invocaciones del detector. Además, en el STREAM_MODE, el detector asigna ID de seguimiento a los objetos, que puedes usar para hacer seguimiento de objetos en los fotogramas. Usa este modo cuando quieras hacer seguimiento de objetos o cuando la baja latencia sea importante, como cuando procesas transmisiones de video en Internet en tiempo real.

    En el SINGLE_IMAGE_MODE, el detector de objetos espera hasta que el cuadro de límite (si habilitaste la clasificación) y la etiqueta de categoría de un objeto detectado estén disponibles antes de mostrar un resultado. En consecuencia, la latencia de detección es más alta potencialmente. Además, en el SINGLE_IMAGE_MODE, no se asignan ID de seguimiento. Usa este modo si la latencia no es importante y no quieres lidiar con resultados parciales.
    Detecta varios objetos y hazles seguimiento false (predeterminado) | true

    Ya sea para detectar y hacer seguimiento de hasta cinco objetos o solo al más prominente (predeterminado).
    Clasifica objetos false (predeterminado) | true

    Ya sea para clasificar o no objetos detectados en categorías ordinarias. Cuando se encuentra habilitado, el detector de objetos clasifica los objetos en las siguientes categorías: productos de moda, comida, productos para el hogar, lugares, plantas y desconocidos.

    La API de detección y seguimiento de objetos está optimizada para estos dos casos prácticos principales:

    • Detección y seguimiento en vivo del objeto más prominente en el visor de la cámara.
    • Detección de múltiples objetos de una imagen estática.

    Si deseas configurar la API para estos casos de uso, utiliza este código:

    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 

    // 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. Obtén una instancia de FirebaseVisionObjectDetector:

    Java 

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

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

    Kotlin 

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

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

2. Ejecuta el detector de objetos

Para detectar objetos y hacerles seguimiento, pasa imágenes al método processImage() de la instancia de FirebaseVisionObjectDetector.

Para cada fotograma de video o imagen en una secuencia, haz lo siguiente:

  1. Crea un objeto FirebaseVisionImage a partir de tu imagen.

    • Para crear un objeto FirebaseVisionImage a partir de un objeto media.Image, como cuando se captura una imagen con la cámara de un dispositivo, pasa el objeto media.Image y la rotación de la imagen a FirebaseVisionImage.fromMediaImage().

      Si usas la biblioteca CameraX, las clases OnImageCapturedListener y ImageAnalysis.Analyzer calculan el valor de rotación por ti, así que solo tienes que convertir la rotación en una de las constantes ROTATION_ de ML Kit antes de llamar a 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

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

      Si no usas una biblioteca de cámaras que te proporcione la rotación de la imagen, puedes calcularla a partir de la rotación del dispositivo y la orientación del sensor de la cámara en el dispositivo:

      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

      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

      Luego, pasa el objeto media.Image y el valor de rotación a FirebaseVisionImage.fromMediaImage():

      Java

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

      Kotlin

      val image = FirebaseVisionImage.fromMediaImage(mediaImage, rotation)
      VisionImage.kt
    • Para crear un objeto FirebaseVisionImage a partir de un URI de archivo, pasa el contexto de la app y el URI de archivo a FirebaseVisionImage.fromFilePath(). Esto es útil cuando usas un intent ACTION_GET_CONTENT para solicitarle al usuario que seleccione una imagen de su app de galería.

      Java

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

      Kotlin

      val image: FirebaseVisionImage
try {
    image = FirebaseVisionImage.fromFilePath(context, uri)
} catch (e: IOException) {
    e.printStackTrace()
}
      VisionImage.kt
    • Para crear un objeto FirebaseVisionImage a partir de un ByteBuffer o un array de bytes, primero calcula la rotación de la imagen como se describió anteriormente para la entrada media.Image.

      Luego, crea un objeto FirebaseVisionImageMetadata que contenga la altura, el ancho, el formato de codificación de color y la rotación de la imagen:

      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

      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

      Usa el búfer o array, y el objeto de metadatos, para crear un objeto FirebaseVisionImage:

      Java

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

      Kotlin

      val image = FirebaseVisionImage.fromByteBuffer(buffer, metadata)
// Or: val image = FirebaseVisionImage.fromByteArray(byteArray, metadata)
      VisionImage.kt
    • Para crear un objeto FirebaseVisionImage a partir de un objeto Bitmap, haz lo siguiente:

      Java

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

      Kotlin

      val image = FirebaseVisionImage.fromBitmap(bitmap)
      VisionImage.kt
      La imagen que representa el objeto Bitmap debe estar en posición vertical, sin que sea necesario rotarla.

  2. Pasa la imagen al método 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 

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

  3. Si la llamada a processImage() se ejecuta correctamente, se pasará una lista de FirebaseVisionObject al objeto de escucha que detecta el resultado correcto.

    Cada FirebaseVisionObject contiene las siguientes propiedades:

    Cuadro de límite Un Rect que indica la posición del objeto en la imagen.
    ID de seguimiento Un número entero que identifica el objeto en las imágenes. Nulo en SINGLE_IMAGE_MODE.
    Categoría La categoría ordinaria del objeto. Si el detector de objetos no tiene habilitada la clasificación, esto es siempre FirebaseVisionObject.CATEGORY_UNKNOWN.
    Confianza El valor de confianza de la clasificación del objeto. Si el detector de objetos no tiene habilitada la clasificación, o el objeto se clasifica como desconocido, su valor es 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 

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

Mejora la usabilidad y el rendimiento

Para obtener la mejor experiencia del usuario, sigue estos lineamientos en tu aplicación:

  • La detección exitosa de objetos depende de la complejidad visual del objeto. Es posible que los objetos con una pequeña cantidad de características visuales deban ocupar un espacio mayor en la imagen para ser detectados. Debes proporcionar a los usuarios una orientación sobre cómo capturar información que funcione bien con el tipo de objetos que deseas detectar.
  • Cuando uses la clasificación, si deseas detectar objetos que no se incluyen de forma clara en las categorías compatibles, implementa un manejo especial para objetos desconocidos.

Además, consulta la [app de muestra de Material Design del Kit de AA][showcase-link]{: .external} y la colección de patrones para las funciones con tecnología de aprendizaje automático de Material Design.

Cuando uses el modo de transmisión en una aplicación en tiempo real, sigue estos lineamientos para lograr los mejores fotogramas:

  • No utilices la detección de múltiples objetos en el modo de transmisión, ya que la mayoría de los dispositivos no podrán producir fotogramas adecuados.

  • Inhabilita la clasificación si no la necesitas.

  • Regula las llamadas al detector. Si hay un fotograma de video nuevo disponible mientras se ejecuta el detector, ignora ese fotograma.
  • Si estás usando la salida del detector para superponer gráficos en la imagen de entrada, primero obtén el resultado de la detección de ML Kit y, luego, procesa la imagen y la superposición en un solo paso. De esta manera procesas la superficie de visualización solo una vez por cada fotograma de entrada.

  • Si usas la API de Camera2, captura imágenes en formato ImageFormat.YUV_420_888.

    Si usas la API de Camera más antigua, captura imágenes en formato ImageFormat.NV21.