ML Kit を使用して顔を検出する（iOS）

このページでは、Firebase 向け ML Kit の一部であった Face Detection APIの古いバージョンについて説明します。この API の開発はスタンドアロンの ML Kit SDK に移行され、Firebase の有無にかかわらず使用できます。詳細。

最新のドキュメントについては、 Detect faces with ML Kit on iOS をご覧ください。

ML Kit を使用すると、画像や動画内の顔を検出できます。

始める前に

1. まだアプリに Firebase を追加していない場合は、スタートガイドの手順に沿って追加してください。
2. ML Kit ライブラリを Podfile に含めます:

   pod 'Firebase/MLVision', '6.25.0'
   # If you want to detect face contours (landmark detection and classification
   # don't require this additional model):
   pod 'Firebase/MLVisionFaceModel', '6.25.0'
   

   プロジェクトの Pod をインストールまたは更新した後に、.xcworkspace を使用して Xcode プロジェクトを開くようにしてください。
3. アプリに Firebase をインポートします。

   Swift

   import Firebase

   Objective-C

   @import Firebase;

入力画像に関するガイドライン

ML Kit で顔を正確に認識するには、入力画像に含まれている顔が十分なピクセルデータによって表現されている必要があります。一般に、画像内で検出する顔は少なくとも 100x100 ピクセルである必要があります。ML Kit で顔の輪郭を検出するには、より高い解像度の入力が必要です。その場合、顔は 200x200 ピクセル以上にする必要があります。

リアルタイム アプリケーションで顔を認識する場合は、入力画像の全体サイズも考慮する必要があります。サイズが小さいほど処理は高速になるため、レイテンシを短くするには画像を低い解像度でキャプチャし（上記の精度要件に留意）、対象の顔が画像のできるだけ多くの部分を占めるようにします。リアルタイムのパフォーマンスを改善するためのヒントもご覧ください。

画像がぼやけていると、認識精度が低下する可能性があります。満足のいく結果が得られない場合は、ユーザーに画像をキャプチャし直すよう求めてください。

カメラに対する顔の向きも、ML Kit で検出される顔の特徴に影響を与える可能性があります。顔検出のコンセプトをご覧ください。

1. 顔検出器を構成する

顔検出器のデフォルト設定のいずれかを変更する場合は、画像に顔検出を適用する前に、VisionFaceDetectorOptions オブジェクトを使用して設定を指定します。次の設定を変更できます。

設定
performanceMode	fast（デフォルト）| accurate 顔を検出する際に速度を優先するか精度を優先するか。
landmarkMode	none（デフォルト）| all 顔の「ランドマーク」（目、耳、鼻、頬、口）を検出するかどうか。
contourMode	none（デフォルト）| all 顔の特徴の輪郭を検出するかどうか。輪郭は、画像内で最も目立つ顔についてのみ検出されます。
classificationMode	none（デフォルト）| all 顔を「ほほ笑んでいる」や「目を開けている」などのカテゴリに分類するかどうか。
minFaceSize	CGFloat（デフォルト: 0.1） 画像を基準とした、検出する顔の最小サイズ。
isTrackingEnabled	false（デフォルト）| true 複数の画像間で顔をトラッキングするために使用できる ID を顔に割り当てるかどうか。 輪郭の検出が有効になっていると、検出される顔が 1 つだけになり、顔トラッキングで有用な結果が得られません。このため、輪郭の検出と顔トラッキングの両方を有効にしないでください。検出速度の向上にもつながります。

たとえば、次のいずれかの例のように VisionFaceDetectorOptions オブジェクトを作成します。

Swift

// High-accuracy landmark detection and face classification
let options = VisionFaceDetectorOptions()
options.performanceMode = .accurate
options.landmarkMode = .all
options.classificationMode = .all

// Real-time contour detection of multiple faces
let options = VisionFaceDetectorOptions()
options.contourMode = .all

Objective-C

// High-accuracy landmark detection and face classification
FIRVisionFaceDetectorOptions *options = [[FIRVisionFaceDetectorOptions alloc] init];
options.performanceMode = FIRVisionFaceDetectorPerformanceModeAccurate;
options.landmarkMode = FIRVisionFaceDetectorLandmarkModeAll;
options.classificationMode = FIRVisionFaceDetectorClassificationModeAll;

// Real-time contour detection of multiple faces
FIRVisionFaceDetectorOptions *options = [[FIRVisionFaceDetectorOptions alloc] init];
options.contourMode = FIRVisionFaceDetectorContourModeAll;

2. 顔検出器を実行する

画像内の顔を検出するには、画像を UIImage または CMSampleBufferRef として VisionFaceDetector の detect(in:) メソッドに渡します。

1. VisionFaceDetector のインスタンスを取得します。

   Swift

   lazy var vision = Vision.vision()
   
   let faceDetector = vision.faceDetector(options: options)
   

   Objective-C

   FIRVision *vision = [FIRVision vision];
   FIRVisionFaceDetector *faceDetector = [vision faceDetector];
   // Or, to change the default settings:
   // FIRVisionFaceDetector *faceDetector =
   //     [vision faceDetectorWithOptions:options];
   

2. UIImage または CMSampleBufferRef を使用して VisionImage オブジェクトを作成します。

   UIImage を使用するには:

   1. 必要に応じて、imageOrientation プロパティが .up になるように画像を回転させます。
   2. 適切に回転させた UIImage を使用して VisionImage オブジェクトを作成します。回転メタデータにはデフォルト値の .topLeft を使用する必要があるため、値を指定しないでください。

      Swift

      let image = VisionImage(image: uiImage)

      Objective-C

      FIRVisionImage *image = [[FIRVisionImage alloc] initWithImage:uiImage];

   CMSampleBufferRef を使用するには:

   1. VisionImageMetadata オブジェクトを作成し、CMSampleBufferRef バッファに格納されている画像データの向きを指定します。

      画像の向きは次のように取得します。

      Swift

      func imageOrientation(
          deviceOrientation: UIDeviceOrientation,
          cameraPosition: AVCaptureDevice.Position
          ) -> VisionDetectorImageOrientation {
          switch deviceOrientation {
          case .portrait:
              return cameraPosition == .front ? .leftTop : .rightTop
          case .landscapeLeft:
              return cameraPosition == .front ? .bottomLeft : .topLeft
          case .portraitUpsideDown:
              return cameraPosition == .front ? .rightBottom : .leftBottom
          case .landscapeRight:
              return cameraPosition == .front ? .topRight : .bottomRight
          case .faceDown, .faceUp, .unknown:
              return .leftTop
          }
      }

      Objective-C

      - (FIRVisionDetectorImageOrientation)
          imageOrientationFromDeviceOrientation:(UIDeviceOrientation)deviceOrientation
                                 cameraPosition:(AVCaptureDevicePosition)cameraPosition {
        switch (deviceOrientation) {
          case UIDeviceOrientationPortrait:
            if (cameraPosition == AVCaptureDevicePositionFront) {
              return FIRVisionDetectorImageOrientationLeftTop;
            } else {
              return FIRVisionDetectorImageOrientationRightTop;
            }
          case UIDeviceOrientationLandscapeLeft:
            if (cameraPosition == AVCaptureDevicePositionFront) {
              return FIRVisionDetectorImageOrientationBottomLeft;
            } else {
              return FIRVisionDetectorImageOrientationTopLeft;
            }
          case UIDeviceOrientationPortraitUpsideDown:
            if (cameraPosition == AVCaptureDevicePositionFront) {
              return FIRVisionDetectorImageOrientationRightBottom;
            } else {
              return FIRVisionDetectorImageOrientationLeftBottom;
            }
          case UIDeviceOrientationLandscapeRight:
            if (cameraPosition == AVCaptureDevicePositionFront) {
              return FIRVisionDetectorImageOrientationTopRight;
            } else {
              return FIRVisionDetectorImageOrientationBottomRight;
            }
          default:
            return FIRVisionDetectorImageOrientationTopLeft;
        }
      }

      次に、メタデータ オブジェクトを作成します。

      Swift

      let cameraPosition = AVCaptureDevice.Position.back  // Set to the capture device you used.
      let metadata = VisionImageMetadata()
      metadata.orientation = imageOrientation(
          deviceOrientation: UIDevice.current.orientation,
          cameraPosition: cameraPosition
      )

      Objective-C

      FIRVisionImageMetadata *metadata = [[FIRVisionImageMetadata alloc] init];
      AVCaptureDevicePosition cameraPosition =
          AVCaptureDevicePositionBack;  // Set to the capture device you used.
      metadata.orientation =
          [self imageOrientationFromDeviceOrientation:UIDevice.currentDevice.orientation
                                       cameraPosition:cameraPosition];

   2. VisionImage オブジェクトと回転メタデータを使用して CMSampleBufferRef オブジェクトを作成します。

      Swift

      let image = VisionImage(buffer: sampleBuffer)
      image.metadata = metadata

      Objective-C

      FIRVisionImage *image = [[FIRVisionImage alloc] initWithBuffer:sampleBuffer];
      image.metadata = metadata;

3. 次に、画像を detect(in:) メソッドに渡します。

   Swift

   faceDetector.process(visionImage) { faces, error in
     guard error == nil, let faces = faces, !faces.isEmpty else {
       // ...
       return
     }
   
     // Faces detected
     // ...
   }
   

   Objective-C

   [faceDetector detectInImage:image
                    completion:^(NSArray<FIRVisionFace *> *faces,
                                 NSError *error) {
     if (error != nil) {
       return;
     } else if (faces != nil) {
       // Recognized faces
     }
   }];
   

3. 検出された顔に関する情報を取得する

顔検出オペレーションが成功すると、顔検出器は VisionFace オブジェクトの配列を完了ハンドラに渡します。各 VisionFace オブジェクトは画像内で検出された顔を表します。顔ごとに、入力画像の境界座標と、顔検出器に検出するよう構成したその他の情報を取得できます。次に例を示します。

Swift

for face in faces {
  let frame = face.frame
  if face.hasHeadEulerAngleY {
    let rotY = face.headEulerAngleY  // Head is rotated to the right rotY degrees
  }
  if face.hasHeadEulerAngleZ {
    let rotZ = face.headEulerAngleZ  // Head is rotated upward rotZ degrees
  }

  // If landmark detection was enabled (mouth, ears, eyes, cheeks, and
  // nose available):
  if let leftEye = face.landmark(ofType: .leftEye) {
    let leftEyePosition = leftEye.position
  }

  // If contour detection was enabled:
  if let leftEyeContour = face.contour(ofType: .leftEye) {
    let leftEyePoints = leftEyeContour.points
  }
  if let upperLipBottomContour = face.contour(ofType: .upperLipBottom) {
    let upperLipBottomPoints = upperLipBottomContour.points
  }

  // If classification was enabled:
  if face.hasSmilingProbability {
    let smileProb = face.smilingProbability
  }
  if face.hasRightEyeOpenProbability {
    let rightEyeOpenProb = face.rightEyeOpenProbability
  }

  // If face tracking was enabled:
  if face.hasTrackingID {
    let trackingId = face.trackingID
  }
}

Objective-C

for (FIRVisionFace *face in faces) {
  // Boundaries of face in image
  CGRect frame = face.frame;

  if (face.hasHeadEulerAngleY) {
    CGFloat rotY = face.headEulerAngleY;  // Head is rotated to the right rotY degrees
  }
  if (face.hasHeadEulerAngleZ) {
    CGFloat rotZ = face.headEulerAngleZ;  // Head is tilted sideways rotZ degrees
  }

  // If landmark detection was enabled (mouth, ears, eyes, cheeks, and
  // nose available):
  FIRVisionFaceLandmark *leftEar = [face landmarkOfType:FIRFaceLandmarkTypeLeftEar];
  if (leftEar != nil) {
    FIRVisionPoint *leftEarPosition = leftEar.position;
  }

  // If contour detection was enabled:
  FIRVisionFaceContour *upperLipBottomContour = [face contourOfType:FIRFaceContourTypeUpperLipBottom];
  if (upperLipBottomContour != nil) {
    NSArray<FIRVisionPoint *> *upperLipBottomPoints = upperLipBottomContour.points;
    if (upperLipBottomPoints.count > 0) {
      NSLog("Detected the bottom contour of the subject's upper lip.")
    }
  }

  // If classification was enabled:
  if (face.hasSmilingProbability) {
    CGFloat smileProb = face.smilingProbability;
  }
  if (face.hasRightEyeOpenProbability) {
    CGFloat rightEyeOpenProb = face.rightEyeOpenProbability;
  }

  // If face tracking was enabled:
  if (face.hasTrackingID) {
    NSInteger trackingID = face.trackingID;
  }
}

顔の輪郭の例

顔の輪郭検出を有効にすると、検出された顔の特徴が点のリストで表示されます。これらの点は特徴の形状を表します。輪郭の表現方法については、顔検出のコンセプトの概要をご覧ください。

次の図は、これらの点が顔にどのようにマッピングされるかを示します（画像をクリックすると拡大します）。

リアルタイム顔検出

リアルタイムのアプリケーションで顔検出を使用する場合は、適切なフレームレートを得るために次のガイドラインに従ってください。

• 顔の輪郭検出、または分類とランドマークの検出のいずれかを使用するように顔検出器を構成してください。両方は使用できません。

  輪郭検出
  ランドマーク検出
  分類
  ランドマークの検出と分類
  輪郭検出とランドマーク検出
  輪郭検出と分類
  輪郭検出、ランドマーク検出、分類
  

• fast モードを有効にします（デフォルトで有効）。

• より低い解像度で画像をキャプチャすることを検討してください。ただし、この API の画像サイズに関する要件にも留意してください。

• 検出器の呼び出しのスロットル調整を行います。検出器の実行中に新しい動画フレームが使用可能になった場合は、そのフレームをドロップします。
• 検出器の出力を使用して入力画像の上にグラフィックスをオーバーレイする場合は、まず ML Kit から検出結果を取得し、画像とオーバーレイを 1 つのステップでレンダリングします。これにより、ディスプレイ サーフェスへのレンダリングは入力フレームごとに 1 回で済みます。例については、ショーケース サンプルアプリの previewOverlayView クラスと FIRDetectionOverlayView クラスをご覧ください。