在安卓上使用ML Kit标注图片

您可以使用ML Kit来识别图像中的文本，使用设备上的模型或云上的模型。请参阅概述以了解每种方法的优点。

有关此API使用的示例，请参阅 GitHub 上的 ML Kit 快速入门示例，或者尝试使用 codelab 。

在您开始之前

  1. 如果您还没有将Firebase添加到您的程序当中，那您可以从开始指南来开始您的工作。

  2. 在app-level的 build.gradle 文件中为ML kit添加依赖:

    1. dependencies {
    2.   // ...
    4.   implementation 'com.google.firebase:firebase-ml-vision:15.0.0'
    5.   implementation 'com.google.firebase:firebase-ml-vision-image-label-model:15.0.0'
    6. }

  3. 可选但建议：如果您使用设备上的API，请将应用配置为在从Play商店安装应用后自动将ML模型下载到设备： 

    1. <meta-data
    2.     android:name="com.google.firebase.ml.vision.DEPENDENCIES"
    3.     android:value="label" />
    4. <!-- 为了能够使用多个模型: android:value="text,model2,model3" -->

    如果您未启用安装时模型下载，则将在您首次运行设备上识别器的时候开始下载该模型。在下载完成之前发出的请求不会有任何结果。

  4. 如果您想使用基于云的模型，并且尚未将项目升级到Blaze计划，请在Firebase控制台中执行此操作。只有Blaze计划的项目才能使用Cloud Vision API。

  5. 如果您想使用基于云的模型，您也需要开启Cloud Vision API：

    • 在云API列表管理平台中打开Cloud Vision API。
    • 确保您的Firebase项目已经在当前菜单页面中被置于顶端。
    • 如果API依旧还是显示为enabled，请点击Enable。

    如果您想要仅仅开启使用设备上的模型，您可以跳过这一步。

现在您已经可以开始使用设备上的模型或者基于云端的模型识别图像中的文本了。

在设备上标注图片

要使用基于云端的图片标注模型，请按以下所述配置和运行图像标注器。

  1. 配置图像标注器

    默认情况下，图片标注后至多会返回10个标签。如果您想要更改该设置，请按照以下实例创建一个FirebaseVisionLabelDetectorOptions对象。

    1. FirebaseVisionLabelDetectorOptions options =
    2.         new FirebaseVisionLabelDetectorOptions.Builder()
    3.                 .setConfidenceThreshold(0.8f)
    4.                 .build();

  2. 运行图像标注器

    为了识别图像中的文本，从任一个Bitmap，media.Image，ByteBuffer，字节阵列，或在设备上的文件中创建一个FirebaseVisionImage对象。然后，传递FirebaseVisionImage对象到FirebaseVisionLabelDetector的detectInImage方法。

    1. 从图像中创建一个FirebaseVisionImage对象。如果您使用Bitmap则图像标签器运行速度最快或者如果您使用camera2 API，一种名为media.Image的JPEG格式，也可最快。当然如果可能，建议您使用（后者）这种格式。

      • 从 Bitmap对象创建FirebaseVisionImage对象：

        1. FirebaseVisionImage image = FirebaseVisionImage.fromBitmap(bitmap);

        Bitmap 对象指示的图像必须是直立的，不能旋转。

      • 要从 media.Image对象创建FirebaseVisionImage对象（例如从设备的相机捕捉图像时），首先要确定图像必须旋转的角度，以补偿设备的旋转和相机传感器在设备中的方向： 

        1. private static final SparseIntArray ORIENTATIONS = new SparseIntArray();
        2. static {
        3.     ORIENTATIONS.append(Surface.ROTATION_0, 90);
        4.     ORIENTATIONS.append(Surface.ROTATION_90, 0);
        5.     ORIENTATIONS.append(Surface.ROTATION_180, 270);
        6.     ORIENTATIONS.append(Surface.ROTATION_270, 180);
        7. }
        9. /**
        10.  * 得到当前图像需要补偿的角度
        11.  */
        12. @RequiresApi(api = Build.VERSION_CODES.LOLLIPOP)
        13. private int getRotationCompensation(String cameraId, Activity activity, Context context)
        14.         throws CameraAccessException {
        15.     // 得到设备当前与原始的角度的旋转差值
        16.     // 然后照片一定要旋转回去相对的差值
        17.     int deviceRotation = activity.getWindowManager().getDefaultDisplay().getRotation();
        18.     int rotationCompensation = ORIENTATIONS.get(deviceRotation);
        20.     // 在大多数的设备上，传感器的方向是90度。但是对于
        21.     // 少数设备，这个值是270度。那么对于这些270度的设备
        22.     // 必须让照片旋转额外的180 ((270 + 270) % 360) 度.
        23.     CameraManager cameraManager = (CameraManager) context.getSystemService(CAMERA_SERVICE);
        24.     int sensorOrientation = cameraManager
        25.             .getCameraCharacteristics(cameraId)
        26.             .get(CameraCharacteristics.SENSOR_ORIENTATION);
        27.     rotationCompensation = (rotationCompensation + sensorOrientation + 270) % 360;
        29.     // 返回相关的FirebaseVisionImageMetadata rotation值。
        30.     int result;
        31.     switch (rotationCompensation) {
        32.         case 0:
        33.             result = FirebaseVisionImageMetadata.ROTATION_0;
        34.             break;
        35.         case 90:
        36.             result = FirebaseVisionImageMetadata.ROTATION_90;
        37.             break;
        38.         case 180:
        39.             result = FirebaseVisionImageMetadata.ROTATION_180;
        40.             break;
        41.         case 270:
        42.             result = FirebaseVisionImageMetadata.ROTATION_270;
        43.             break;
        44.         default:
        45.             result = FirebaseVisionImageMetadata.ROTATION_0;
        46.             Log.e(TAG, "Bad rotation value: " + rotationCompensation);
        47.     }
        48.     return result;
        49. }

        然后，将media.Image对象和旋转值传递给FirebaseVisionImage.fromMediaImage()： 

        1. FirebaseVisionImage image = FirebaseVisionImage.fromMediaImage(mediaImage,rotation);

      • 要从一个字节数组或ByteBuffer创建一个FirebaseVisionImage对象，首先按照上面的描述计算图像旋转角度。

        然后，创建一个包含图像高度，宽度，颜色编码格式和旋转度的FirebaseVisionImageMetadata对象：

        1. FirebaseVisionImageMetadata metadata = new FirebaseVisionImageMetadata.Builder()
        2.         .setWidth(1280)
        3.         .setHeight(720)
        4.         .setFormat(FirebaseVisionImageMetadata.IMAGE_FORMAT_NV21)
        5.         .setRotation(rotation)
        6.         .build();

        使用缓冲区或数组以及元数据对象来创建一个 FirebaseVisionImage对象： 

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

      • 要从文件创建FirebaseVisionImage对象，请将应用context和文件URI传递给FirebaseVisionImage.fromFilePath()： 

        1. FirebaseVisionImage image;
        2. try {
        3.     image = FirebaseVisionImage.fromFilePath(context, uri);
        4. } catch (IOException e) {
        5.     e.printStackTrace();
        6. }

    2. 获取一个 FirebaseVisionLabelDetector实例:

      1. FirebaseVisionLabelDetector detector = FirebaseVision.getInstance()
      2.         .getVisionLabelDetector();
      3. // 或者设置您想要的最小置信度:
      4. FirebaseVisionLabelDetector detector = FirebaseVision.getInstance()
      5.         .getVisionLabelDetector(options);

    3. 最后，传递图片到 detectInImage 方法：

      1. Task<List<FirebaseVisionLabel>> result =
      2.         detector.detectInImage(image)
      3.                 .addOnSuccessListener(
      4.                         new OnSuccessListener<List<FirebaseVisionLabel>>() {
      5.                             @Override
      6.                             public void onSuccess(List<FirebaseVisionLabel> labels) {
      7.                                 // 任务完成
      8.                                 // ...
      9.                             }
      10.                         })
      11.                 .addOnFailureListener(
      12.                         new OnFailureListener() {
      13.                             @Override
      14.                             public void onFailure(@NonNull Exception e) {
      15.                                 // 任务失败并出异常
      16.                                 // ...
      17.                             }
      18.                         });

  3. 获取被标注的对象的相关信息

    如果图像标注操作成功，则会将FirebaseVisionLabel 对象列表传递给成功侦听器(success listener)。每个FirebaseVisionLabel 对象都表示图像中标记的内容。对于每个标签，您可以获取标签的文本说明， 知识图谱实体标识ID （如果可用）以及匹配物体/行为的置信度分数。例如： 

    1. for (FirebaseVisionLabel label: labels) {
    2.     String text = label.getLabel();
    3.     String entityId = label.getEntityId();
    4.     float confidence = label.getConfidence();
    5. }

基于云端的图片标注

为了使用基于云端的图片标注模型，请按下边描述配置和运行图片标注器

  1. 配置图像标注器

    默认情况下，云端识别器使用模型的STABLE版本，并返回多达10个的结果。如果您要修改这些设置中的任何一个，请用FirebaseVisionCloudDetectorOptions 对象指定它们。

    例如，要更改这两个默认设置，请按照以下示例构建一个FirebaseVisionCloudDetectorOptions对象。

    1. FirebaseVisionCloudDetectorOptions options =
    2.     new FirebaseVisionCloudDetectorOptions.Builder()
    3.         .setModelType(FirebaseVisionCloudDetectorOptions.LATEST_MODEL)
    4.         .setMaxResults(15)
    5.         .build();

    要使用默认设置，您可以在下一步中使用 FirebaseVisionCloudDetectorOptions。

  2. 运行图像标注器

    为了进行图片标注，从任一个Bitmap，media.Image，ByteBuffer，字节阵列，或在设备上的文件中创建一个FirebaseVisionImage对象。然后，传递FirebaseVisionImage对象到FirebaseCloudVisionLabelDetector的detectInImage方法。

    1. 从图像中创建一个FirebaseVisionImage对象。如果您使用Bitmap则图像标签器运行速度最快或者如果您使用camera2 API，一种名为media.Image的JPEG格式，也可最快。当然如果可能，建议您使用（后者）这种格式。

      • 从 Bitmap对象创建FirebaseVisionImage对象：

        1. FirebaseVisionImage image = FirebaseVisionImage.fromBitmap(bitmap);

        Bitmap 对象指示的图像必须是直立的，不能旋转。

      • 要从 media.Image对象创建FirebaseVisionImage对象（例如从设备的相机捕捉图像时），首先要确定图像必须旋转的角度，以补偿设备的旋转和相机传感器在设备中的方向： 

        1. private static final SparseIntArray ORIENTATIONS = new SparseIntArray();
        2. static {
        3.     ORIENTATIONS.append(Surface.ROTATION_0, 90);
        4.     ORIENTATIONS.append(Surface.ROTATION_90, 0);
        5.     ORIENTATIONS.append(Surface.ROTATION_180, 270);
        6.     ORIENTATIONS.append(Surface.ROTATION_270, 180);
        7. }
        9. /**
        10.  * 得到当前图像需要补偿的角度
        11.  */
        12. @RequiresApi(api = Build.VERSION_CODES.LOLLIPOP)
        13. private int getRotationCompensation(String cameraId, Activity activity, Context context)
        14.         throws CameraAccessException {
        15.     // 得到设备当前与原始的角度的旋转差值
        16.     // 然后照片一定要旋转回去相对的差值
        17.     int deviceRotation = activity.getWindowManager().getDefaultDisplay().getRotation();
        18.     int rotationCompensation = ORIENTATIONS.get(deviceRotation);
        20.     // 在大多数的设备上，传感器的方向是90度。但是对于
        21.     // 少数设备，这个值是270度。那么对于这些270度的设备
        22.     // 必须让照片旋转额外的180 ((270 + 270) % 360) 度.
        23.     CameraManager cameraManager = (CameraManager) context.getSystemService(CAMERA_SERVICE);
        24.     int sensorOrientation = cameraManager
        25.             .getCameraCharacteristics(cameraId)
        26.             .get(CameraCharacteristics.SENSOR_ORIENTATION);
        27.     rotationCompensation = (rotationCompensation + sensorOrientation + 270) % 360;
        29.     // 返回相关的FirebaseVisionImageMetadata rotation值。
        30.     int result;
        31.     switch (rotationCompensation) {
        32.         case 0:
        33.             result = FirebaseVisionImageMetadata.ROTATION_0;
        34.             break;
        35.         case 90:
        36.             result = FirebaseVisionImageMetadata.ROTATION_90;
        37.             break;
        38.         case 180:
        39.             result = FirebaseVisionImageMetadata.ROTATION_180;
        40.             break;
        41.         case 270:
        42.             result = FirebaseVisionImageMetadata.ROTATION_270;
        43.             break;
        44.         default:
        45.             result = FirebaseVisionImageMetadata.ROTATION_0;
        46.             Log.e(TAG, "Bad rotation value: " + rotationCompensation);
        47.     }
        48.     return result;
        49. }

        然后，将media.Image对象和旋转值传递给FirebaseVisionImage.fromMediaImage()： 

        1. FirebaseVisionImage image = FirebaseVisionImage.fromMediaImage(mediaImage,rotation);

      • 要从一个字节数组或ByteBuffer创建一个FirebaseVisionImage对象，首先按照上面的描述计算图像旋转角度。

        然后，创建一个包含图像高度，宽度，颜色编码格式和旋转度的FirebaseVisionImageMetadata对象：

        1. FirebaseVisionImageMetadata metadata = new FirebaseVisionImageMetadata.Builder()
        2.         .setWidth(1280)
        3.         .setHeight(720)
        4.         .setFormat(FirebaseVisionImageMetadata.IMAGE_FORMAT_NV21)
        5.         .setRotation(rotation)
        6.         .build();

        使用缓冲区或数组以及元数据对象来创建一个 FirebaseVisionImage对象： 

        1. FirebaseVisionImage image = FirebaseVisionImage.fromByteBuffer(buffer, metadata);
        2. // 或者: FirebaseVisionImage image = FirebaseVisionImage.fromByteArray(byteArray, metadata);

      • 要从文件创建FirebaseVisionImage对象，请将应用context和文件URI传递给FirebaseVisionImage.fromFilePath()： 

        1. FirebaseVisionImage image;
        2. try {
        3.     image = FirebaseVisionImage.fromFilePath(context, uri);
        4. } catch (IOException e) {
        5.     e.printStackTrace();
        6. }

    2. 获得一个 FirebaseVisionCloudLabelDetector 实例：

      1. FirebaseVisionCloudLabelDetector detector = FirebaseVision.getInstance()
      2.         .getVisionCloudLabelDetector();
      3. // 或者，修改默认设置:
      4. // FirebaseVisionCloudLabelDetector detector = FirebaseVision.getInstance()
      5. //         .getVisionCloudLabelDetector(options);

    3. 最后，将图像传递至detectInImage方法：

      1. Task<List<FirebaseVisionCloudLabel>> result =
      2.         detector.detectInImage(image)
      3.                 .addOnSuccessListener(
      4.                         new OnSuccessListener<List<FirebaseVisionCloudLabel>>() {
      5.                             @Override
      6.                             public void onSuccess(List<FirebaseVisionCloudLabel> labels) {
      7.                                 // 任务成功
      8.                                 // ...
      9.                             }
      10.                         })
      11.                 .addOnFailureListener(
      12.                         new OnFailureListener() {
      13.                             @Override
      14.                             public void onFailure(@NonNull Exception e) {
      15.                                 // 任务失败并且报错
      16.                                 // ...
      17.                             }
      18.                         });

  3. 获取被标注的对象的相关信息

    如果图像标注操作成功，则会将FirebaseVisionLabel 对象列表传递给成功侦听器(success listener)。每个FirebaseVisionLabel 对象都表示图像中标记的内容。对于每个标签，您可以获取标签的文本说明， 知识图谱实体标识ID （如果可用）以及匹配物体/行为的置信度分数。例如： 

    1. for (FirebaseVisionCloudLabel label: labels) {
    2.     String text = label.getLabel();
    3.     String entityId = label.getEntityId();
    4.     float confidence = label.getConfidence();
    5. }