顔の検出

Video Intelligence API の顔検出機能は、動画内の顔を検出します。

Cloud Storage 内のファイルからの顔検出

Cloud Storage にあるファイル上の顔を検出するサンプルを以下に示します。

REST

動画アノテーションリクエストを送信する

POST リクエストを videos:annotate メソッドに送信する方法を以下に示します。この例では、Google Cloud CLI を使用してアクセス トークンを生成します。gcloud CLI のインストール手順については、Video Intelligence API のクイックスタートをご覧ください。

リクエストのデータを使用する前に、次のように置き換えます。

  • INPUT_URI: アノテーションを付けるファイルを含む Cloud Storage バケット（ファイル名を含む）。先頭は gs:// でなければなりません。
    例:「"inputUri":" gs://cloud-samples-data/video/googlework_short.mp4"」
  • PROJECT_NUMBER: Google Cloud プロジェクトの数値識別子。

HTTP メソッドと URL: 

POST https://videointelligence.googleapis.com/v1/videos:annotate

リクエストの本文（JSON）: 

{
    "inputUri": "INPUT_URI",
    "features": ["FACE_DETECTION"]
}

リクエストを送信するには、次のいずれかのオプションを展開します。

次のような JSON レスポンスが返されます。

レスポンスが成功すると、Video Intelligence API はオペレーションの name を返します。上記は、このようなレスポンスの例です。

  • PROJECT_NUMBER: プロジェクトの数
  • LOCATION_ID: アノテーションを実行する Cloud リージョン。サポート対象のクラウド リージョンは us-east1、us-west1、europe-west1、asia-east1 です。リージョンを指定しないと、動画ファイルの場所に基づいてリージョンが選択されます。
  • OPERATION_ID: リクエストに対して作成され、オペレーション開始時にレスポンスで指定された長時間実行オペレーションの ID（例: 12345...）

アノテーションの結果を取得する

オペレーションの結果を取得するには、次の例のように、動画アノテーションの呼び出しから返されたオペレーション名を使用して GET リクエストを行います。

リクエストのデータを使用する前に、次のように置き換えます。

  • OPERATION_NAME: Video Intelligence API によって返されるオペレーションの名前。オペレーション名の形式は projects/PROJECT_NUMBER/locations/LOCATION_ID/operations/OPERATION_ID です。
  • PROJECT_NUMBER: Google Cloud プロジェクトの数値識別子。

HTTP メソッドと URL: 

GET https://videointelligence.googleapis.com/v1/OPERATION_NAME

リクエストを送信するには、次のいずれかのオプションを展開します。

次のような JSON レスポンスが返されます。

顔検出アノテーションは、faceAnnotations リストとして返されます。注: doneフィールドは、値が True の場合にのみ返されます。オペレーションが完了していない場合、レスポンスには含まれません。

Java

Video Intelligence への認証を行うには、アプリケーションのデフォルト認証情報を設定します。 詳細については、ローカル開発環境の認証を設定するをご覧ください。


import com.google.api.gax.longrunning.OperationFuture;
import com.google.cloud.videointelligence.v1.AnnotateVideoProgress;
import com.google.cloud.videointelligence.v1.AnnotateVideoRequest;
import com.google.cloud.videointelligence.v1.AnnotateVideoResponse;
import com.google.cloud.videointelligence.v1.DetectedAttribute;
import com.google.cloud.videointelligence.v1.FaceDetectionAnnotation;
import com.google.cloud.videointelligence.v1.FaceDetectionConfig;
import com.google.cloud.videointelligence.v1.Feature;
import com.google.cloud.videointelligence.v1.TimestampedObject;
import com.google.cloud.videointelligence.v1.Track;
import com.google.cloud.videointelligence.v1.VideoAnnotationResults;
import com.google.cloud.videointelligence.v1.VideoContext;
import com.google.cloud.videointelligence.v1.VideoIntelligenceServiceClient;
import com.google.cloud.videointelligence.v1.VideoSegment;

public class DetectFacesGcs {

  public static void detectFacesGcs() throws Exception {
    // TODO(developer): Replace these variables before running the sample.
    String gcsUri = "gs://cloud-samples-data/video/googlework_short.mp4";
    detectFacesGcs(gcsUri);
  }

  // Detects faces in a video stored in Google Cloud Storage using the Cloud Video Intelligence API.
  public static void detectFacesGcs(String gcsUri) throws Exception {
    try (VideoIntelligenceServiceClient videoIntelligenceServiceClient =
        VideoIntelligenceServiceClient.create()) {

      FaceDetectionConfig faceDetectionConfig =
          FaceDetectionConfig.newBuilder()
              // Must set includeBoundingBoxes to true to get facial attributes.
              .setIncludeBoundingBoxes(true)
              .setIncludeAttributes(true)
              .build();
      VideoContext videoContext =
          VideoContext.newBuilder().setFaceDetectionConfig(faceDetectionConfig).build();

      AnnotateVideoRequest request =
          AnnotateVideoRequest.newBuilder()
              .setInputUri(gcsUri)
              .addFeatures(Feature.FACE_DETECTION)
              .setVideoContext(videoContext)
              .build();

      // Detects faces in a video
      OperationFuture<AnnotateVideoResponse, AnnotateVideoProgress> future =
          videoIntelligenceServiceClient.annotateVideoAsync(request);

      System.out.println("Waiting for operation to complete...");
      AnnotateVideoResponse response = future.get();

      // Gets annotations for video
      VideoAnnotationResults annotationResult = response.getAnnotationResultsList().get(0);

      // Annotations for list of people detected, tracked and recognized in video.
      for (FaceDetectionAnnotation faceDetectionAnnotation :
          annotationResult.getFaceDetectionAnnotationsList()) {
        System.out.print("Face detected:\n");
        for (Track track : faceDetectionAnnotation.getTracksList()) {
          VideoSegment segment = track.getSegment();
          System.out.printf(
              "\tStart: %d.%.0fs\n",
              segment.getStartTimeOffset().getSeconds(),
              segment.getStartTimeOffset().getNanos() / 1e6);
          System.out.printf(
              "\tEnd: %d.%.0fs\n",
              segment.getEndTimeOffset().getSeconds(), segment.getEndTimeOffset().getNanos() / 1e6);

          // Each segment includes timestamped objects that
          // include characteristics of the face detected.
          TimestampedObject firstTimestampedObject = track.getTimestampedObjects(0);

          for (DetectedAttribute attribute : firstTimestampedObject.getAttributesList()) {
            // Attributes include glasses, headwear, smiling, direction of gaze
            System.out.printf(
                "\tAttribute %s: %s %s\n",
                attribute.getName(), attribute.getValue(), attribute.getConfidence());
          }
        }
      }
    }
  }
}

Node.js

Video Intelligence への認証を行うには、アプリケーションのデフォルト認証情報を設定します。 詳細については、ローカル開発環境の認証を設定するをご覧ください。

/**
 * TODO(developer): Uncomment these variables before running the sample.
 */
// const gcsUri = 'GCS URI of the video to analyze, e.g. gs://my-bucket/my-video.mp4';

// Imports the Google Cloud Video Intelligence library + Node's fs library
const Video = require('@google-cloud/video-intelligence').v1;

// Creates a client
const video = new Video.VideoIntelligenceServiceClient();

async function detectFacesGCS() {
  const request = {
    inputUri: gcsUri,
    features: ['FACE_DETECTION'],
    videoContext: {
      faceDetectionConfig: {
        // Must set includeBoundingBoxes to true to get facial attributes.
        includeBoundingBoxes: true,
        includeAttributes: true,
      },
    },
  };
  // Detects faces in a video
  // We get the first result because we only process 1 video
  const [operation] = await video.annotateVideo(request);
  const results = await operation.promise();
  console.log('Waiting for operation to complete...');

  // Gets annotations for video
  const faceAnnotations =
    results[0].annotationResults[0].faceDetectionAnnotations;

  for (const {tracks} of faceAnnotations) {
    console.log('Face detected:');

    for (const {segment, timestampedObjects} of tracks) {
      console.log(
        `\tStart: ${segment.startTimeOffset.seconds}.` +
          `${(segment.startTimeOffset.nanos / 1e6).toFixed(0)}s`
      );
      console.log(
        `\tEnd: ${segment.endTimeOffset.seconds}.` +
          `${(segment.endTimeOffset.nanos / 1e6).toFixed(0)}s`
      );

      // Each segment includes timestamped objects that
      // include characteristics of the face detected.
      const [firstTimestapedObject] = timestampedObjects;

      for (const {name} of firstTimestapedObject.attributes) {
        // Attributes include 'glasses', 'headwear', 'smiling'.
        console.log(`\tAttribute: ${name}; `);
      }
    }
  }
}

detectFacesGCS();

Python

Video Intelligence への認証を行うには、アプリケーションのデフォルト認証情報を設定します。 詳細については、ローカル開発環境の認証を設定するをご覧ください。

from google.cloud import videointelligence_v1 as videointelligence


def detect_faces(gcs_uri="gs://YOUR_BUCKET_ID/path/to/your/video.mp4"):
    """Detects faces in a video."""

    client = videointelligence.VideoIntelligenceServiceClient()

    # Configure the request
    config = videointelligence.FaceDetectionConfig(
        include_bounding_boxes=True, include_attributes=True
    )
    context = videointelligence.VideoContext(face_detection_config=config)

    # Start the asynchronous request
    operation = client.annotate_video(
        request={
            "features": [videointelligence.Feature.FACE_DETECTION],
            "input_uri": gcs_uri,
            "video_context": context,
        }
    )

    print("\nProcessing video for face detection annotations.")
    result = operation.result(timeout=300)

    print("\nFinished processing.\n")

    # Retrieve the first result, because a single video was processed.
    annotation_result = result.annotation_results[0]

    for annotation in annotation_result.face_detection_annotations:
        print("Face detected:")
        for track in annotation.tracks:
            print(
                "Segment: {}s to {}s".format(
                    track.segment.start_time_offset.seconds
                    + track.segment.start_time_offset.microseconds / 1e6,
                    track.segment.end_time_offset.seconds
                    + track.segment.end_time_offset.microseconds / 1e6,
                )
            )

            # Each segment includes timestamped faces that include
            # characteristics of the face detected.
            # Grab the first timestamped face
            timestamped_object = track.timestamped_objects[0]
            box = timestamped_object.normalized_bounding_box
            print("Bounding box:")
            print("\tleft  : {}".format(box.left))
            print("\ttop   : {}".format(box.top))
            print("\tright : {}".format(box.right))
            print("\tbottom: {}".format(box.bottom))

            # Attributes include glasses, headwear, smiling, direction of gaze
            print("Attributes:")
            for attribute in timestamped_object.attributes:
                print(
                    "\t{}:{} {}".format(
                        attribute.name, attribute.value, attribute.confidence
                    )
                )

その他の言語

C#: クライアント ライブラリ ページの C# の設定手順を実行してから、.NET の Video Intelligence のリファレンス ドキュメントをご覧ください。

PHP: クライアント ライブラリ ページの PHP の設定手順を実行してから、PHP の Video Intelligence のリファレンス ドキュメントをご覧ください。

Ruby: クライアント ライブラリ ページの Ruby の設定手順を実行してから、Ruby の Video Intelligence のリファレンス ドキュメントをご覧ください。

ローカル ファイルからの顔検出

以下の例では、顔検出を使用して、お使いのローカルマシンからアップロードされた動画ファイルから動画内のエンティティを検索します。

REST

プロセス リクエストを送信する

ローカル動画ファイルで顔検出を行うには、動画ファイルの内容を Base64 形式でエンコードします。動画ファイルのコンテンツを Base64 形式でエンコードする方法については、Base64 エンコードをご覧ください。次に、videos:annotate メソッドに対する POST リクエストを行います。リクエストの inputContent フィールドに Base64 形式でエンコードされたコンテンツを格納し、FACE_DETECTION 機能を指定します。

以下は、curl を使用した POST リクエストの例です。この例では、Google Cloud CLI を使用してアクセス トークンを生成します。gcloud CLI のインストール手順については、Video Intelligence API のクイックスタートをご覧ください。

リクエストのデータを使用する前に、次のように置き換えます。

  • inputContent: バイナリ形式のローカル動画ファイル
    例:「AAAAGGZ0eXBtcDQyAAAAAGlzb21tcDQyAAGVYW1vb3YAAABsbXZozaAAAADWvhlR1r4 ズ QABX5ABCO の上 AAEAAAEAAAAAAA4...」
  • PROJECT_NUMBER: Google Cloud プロジェクトの数値識別子。

HTTP メソッドと URL: 

POST https://videointelligence.googleapis.com/v1/videos:annotate

リクエストの本文（JSON）: 

{
    inputContent: "Local video file in binary format",
    "features": ["FACE_DETECTION"]
}

リクエストを送信するには、次のいずれかのオプションを展開します。

次のような JSON レスポンスが返されます。

リクエストが成功すると、Video Intelligence がオペレーションの name を返します。上記はレスポンスの例です。project-number はプロジェクトの番号、operation-id はリクエストに対して作成された長時間実行オペレーションの ID です。

{ "name": "us-west1.17122464255125931980" }

結果を取得する

オペレーションの結果を取得するには、operations エンドポイントに GET リクエストを行い、オペレーションの名前を指定します。

リクエストのデータを使用する前に、次のように置き換えます。

  • OPERATION_NAME: Video Intelligence API によって返されるオペレーションの名前。オペレーション名の形式は projects/PROJECT_NUMBER/locations/LOCATION_ID/operations/OPERATION_ID です。
  • PROJECT_NUMBER: Google Cloud プロジェクトの数値識別子。

HTTP メソッドと URL: 

GET https://videointelligence.googleapis.com/v1/OPERATION_NAME

リクエストを送信するには、次のいずれかのオプションを展開します。

次のような JSON レスポンスが返されます。

Java

Video Intelligence への認証を行うには、アプリケーションのデフォルト認証情報を設定します。 詳細については、ローカル開発環境の認証を設定するをご覧ください。


import com.google.api.gax.longrunning.OperationFuture;
import com.google.cloud.videointelligence.v1.AnnotateVideoProgress;
import com.google.cloud.videointelligence.v1.AnnotateVideoRequest;
import com.google.cloud.videointelligence.v1.AnnotateVideoResponse;
import com.google.cloud.videointelligence.v1.DetectedAttribute;
import com.google.cloud.videointelligence.v1.FaceDetectionAnnotation;
import com.google.cloud.videointelligence.v1.FaceDetectionConfig;
import com.google.cloud.videointelligence.v1.Feature;
import com.google.cloud.videointelligence.v1.TimestampedObject;
import com.google.cloud.videointelligence.v1.Track;
import com.google.cloud.videointelligence.v1.VideoAnnotationResults;
import com.google.cloud.videointelligence.v1.VideoContext;
import com.google.cloud.videointelligence.v1.VideoIntelligenceServiceClient;
import com.google.cloud.videointelligence.v1.VideoSegment;
import com.google.protobuf.ByteString;
import java.nio.file.Files;
import java.nio.file.Path;
import java.nio.file.Paths;

public class DetectFaces {

  public static void detectFaces() throws Exception {
    // TODO(developer): Replace these variables before running the sample.
    String localFilePath = "resources/googlework_short.mp4";
    detectFaces(localFilePath);
  }

  // Detects faces in a video stored in a local file using the Cloud Video Intelligence API.
  public static void detectFaces(String localFilePath) throws Exception {
    try (VideoIntelligenceServiceClient videoIntelligenceServiceClient =
        VideoIntelligenceServiceClient.create()) {
      // Reads a local video file and converts it to base64.
      Path path = Paths.get(localFilePath);
      byte[] data = Files.readAllBytes(path);
      ByteString inputContent = ByteString.copyFrom(data);

      FaceDetectionConfig faceDetectionConfig =
          FaceDetectionConfig.newBuilder()
              // Must set includeBoundingBoxes to true to get facial attributes.
              .setIncludeBoundingBoxes(true)
              .setIncludeAttributes(true)
              .build();
      VideoContext videoContext =
          VideoContext.newBuilder().setFaceDetectionConfig(faceDetectionConfig).build();

      AnnotateVideoRequest request =
          AnnotateVideoRequest.newBuilder()
              .setInputContent(inputContent)
              .addFeatures(Feature.FACE_DETECTION)
              .setVideoContext(videoContext)
              .build();

      // Detects faces in a video
      OperationFuture<AnnotateVideoResponse, AnnotateVideoProgress> future =
          videoIntelligenceServiceClient.annotateVideoAsync(request);

      System.out.println("Waiting for operation to complete...");
      AnnotateVideoResponse response = future.get();

      // Gets annotations for video
      VideoAnnotationResults annotationResult = response.getAnnotationResultsList().get(0);

      // Annotations for list of faces detected, tracked and recognized in video.
      for (FaceDetectionAnnotation faceDetectionAnnotation :
          annotationResult.getFaceDetectionAnnotationsList()) {
        System.out.print("Face detected:\n");
        for (Track track : faceDetectionAnnotation.getTracksList()) {
          VideoSegment segment = track.getSegment();
          System.out.printf(
              "\tStart: %d.%.0fs\n",
              segment.getStartTimeOffset().getSeconds(),
              segment.getStartTimeOffset().getNanos() / 1e6);
          System.out.printf(
              "\tEnd: %d.%.0fs\n",
              segment.getEndTimeOffset().getSeconds(), segment.getEndTimeOffset().getNanos() / 1e6);

          // Each segment includes timestamped objects that
          // include characteristics of the face detected.
          TimestampedObject firstTimestampedObject = track.getTimestampedObjects(0);

          for (DetectedAttribute attribute : firstTimestampedObject.getAttributesList()) {
            // Attributes include glasses, headwear, smiling, direction of gaze
            System.out.printf(
                "\tAttribute %s: %s %s\n",
                attribute.getName(), attribute.getValue(), attribute.getConfidence());
          }
        }
      }
    }
  }
}

Node.js

Video Intelligence への認証を行うには、アプリケーションのデフォルト認証情報を設定します。 詳細については、ローカル開発環境の認証を設定するをご覧ください。

/**
 * TODO(developer): Uncomment these variables before running the sample.
 */
// const path = 'Local file to analyze, e.g. ./my-file.mp4';

// Imports the Google Cloud Video Intelligence library + Node's fs library
const Video = require('@google-cloud/video-intelligence').v1;
const fs = require('fs');

// Creates a client
const video = new Video.VideoIntelligenceServiceClient();

// Reads a local video file and converts it to base64
const file = fs.readFileSync(path);
const inputContent = file.toString('base64');

async function detectFaces() {
  const request = {
    inputContent: inputContent,
    features: ['FACE_DETECTION'],
    videoContext: {
      faceDetectionConfig: {
        // Must set includeBoundingBoxes to true to get facial attributes.
        includeBoundingBoxes: true,
        includeAttributes: true,
      },
    },
  };
  // Detects faces in a video
  // We get the first result because we only process 1 video
  const [operation] = await video.annotateVideo(request);
  const results = await operation.promise();
  console.log('Waiting for operation to complete...');

  // Gets annotations for video
  const faceAnnotations =
    results[0].annotationResults[0].faceDetectionAnnotations;
  for (const {tracks} of faceAnnotations) {
    console.log('Face detected:');
    for (const {segment, timestampedObjects} of tracks) {
      console.log(
        `\tStart: ${segment.startTimeOffset.seconds}` +
          `.${(segment.startTimeOffset.nanos / 1e6).toFixed(0)}s`
      );
      console.log(
        `\tEnd: ${segment.endTimeOffset.seconds}.` +
          `${(segment.endTimeOffset.nanos / 1e6).toFixed(0)}s`
      );

      // Each segment includes timestamped objects that
      // include characteristics of the face detected.
      const [firstTimestapedObject] = timestampedObjects;

      for (const {name} of firstTimestapedObject.attributes) {
        // Attributes include 'glasses', 'headwear', 'smiling'.
        console.log(`\tAttribute: ${name}; `);
      }
    }
  }
}

detectFaces();

Python

Video Intelligence への認証を行うには、アプリケーションのデフォルト認証情報を設定します。 詳細については、ローカル開発環境の認証を設定するをご覧ください。

import io

from google.cloud import videointelligence_v1 as videointelligence


def detect_faces(local_file_path="path/to/your/video-file.mp4"):
    """Detects faces in a video from a local file."""

    client = videointelligence.VideoIntelligenceServiceClient()

    with io.open(local_file_path, "rb") as f:
        input_content = f.read()

    # Configure the request
    config = videointelligence.FaceDetectionConfig(
        include_bounding_boxes=True, include_attributes=True
    )
    context = videointelligence.VideoContext(face_detection_config=config)

    # Start the asynchronous request
    operation = client.annotate_video(
        request={
            "features": [videointelligence.Feature.FACE_DETECTION],
            "input_content": input_content,
            "video_context": context,
        }
    )

    print("\nProcessing video for face detection annotations.")
    result = operation.result(timeout=300)

    print("\nFinished processing.\n")

    # Retrieve the first result, because a single video was processed.
    annotation_result = result.annotation_results[0]

    for annotation in annotation_result.face_detection_annotations:
        print("Face detected:")
        for track in annotation.tracks:
            print(
                "Segment: {}s to {}s".format(
                    track.segment.start_time_offset.seconds
                    + track.segment.start_time_offset.microseconds / 1e6,
                    track.segment.end_time_offset.seconds
                    + track.segment.end_time_offset.microseconds / 1e6,
                )
            )

            # Each segment includes timestamped faces that include
            # characteristics of the face detected.
            # Grab the first timestamped face
            timestamped_object = track.timestamped_objects[0]
            box = timestamped_object.normalized_bounding_box
            print("Bounding box:")
            print("\tleft  : {}".format(box.left))
            print("\ttop   : {}".format(box.top))
            print("\tright : {}".format(box.right))
            print("\tbottom: {}".format(box.bottom))

            # Attributes include glasses, headwear, smiling, direction of gaze
            print("Attributes:")
            for attribute in timestamped_object.attributes:
                print(
                    "\t{}:{} {}".format(
                        attribute.name, attribute.value, attribute.confidence
                    )
                )

その他の言語

C#: クライアント ライブラリ ページの C# の設定手順を実行してから、.NET の Video Intelligence のリファレンス ドキュメントをご覧ください。

PHP: クライアント ライブラリ ページの PHP の設定手順を実行してから、PHP の Video Intelligence のリファレンス ドキュメントをご覧ください。

Ruby: クライアント ライブラリ ページの Ruby の設定手順を実行してから、Ruby の Video Intelligence のリファレンス ドキュメントをご覧ください。