Didacticiel de détection de thèmes

Public

Ce tutoriel est conçu de manière à vous permettre de rapidement commencer à explorer et à développer des applications avec l'API Cloud Video Intelligence. Il s'adresse aux personnes ayant des connaissances de base en programmation. Si c'est votre cas, vous devriez être capable de le suivre, même sans avoir de connaissances avancées en programmation. Après avoir parcouru ce tutoriel, vous devriez être capable d'utiliser la documentation de référence pour créer vos propres applications de base.

Ce tutoriel vous présente une application de l'API Video Intelligence avec du code Python. Le but ici n'est pas de décrire les bibliothèques clientes Python, mais d'expliquer comment faire des appels à l'API Video Intelligence. Les applications en Java et Node.js sont similaires pour l'essentiel.

Si vous recherchez uniquement un exemple de code ou un exemple dans un autre langage, consultez le guide pratique associé.

Prérequis

Ce tutoriel a plusieurs prérequis :

Annoter une vidéo avec la détection de thèmes

Ce tutoriel vous présente une application de base de l'API Video à l'aide d'une requête LABEL_DETECTION. Une requête LABEL_DETECTION annote une vidéo avec des libellés (ou "tags") sélectionnés en fonction du contenu des images. Par exemple, la vidéo d'un train à un passage à niveau peut produire les libellés "train", "transport", "passage à niveau", etc.

Nous affichons d'abord l'ensemble du code. Notez que nous avons supprimé la plupart des commentaires de ce code afin de vous montrer à quel point il est court. Nous ajouterons des commentaires en parcourant le code.

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)

Cette application simple effectue les tâches suivantes :

  • Elle importe les bibliothèques nécessaires pour exécuter l'application.
  • Elle prend un fichier vidéo stocké dans l'URI Google Cloud Storage comme argument, et le transmet à la fonction main().
  • Elle obtient les identifiants permettant d'exécuter le service de l'API Video Intelligence.
  • Elle crée une requête d'annotation vidéo à destination du service vidéo.
  • Elle envoie la requête et renvoie une opération de longue durée.
  • Elle boucle sur l'opération de longue durée jusqu'à ce que la vidéo soit traitée et que les valeurs de retour soient disponibles.
  • Elle analyse la réponse pour le service et l'affiche à l'utilisateur.

Nous reviendrons plus en détail sur ces étapes ci-dessous.

Importer des bibliothèques

import argparse

from google.cloud import videointelligence

Nous importons des bibliothèques standards : argparse pour permettre à l'application d'accepter des noms de fichier comme arguments en entrée et sys pour formater le résultat en attendant les réponses de l'API. Nous importons également time pour exécuter des boucles d'attente simples.

Pour utiliser l'API Cloud Video Intelligence, nous devons également importer google.cloud.videointelligence_v1 et sa classe d'énumération. Celle-ci contient le répertoire de nos appels d'API.

Exécution de l'application

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)

Ici, nous analysons simplement l'argument transmis (nom du fichier vidéo) à l'URI Google Cloud Storage, et nous le transmettons à la fonction main().

S'authentifier dans l'API

Avant de communiquer avec le service de l'API Video Intelligence, vous devez authentifier votre service avec les identifiants précédemment acquis. Dans une application, le moyen le plus simple d'obtenir des identifiants est d'utiliser les identifiants par défaut de l'application. Par défaut, la stratégie des identifiants par défaut de l'application tente d'obtenir les identifiants à partir du fichier d'environnement GOOGLE_APPLICATION_CREDENTIALS. Ce fichier doit être défini pour pointer vers le fichier de clé JSON de votre compte de service. Vous devez avoir configuré votre compte de service et votre environnement pour utiliser cette stratégie dans QuickStart.

Construire la requête

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

Maintenant que le service de l'API Video Intelligence est prêt, nous pouvons construire une requête vers ce service. Les requêtes adressées à l'API Cloud Video Intelligence sont fournies en tant qu'objets JSON. Consultez le document de référence de l'API Video Intelligence pour obtenir des informations complètes sur la structure spécifique d'une telle requête.

Cet extrait de code effectue les tâches suivantes :

  1. Il construit le JSON pour une requête POST vers la méthode annotate_video().
  2. Il injecte dans la requête l'emplacement Google Cloud Storage du nom du fichier vidéo transmis.
  3. Il indique que la méthode annotate doit exécuter une requête LABEL_DETECTION.

Vérifier l'opération

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

La requête d'opération existante pour notre opération existante nous permet de construire une boucle while pour vérifier de manière périodique l'état de cette opération. Lorsque notre opération nous indique que l'état est done, nous sortons de la boucle. Nous pouvons alors analyser la réponse.

Analyser la réponse

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')

Une fois l'opération terminée, le résultat sera inclus dans une réponse AnnotateVideoResponse, qui consiste en une liste de résultats annotationResults (un pour chaque vidéo envoyée dans la requête). Comme nous n'avons envoyé qu'une seule vidéo dans la requête, nous prenons le premier résultat segmentLabelAnnotations de la liste. Nous effectuons ensuite une boucle sur tous les libellés dans segmentLabelAnnotations. Pour ce tutoriel, nous n'affichons que les annotations au niveau de la vidéo. Pour identifier celles-ci, nous extrayons les données segment_label_annotations des résultats. Chaque annotation de thème des séquences comprend une description (segment_label.description), la liste des catégories d'entités (category_entity.description) et leur emplacement dans les séquences (en fonction des décalages de temps de début et de fin à partir du début de la vidéo).

{
   "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
                  }
                ]
              },
               ...
            ]
         }
      ]
   }
}

Comme nous n'avons envoyé qu'une seule vidéo dans la requête, nous prenons la première description du premier résultat, et nous imprimons cette description.

Exécuter l'application

Pour exécuter l'application, transmettez-lui simplement l'URI Google Cloud Storage d'une vidéo :

$ 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
...
 

Félicitations ! Vous avez réalisé une annotation à l'aide de l'API Cloud Video Intelligence !