顔検出ガイド(iOS)

顔検出タスクを使用すると、画像や動画内の顔を検出できます。次を使用: このタスクでは、フレーム内の顔と顔の特徴を検出します。このタスクでは、 単一の画像または連続ストリームで動作する機械学習(ML)モデル できます。このタスクでは、顔の位置と以下の顔キーが出力されます。 ポイント: 左目、右目、鼻先、口、左目のトラジオン、右目 あります

この手順で説明するコードサンプルは GitHub で入手できます。 このタスクの動作を確認するには、こちらのウェブ デモをご覧ください。詳細 その機能やモデル、構成オプションに関する情報を 詳細については、 概要

サンプルコード

MediaPipe Tasks のサンプルコードは顔検出器の単純な実装です アプリこの例では、物理的な Android デバイスのカメラを使用して、 連続する動画ストリームで識別します。また、このアプリで画像内の顔を検出したり、 動画をストリーミングできます

独自の iOS アプリの出発点としてアプリを使用することも、アプリ自体に言及することもできます。 変更する際の注意点があります。顔検出器のサンプルコードは次の場所でホストされています: GitHub

コードをダウンロードする

次の手順では、サンプルのローカルコピーを作成する方法を示します。 git コマンドライン ツールを使用してコードを実行します。

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

サンプルコードをダウンロードするには:

  1. 次のコマンドを使用して Git リポジトリのクローンを作成します。

    git clone https://github.com/google-ai-edge/mediapipe-samples
    
  2. 必要に応じて、スパース チェックアウトを使用するように Git インスタンスを構成し、 Face Detector サンプルアプリのファイルのみを表示します。

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

ローカル バージョンのサンプルコードを作成したら、 MediaPipe タスク ライブラリで、Xcode を使用してプロジェクトを開き、アプリを実行します。対象 手順については、iOS の設定ガイドをご覧ください。

主要コンポーネント

次のファイルには、顔検出のサンプルで使用する重要なコードが含まれています。 アプリケーション:

  • FaceDetectorService.swift: 検出機能を初期化し、モデル選択を処理して、入力データに対する推論を実行します。
  • CameraViewController: ライブカメラフィード入力モードの UI を実装し、検出結果を可視化します。
  • MediaLibraryViewController.swift: 静止画像ファイルと動画ファイル入力モードの UI を実装し、検出結果を可視化します。

セットアップ

このセクションでは、開発環境をセットアップする主な手順と Face Detector を使用するコード プロジェクトを作成します。設定に関する一般的な情報については、 MediaPipe タスクを使用するための開発環境(プラットフォーム バージョンを含む) iOS の設定ガイドをご覧ください。

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

依存関係

顔検出機能は MediaPipeTasksVision ライブラリを使用します。このライブラリをインストールする必要があります。 構築しましたこのライブラリは Swift アプリと Objective-C アプリの両方と互換性がある 言語固有の追加の設定は不要です

macOS に CocoaPods をインストールする手順については、CocoaPods インストール ガイドをご覧ください。 必要な Pod を使用して Podfile を作成する方法については、 詳しくは、 CocoaPods

次のコードを使用して、Podfile に MediaPipeTasksVision Pod を追加します。

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

アプリに単体テスト ターゲットが含まれている場合は、 iOS をご覧ください。 あなたのPodfile

モデル

MediaPipe Face Detector タスクには、互換性のあるトレーニング済みモデルが必要です 見ていきましょう。利用可能なトレーニング済みモデルについて詳しくは、 顔検出機能については、タスクの概要をご覧ください。モデル セクションをご覧ください

モデルを選択してダウンロードし、Xcode を使用してプロジェクト ディレクトリに追加します。 Xcode プロジェクトにファイルを追加する方法については、 Xcode 内のファイルとフォルダ プロジェクトです。

BaseOptions.modelAssetPath プロパティを使用してモデルのパスを指定する 追加できますコード例については、次のセクションをご覧ください。

タスクを作成する

顔検出タスクを作成するには、いずれかのイニシャライザを呼び出します。「 FaceDetector(options:) イニシャライザが構成の値を受け入れる 。

カスタマイズされた構成で初期化された顔検出器が不要な場合 FaceDetector(modelPath:) イニシャライザを使用して、 顔検出器とデフォルトのオプション。リソースの構成について 構成の概要をご覧ください。

顔検出タスクは、静止画像と動画ファイルの 3 つの入力データタイプをサポートします。 ストリーミング動画にも対応していますデフォルトでは、FaceDetector(modelPath:) は 行います。動画を処理するためにタスクを初期化する場合は、 ファイルまたはライブ動画ストリームの場合は、FaceDetector(options:) を使用して動画を指定します 配信モードを選択できますライブ配信モードでは、 faceDetectorLiveStreamDelegate 構成オプションを使用すると、 顔検出を使用して、顔検出の結果をデリゲートに非同期で配信します。

ランニングモードに対応するタブを選択すると、タスクの作成方法を確認できます 推論を実行できます

Swift

画像

import MediaPipeTasksVision

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

let options = FaceDetectorOptions()
options.baseOptions.modelAssetPath = modelPath
options.runningMode = .image

let faceDetector = try FaceDetector(options: options)
    

動画

import MediaPipeTasksVision

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

let options = FaceDetectorOptions()
options.baseOptions.modelAssetPath = modelPath
options.runningMode = .video

let faceDetector = try FaceDetector(options: options)
    

ライブ配信

import MediaPipeTasksVision

// Class that conforms to the `FaceDetectorLiveStreamDelegate` protocol and
// implements the method that the face detector calls once it finishes
// detecting faces in each input frame.
class FaceDetectorResultProcessor: NSObject, FaceDetectorLiveStreamDelegate {

  func faceDetector(
    _ faceDetector: FaceDetector,
    didFinishDetection result: FaceDetectorResult?,
    timestampInMilliseconds: Int,
    error: Error?) {

    // Process the face detection result or errors here.

  }
}

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

let options = FaceDetectorOptions()
options.baseOptions.modelAssetPath = modelPath
options.runningMode = .liveStream

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

let faceDetector = try FaceDetector(options: options)
    

Objective-C

画像

@import MediaPipeTasksVision;

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

MPPFaceDetectorOptions *options = [[MPPFaceDetectorOptions alloc] init];
options.baseOptions.modelAssetPath = modelPath;
options.runningMode = MPPRunningModeImage;

MPPFaceDetector *faceDetector =
      [[MPPFaceDetector alloc] initWithOptions:options error:nil];
    

動画

@import MediaPipeTasksVision;

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

MPPFaceDetectorOptions *options = [[MPPFaceDetectorOptions alloc] init];
options.baseOptions.modelAssetPath = modelPath;
options.runningMode = MPPRunningModeVideo;

MPPFaceDetector *faceDetector =
      [[MPPFaceDetector alloc] initWithOptions:options error:nil];
    

ライブ配信

@import MediaPipeTasksVision;

// Class that conforms to the `MPPFaceDetectorLiveStreamDelegate` protocol
// and implements the method that the face detector calls once it finishes
// detecting faces in each input frame.

@interface APPFaceDetectorResultProcessor : NSObject 

@end

@implementation APPFaceDetectorResultProcessor

-   (void)faceDetector:(MPPFaceDetector *)faceDetector
    didFinishDetectionWithResult:(MPPFaceDetectorResult *)faceDetectorResult
         timestampInMilliseconds:(NSInteger)timestampInMilliseconds
                           error:(NSError *)error {

    // Process the face detector result or errors here.

}

@end

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

MPPFaceDetectorOptions *options = [[MPPFaceDetectorOptions alloc] init];
options.baseOptions.modelAssetPath = modelPath;
options.runningMode = MPPRunningModeLiveStream;

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

MPPFaceDetector *faceDetector =
      [[MPPFaceDetector alloc] initWithOptions:options error:nil];
    

注: 動画モードまたはライブ配信モードを使用している場合、顔検出機能は フレームごとに検出モデルをトリガーすることを避け、 レイテンシを短縮できます

構成オプション

このタスクには、iOS アプリの場合、次の構成オプションがあります。

オプション名 説明 値の範囲 デフォルト値
runningMode タスクの実行モードを設定します。3 つの モード:

IMAGE: 単一画像入力のモード。

VIDEO: 動画のデコードされたフレームのモード。

LIVE_STREAM: 入力のライブ配信のモード カメラからのデータなどです。このモードでは、resultListener は 結果を受け取るリスナーを設定するために呼び出されます。 使用できます。
{RunningMode.image, RunningMode.video, RunningMode.liveStream} RunningMode.image
minDetectionConfidence 顔検出が成功とみなされるための最小信頼スコア。 Float [0,1] 0.5
minSuppressionThreshold 重複とみなされる顔検出の非最大抑制しきい値の最小値。 Float [0,1] 0.3

ライブ配信の設定

ランニング モードが [ライブ配信] に設定されている場合、顔検出機能は 追加の faceDetectorLiveStreamDelegate 構成オプション。これにより、 非同期で検出結果を配信することもできます。委譲 実装する faceDetector(_:didFinishDetection:timestampInMilliseconds:error:) メソッド、 顔検出が顔検出の結果を処理した後で呼び出すと、 表示されます。

オプション名 説明 値の範囲 デフォルト値
faceDetectorLiveStreamDelegate 顔検出機能が顔検出の結果を非同期で受信できるようにします [ライブストリームモード]をクリックしますインスタンスがこのプロパティに設定されているクラスは、 実装する faceDetector(_:didFinishDetection:timestampInMilliseconds:error:) メソッドを呼び出します。 該当なし 未設定

データの準備

事前に入力画像またはフレームを MPImage オブジェクトに変換する必要があります。 顔検出器に渡されます。MPImage はさまざまな種類の iOS 画像をサポートしています 形式があり、任意の実行モードで推論に使用できます。詳細 MPImage の詳細については、 MPImage API

ユースケースと実行モードに基づいて、iOS 画像形式を選択してください MPImage は、UIImageCVPixelBuffer、および 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 の画像を生成するアプリ 顔検出機能に送信すると、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 をご覧ください。 デベロッパー ドキュメントをご覧ください。

タスクを実行する

顔検出機能を実行するには、割り当てられている項目に固有の detect() メソッドを使用します。 実行モード:

  • 静止画像: detect(image:)
  • 動画: detect(videoFrame:timestampInMilliseconds:)
  • ライブ配信: detectAsync(image:timestampInMilliseconds:)

顔検出は、入力画像またはフレーム内で検出された顔を返します。

次のコードサンプルは、顔検出ツールを実行する方法の簡単な例を示しています。 実行モードが 3 つあります

Swift

画像

let result = try faceDetector.detect(image: image)
    

動画

let result = try faceDetector.detect(
  videoFrame: image,
  timestampInMilliseconds: timestamp)
    

ライブ配信

try faceDetector.detectAsync(
  image: image,
  timestampInMilliseconds: timestamp)
    

Objective-C

画像

MPPFaceDetectorResult *result = [faceDetector detectInImage:image
                                                      error:nil];
    

動画

MPPFaceDetectorResult *result = [faceDetector detectInVideoFrame:image
                                         timestampInMilliseconds:timestamp
                                                           error:nil];
    

ライブ配信

BOOL success = [faceDetector detectAsyncInImage:image
                        timestampInMilliseconds:timestamp
                                          error:nil];
    

顔検出器のコード例は、これらの各モードの実装を示しています。 詳細: detect(image:)detect(videoFrame:timestampInMilliseconds:)、 および detectAsync(image:timestampInMilliseconds:)。サンプルコードでは ユーザーが不要な処理モードを切り替えられるようにする あります。

次の点にご留意ください。

  • 動画モードまたはライブ配信モードで実行する場合は、 顔検出タスクへの入力フレームのタイムスタンプ。

  • 画像モードまたは動画モードで実行すると、顔検出タスクによって 入力画像やフレームの処理が完了するまで待機しません。宛先 現在のスレッドをブロックせずにバックグラウンドで処理を実行 使用すると、 Dispatch または NSOperation 説明します。

  • ライブ配信モードで実行すると、顔検出タスクがすぐに返されます。 現在のスレッドをブロックしません。このメソッドは、 faceDetector(_:didFinishDetection:timestampInMilliseconds:error:) メソッド 顔検出の結果を返します。「 Face Detector は、このメソッドを専用のシリアル ディスパッチキューに格納されます。ユーザー インターフェースに結果を表示するには、 メインキューに送られます。detectAsync 関数は、Face Detector タスクが別の画像を処理しているときに 顔検出器は新しい入力フレームを無視します。

結果の処理と表示

推論を実行すると、Face Detector タスクは FaceDetectorResult を返します。 このオブジェクトには、検出された顔の境界ボックスと信頼度を含む スコアで表します。

このタスクからの出力データの例を次に示します。

FaceDetectionResult:
  Detections:
    Detection #0:
      BoundingBox:
        origin_x: 126
        origin_y: 100
        width: 463
        height: 463
      Categories:
        Category #0:
          index: 0
          score: 0.9729152917861938
      NormalizedKeypoints:
        NormalizedKeypoint #0:
          x: 0.18298381567001343
          y: 0.2961040139198303
        NormalizedKeypoint #1:
          x: 0.3302789330482483
          y: 0.29289937019348145
        ... (6 keypoints for each face)
    Detection #1:
      BoundingBox:
        origin_x: 616
        origin_y: 193
        width: 430
        height: 430
      Categories:
        Category #0:
          index: 0
          score: 0.9251380562782288
      NormalizedKeypoints:
        NormalizedKeypoint #0:
          x: 0.6151331663131714
          y: 0.3713381886482239
        NormalizedKeypoint #1:
          x: 0.7460576295852661
          y: 0.38825345039367676
        ... (6 keypoints for each face)

次の図は、タスク出力を可視化したものです。

境界ボックスのない画像については、元の画像をご覧ください。

顔検出機能のサンプルコードは、結果を表示する方法を示しています。詳しくは、 コードサンプルをご覧ください。