Tutorial de detecção de marcadores

Público-alvo

Este tutorial foi criado para ajudar você a começar a explorar e desenvolver aplicativos com a API Video Intelligence. Para isso, você precisa ter conhecimentos básicos de Python. Você consegue acompanhar se tiver algum conhecimento de programação. Após concluir este tutorial, você estará apto a usar a Documentação de referência para criar aplicativos básicos.

Neste tutorial, vamos trabalhar com um aplicativo da Video Intelligence API usando o código Python. O objetivo aqui não é explicar as bibliotecas de cliente Python, mas explicar como fazer chamadas para a API Video Intelligence usando o recurso de detecção de rótulos de vídeo. Aplicativos em Java e Node.js são basicamente similares.

Se você está procurando um exemplo somente de código ou em outra linguagem, consulte o guia de instruções complementar.

Pré-requisitos

Este tutorial tem os seguintes pré-requisitos:

a configuração de um projeto da API Video Intelligence no console do Google Cloud;
configuração do ambiente usando uma conta de serviço e o Application Default Credentials;
conhecimentos básicos sobre programação em Python;
Você configurou o ambiente para desenvolvedores do Python.
É recomendável ter a versão mais recente do Python, pip, e virtualenv instalados no seu sistema. Para ver instruções, consulte o Guia de configuração do ambiente de desenvolvimento do Python para o Google Cloud Platform.
instalação da biblioteca de cliente do Google Cloud.

Como fazer anotações em um vídeo usando a detecção de rótulos

Este tutorial é um passo a passo de um aplicativo básico da API Video, usando uma solicitação LABEL_DETECTION. Uma solicitação LABEL_DETECTION anota um vídeo com rótulos (ou "tags") selecionados com base no conteúdo da imagem. Por exemplo, um vídeo de um trem em um cruzamento produz marcadores como "trem", "transporte", "travessia da linha de trem".

Veja a seguir todo o código necessário para este tutorial. A maioria dos comentários foi removida desse código para destacar o quanto ele é breve. Em vez disso, os comentários serão feitos posteriormente à medida que analisarmos o código.

import argparse

from google.cloud import videointelligence

def analyze_labels(path):
    """Detects labels given a GCS path."""
    video_client = videointelligence.VideoIntelligenceServiceClient()
    features = [videointelligence.Feature.LABEL_DETECTION]
    operation = video_client.annotate_video(
        request={"features": features, "input_uri": path}
    )
    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.microseconds / 1e6
            )
            end_time = (
                segment.segment.end_time_offset.seconds
                + segment.segment.end_time_offset.microseconds / 1e6
            )
            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)

Esse aplicativo simples:

Importa as bibliotecas necessárias para executar o aplicativo.
Usa um arquivo de vídeo armazenado no URI do Cloud Storage como um argumento e transmita-o para a função main().
Recebe credenciais para executar o serviço da API Video Intelligence.
Cria uma solicitação de anotação de vídeo para enviar ao serviço de vídeo.
Envia a solicitação e retorna uma operação de longa duração.
Repete a operação de longa duração até o vídeo ser processado e retorna valores disponíveis.
Analisa a resposta do serviço e exibe a resposta para o usuário.

Importar bibliotecas

import argparse

from google.cloud import videointelligence

Algumas bibliotecas padrão são importadas: argparse para permitir que o aplicativo aceite nomes de arquivos de entrada como argumentos e sys para formatação de saída enquanto aguarda as respostas da API. O pacote time é importado para executar alguns loops de espera simples.

Ao usar a API Video Intelligence, você também precisará importar o google.cloud.videointelligence_v1 e a classe de enumeração correspondente, que contém o diretório das chamadas de API.

Execute o aplicativo

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)

Aqui, o argumento transmitido é analisado para o URI do Cloud Storage do nome de arquivo de vídeo e transmitido à função main().

Faça sua autenticação na API

Antes de iniciar a comunicação com o serviço da API Video Intelligence, autentique seu serviço usando as credenciais recebidas anteriormente. A maneira mais simples de receber credenciais em um aplicativo é usar o Application Default Credentials (ADC). No ADC, as credenciais são adquiridas no arquivo de ambiente GOOGLE_APPLICATION_CREDENTIALS por padrão. Ele precisa apontar para o arquivo da chave JSON da sua conta de serviço. É necessário configurar essa conta de serviço e o ambiente para usar o ADC no Guia de início rápido.

Crie a solicitação

video_client = videointelligence.VideoIntelligenceServiceClient()
features = [videointelligence.Feature.LABEL_DETECTION]
operation = video_client.annotate_video(
    request={"features": features, "input_uri": path}
)

Você pode criar uma solicitação para o serviço da API Video Intelligence agora que ele está pronto. As solicitações a essa API são fornecidas como objetos JSON. Consulte a Referência da Video Intelligence API para informações completas sobre a estrutura específica da solicitação.

Esse snippet de código executa as seguintes tarefas:

Cria o JSON de uma solicitação POST para o método annotate_video().
Injeta o local do Cloud Storage do nome de arquivo de vídeo transmitido na solicitação.
Indica que o método annotate deve executar LABEL_DETECTION.

Verifique a operação

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

Com a solicitação de operação existente, a repetição while é criada para verificar periodicamente o estado dessa operação. Depois que a operação indicar que é done, a resposta será analisada.

Analise a resposta

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.microseconds / 1e6
        )
        end_time = (
            segment.segment.end_time_offset.seconds
            + segment.segment.end_time_offset.microseconds / 1e6
        )
        positions = "{}s to {}s".format(start_time, end_time)
        confidence = segment.confidence
        print("\tSegment {}: {}".format(i, positions))
        print("\tConfidence: {}".format(confidence))
    print("\n")

Depois que a operação for concluída, a resposta conterá o resultado em um AnnotateVideoResponse, que consiste em uma lista de annotationResults, uma para cada vídeo enviado na solicitação. Como somente um vídeo foi enviado na solicitação, o primeiro segmentLabelAnnotations dos resultados é retirado, todos os rótulos em segmentLabelAnnotations são repetidos. Usando somente segmentLabelAnnotations, este tutorial exibe apenas anotações no nível de vídeo. Cada segment_label inclui uma descrição (segment_label.description), uma lista de categorias de entidade (segment_label.category_entities) e uma lista de trechos que identificam o horário de início/término das ocorrências de rótulo no vídeo (precisa ser um trecho que abrange todo o vídeo ou trecho de vídeo no caso de segment_label_annotations).

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

Como somente um vídeo foi enviado na solicitação, o primeiro description do primeiro resultado é exibido.

Execute o aplicativo

Para executar seu aplicativo, basta passar o URI do Cloud Storage de um vídeo:

$ python labels.py gs://YOUR_BUCKET/YOUR_OBJECT
Operation us-west1.4757250774497581229 started: 2020-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
...

Saída

Veja abaixo um exemplo de saída possível.

Processing video for label annotations:

Finished processing. Video label description: crowd Label category description: people Segment 0: 0.0s to 60.24s Confidence: 0.527720749378

Video label description: official Label category description: person Segment 0: 0.0s to 60.24s Confidence: 0.372822880745

Video label description: audience Label category description: people Segment 0: 0.0s to 60.24s Confidence: 0.501719772816

Video label description: news Segment 0: 0.0s to 60.24s Confidence: 0.867252230644

Video label description: people Label category description: person Segment 0: 0.0s to 60.24s Confidence: 0.46747264266

Video label description: politics Segment 0: 0.0s to 60.24s Confidence: 0.319397002459

Parabéns! Você executou uma tarefa de anotação usando a API Video Intelligence.