Se usó la API de Cloud Translation para traducir esta página.

Etiquetar imágenes con ML Kit en Android

Puede usar ML Kit para etiquetar objetos reconocidos en una imagen, usando un modelo en el dispositivo o un modelo en la nube. Consulte la descripción general para conocer los beneficios de cada enfoque.

Antes de que empieces

Si aún no lo ha hecho, agregue Firebase a su proyecto de Android .

Agregue las dependencias para las bibliotecas de Android ML Kit a su archivo Gradle de módulo (nivel de aplicación) (generalmente 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-image-label-model:20.0.1'
}

Opcional pero recomendado : si usa la API en el dispositivo, configure su aplicación para descargar automáticamente el modelo ML al dispositivo después de que su aplicación se instale desde Play Store.
Para hacerlo, agregue la siguiente declaración al archivo AndroidManifest.xml de su aplicación:
```
<application ...>
  ...
  <meta-data
      android:name="com.google.firebase.ml.vision.DEPENDENCIES"
      android:value="label" />
  
</application>
```
Si no habilita las descargas de modelos en el momento de la instalación, el modelo se descargará la primera vez que ejecute el detector en el dispositivo. Las solicitudes que realice antes de que se complete la descarga no producirán ningún resultado.
Si desea utilizar el modelo basado en la nube y aún no ha habilitado las API basadas en la nube para su proyecto, hágalo ahora:
1. Abra la página de las API del kit de aprendizaje automático de Firebase console.
2. Si aún no ha actualizado su proyecto a un plan de precios de Blaze, haga clic en Actualizar para hacerlo. (Se le pedirá que actualice solo si su proyecto no está en el plan Blaze).
  Solo los proyectos de nivel Blaze pueden usar API basadas en la nube.
3. Si las API basadas en la nube aún no están habilitadas, haga clic en Habilitar API basadas en la nube .
Antes de implementar en producción una aplicación que usa una API en la nube, debe tomar algunas medidas adicionales para prevenir y mitigar el efecto del acceso no autorizado a la API .
Si desea utilizar solo el modelo en el dispositivo, puede omitir este paso.

Ahora está listo para etiquetar imágenes utilizando un modelo en el dispositivo o un modelo basado en la nube.

1. Preparar la imagen de entrada

Cree un objeto FirebaseVisionImage a partir de su imagen. El etiquetador de imágenes se ejecuta más rápido cuando usa un Bitmap de bits o, si usa la API camera2, una imagen multimedia con formato media.Image , que se recomiendan cuando sea posible.

Para crear un objeto FirebaseVisionImage a partir de un objeto media.Image , como al capturar una imagen de la cámara de un dispositivo, pase el objeto media.Image y la rotación de la imagen a FirebaseVisionImage.fromMediaImage() .

Si usa la biblioteca CameraX , las clases OnImageCapturedListener e ImageAnalysis.Analyzer calculan el valor de rotación por usted, por lo que solo necesita convertir la rotación a 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+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
            // ...
        }
    }
}

Si no usa una biblioteca de cámaras que le proporcione la rotación de la imagen, puede 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+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

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+KTX

val image = FirebaseVisionImage.fromMediaImage(mediaImage, rotation)VisionImage.kt

Para crear un objeto FirebaseVisionImage a partir de un URI de archivo, pase el contexto de la aplicación y el URI del archivo a FirebaseVisionImage.fromFilePath() . Esto es útil cuando usa una intención ACTION_GET_CONTENT para solicitar al usuario que seleccione una imagen de su aplicación de galería.

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

Para crear un objeto FirebaseVisionImage a partir de un ByteBuffer o una matriz de bytes, primero calcule la rotación de la imagen como se describe anteriormente para la entrada de media.Image .

Luego, crea un objeto FirebaseVisionImageMetadata que contenga la altura, el ancho, el formato de codificación de colores 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+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

Usa el búfer o la matriz 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+KTX

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 :
Java
```
FirebaseVisionImage image = FirebaseVisionImage.fromBitmap(bitmap);VisionImage.java
```
Kotlin+KTX
```
val image = FirebaseVisionImage.fromBitmap(bitmap)VisionImage.kt
```
La imagen representada por el objeto de Bitmap de bits debe estar en posición vertical, sin necesidad de rotación adicional.

2. Configure y ejecute el etiquetador de imágenes

Para etiquetar objetos en una imagen, pasa el objeto FirebaseVisionImage al método processImage de FirebaseVisionImageLabeler .

Primero, obtenga una instancia de FirebaseVisionImageLabeler .

Si desea utilizar el etiquetador de imágenes en el dispositivo:

Java

FirebaseVisionImageLabeler labeler = FirebaseVision.getInstance()
    .getOnDeviceImageLabeler();

// Or, to set the minimum confidence required:
// FirebaseVisionOnDeviceImageLabelerOptions options =
//     new FirebaseVisionOnDeviceImageLabelerOptions.Builder()
//         .setConfidenceThreshold(0.7f)
//         .build();
// FirebaseVisionImageLabeler labeler = FirebaseVision.getInstance()
//     .getOnDeviceImageLabeler(options);

Kotlin+KTX

val labeler = FirebaseVision.getInstance().getOnDeviceImageLabeler()

// Or, to set the minimum confidence required:
// val options = FirebaseVisionOnDeviceImageLabelerOptions.Builder()
//     .setConfidenceThreshold(0.7f)
//     .build()
// val labeler = FirebaseVision.getInstance().getOnDeviceImageLabeler(options)

Si desea utilizar el etiquetador de imágenes en la nube:

Java

FirebaseVisionImageLabeler labeler = FirebaseVision.getInstance()
    .getCloudImageLabeler();

// Or, to set the minimum confidence required:
// FirebaseVisionCloudImageLabelerOptions options =
//     new FirebaseVisionCloudImageLabelerOptions.Builder()
//         .setConfidenceThreshold(0.7f)
//         .build();
// FirebaseVisionImageLabeler labeler = FirebaseVision.getInstance()
//     .getCloudImageLabeler(options);

Kotlin+KTX

val labeler = FirebaseVision.getInstance().getCloudImageLabeler()

// Or, to set the minimum confidence required:
// val options = FirebaseVisionCloudImageLabelerOptions.Builder()
//     .setConfidenceThreshold(0.7f)
//     .build()
// val labeler = FirebaseVision.getInstance().getCloudImageLabeler(options)

Luego, pasa la imagen al método processImage() :

Java

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

Kotlin+KTX

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

3. Obtener información sobre objetos etiquetados

Si la operación de etiquetado de imágenes tiene éxito, se pasará una lista de objetos FirebaseVisionImageLabel al agente de escucha correcto. Cada objeto FirebaseVisionImageLabel representa algo que se etiquetó en la imagen. Para cada etiqueta, puede obtener la descripción de texto de la etiqueta, su ID de entidad de Knowledge Graph (si está disponible) y la puntuación de confianza de la coincidencia. Por ejemplo:

Java

for (FirebaseVisionImageLabel label: labels) {
  String text = label.getText();
  String entityId = label.getEntityId();
  float confidence = label.getConfidence();
}

Kotlin+KTX

for (label in labels) {
  val text = label.text
  val entityId = label.entityId
  val confidence = label.confidence
}

Sugerencias para mejorar el rendimiento en tiempo real

Si desea etiquetar imágenes en una aplicación en tiempo real, siga estas pautas para lograr las mejores tasas de cuadros:

Acelera las llamadas al etiquetador de imágenes. Si un nuevo cuadro de video está disponible mientras se ejecuta el etiquetador de imágenes, suelte el cuadro.
Si está utilizando la salida del etiquetador de imágenes para superponer gráficos en la imagen de entrada, primero obtenga el resultado de ML Kit, luego renderice la imagen y superponga en un solo paso. Al hacerlo, renderiza en la superficie de visualización solo una vez para cada cuadro de entrada.
Si usa la API Camera2, capture imágenes en formato ImageFormat.YUV_420_888 .
Si usa la API de cámara anterior, capture imágenes en formato ImageFormat.NV21 .

Próximos pasos

Antes de implementar en producción una aplicación que usa una API en la nube, debe tomar algunas medidas adicionales para prevenir y mitigar el efecto del acceso no autorizado a la API .