使用 AutoML 训练的模型给图片加标签 (Android)

在您使用 AutoML Vision Edge 训练自己的模型后，就可以在应用中用它给图片加标签。

您可以通过以下两种方式集成经过 AutoML Vision Edge 训练的模型：可以将模型嵌入应用的资源文件夹中以捆绑模型，也可以从 Firebase 动态下载模型。

模型捆绑方式
捆绑在您的应用中	模型是应用的 APK 的一部分即使 Android 设备处于离线状态，模型也可立即使用不需要 Firebase 项目
使用 Firebase 进行托管	通过将模型上传到 Firebase Machine Learning 来托管该模型减小 APK 大小模型按需下载无需重新发布应用即可推送模型更新使用 Firebase Remote Config 轻松进行 A/B 测试需要 Firebase 项目

准备工作

将 Android 版机器学习套件库的依赖项添加到模块的应用级 Gradle 文件（通常为 app/build.gradle）：

如需将模型捆绑到您的应用，请添加以下依赖项：

dependencies {
  // ...
  // Image labeling feature with bundled automl model
  implementation 'com.google.mlkit:image-labeling-custom:16.3.1'
}

如需从 Firebase 动态下载模型，请添加 linkFirebase 依赖项：

dependencies {
  // ...
  // Image labeling feature with automl model downloaded
  // from firebase
  implementation 'com.google.mlkit:image-labeling-custom:16.3.1'
  implementation 'com.google.mlkit:linkfirebase:16.1.0'
}

如果您想下载模型，请务必将 Firebase 添加到您的 Android 项目（如果尚未添加）。捆绑模型时不需要这样做。

1. 加载模型

配置本地模型来源

如需将模型捆绑到您的应用，请执行以下操作：

找到您从 Firebase 控制台下载的 zip 归档文件，从其中解压缩模型及其元数据。我们建议您依所下载文件的原样使用这些文件，不要做出修改（包括文件名）。
将您的模型及其元数据文件包含在自己的应用软件包中：
1. 如果您的项目中没有资源文件夹，请创建一个，方法是右键点击 app/ 文件夹，然后依次点击新建 > 文件夹 > 资源文件夹 (New > Folder > Assets Folder)。
2. 在资源文件夹下创建一个子文件夹，以包含模型文件。
3. 将文件 model.tflite、dict.txt 和 manifest.json 复制到子文件夹（这三个文件必须位于同一文件夹中）。
将以下内容添加到应用的 build.gradle 文件中，以确保 Gradle 在构建应用时不会压缩模型文件：
```
android {
    // ...
    aaptOptions {
        noCompress "tflite"
    }
}
```
模型文件将包含在应用软件包中，并作为原始资源提供给机器学习套件使用。
注意：从 Android Gradle 插件 4.1 版开始，默认会将 .tflite 添加到 noCompress 列表，不再需要执行上述步骤。

创建一个 LocalModel 对象，指定模型清单文件的路径：

Java

AutoMLImageLabelerLocalModel localModel =
    new AutoMLImageLabelerLocalModel.Builder()
        .setAssetFilePath("manifest.json")
        // or .setAbsoluteFilePath(absolute file path to manifest file)
        .build();

Kotlin

val localModel = LocalModel.Builder()
    .setAssetManifestFilePath("manifest.json")
    // or .setAbsoluteManifestFilePath(absolute file path to manifest file)
    .build()

配置 Firebase 托管的模型来源

如需使用远程托管的模型，请创建一个 CustomRemoteModel 对象，指明您在发布该模型时为其分配的名称：

Java

// Specify the name you assigned in the Firebase console.
FirebaseModelSource firebaseModelSource =
    new FirebaseModelSource.Builder("your_model_name").build();
CustomRemoteModel remoteModel =
    new CustomRemoteModel.Builder(firebaseModelSource).build();

Kotlin

// Specify the name you assigned in the Firebase console.
val firebaseModelSource = FirebaseModelSource.Builder("your_model_name")
    .build()
val remoteModel = CustomRemoteModel.Builder(firebaseModelSource).build()

然后，启动模型下载任务，指定允许下载模型的条件。如果模型不在设备上，或模型有较新的版本，则该任务将从 Firebase 异步下载模型：

Java

DownloadConditions downloadConditions = new DownloadConditions.Builder()
        .requireWifi()
        .build();
RemoteModelManager.getInstance().download(remoteModel, downloadConditions)
        .addOnSuccessListener(new OnSuccessListener<Void>() {
            @Override
            public void onSuccess(@NonNull Task<Void> task) {
                // Success.
            }
        });

Kotlin

val downloadConditions = DownloadConditions.Builder()
    .requireWifi()
    .build()
RemoteModelManager.getInstance().download(remoteModel, downloadConditions)
    .addOnSuccessListener {
        // Success.
    }

许多应用会通过其初始化代码启动下载任务，但您可以在需要使用该模型之前随时启动下载任务。

根据模型创建图片标记器

配置模型来源后，根据其中一个模型创建 ImageLabeler 对象。

如果您只有本地捆绑的模型，只需根据您的 CustomImageLabelerOptions 对象创建一个标记器，然后配置您需要的置信度得分阈值（请参阅评估您的模型）：

Java

CustomImageLabelerOptions customImageLabelerOptions = new CustomImageLabelerOptions.Builder(localModel)
    .setConfidenceThreshold(0.0f)  // Evaluate your model in the Cloud console
                                   // to determine an appropriate value.
    .build();
ImageLabeler labeler = ImageLabeling.getClient(customImageLabelerOptions);

Kotlin

val customImageLabelerOptions = CustomImageLabelerOptions.Builder(localModel)
    .setConfidenceThreshold(0.0f)  // Evaluate your model in the Cloud console
                                   // to determine an appropriate value.
    .build()
val labeler = ImageLabeling.getClient(customImageLabelerOptions)

如果您使用的是远程托管的模型，则必须在运行之前检查该模型是否已下载。您可以使用模型管理器的 isModelDownloaded() 方法检查模型下载任务的状态。

虽然您只需在运行标记器之前确认这一点，但如果您同时拥有远程托管模型和本地捆绑模型，则可能需要在实例化图片标记器时执行此项检查：如果已下载远程模型，则根据该模型创建标记器，否则根据本地模型进行创建。

Java

RemoteModelManager.getInstance().isModelDownloaded(remoteModel)
        .addOnSuccessListener(new OnSuccessListener<Boolean>() {
            @Override
            public void onSuccess(Boolean isDownloaded) {
                CustomImageLabelerOptions.Builder optionsBuilder;
                if (isDownloaded) {
                    optionsBuilder = new CustomImageLabelerOptions.Builder(remoteModel);
                } else {
                    optionsBuilder = new CustomImageLabelerOptions.Builder(localModel);
                }
                CustomImageLabelerOptions options = optionsBuilder
                        .setConfidenceThreshold(0.0f)  // Evaluate your model in the Cloud console
                                                       // to determine an appropriate threshold.
                        .build();

                ImageLabeler labeler = ImageLabeling.getClient(options);
            }
        });

Kotlin

RemoteModelManager.getInstance().isModelDownloaded(remoteModel)
    .addOnSuccessListener { isDownloaded ->
        val optionsBuilder =
            if (isDownloaded) {
                CustomImageLabelerOptions.Builder(remoteModel)
            } else {
                CustomImageLabelerOptions.Builder(localModel)
            }
        // Evaluate your model in the Cloud console to determine an appropriate threshold.
        val options = optionsBuilder.setConfidenceThreshold(0.0f).build()
        val labeler = ImageLabeling.getClient(options)
}

如果您只有远程托管的模型，应停用与模型相关的功能（例如使界面的一部分变灰或将其隐藏），直到您确认模型已下载。这可以通过将监听器附加到模型管理器的 download() 方法来实现：

Java

RemoteModelManager.getInstance().download(remoteModel, conditions)
        .addOnSuccessListener(new OnSuccessListener<Void>() {
            @Override
            public void onSuccess(Void v) {
              // Download complete. Depending on your app, you could enable
              // the ML feature, or switch from the local model to the remote
              // model, etc.
            }
        });

Kotlin

RemoteModelManager.getInstance().download(remoteModel, conditions)
    .addOnSuccessListener {
        // Download complete. Depending on your app, you could enable the ML
        // feature, or switch from the local model to the remote model, etc.
    }

2. 准备输入图片

接下来，基于每个您想要加标签的图片创建一个 InputImage 对象。使用 Bitmap 或 YUV_420_888 media.Image（如果您使用 Camera2 API）时，图片标记器的运行速度最快；建议您尽量使用这两种格式的图片。

您可以基于不同来源创建 InputImage，下文分别介绍了具体方法。

使用 `media.Image`

如需基于 media.Image 对象创建 InputImage 对象（例如从设备的相机捕获图片时），请将 media.Image 对象和图片的旋转角度传递给 InputImage.fromMediaImage()。

如果您使用 CameraX 库，OnImageCapturedListener 和 ImageAnalysis.Analyzer 类会为您计算旋转角度值。

Kotlin+KTX

private class YourImageAnalyzer : ImageAnalysis.Analyzer {
    override fun analyze(imageProxy: ImageProxy?) {
        val mediaImage = imageProxy?.image
        if (mediaImage != null) {
            val image = InputImage.fromMediaImage(mediaImage, imageProxy.imageInfo.rotationDegrees)
            // Pass image to an ML Kit Vision API
            // ...
        }
    }
}

Java

private class YourAnalyzer implements ImageAnalysis.Analyzer {

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

如果您不使用可提供图片旋转角度的相机库，则可以根据设备的旋转角度和设备中相机传感器的朝向来计算旋转角度：

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

然后，将 media.Image 对象及其旋转角度值传递给 InputImage.fromMediaImage()：

Kotlin+KTX

val image = InputImage.fromMediaImage(mediaImage, rotation)

Java

InputImage image = InputImage.fromMediaImage(mediaImage, rotation);

使用文件 URI

如需基于文件 URI 创建 InputImage 对象，请将应用上下文和文件 URI 传递给 InputImage.fromFilePath()。如果您使用 ACTION_GET_CONTENT Intent 提示用户从图库应用中选择图片，则这一操作非常有用。

Kotlin+KTX

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

Java

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

使用 `ByteBuffer` 或 `ByteArray`

如需基于 ByteBuffer 或 ByteArray 创建 InputImage 对象，请首先按先前 media.Image 输入的说明计算图片旋转角度。然后，使用缓冲区或数组以及图片的高度、宽度、颜色编码格式和旋转角度创建 InputImage 对象：

Kotlin+KTX

val image = InputImage.fromByteBuffer(
        byteBuffer,
        /* image width */ 480,
        /* image height */ 360,
        rotationDegrees,
        InputImage.IMAGE_FORMAT_NV21 // or IMAGE_FORMAT_YV12
)

Java

InputImage image = InputImage.fromByteBuffer(byteBuffer,
        /* image width */ 480,
        /* image height */ 360,
        rotationDegrees,
        InputImage.IMAGE_FORMAT_NV21 // or IMAGE_FORMAT_YV12
);

使用 `Bitmap`

如需基于 Bitmap 对象创建 InputImage 对象，请进行以下声明：

Kotlin+KTX

val image = InputImage.fromBitmap(bitmap, 0)

Java

InputImage image = InputImage.fromBitmap(bitmap, rotationDegree);

图片由 Bitmap 对象以及旋转角度表示。

3. 运行图片标记器

如需给图片中的对象加标签，请将 image 对象传递给 ImageLabeler 的 process() 方法。

Java

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

Kotlin

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

4. 获取已加标签的对象的相关信息

如果为图片添加标签的操作成功完成，系统会向成功监听器传递一组 ImageLabel 对象。每个 ImageLabel 对象代表图片中加了标签的某个事物。您可以获取每个标签的文本说明、匹配的置信度分数和匹配的索引。例如：

Java

for (ImageLabel label : labels) {
    String text = label.getText();
    float confidence = label.getConfidence();
    int index = label.getIndex();
}

Kotlin

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

提高实时性能的相关提示

如果要在实时应用中为图片加标签，请遵循以下准则以实现最佳帧速率：

限制图片标记器的调用次数。如果在图片标记器运行时有新的视频帧可用，请丢弃该帧。如需查看示例，请参阅快速入门示例应用中的 VisionProcessorBase 类。
如果要将图片标记器的输出作为图形叠加在输入图片上，请先获取结果，然后在一个步骤中完成图片的呈现和叠加。采用这一方法，每个输入帧只需在显示表面呈现一次。如需查看示例，请参阅快速入门示例应用中的 CameraSourcePreview 和 GraphicOverlay 类。
如果您使用 Camera2 API，请以 ImageFormat.YUV_420_888 格式捕获图片。

如果您使用旧版 Camera API，请以 ImageFormat.NV21 格式捕获图片。

使用 AutoML 训练的模型给图片加标签 (Android)

准备工作

1. 加载模型

配置本地模型来源

Java

Kotlin

配置 Firebase 托管的模型来源

Java

Kotlin

Java

Kotlin

根据模型创建图片标记器

Java

Kotlin

Java

Kotlin

Java

Kotlin

2. 准备输入图片

使用 media.Image

Kotlin+KTX

Java

Kotlin+KTX

Java

Kotlin+KTX

Java

使用文件 URI

Kotlin+KTX

Java

使用 ByteBuffer 或 ByteArray

Kotlin+KTX

Java

使用 Bitmap

Kotlin+KTX

Java

3. 运行图片标记器

Java

Kotlin

4. 获取已加标签的对象的相关信息

Java

Kotlin

提高实时性能的相关提示

使用 `media.Image`

使用 `ByteBuffer` 或 `ByteArray`

使用 `Bitmap`