标签检测教程

受众

本教程旨在帮助您快速上手通过 Cloud Video Intelligence API 探索和开发应用。它专为熟悉基本编程的人设计,即使没有太多编程知识,您也应该能够按照说明操作。阅读完本教程后,您应该能够根据参考文档创建您自己的基本应用。

本教程介绍使用 Python 代码的 Video Intelligence API 应用。但我们的目的不是解说 Python 客户端库,而是说明如何调用 Video Intelligence API。Java 和 Node.js 应用基本相似。

如果您想要查看只含代码的示例或其他语言的示例,请查看配套的方法指南

前提条件

本教程有几个前提条件:

使用标签检测功能为视频添加注释

本教程介绍了一个使用 LABEL_DETECTION 请求的基本 Video API 应用。LABEL_DETECTION 请求会使用根据图像内容选择的标签(或“标记”)为视频添加注释。例如,如果某个视频中有一辆火车停在岔道口,则可能会产生“火车”、“运输”、“铁路岔道口”等标签。

我们首先来看看涉及的所有代码。请注意,我们从代码中删除了大多数注释,以向您展示它的简短程度。在解说代码的过程中,我们会提供更多注释。

import argparse

from google.cloud import videointelligence

def analyze_labels(path):
    """ Detects labels given a GCS path. """
    video_client = videointelligence.VideoIntelligenceServiceClient()
    features = [videointelligence.enums.Feature.LABEL_DETECTION]
    operation = video_client.annotate_video(path, features=features)
    print('\nProcessing video for label annotations:')

    result = operation.result(timeout=90)
    print('\nFinished processing.')

    segment_labels = result.annotation_results[0].segment_label_annotations
    for i, segment_label in enumerate(segment_labels):
        print('Video label description: {}'.format(
            segment_label.entity.description))
        for category_entity in segment_label.category_entities:
            print('\tLabel category description: {}'.format(
                category_entity.description))

        for i, segment in enumerate(segment_label.segments):
            start_time = (segment.segment.start_time_offset.seconds +
                          segment.segment.start_time_offset.nanos / 1e9)
            end_time = (segment.segment.end_time_offset.seconds +
                        segment.segment.end_time_offset.nanos / 1e9)
            positions = '{}s to {}s'.format(start_time, end_time)
            confidence = segment.confidence
            print('\tSegment {}: {}'.format(i, positions))
            print('\tConfidence: {}'.format(confidence))
        print('\n')

if __name__ == '__main__':
    parser = argparse.ArgumentParser(
        description=__doc__,
        formatter_class=argparse.RawDescriptionHelpFormatter)
    parser.add_argument('path', help='GCS file path for label detection.')
    args = parser.parse_args()

    analyze_labels(args.path)

这个简单的应用可执行以下任务:

  • 导入运行应用所需的库
  • 将 Google Cloud Storage URI 中存储的视频文件作为参数传递给 main() 函数
  • 获取凭据以运行 Video Intelligence API 服务
  • 创建要发送到视频服务的视频注释请求
  • 发送请求并返回一个长时间运行的操作
  • 轮询长时间运行的操作,直到视频处理完成并给出返回值
  • 解析服务的响应并将其显示给用户

我们将在下面更详细地介绍这些步骤。

导入库

import argparse

from google.cloud import videointelligence

我们导入一些标准库:argparse(以允许应用接受输入文件名作为参数)和 sys(用于在等待 API 响应时为输出设置格式)。我们还导入 time 来运行一些简单的等待循环。

为了使用 Cloud Video Intelligence API,我们还需要导入 google.cloud.videointelligence_v1 及其枚举类,其中包含了 API 调用的目录。

运行应用

parser = argparse.ArgumentParser(
    description=__doc__,
    formatter_class=argparse.RawDescriptionHelpFormatter)
parser.add_argument('path', help='GCS file path for label detection.')
args = parser.parse_args()

analyze_labels(args.path)

这里,我们所做的就是解析传递的视频文件名 Google Cloud Storage URI 参数,并将其传递给 main() 函数。

对 API 进行身份验证

与 Video Intelligence API 服务通信之前,您需要使用先前获得的凭据来对您的服务进行身份验证。在应用中,获取凭据的最简单方法是使用应用默认凭据 (ADC)。默认情况下,ADC 将尝试从 GOOGLE_APPLICATION_CREDENTIALS 环境文件获取凭据,该文件应设置为指向您的服务帐号的 JSON 密钥文件。(您应该已在快速入门中设置了您的服务帐号和环境以使用 ADC。)

构建请求

video_client = videointelligence.VideoIntelligenceServiceClient()
features = [videointelligence.enums.Feature.LABEL_DETECTION]
operation = video_client.annotate_video(path, features=features)

现在,Video Intelligence API 服务已准备就绪,我们可以构建要发送至该服务的请求。向 Cloud Video Intelligence API 发出的请求是作为 JSON 对象提供的。如需全面了解此类请求的具体结构,请参阅 Video Intelligence API 参考

此代码段执行以下任务:

  1. 为向 annotate_video() 方法发送的 POST 请求构建 JSON。
  2. 将传递的视频文件名所在的 Google Cloud Storage 位置注入请求。
  3. 指出 annotate 方法应执行 LABEL_DETECTION

检查操作

result = operation.result(timeout=90)
print('\nFinished processing.')

通过使用现有操作的请求,我们可以构建一个 while 循环,以定期检查该操作的状态。当操作表明其状态变为 done 后,我们可以终止循环并解析响应。

解析响应

segment_labels = result.annotation_results[0].segment_label_annotations
for i, segment_label in enumerate(segment_labels):
    print('Video label description: {}'.format(
        segment_label.entity.description))
    for category_entity in segment_label.category_entities:
        print('\tLabel category description: {}'.format(
            category_entity.description))

    for i, segment in enumerate(segment_label.segments):
        start_time = (segment.segment.start_time_offset.seconds +
                      segment.segment.start_time_offset.nanos / 1e9)
        end_time = (segment.segment.end_time_offset.seconds +
                    segment.segment.end_time_offset.nanos / 1e9)
        positions = '{}s to {}s'.format(start_time, end_time)
        confidence = segment.confidence
        print('\tSegment {}: {}'.format(i, positions))
        print('\tConfidence: {}'.format(confidence))
    print('\n')

操作完成后,响应将包含 AnnotateVideoResponse(其中包括一个 annotationResults 列表,在请求中发送的每个视频各有一个结果)中的结果。由于我们仅在请求中发送了一个视频,因此,我们选取这些结果的第一个 segmentLabelAnnotations。然后,我们可以循环遍历 segmentLabelAnnotations 中的所有标签。在本教程中,我们仅显示视频级注释。为标识视频级注释,我们从结果中拉取 segment_label_annotations 数据。每个片段标签注释都包含说明 (segment_label.description)、实体类别列表 (category_entity.description) 以及注释在片段中的位置(用相对于视频开头的开始时间和结束时间偏移量来表示)。

{
   "name":"us-west1.12089999971048628582",
   "metadata":{
      "@type":"type.googleapis.com/google.cloud.videointelligence.v1.AnnotateVideoProgress",
      "annotationProgress":[
         {
            "inputUri":"/cloud-ml-sandbox/video/chicago.mp4",
            "updateTime":"2017-01-31T01:49:52.498015Z",
            "startTime":"2017-01-31T01:49:43.056481Z"
         }
      ]
   },
   "done": true,
   "response":{
      "@type":"type.googleapis.com/google.cloud.videointelligence.v1.AnnotateVideoResponse",
      "annotationResults":[
         {
            "inputUri":"/cloud-ml-sandbox/video/chicago.mp4",
            "segmentLabelAnnotations": [
              {
                "entity": {
                  "entityId": "/m/01yrx",
                  "languageCode": "en-US"
                },
                "segments": [
                  {
                    "segment": {
                      "startTimeOffset": "0s",
                      "endTimeOffset": "14.833664s"
                    },
                    "confidence": 0.98509187
                  }
                ]
              },
               ...
            ]
         }
      ]
   }
}

由于我们在请求中只发送了一个视频,因此我们将选取第一个结果的第一个 description 并打印该 description

运行应用

要运行应用,只需向其传递视频的 Google Cloud Storage URI 即可:

$ python label_det.py gs://cloud-ml-sandbox/video/chicago.mp4
Operation us-west1.4757250774497581229 started: 2017-01-30T01:46:30.158989Z
Operation processing ...
The video has been successfully processed.

Video label description: urban area
        Label category description: city
        Segment 0: 0.0s to 38.752016s
        Confidence: 0.946980476379

Video label description: traffic
        Segment 0: 0.0s to 38.752016s
        Confidence: 0.94105899334

Video label description: vehicle
        Segment 0: 0.0s to 38.752016s
        Confidence: 0.919958174229
...
 

恭喜!您已使用 Cloud Video Intelligence API 执行了注释操作!