Tutoriel sur l'outil de suggestions de recadrage

Public

L'objectif de ce tutoriel est de vous aider à développer des applications à l'aide de la fonctionnalité Crop Hints (suggestions de recadrage) de l'API Cloud Vision. Nous partons du principe que vous maîtrisez les constructions et les techniques de programmation de base. Cependant, même si vous débutez dans la programmation, vous devriez pouvoir suivre et exécuter ce tutoriel sans difficulté, puis utiliser la documentation de référence de l'API Cloud Vision pour créer des applications de base.

Ce tutoriel décrit une application de l'API Vision montrant comment faire appel à cette API pour utiliser la fonctionnalité de suggestions de recadrage.

Prérequis

• Configurez un projet d'API Cloud Vision dans la console Google Cloud Platform.

• Configurez votre environnement pour utiliser les identifiants par défaut de l'application.

Python

• Installez Python.
• Installez pip.
• Installez la bibliothèque cliente Google Cloud.
• Installez Python Imaging Library (bibliothèque de traitement d'images Python)

Aperçu

Ce tutoriel présente une application de base de l'API Vision qui utilise une requête Crop Hints. L'image à traiter peut être fournie via un URI Google Cloud Storage (emplacement du bucket Cloud Storage) ou intégrée à la requête. Une réponse Crop Hints réussie renvoie les coordonnées d'une zone de découpage autour de l'objet ou du visage dominant dans l'image.

Intégralité du code

Lors de la lecture du code, nous vous recommandons de vous reporter également la documentation de référence de l'API Cloud Vision pour Python.

vision/cloud-client/crop_hints/crop_hints.py

Afficher sur GitHub

import argparse
import io

from google.cloud import vision
from google.cloud.vision import types
from PIL import Image, ImageDraw

def get_crop_hint(path):
    """Detect crop hints on a single image and return the first result."""
    client = vision.ImageAnnotatorClient()

    with io.open(path, 'rb') as image_file:
        content = image_file.read()

    image = types.Image(content=content)

    crop_hints_params = types.CropHintsParams(aspect_ratios=[1.77])
    image_context = types.ImageContext(crop_hints_params=crop_hints_params)

    response = client.crop_hints(image=image, image_context=image_context)
    hints = response.crop_hints_annotation.crop_hints

    # Get bounds for the first crop hint using an aspect ratio of 1.77.
    vertices = hints[0].bounding_poly.vertices

    return vertices

def draw_hint(image_file):
    """Draw a border around the image using the hints in the vector list."""
    vects = get_crop_hint(image_file)

    im = Image.open(image_file)
    draw = ImageDraw.Draw(im)
    draw.polygon([
        vects[0].x, vects[0].y,
        vects[1].x, vects[1].y,
        vects[2].x, vects[2].y,
        vects[3].x, vects[3].y], None, 'red')
    im.save('output-hint.jpg', 'JPEG')
    print('Saved new image to output-crop.jpg')

def crop_to_hint(image_file):
    """Crop the image using the hints in the vector list."""
    vects = get_crop_hint(image_file)

    im = Image.open(image_file)
    im2 = im.crop([vects[0].x, vects[0].y,
                  vects[2].x - 1, vects[2].y - 1])
    im2.save('output-crop.jpg', 'JPEG')
    print('Saved new image to output-crop.jpg')

if __name__ == '__main__':
    parser = argparse.ArgumentParser()
    parser.add_argument('image_file', help='The image you\'d like to crop.')
    parser.add_argument('mode', help='Set to "crop" or "draw".')
    args = parser.parse_args()

    parser = argparse.ArgumentParser()

    if args.mode == 'crop':
        crop_to_hint(args.image_file)
    elif args.mode == 'draw':
        draw_hint(args.image_file)

En détail

Importer des bibliothèques

vision/cloud-client/crop_hints/crop_hints.py

Afficher sur GitHub

import argparse
import io

from google.cloud import vision
from google.cloud.vision import types
from PIL import Image, ImageDraw

Nous importons des bibliothèques standards :

• argparse pour permettre à l'application d'accepter de noms de fichiers comme arguments en entrée ;
• io pour les E/S de fichier.

Autres importations :

• la classe ImageAnnotatorClient de la bibliothèque google.cloud.vision pour accéder à l'API Vision ;
• le module types de la bibliothèque google.cloud.vision pour la construction de requêtes ;
• les modules Image et ImageDraw de la bibliothèque de traitement d'images Python Imaging Library (PIL) pour tracer une zone de recadrage sur l'image d'entrée.

Exécuter l'application

vision/cloud-client/crop_hints/crop_hints.py

Afficher sur GitHub

parser = argparse.ArgumentParser()
parser.add_argument('image_file', help='The image you\'d like to crop.')
parser.add_argument('mode', help='Set to "crop" or "draw".')
args = parser.parse_args()

parser = argparse.ArgumentParser()

if args.mode == 'crop':
    crop_to_hint(args.image_file)
elif args.mode == 'draw':
    draw_hint(args.image_file)

Ici, nous analysons simplement l'argument transmis qui spécifie le nom de fichier de l'image locale et nous le transmettons à une fonction pour recadrer l'image ou tracer la zone de recadrage suggérée.

S'authentifier dans l'API

Avant de communiquer avec le service de l'API Vision, 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 bibliothèque cliente tente d'obtenir les identifiants de la variable d'environnement GOOGLE_APPLICATION_CREDENTIALS, laquelle doit être définie de manière à pointer sur le fichier de clé JSON de votre compte de service (consultez la section Configurer un compte de service pour en savoir plus).

Obtenir des annotations de suggestions de recadrage pour l’image

Maintenant que la bibliothèque cliente Vision est authentifiée, nous pouvons accéder au service en appelant la méthode crop_hints de l'instance ImageAnnotatorClient. Le format de la sortie est spécifié dans un objet ImageContext. Si plusieurs formats sont transmis, plusieurs suggestions de recadrage sont renvoyées, une pour chaque format.

vision/cloud-client/crop_hints/crop_hints.py

Afficher sur GitHub

"""Detect crop hints on a single image and return the first result."""
client = vision.ImageAnnotatorClient()

with io.open(path, 'rb') as image_file:
    content = image_file.read()

image = types.Image(content=content)

crop_hints_params = types.CropHintsParams(aspect_ratios=[1.77])
image_context = types.ImageContext(crop_hints_params=crop_hints_params)

response = client.crop_hints(image=image, image_context=image_context)
hints = response.crop_hints_annotation.crop_hints

# Get bounds for the first crop hint using an aspect ratio of 1.77.
vertices = hints[0].bounding_poly.vertices

La bibliothèque cliente encapsule les informations sur les requêtes adressées à l'API et sur les réponses obtenues. Voir la documentation de référence de l'API Vision pour obtenir des informations complètes sur la structure d'une requête

Utiliser la réponse pour recadrer ou dessiner la zone de recadrage suggérée

Une fois l'opération terminée, la réponse de l'API contient les coordonnées de la zone de recadrage d'un ou plusieurs cropHints. La méthode draw_hint trace des lignes autour de la zone de recadrage CropHints, puis écrit l'image dans un fichier output-hint.jpg.

vision/cloud-client/crop_hints/crop_hints.py

Afficher sur GitHub

vects = get_crop_hint(image_file)

im = Image.open(image_file)
draw = ImageDraw.Draw(im)
draw.polygon([
    vects[0].x, vects[0].y,
    vects[1].x, vects[1].y,
    vects[2].x, vects[2].y,
    vects[3].x, vects[3].y], None, 'red')
im.save('output-hint.jpg', 'JPEG')
print('Saved new image to output-crop.jpg')

La méthode crop_to_hint recadre l'image en fonction de la zone de recadrage suggérée.

vision/cloud-client/crop_hints/crop_hints.py

Afficher sur GitHub

vects = get_crop_hint(image_file)

im = Image.open(image_file)
im2 = im.crop([vects[0].x, vects[0].y,
              vects[2].x - 1, vects[2].y - 1])
im2.save('output-crop.jpg', 'JPEG')
print('Saved new image to output-crop.jpg')

Exécuter l'application

Pour exécuter l'application, vous pouvez télécharger ce fichier cat.jpg (vous devrez peut-être cliquer avec le bouton droit de la souris sur le lien), puis transmettre l'emplacement du fichier téléchargé sur votre machine local à l'application de tutoriel (crop_hints.py).

Voici la commande Python, suivie de la sortie de la console, qui affiche la réponse JSON cropHintsAnnotation. Cette réponse contient les coordonnées de la zone de recadrage cropHints. Nous avons demandé une zone de recadrage avec un ratio largeur/hauteur de 1,77. Les coordonnées x,y renvoyées en haut à gauche et en bas à droite du rectangle de recadrage sont 0,336, 1100,967.

python crop_hints.py cat.jpeg crop

Remarque : Les valeurs des coordonnées nulles sont ignorées. Lorsque l'API détecte une valeur de coordonnée ("x" ou "y") égale à 0, cette coordonnée est ignorée dans la réponse JSON. Ainsi, une réponse qui contient les coordonnées de la zone d'intérêt ("boundingpoly") autour de l'ensemble de l'image s'affiche au format
[{},{"x": 100},{"x": 100,"y": 100},{"y": 100}] pour une image de 100 pixels par 100 pixels. Pour en savoir plus, consultez la documentation de référence de l'API.

{
 "responses": [
  {
   "cropHintsAnnotation": {
    "cropHints": [
     {
      "boundingPoly": {
       "vertices": [
        {
         "y": 336
        },
        {
         "x": 1100,
         "y": 336
        },
        {
         "x": 1100,
         "y": 967
        },
        {
         "y": 967
        }
       ]
      },
      "confidence": 0.79999995,
      "importanceFraction": 0.69
     }
    ]
   }
  }
 ]
}

Voici l'image recadrée.

Félicitations ! Vous avez exécuté l'API Crop Hints de Cloud Vision pour renvoyer les coordonnées optimisées de la zone de recadrage autour de l'objet dominant détecté dans l'image !