Reconhecer pontos de referência com o Firebase ML no Android

Nesta página, descrevemos uma versão antiga do reconhecimento de pontos de referência conhecidos em imagens usando o SDK do Firebase ML Vision que foi descontinuado. Como alternativa, é possível chamar as APIs do Cloud Vision usando o Firebase Auth e funções chamáveis para permitir que apenas usuários que fizeram login no seu app acessem a API.

É possível usar o Firebase ML para reconhecer pontos de referência conhecidos em uma imagem.

O uso das APIs do Cloud Vision está sujeito ao Contrato de Licença do Google Cloud Platform e aos Termos de Serviço Específicos. Além disso, a cobrança é feita de acordo com essas diretrizes. Para informações de faturamento, consulte a página Preços.

Antes de começar

1. Adicione o Firebase ao seu projeto para Android, caso ainda não tenha feito isso.
2. No arquivo Gradle do módulo (nível do app) (geralmente <project>/<app-module>/build.gradle.kts ou <project>/<app-module>/build.gradle), adicione a dependência da biblioteca Android do Firebase ML Vision. Para gerenciar o controle de versões das bibliotecas, recomendamos usar a BoM do Firebase para Android.

   dependencies {
       // Import the BoM for the Firebase platform
       implementation(platform("com.google.firebase:firebase-bom:32.3.1"))
   
       // Add the dependency for the Firebase ML Vision library
       // When using the BoM, you don't specify versions in Firebase library dependencies
       implementation 'com.google.firebase:firebase-ml-vision'
   }
   

   Com a BoM do Firebase para Android, seu app sempre vai usar versões compatíveis das bibliotecas do Firebase para Android.

   (Alternativa) Adicionar dependências das bibliotecas do Firebase sem usar a BoM

   Se você preferir não usar a BoM do Firebase, especifique cada versão das bibliotecas do Firebase na linha de dependência correspondente.

   Se você usa várias bibliotecas do Firebase no seu app, recomendamos utilizar a BoM para gerenciar as versões delas, porque isso ajuda a garantir a compatibilidade de todas as bibliotecas.

   dependencies {
       // Add the dependency for the Firebase ML Vision library
       // When NOT using the BoM, you must specify versions in Firebase library dependencies
       implementation 'com.google.firebase:firebase-ml-vision:24.1.0'
   }
   

3. Se você ainda não ativou APIs baseadas em nuvem no seu projeto, siga estas instruções:

   1. Abra a página de APIs do Firebase ML no Console do Firebase.

   2. Se você ainda não fez o upgrade do seu projeto para o plano de preços Blaze, clique em Fazer upgrade. Você só vai receber uma mensagem para fazer upgrade se o projeto não estiver no plano Blaze.

      Apenas projetos no nível Blaze podem usar APIs baseadas na nuvem.

   3. Caso as APIs baseadas na nuvem ainda não estejam ativadas, clique em Ativar APIs baseadas na nuvem.
   Antes de implantar em produção um app que usa uma API do Cloud, é preciso seguir mais algumas etapas para evitar e diminuir o impacto do acesso não autorizado às APIs.

Configurar o detector de pontos de referência

Por padrão, o detector do Cloud usa a versão STABLE do modelo e retorna até 10 resultados. Se você quiser alterar qualquer uma dessas configurações, especifique-as com um objeto FirebaseVisionCloudDetectorOptions.

Por exemplo, para alterar as duas configurações padrão, crie um objeto FirebaseVisionCloudDetectorOptions como no exemplo a seguir:

Kotlin+KTX

val options = FirebaseVisionCloudDetectorOptions.Builder()
    .setModelType(FirebaseVisionCloudDetectorOptions.LATEST_MODEL)
    .setMaxResults(15)
    .build()
MainActivity.kt

Java

FirebaseVisionCloudDetectorOptions options =
        new FirebaseVisionCloudDetectorOptions.Builder()
                .setModelType(FirebaseVisionCloudDetectorOptions.LATEST_MODEL)
                .setMaxResults(15)
                .build();
MainActivity.java

Para usar as configurações padrão, use FirebaseVisionCloudDetectorOptions.DEFAULT na próxima etapa.

Executar o detector de pontos de referência

Para reconhecer pontos de referência em uma imagem, crie um objeto FirebaseVisionImage usando Bitmap, media.Image, ByteBuffer, matriz de bytes ou um arquivo no dispositivo. Em seguida, transmita o objeto FirebaseVisionImage para o método detectInImage do FirebaseVisionCloudLandmarkDetector.

1. Crie um objeto FirebaseVisionImage usando sua imagem.

   • Para criar um objeto FirebaseVisionImage com base em um objeto media.Image, como ao capturar uma imagem da câmera de um dispositivo, transmita o objeto media.Image e a rotação da imagem para FirebaseVisionImage.fromMediaImage().

     Se você usar a biblioteca CameraX, as classes OnImageCapturedListener e ImageAnalysis.Analyzer vão calcular o valor de rotação para você. Basta converter a rotação em uma das constantes ROTATION_ do Firebase ML antes de chamar FirebaseVisionImage.fromMediaImage():

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

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

     Se você não usar uma biblioteca de câmera que ofereça a rotação da imagem, será possível calculá-la usando a rotação do dispositivo e a orientação do sensor da câmera:

     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

     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

     Em seguida, transmita o objeto media.Image e o valor de rotação para FirebaseVisionImage.fromMediaImage():

     Kotlin+KTX

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

     Java

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

   • Para criar um objeto FirebaseVisionImage com base no URI de um arquivo, transmita o contexto do aplicativo e o URI do arquivo para FirebaseVisionImage.fromFilePath(). Isso é útil ao usar uma intent ACTION_GET_CONTENT para solicitar que o usuário selecione uma imagem no app de galeria dele.

     Kotlin+KTX

     val image: FirebaseVisionImage
     try {
         image = FirebaseVisionImage.fromFilePath(context, uri)
     } catch (e: IOException) {
         e.printStackTrace()
     }
     VisionImage.kt

     Java

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

   • Para criar um objeto FirebaseVisionImage com base em um ByteBuffer ou uma matriz de bytes, primeiro calcule a rotação da imagem conforme descrito acima para a entrada media.Image.

     Em seguida, crie um objeto FirebaseVisionImageMetadata que contenha a altura, a largura, o formato de codificação de cores e a rotação da imagem:

     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

     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

     Use o buffer ou a matriz e o objeto de metadados para criar um objeto FirebaseVisionImage:

     Kotlin+KTX

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

     Java

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

   • Para criar um objeto FirebaseVisionImage com base em um objeto Bitmap:

     Kotlin+KTX

     val image = FirebaseVisionImage.fromBitmap(bitmap)
     VisionImage.kt

     Java

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

     A imagem representada pelo objeto Bitmap precisa estar na posição vertical, sem a necessidade de ser girada novamente.

2. Receba uma instância de FirebaseVisionCloudLandmarkDetector:

   Kotlin+KTX

   val detector = FirebaseVision.getInstance()
       .visionCloudLandmarkDetector
   // Or, to change the default settings:
   // val detector = FirebaseVision.getInstance()
   //         .getVisionCloudLandmarkDetector(options)
   LandmarkRecognitionActivity.kt

   Java

   FirebaseVisionCloudLandmarkDetector detector = FirebaseVision.getInstance()
           .getVisionCloudLandmarkDetector();
   // Or, to change the default settings:
   // FirebaseVisionCloudLandmarkDetector detector = FirebaseVision.getInstance()
   //         .getVisionCloudLandmarkDetector(options);
   LandmarkRecognitionActivity.java

3. Por fim, transmita a imagem para o método detectInImage:

   Kotlin+KTX

   val result = detector.detectInImage(image)
       .addOnSuccessListener { firebaseVisionCloudLandmarks ->
           // Task completed successfully
           // ...
       }
       .addOnFailureListener { e ->
           // Task failed with an exception
           // ...
       }
   LandmarkRecognitionActivity.kt

   Java

   Task<List<FirebaseVisionCloudLandmark>> result = detector.detectInImage(image)
           .addOnSuccessListener(new OnSuccessListener<List<FirebaseVisionCloudLandmark>>() {
               @Override
               public void onSuccess(List<FirebaseVisionCloudLandmark> firebaseVisionCloudLandmarks) {
                   // Task completed successfully
                   // ...
               }
           })
           .addOnFailureListener(new OnFailureListener() {
               @Override
               public void onFailure(@NonNull Exception e) {
                   // Task failed with an exception
                   // ...
               }
           });
   LandmarkRecognitionActivity.java

Ver informações sobre os pontos de referência reconhecidos

Se a operação de reconhecimento de pontos de referência for bem-sucedida, uma lista de objetos FirebaseVisionCloudLandmark será transmitida ao listener de êxito. Cada objeto FirebaseVisionCloudLandmark representa um ponto de referência que foi reconhecido na imagem. Para cada ponto de referência, é possível receber as coordenadas delimitadoras na imagem de entrada, o nome do ponto de referência, a latitude e a longitude, o ID da entidade do Mapa de informações dele (se disponível) e a pontuação de confiança da correspondência. Exemplo:

Kotlin+KTX

for (landmark in firebaseVisionCloudLandmarks) {
    val bounds = landmark.boundingBox
    val landmarkName = landmark.landmark
    val entityId = landmark.entityId
    val confidence = landmark.confidence

    // Multiple locations are possible, e.g., the location of the depicted
    // landmark and the location the picture was taken.
    for (loc in landmark.locations) {
        val latitude = loc.latitude
        val longitude = loc.longitude
    }
}
LandmarkRecognitionActivity.kt

Java

for (FirebaseVisionCloudLandmark landmark: firebaseVisionCloudLandmarks) {

    Rect bounds = landmark.getBoundingBox();
    String landmarkName = landmark.getLandmark();
    String entityId = landmark.getEntityId();
    float confidence = landmark.getConfidence();

    // Multiple locations are possible, e.g., the location of the depicted
    // landmark and the location the picture was taken.
    for (FirebaseVisionLatLng loc: landmark.getLocations()) {
        double latitude = loc.getLatitude();
        double longitude = loc.getLongitude();
    }
}
LandmarkRecognitionActivity.java

Próximas etapas

• Antes de implantar em produção um app que usa uma API do Cloud, é preciso seguir mais algumas etapas para evitar ou atenuar o efeito do acesso não autorizado à API.