Tutorial sui suggerimenti di ritaglio

Pubblico

L'obiettivo di questo tutorial è aiutarti a sviluppare applicazioni utilizzando la funzionalità Suggerimenti di ritaglio dell'API Vision. Si presuppone che tu conosca i costrutti e le tecniche di programmazione di base. Tuttavia, anche se sei un programmatore principiante, dovresti essere in grado di seguire ed eseguire questo tutorial senza difficoltà, quindi utilizzare la documentazione di riferimento dell'API Vision per creare applicazioni di base.

Questo tutorial illustra un'applicazione dell'API Vision, mostrando come effettuare una chiamata all'API Vision per utilizzare la funzionalità Suggerimenti di ritaglio.

Prerequisiti

• Configura un progetto dell'API Vision nella Google Cloud console.

• Configura l'ambiente per l'utilizzo delle Credenziali predefinite dell'applicazione.

Python

• Installa Python.
• Installa pip.
• Installa la libreria client Google Cloud.
• Installa la libreria di imaging Python

Panoramica

Questo tutorial ti guida attraverso un'applicazione di base dell'API Vision che utilizza una richiesta Crop Hints. Puoi fornire l'immagine da elaborare tramite un URI Cloud Storage (posizione del bucket Cloud Storage) o incorporata nella richiesta. Una risposta Crop Hints riuscita restituisce le coordinate di un riquadro di delimitazione ritagliato attorno all'oggetto o al volto dominante nell'immagine.

Elenco del codice

Durante la lettura del codice, ti consigliamo di seguire la documentazione di riferimento dell'API Cloud Vision per Python .

import argparse

from typing import MutableSequence

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



def get_crop_hint(path: str) -> MutableSequence[vision.Vertex]:
    """Detect crop hints on a single image and return the first result.

    Args:
        path: path to the image file.

    Returns:
        The vertices for the bounding polygon.
    """
    client = vision.ImageAnnotatorClient()

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

    image = vision.Image(content=content)

    crop_hints_params = vision.CropHintsParams(aspect_ratios=[1.77])
    image_context = vision.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: str) -> None:
    """Draw a border around the image using the hints in the vector list.

    Args:
        image_file: path to the image file.
    """
    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-hint.jpg")


def crop_to_hint(image_file: str) -> None:
    """Crop the image using the hints in the vector list.

    Args:
        image_file: path to the image file.
    """
    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()

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

Un'occhiata più da vicino

Importazione delle librerie

import argparse

from typing import MutableSequence

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

Importiamo le librerie standard:

• argparse per consentire all'applicazione di accettare i nomi dei file di input come argomenti
• io per l'I/O di file

Altri import:

• La classe ImageAnnotatorClient all'interno della libreria google.cloud.vision per l'accesso all'API Vision.
• Il modulo types all'interno della libreria google.cloud.vision per la creazione di richieste
• I moduli Image e ImageDraw della Python Imaging Library (PIL). per disegnare un riquadro di delimitazione sull'immagine di input.

Esecuzione dell'applicazione

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

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

Qui, analizziamo semplicemente l'argomento passato che specifica il nome del file immagine locale e lo passiamo a una funzione per ritagliare l'immagine o disegnare il suggerimento.

Autenticazione nell'API

Prima di comunicare con il servizio API Vision, devi autenticare il servizio utilizzando le credenziali acquisite in precedenza. All'interno di un' applicazione, il modo più semplice per ottenere le credenziali è utilizzare le Credenziali predefinite dell'applicazione (ADC). Per impostazione predefinita, la libreria client tenterà di ottenere le credenziali dalla GOOGLE_APPLICATION_CREDENTIALS variabile di ambiente, che deve essere impostata in modo da puntare al file della chiave JSON dell'account di servizio (per ulteriori informazioni, consulta Configurare un account di servizio ).

Ottenere le annotazioni dei suggerimenti di ritaglio per l'immagine

Ora che la libreria client Vision è autenticata, possiamo accedere al servizio chiamando il metodo crop_hints dell'istanza ImageAnnotatorClient. Le proporzioni per l'output sono specificate in un oggetto ImageContext; se vengono passate più proporzioni, verranno restituiti più suggerimenti di ritaglio, uno per ogni proporzione.

"""Detect crop hints on a single image and return the first result.

Args:
    path: path to the image file.

Returns:
    The vertices for the bounding polygon.
"""
client = vision.ImageAnnotatorClient()

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

image = vision.Image(content=content)

crop_hints_params = vision.CropHintsParams(aspect_ratios=[1.77])
image_context = vision.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 libreria client incapsula i dettagli per le richieste e le risposte all'API. Per informazioni complete sulla struttura di una richiesta, consulta il Riferimento API Vision.

Utilizzare la risposta per ritagliare o disegnare il riquadro di delimitazione del suggerimento

Una volta completata l'operazione, la risposta dell'API conterrà le coordinate del riquadro di delimitazione di uno o più cropHint. Il metodo draw_hint disegna le linee attorno al riquadro di delimitazione CropHints, quindi scrive l'immagine in output-hint.jpg.

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-hint.jpg")

Il metodo crop_to_hint ritaglia l'immagine utilizzando il suggerimento di ritaglio suggerito.

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

Esecuzione dell'applicazione

Per eseguire l'applicazione, puoi scaricare questo cat.jpg file (potrebbe essere necessario fare clic con il tasto destro del mouse sul link), quindi passare la posizione in cui hai scaricato il file sul computer locale all'applicazione del tutorial (crop_hints.py).

Ecco il comando Python, seguito dall'output della console, che mostra la risposta JSON cropHintsAnnotation. Questa risposta include le coordinate del riquadro di delimitazione cropHints. Abbiamo richiesto un'area di ritaglio con proporzioni di larghezza/altezza pari a 1,77 e le coordinate x,y in alto a sinistra e in basso a destra del rettangolo di ritaglio restituite sono 0,336, 1100,967.

python crop_hints.py cat.jpeg crop

Note: Zero coordinate values omitted. When the API detects a coordinate ("x" or "y") value of 0, that coordinate is omitted in the JSON response. Thus, a response with a bounding poly around the entire image would be
[{},{"x": 100},{"x": 100,"y": 100},{"y": 100}] for an image that is 100 pixels by 100 pixels. For more information, see the API Reference documentation.

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

Ed ecco l'immagine ritagliata.

Complimenti! Hai eseguito l'API Suggerimenti di ritaglio di Cloud Vision per restituire le coordinate del riquadro di delimitazione ottimizzate attorno all'oggetto dominante rilevato nell'immagine.