このページは Cloud Translation API によって翻訳されました。

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

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

機能	バンドル解除	バンドル
実装	モデルは Google Play 開発者サービス経由で動的にダウンロードされます。	モデルはビルド時にアプリに静的にリンクされます。
アプリのサイズ	サイズが約 800 KB 増加します。	サイズが約 6.9 MB 増加します。
初期化時間	初めて使用する前にモデルのダウンロードを待つ必要がある場合があります。	モデルはすぐに利用可能

試してみる

サンプルアプリを試して、この API の使用例を確認してください。
Codelab でコードを試す。

始める前に

この API には Android API レベル 21 以降が必要です。アプリのビルドファイルで minSdkVersion の値が 21 以上であることを確認します。

プロジェクトレベルの build.gradle ファイルの buildscript セクションと allprojects セクションの両方に Google の Maven リポジトリを組み込みます。

ML Kit Android ライブラリの依存関係をモジュールのアプリレベルの Gradle ファイル（通常は app/build.gradle）に追加します。ニーズに応じて、次のいずれかの依存関係を選択します。

モデルをアプリにバンドルする場合:

dependencies {
  // ...
  // Use this dependency to bundle the model with your app
  implementation 'com.google.mlkit:face-detection:16.1.7'
}

Google Play 開発者サービスでモデルを使用する場合:

dependencies {
  // ...
  // Use this dependency to use the dynamically downloaded model in Google Play Services
  implementation 'com.google.android.gms:play-services-mlkit-face-detection:17.1.0'
}

Google Play 開発者サービスでモデルを使用する場合は、アプリが Google Play ストアからインストールされたら、モデルをデバイスに自動的にダウンロードするようにアプリを構成できます。この構成を行うには、アプリの AndroidManifest.xml ファイルに次の宣言を追加します。
```
<application ...>
      ...
      <meta-data
          android:name="com.google.mlkit.vision.DEPENDENCIES"
          android:value="face" >
      
</application>
```
Google Play 開発者サービスの ModuleInstallClient API を使用して、モデルの可用性を明示的に確認し、ダウンロードをリクエストすることもできます。

インストール時のモデルのダウンロードを有効にしない、または明示的なダウンロードをリクエストしない場合は、検出器の初回実行時にモデルがダウンロードされます。ダウンロードが完了する前にリクエストしても結果は生成されません。

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

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

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

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

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

1. 顔検出器を構成する

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

設定
`setPerformanceMode`	`PERFORMANCE_MODE_FAST`（デフォルト） \| `PERFORMANCE_MODE_ACCURATE` 顔を検出する際に速度を優先するか精度を優先するか。
`setLandmarkMode`	`LANDMARK_MODE_NONE`（デフォルト） \| `LANDMARK_MODE_ALL` 顔の「ランドマーク」（目、耳、鼻、頬、口）を識別するかどうか。
`setContourMode`	`CONTOUR_MODE_NONE`（デフォルト） \| `CONTOUR_MODE_ALL` 顔の特徴の輪郭を検出するかどうか。輪郭は、画像内で最も目立つ顔についてのみ検出されます。
`setClassificationMode`	`CLASSIFICATION_MODE_NONE`（デフォルト） \| `CLASSIFICATION_MODE_ALL` 顔を「ほほ笑んでいる」や「目を開けている」などのカテゴリに分類するかどうか。
`setMinFaceSize`	`float`（デフォルト: `0.1f`）希望する最小の顔サイズを設定します。これは、頭の幅と画像の幅の比率で表されます。
`enableTracking`	`false`（デフォルト）\| `true` 複数の画像間で顔をトラッキングするために使用できる ID を顔に割り当てるかどうか。輪郭の検出が有効になっていると、検出される顔が 1 つだけになり、顔トラッキングで有用な結果が得られません。このため、輪郭の検出と顔トラッキングの両方を有効にしないでください。検出速度の向上にもつながります。

次に例を示します。

Kotlin

// High-accuracy landmark detection and face classification
val highAccuracyOpts = FaceDetectorOptions.Builder()
        .setPerformanceMode(FaceDetectorOptions.PERFORMANCE_MODE_ACCURATE)
        .setLandmarkMode(FaceDetectorOptions.LANDMARK_MODE_ALL)
        .setClassificationMode(FaceDetectorOptions.CLASSIFICATION_MODE_ALL)
        .build()

// Real-time contour detection
val realTimeOpts = FaceDetectorOptions.Builder()
        .setContourMode(FaceDetectorOptions.CONTOUR_MODE_ALL)
        .build()FaceDetectionActivity.kt

Java

// High-accuracy landmark detection and face classification
FaceDetectorOptions highAccuracyOpts =
        new FaceDetectorOptions.Builder()
                .setPerformanceMode(FaceDetectorOptions.PERFORMANCE_MODE_ACCURATE)
                .setLandmarkMode(FaceDetectorOptions.LANDMARK_MODE_ALL)
                .setClassificationMode(FaceDetectorOptions.CLASSIFICATION_MODE_ALL)
                .build();

// Real-time contour detection
FaceDetectorOptions realTimeOpts =
        new FaceDetectorOptions.Builder()
                .setContourMode(FaceDetectorOptions.CONTOUR_MODE_ALL)
                .build();FaceDetectionActivity.java

2. 入力画像を準備する

画像内の顔を検出するには、Bitmap、media.Image、ByteBuffer、バイト配列、またはデバイス上のファイルから InputImage オブジェクトを作成します。次に、InputImage オブジェクトを FaceDetector の process メソッドに渡します。

顔検出には、480x360 ピクセル以上の画像を使用する必要があります。リアルタイムで顔を検出している場合、この最小解像度でフレームをキャプチャすると、レイテンシを短縮できます。

さまざまなソースから InputImage オブジェクトを作成できます。各ソースは次のとおりです。

`media.Image` の使用

media.Image オブジェクトから InputImage オブジェクトを作成するには（デバイスのカメラから画像をキャプチャする場合など）、media.Image オブジェクトと画像の回転を InputImage.fromMediaImage() に渡します。

CameraX ライブラリを使用する場合は、OnImageCapturedListener クラスと ImageAnalysis.Analyzer クラスによって回転値が計算されます。

Kotlin

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) {
        Image mediaImage = imageProxy.getImage();
        if (mediaImage != null) {
          InputImage image =
                InputImage.fromMediaImage(mediaImage, imageProxy.getImageInfo().getRotationDegrees());
          // Pass image to an ML Kit Vision API
          // ...
        }
    }
}

画像の回転角度を取得するカメラライブラリを使用しない場合は、デバイスの回転角度とデバイス内のカメラセンサーの向きから計算できます。

Kotlin

private val ORIENTATIONS = SparseIntArray()

init {
    ORIENTATIONS.append(Surface.ROTATION_0, 0)
    ORIENTATIONS.append(Surface.ROTATION_90, 90)
    ORIENTATIONS.append(Surface.ROTATION_180, 180)
    ORIENTATIONS.append(Surface.ROTATION_270, 270)
}

/**
 * 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, isFrontFacing: Boolean): 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)

    // Get the device's sensor orientation.
    val cameraManager = activity.getSystemService(CAMERA_SERVICE) as CameraManager
    val sensorOrientation = cameraManager
            .getCameraCharacteristics(cameraId)
            .get(CameraCharacteristics.SENSOR_ORIENTATION)!!

    if (isFrontFacing) {
        rotationCompensation = (sensorOrientation + rotationCompensation) % 360
    } else { // back-facing
        rotationCompensation = (sensorOrientation - rotationCompensation + 360) % 360
    }
    return rotationCompensation
}MLKitVisionImage.kt

Java

private static final SparseIntArray ORIENTATIONS = new SparseIntArray();
static {
    ORIENTATIONS.append(Surface.ROTATION_0, 0);
    ORIENTATIONS.append(Surface.ROTATION_90, 90);
    ORIENTATIONS.append(Surface.ROTATION_180, 180);
    ORIENTATIONS.append(Surface.ROTATION_270, 270);
}

/**
 * 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, boolean isFrontFacing)
        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);

    // Get the device's sensor orientation.
    CameraManager cameraManager = (CameraManager) activity.getSystemService(CAMERA_SERVICE);
    int sensorOrientation = cameraManager
            .getCameraCharacteristics(cameraId)
            .get(CameraCharacteristics.SENSOR_ORIENTATION);

    if (isFrontFacing) {
        rotationCompensation = (sensorOrientation + rotationCompensation) % 360;
    } else { // back-facing
        rotationCompensation = (sensorOrientation - rotationCompensation + 360) % 360;
    }
    return rotationCompensation;
}

次に、media.Image オブジェクトと回転角度値を InputImage.fromMediaImage() に渡します。

Kotlin

val image = InputImage.fromMediaImage(mediaImage, rotation)MLKitVisionImage.kt

Java

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

ファイル URI の使用

ファイルの URI から InputImage オブジェクトを作成するには、アプリコンテキストとファイルの URI を InputImage.fromFilePath() に渡します。これは、ACTION_GET_CONTENT インテントを使用して、ギャラリーアプリから画像を選択するようにユーザーに促すときに便利です。

Kotlin

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

Java

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

`ByteBuffer` または `ByteArray` の使用

ByteBuffer または ByteArray から InputImage オブジェクトを作成するには、media.Image 入力について上記のように、まず画像の回転角度を計算します。次に、画像の高さ、幅、カラーエンコード形式、回転角度とともに、バッファまたは配列を含む InputImage オブジェクトを作成します。

Kotlin

val image = InputImage.fromByteBuffer(
        byteBuffer,
        /* image width */ 480,
        /* image height */ 360,
        rotationDegrees,
        InputImage.IMAGE_FORMAT_NV21 // or IMAGE_FORMAT_YV12
)MLKitVisionImage.kt
// Or:
val image = InputImage.fromByteArray(
        byteArray,
        /* image width */ 480,
        /* image height */ 360,
        rotationDegrees,
        InputImage.IMAGE_FORMAT_NV21 // or IMAGE_FORMAT_YV12
)
MLKitVisionImage.kt

Java

InputImage image = InputImage.fromByteBuffer(byteBuffer,
        /* image width */ 480,
        /* image height */ 360,
        rotationDegrees,
        InputImage.IMAGE_FORMAT_NV21 // or IMAGE_FORMAT_YV12
);MLKitVisionImage.java
// Or:
InputImage image = InputImage.fromByteArray(
        byteArray,
        /* image width */480,
        /* image height */360,
        rotation,
        InputImage.IMAGE_FORMAT_NV21 // or IMAGE_FORMAT_YV12
);MLKitVisionImage.java

`Bitmap` の使用

Bitmap オブジェクトから InputImage オブジェクトを作成するには、次の宣言を行います。

Kotlin

val image = InputImage.fromBitmap(bitmap, 0)MLKitVisionImage.kt

Java

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

画像は Bitmap オブジェクトと回転角度で表されます。

3. FaceDetector のインスタンスを取得する

Kotlin

val detector = FaceDetection.getClient(options)
// Or, to use the default option:
// val detector = FaceDetection.getClient();FaceDetectionActivity.kt

Java

FaceDetector detector = FaceDetection.getClient(options);
// Or use the default options:
// FaceDetector detector = FaceDetection.getClient();FaceDetectionActivity.java

4. 画像を処理する

画像を process メソッドに渡します。

Kotlin

val result = detector.process(image)
        .addOnSuccessListener { faces ->
            // Task completed successfully
            // ...
        }
        .addOnFailureListener { e ->
            // Task failed with an exception
            // ...
        }FaceDetectionActivity.kt

Java

Task<List<Face>> result =
        detector.process(image)
                .addOnSuccessListener(
                        new OnSuccessListener<List<Face>>() {
                            @Override
                            public void onSuccess(List<Face> faces) {
                                // Task completed successfully
                                // ...
                            }
                        })
                .addOnFailureListener(
                        new OnFailureListener() {
                            @Override
                            public void onFailure(@NonNull Exception e) {
                                // Task failed with an exception
                                // ...
                            }
                        });FaceDetectionActivity.java

注: CameraX API を使用している場合は、使用を終了したら ImageProxy を閉じるようにしてください。たとえば、process メソッドから返された Task に OnCompleteListener を追加します。例については、クイックスタートサンプルアプリの VisionProcessorBase クラスをご覧ください。

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

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

Kotlin

for (face in faces) {
    val bounds = face.boundingBox
    val rotY = face.headEulerAngleY // Head is rotated to the right rotY degrees
    val rotZ = face.headEulerAngleZ // Head is tilted sideways rotZ degrees

    // If landmark detection was enabled (mouth, ears, eyes, cheeks, and
    // nose available):
    val leftEar = face.getLandmark(FaceLandmark.LEFT_EAR)
    leftEar?.let {
        val leftEarPos = leftEar.position
    }

    // If contour detection was enabled:
    val leftEyeContour = face.getContour(FaceContour.LEFT_EYE)?.points
    val upperLipBottomContour = face.getContour(FaceContour.UPPER_LIP_BOTTOM)?.points

    // If classification was enabled:
    if (face.smilingProbability != null) {
        val smileProb = face.smilingProbability
    }
    if (face.rightEyeOpenProbability != null) {
        val rightEyeOpenProb = face.rightEyeOpenProbability
    }

    // If face tracking was enabled:
    if (face.trackingId != null) {
        val id = face.trackingId
    }
}FaceDetectionActivity.kt

Java

for (Face face : faces) {
    Rect bounds = face.getBoundingBox();
    float rotY = face.getHeadEulerAngleY();  // Head is rotated to the right rotY degrees
    float rotZ = face.getHeadEulerAngleZ();  // Head is tilted sideways rotZ degrees

    // If landmark detection was enabled (mouth, ears, eyes, cheeks, and
    // nose available):
    FaceLandmark leftEar = face.getLandmark(FaceLandmark.LEFT_EAR);
    if (leftEar != null) {
        PointF leftEarPos = leftEar.getPosition();
    }

    // If contour detection was enabled:
    List<PointF> leftEyeContour =
            face.getContour(FaceContour.LEFT_EYE).getPoints();
    List<PointF> upperLipBottomContour =
            face.getContour(FaceContour.UPPER_LIP_BOTTOM).getPoints();

    // If classification was enabled:
    if (face.getSmilingProbability() != null) {
        float smileProb = face.getSmilingProbability();
    }
    if (face.getRightEyeOpenProbability() != null) {
        float rightEyeOpenProb = face.getRightEyeOpenProbability();
    }

    // If face tracking was enabled:
    if (face.getTrackingId() != null) {
        int id = face.getTrackingId();
    }
}FaceDetectionActivity.java

顔の輪郭の例

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

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

リアルタイム顔検出

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

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

輪郭検出
ランドマーク検出
分類
ランドマークの検出と分類
輪郭検出とランドマーク検出
輪郭検出と分類
輪郭検出、ランドマーク検出、分類
FAST モードを有効にします（デフォルトで有効）。
より低い解像度で画像をキャプチャすることを検討してください。ただし、この API の画像サイズに関する要件にも留意してください。

Camera または camera2 API を使用する場合は、検出器への呼び出しをスロットルします。検出器の実行中に新しい動画フレームが使用可能になった場合は、そのフレームをドロップします。例については、クイックスタートサンプルアプリの VisionProcessorBase クラスをご覧ください。

CameraX API を使用する場合は、バックプレッシャー戦略がデフォルト値 ImageAnalysis.STRATEGY_KEEP_ONLY_LATEST に設定されていることを確認してください。これにより、一度に分析のために配信される画像は 1 つだけになります。アナライザがビジー状態のときにさらに画像が生成された場合、それらの画像は自動的に破棄され、配信キューには追加されません。分析中の画像が ImageProxy.close() を呼び出されて閉じられると、次に最新の画像が配信されます。

検出器の出力を使用して入力画像の上にグラフィックスをオーバーレイする場合は、まず ML Kit から検出結果を取得し、画像とオーバーレイを 1 つのステップでレンダリングします。これにより、ディスプレイサーフェスへのレンダリングは入力フレームごとに 1 回で済みます。例については、クイックスタートサンプルアプリの CameraSourcePreview クラスと GraphicOverlay クラスをご覧ください。

Camera2 API を使用する場合は、ImageFormat.YUV_420_888 形式で画像をキャプチャします。古い Camera API を使用する場合は、ImageFormat.NV21 形式で画像をキャプチャします。

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

試してみる

始める前に

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

1. 顔検出器を構成する

Kotlin

Java

2. 入力画像を準備する

media.Image の使用

Kotlin

Java

Kotlin

Java

Kotlin

Java

ファイル URI の使用

Kotlin

Java

ByteBuffer または ByteArray の使用

Kotlin

Java

Bitmap の使用

Kotlin

Java

3. FaceDetector のインスタンスを取得する

Kotlin

Java

4. 画像を処理する

Kotlin

Java

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

Kotlin

Java

顔の輪郭の例

リアルタイム顔検出

`media.Image` の使用

`ByteBuffer` または `ByteArray` の使用

`Bitmap` の使用