适用于 iOS 的图片分类指南

借助图片分类器任务，您可以对图片进行分类。您可以使用 此任务以确定图片所代表的一组类别， 学习的。这些说明将向您介绍如何在 iOS 应用。您可在 GitHub

您可以查看此网页 演示。对于 功能、模型和配置选项 请参阅 概览。

代码示例

MediaPipe Tasks 示例代码是图像分类器的基本实现 。该示例使用 iOS 实体设备上的相机 对对象进行连续分类，也可以使用 用于对对象进行静态分类。

您可以以此为基础来创建自己的 iOS 应用，也可以作为参考 对现有应用进行了修改。图像分类器示例代码托管在 GitHub

下载代码

以下说明介绍了如何创建示例的本地副本 使用 git 命令行工具运行 git 代码库。

<ph type="x-smartling-placeholder">

如需下载示例代码，请执行以下操作：

  1. 使用以下命令克隆 git 代码库：

    git clone https://github.com/google-ai-edge/mediapipe-samples

  2. （可选）配置您的 git 实例以使用稀疏检出，这样您 只有图像分类器示例应用的文件：

    cd mediapipe
git sparse-checkout init --cone
git sparse-checkout set examples/image_classification/ios/

创建示例代码的本地版本后，您可以安装 MediaPipe 任务库，使用 Xcode 打开项目并运行应用。对于 请参阅 iOS 设置指南。

关键组件

以下文件包含图像分类器示例的关键代码 应用：

设置

本部分介绍了设置开发环境和 代码项目使用图像分类器。有关如何设置 用于使用 MediaPipe 任务（包括平台版本）的开发环境 要求，请参阅 iOS 设置指南。

<ph type="x-smartling-placeholder">

依赖项

图片分类器使用 MediaPipeTasksVision 库，必须安装该库 使用 CocoaPods 构建容器。该库与 Swift 和 Objective-C 应用兼容 并且不需要任何额外的语言相关设置。

如需了解如何在 macOS 上安装 CocoaPods，请参阅 CocoaPods 安装指南。 如需了解如何创建包含必要 Pod 的 Podfile，请参阅 请参阅使用 CocoaPods。

使用以下代码在 Podfile 中添加 MediaPipeTasksVision pod：

target 'MyImageClassifierApp' do
  use_frameworks!
  pod 'MediaPipeTasksVision'
end

如果您的应用包含单元测试目标，请参阅应用的设置指南 iOS 设备，详细了解如何设置 您的Podfile。

型号

MediaPipe 图像分类器任务需要一个与 此任务。如需详细了解适用于 Kubernetes 的 请参阅任务概览模型 部分。

选择并下载模型，然后使用 Xcode 将其添加到您的项目目录。 有关如何向 Xcode 项目添加文件的说明，请参阅管理 Xcode 中的文件和文件夹 项目。

使用 BaseOptions.modelAssetPath 属性指定模型的路径 。如需查看代码示例，请参阅下一部分。

创建任务

您可以通过调用图片分类器的初始化程序之一来创建该任务。通过 ImageClassifier(options:) 初始化程序用于为配置选项设置值 包括运行模式、显示名称语言区域、结果数上限、置信度 阈值、类别许可名单和拒绝名单。

如果您不需要使用自定义配置初始化的图片分类器 可以使用 ImageClassifier(modelPath:) 初始化程序创建 具有默认选项的图片分类器。如需详细了解配置 选项，请参阅配置概览。

图片分类器任务支持 3 种输入数据类型：静态图片、视频文件 和直播视频流默认情况下，ImageClassifier(modelPath:) 会初始化 执行任务。如果您希望将任务初始化以处理视频 文件或直播视频串流，请使用 ImageClassifier(options:) 来指定 视频/直播运行模式直播模式还要求 额外的 imageClassifierLiveStreamDelegate 配置选项 可让图像分类器将图像分类结果 异步委托

选择与运行模式对应的标签页，了解如何创建任务 并进行推理。

Swift

映像

import MediaPipeTasksVision

let modelPath = Bundle.main.path(forResource: "model",
                                      ofType: "tflite")

let options = ImageClassifierOptions()
options.baseOptions.modelAssetPath = modelPath
options.runningMode = .image
options.maxResults = 5

let imageClassifier = try ImageClassifier(options: options)

视频

import MediaPipeTasksVision

let modelPath = Bundle.main.path(forResource: "model",
                                      ofType: "tflite")

let options = ImageClassifierOptions()
options.baseOptions.modelAssetPath = modelPath
options.runningMode = .video
options.maxResults = 5

let imageClassifier = try ImageClassifier(options: options)

直播

import MediaPipeTasksVision

// Class that conforms to the `ImageClassifierLiveStreamDelegate` protocol and
// implements the method that the image classifier calls once it
// finishes performing classification on each input frame.
class ImageClassifierResultProcessor: NSObject, ImageClassifierLiveStreamDelegate {

   func imageClassifier(
    _ imageClassifier: ImageClassifier,
    didFinishClassification result: ImageClassifierResult?,
    timestampInMilliseconds: Int,
    error: Error?) {

    // Process the image classifier result or errors here.

  }
}

let modelPath = Bundle.main.path(
  forResource: "model",
  ofType: "tflite")

let options = ImageClassifierOptions()
options.baseOptions.modelAssetPath = modelPath
options.runningMode = .liveStream
options.maxResults = 5

// Assign an object of the class to the `imageClassifierLiveStreamDelegate`
// property.
let processor = ImageClassifierResultProcessor()
options.imageClassifierLiveStreamDelegate = processor

let imageClassifier = try ImageClassifier(options: options)

Objective-C

映像

@import MediaPipeTasksVision;

NSString *modelPath = [[NSBundle mainBundle] pathForResource:@"model"
                                                      ofType:@"tflite"];

MPPImageClassifierOptions *options = [[MPPImageClassifierOptions alloc] init];
options.baseOptions.modelAssetPath = modelPath;
options.runningMode = MPPRunningModeImage;
options.maxResults = 5;

MPPImageClassifier *imageClassifier =
      [[MPPImageClassifier alloc] initWithOptions:options error:nil];

视频

@import MediaPipeTasksVision;

NSString *modelPath = [[NSBundle mainBundle] pathForResource:@"model"
                                                      ofType:@"tflite"];

MPPImageClassifierOptions *options = [[MPPImageClassifierOptions alloc] init];
options.baseOptions.modelAssetPath = modelPath;
options.runningMode = MPPRunningModeVideo;
options.maxResults = 5;

MPPImageClassifier *imageClassifier =
      [[MPPImageClassifier alloc] initWithOptions:options error:nil];

直播

@import MediaPipeTasksVision;

// Class that conforms to the `MPPImageClassifierLiveStreamDelegate` protocol
// and implements the method that the image classifier calls once it finishes
// performing classification on each input frame.

@interface APPImageClassifierResultProcessor : NSObject 

@end

@implementation APPImageClassifierResultProcessor

-   (void)imageClassifier:(MPPImageClassifier *)imageClassifier
    didFinishClassificationWithResult:(MPPImageClassifierResult *)imageClassifierResult
              timestampInMilliseconds:(NSInteger)timestampInMilliseconds
                                error:(NSError *)error {

    // Process the image classifier result or errors here.

}

@end

NSString *modelPath = [[NSBundle mainBundle] pathForResource:@"model"
                                                      ofType:@"tflite"];

MPPImageClassifierOptions *options = [[MPPImageClassifierOptions alloc] init];
options.baseOptions.modelAssetPath = modelPath;
options.runningMode = MPPRunningModeLiveStream;
options.maxResults = 5;

// Assign an object of the class to the `imageClassifierLiveStreamDelegate`
// property.
APPImageClassifierResultProcessor *processor = [APPImageClassifierResultProcessor new];
options.imageClassifierLiveStreamDelegate = processor;

MPPImageClassifier *imageClassifier =
      [[MPPImageClassifier alloc] initWithOptions:options error:nil];

配置选项

此任务具有以下适用于 iOS 应用的配置选项：

选项名称 说明 值范围 默认值
runningMode 设置任务的运行模式。有三个 模式：

IMAGE：单图输入的模式。

VIDEO：视频已解码帧的模式。

LIVE_STREAM：输入流媒体直播模式 例如来自相机的数据。在此模式下，resultListener 必须为 调用以设置监听器以接收结果 异步执行。		 {RunningMode.image, RunningMode.video, RunningMode.liveStream} RunningMode.image
displayNamesLocale 设置要用于 任务模型的元数据（如果有）。默认值为 en， 英语。您可以向自定义模型的元数据中添加本地化标签 使用 TensorFlow Lite Metadata Writer API 语言区域代码 en
maxResults 将评分最高的分类结果的可选数量上限设置为 return。如果 <0，则返回所有可用的结果。 任何正数 -1
scoreThreshold 设置预测分数阈值，以替换 模型元数据（如果有）。低于此值的结果将被拒绝。 任意浮点数 未设置
categoryAllowlist 设置允许的类别名称的可选列表。如果不为空， 类别名称未包含在此集合中的分类结果 已滤除。重复或未知的类别名称会被忽略。 此选项与 categoryDenylist 互斥，使用 都会导致错误。 任何字符串 未设置
categoryDenylist 设置不允许使用的类别名称的可选列表。如果 非空，类别名称在此集中的分类结果将被滤除 。重复或未知的类别名称会被忽略。这个选项 categoryAllowlist 不包含，同时使用这两个元素会导致错误。 任何字符串 未设置
resultListener 设置结果监听器以接收分类结果 当图像分类器在直播中时异步执行 模式。仅在跑步模式设为“LIVE_STREAM”时才能使用 不适用 未设置

直播配置

当跑步模式设置为直播时，图像分类器需要 额外的 imageClassifierLiveStreamDelegate 配置选项 使分类器异步传送分类结果。通过 委托会实现 imageClassifier(_:didFinishClassification:timestampInMilliseconds:error:) 方法，图片分类器在处理分类后调用该方法 每个帧的结果。

选项名称 说明 值范围 默认值
imageClassifierLiveStreamDelegate 启用图片分类器以异步接收分类结果 处于直播模式将实例设置为此属性的类必须 实施 imageClassifier(_:didFinishClassification:timestampInMilliseconds:error:) 方法。 不适用 未设置

准备数据

您需要先将输入图片或帧转换为 MPImage 对象，然后才能 传递给图像分类器。MPImage 支持不同类型的 iOS 图片 并且可在任何运行模式下使用它们进行推理。有关 有关 MPImage 的信息，请参阅 MPImage API

根据您的使用情形和应用的运行模式选择 iOS 图片格式 MPImage 接受 UIImage、CVPixelBuffer 和 CMSampleBuffer iOS 图片格式。

UIImage

UIImage 格式非常适合以下运行模式：

  • 图片：来自 app bundle、用户图库或文件系统的图片，格式为 UIImage 图片可转换为 MPImage 对象。

  • 视频：使用 AVAssetImageGenerator 将视频帧提取到 CGImage 格式，然后将其转换为 UIImage 图片。

Swift

// Load an image on the user's device as an iOS `UIImage` object.

// Convert the `UIImage` object to a MediaPipe's Image object having the default
// orientation `UIImage.Orientation.up`.
let image = try MPImage(uiImage: image)

Objective-C

// Load an image on the user's device as an iOS `UIImage` object.

// Convert the `UIImage` object to a MediaPipe's Image object having the default
// orientation `UIImageOrientationUp`.
MPImage *image = [[MPPImage alloc] initWithUIImage:image error:nil];

本示例使用默认值初始化 MPImage。 UIImage.Orientation.Up 屏幕方向。您可以使用任何受支持的MPImage UIImage.Orientation 值。图片分类器不支持 .upMirrored 等镜像方向， .downMirrored、.leftMirrored、.rightMirrored。

有关 UIImage 的详细信息，请参阅 UIImage Apple Developer 文档。

CVPixelBuffer

CVPixelBuffer 格式非常适合生成帧的应用 并使用 iOS CoreImage 处理框架

CVPixelBuffer 格式非常适合以下运行模式：

  • 图片：应用会在经过一些处理后生成 CVPixelBuffer 图片 使用 iOS 的 CoreImage 框架发送到图片分类器的 映像运行模式

  • 视频：可将视频帧转换为 CVPixelBuffer 格式，以便 处理，然后在视频模式下发送到图像分类器。

  • 直播：使用 iOS 相机生成帧的应用可能会被转换 转换为 CVPixelBuffer 格式进行处理，然后再发送到 直播模式下的图片分类器。

Swift

// Obtain a CVPixelBuffer.

// Convert the `CVPixelBuffer` object to a MediaPipe's Image object having the default
// orientation `UIImage.Orientation.up`.
let image = try MPImage(pixelBuffer: pixelBuffer)

Objective-C

// Obtain a CVPixelBuffer.

// Convert the `CVPixelBuffer` object to a MediaPipe's Image object having the
// default orientation `UIImageOrientationUp`.
MPImage *image = [[MPPImage alloc] initWithUIImage:image error:nil];

如需详细了解 CVPixelBuffer，请参阅 CVPixelBuffer Apple 开发者 文档。

CMSampleBuffer

CMSampleBuffer 格式用于存储统一媒体类型的媒体样本， 非常适合直播运行模式。来自 iOS 相机的实时帧 由 iOS 以 CMSampleBuffer 格式异步传送 AVCaptureVideoDataOutput.

Swift

// Obtain a CMSampleBuffer.

// Convert the `CMSampleBuffer` object to a MediaPipe's Image object having the default
// orientation `UIImage.Orientation.up`.
let image = try MPImage(sampleBuffer: sampleBuffer)

Objective-C

// Obtain a `CMSampleBuffer`.

// Convert the `CMSampleBuffer` object to a MediaPipe's Image object having the
// default orientation `UIImageOrientationUp`.
MPImage *image = [[MPPImage alloc] initWithSampleBuffer:sampleBuffer error:nil];

如需详细了解 CMSampleBuffer，请参阅 CMSampleBuffer Apple 开发者 文档。

运行任务

如需运行图像分类器，请使用专用于指定图像分类器的 classify() 方法 跑步模式：

  • 静态图片：classify(image:)
  • 视频：classify(videoFrame:timestampInMilliseconds:)
  • 直播：classifyAsync(image:timestampInMilliseconds:)

图像分类器会返回对象在 输入图像或帧。

以下代码示例显示了如何在 不同的跑步模式：

Swift

映像

let result = try imageClassifier.classify(image: image)

视频

let result = try imageClassifier.classify(
  videoFrame: image,
  timestampInMilliseconds: timestamp)

直播

try imageClassifier.classifyAsync(
  image: image,
  timestampInMilliseconds: timestamp)

Objective-C

映像

MPPImageClassifierResult *result = [imageClassifier classifyImage:image
                                                            error:nil];

视频

MPPImageClassifierResult *result = [imageClassifier classifyVideoFrame:image
                                               timestampInMilliseconds:timestamp
                                                                 error:nil];

直播

BOOL success = [imageClassifier classifyAsyncImage:image
                          timestampInMilliseconds:timestamp
                                            error:nil];

图像分类器代码示例展示了每种模式的实现 classify(image:)， classify(videoFrame:timestampInMilliseconds:)和 classifyAsync(image:timestampInMilliseconds:)。示例代码允许 让用户可以在您可能并不需要的处理模式之间进行切换 这种情况。

请注意以下几点：

  • 在视频模式或直播模式下运行时，您还必须提供 图像分类器任务的输入帧的时间戳。

  • 在图片或视频模式下运行时，图片分类器任务会阻止 当前线程，直到处理完输入图像或帧为止。接收者 避免阻塞当前线程，在后台执行处理 使用 iOS 的会话串 Dispatch 或 NSOperation 框架。

  • 在实时模式下运行时，图像分类器任务会立即返回 并且不会阻塞当前线程。它会调用 imageClassifier(_:didFinishClassification:timestampInMilliseconds:error:) 方法与分类结果相关联。通过 图像分类器在专用序列上异步调用此方法 调度队列。要在界面上显示结果，请分派 并在处理后将结果发送到主队列中。如果 当图像分类器任务忙时，系统会调用 classifyAsync 函数 处理其他帧时，图像分类器会忽略新的输入帧。

处理和显示结果

运行推理时，图像分类器任务会返回 ImageClassifierResult 对象，该对象包含可能的类别列表 输入图片或帧中的对象。

以下示例展示了此任务的输出数据：

ImageClassifierResult:
 Classifications #0 (single classification head):
  head index: 0
  category #0:
   category name: "/m/01bwb9"
   display name: "Passer domesticus"
   score: 0.91406
   index: 671
  category #1:
   category name: "/m/01bwbt"
   display name: "Passer montanus"
   score: 0.00391
   index: 670

此结果是通过运行 Bird Classifier 获得的 日期：

图像分类器示例代码演示了如何显示分类 结果，请参阅代码 示例 了解详情。