Como migrar para a biblioteca de cliente do Python v0.25.1

Na biblioteca de cliente do Python v0.25.1 estão incluídas algumas alterações significativas em relação à concepção das anteriores. Essas alterações podem ser resumidas da seguinte maneira:

Consolidação de módulos em menos tipos
Substituição de parâmetros não tipados por enumerações e classes fortemente tipadas.

Neste tópico, você encontra detalhes sobre as alterações que precisará fazer no código Python das bibliotecas de cliente da API Cloud Vision para usar a biblioteca de cliente do Python v0.25.1.

Como executar versões anteriores da biblioteca de cliente

Não é obrigatório atualizar a biblioteca de cliente do Python para a versão v0.25.1. Se você quiser continuar usando uma versão anterior da biblioteca de cliente do Python e não quiser migrar seu código, especifique a versão da biblioteca que o aplicativo usa. Para especificar uma determinada versão da biblioteca, edite o arquivo requirements.txt conforme mostrado:

google-cloud-vision==0.25

Módulos removidos

Os módulos a seguir foram removidos do pacote da biblioteca de cliente do Python v0.25.1.

google.cloud.vision.annotations
google.cloud.vision.batch
google.cloud.vision.client
google.cloud.vision.color
google.cloud.vision.crop_hint
google.cloud.vision.entity
google.cloud.vision.face
google.cloud.vision.feature
google.cloud.vision.geometry
google.cloud.vision.image
google.cloud.vision.likelihood
google.cloud.vision.safe_search
google.cloud.vision.text
google.cloud.vision.web

Alterações de código necessárias

Importações

Inclua o novo módulo google.cloud.vision.types para acessar os novos tipos na biblioteca de cliente do Python v0.25.1.

O módulo types contém as novas classes que são necessárias para criar solicitações, como types.Image.

from google.cloud import vision

Além disso, o novo módulo google.cloud.vision.enums contém as enumerações úteis para analisar e compreender as respostas da API, como enums.Likelihood.UNLIKELY e enums.FaceAnnotation.Landmark.Type.LEFT_EYE.

Criar um cliente

A classe Client foi substituída pela classe ImageAnnotatorClient. Substitua as referências à classe Client por ImageAnnotatorClient.

Versões anteriores das bibliotecas de cliente:

old_client = vision.Client()

Biblioteca de cliente do Python v0.25.1:

client = vision.ImageAnnotatorClient()

Como construir objetos que representam o conteúdo da imagem

Para identificar o conteúdo da imagem de um arquivo local, de um URI do Google Cloud Storage ou de um URI da Web, use a nova classe Image.

Como construir objetos que representam o conteúdo da imagem de um arquivo local

O exemplo a seguir mostra a nova maneira de representar o conteúdo da imagem em um arquivo local.

Versões anteriores das bibliotecas de cliente:

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

image = old_client.image(content=content)

Biblioteca de cliente do Python v0.25.1:

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

image = vision.Image(content=content)

Como construir objetos que representam o conteúdo da imagem de um URI

Veja no exemplo a seguir a nova maneira de representar o conteúdo da imagem de um URI do Google Cloud Storage ou da Web. uri é o URI para um arquivo de imagem no Google Cloud Storage ou na Web.

Versões anteriores das bibliotecas de cliente:

image = old_client.image(source_uri=uri)

Biblioteca de cliente do Python v0.25.1:

image = vision.Image()
image.source.image_uri = uri

Como fazer solicitações e processar respostas

Com a biblioteca de cliente do Python v.0.25.1, os métodos da API, como face_detection, pertencem ao objeto ImageAnnotatorClient, em oposição aos objetos Image.

Os valores retornados são diferentes de acordo com os vários métodos, conforme explicado abaixo.

Especificamente, os vértices da caixa delimitadora agora são armazenados em bounding_poly.vertices, e não em bounds.vertices. As coordenadas de cada vértice são armazenadas em vertex.x e vertex.y, e não em vertex.x_coordinate e vertex.y_coordinate.

A alteração da caixa delimitadora afeta face_detection, logo_detection, text_detection, document_text_detection e crop_hints.

Como fazer uma solicitação de detecção facial e processar a resposta

As probabilidades de emoção agora são retornadas como enumerações armazenadas em face.surprise_likelihood, e não em face.emotions.surprise. É possível recuperar os nomes dos rótulos de probabilidade por meio da importação de google.cloud.vision.enums.Likelihood.

Versões anteriores das bibliotecas de cliente:

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

image = old_client.image(content=content)

faces = image.detect_faces()

for face in faces:
    print('anger: {}'.format(face.emotions.anger))
    print('joy: {}'.format(face.emotions.joy))
    print('surprise: {}'.format(face.emotions.surprise))

    vertices = (['({},{})'.format(bound.x_coordinate, bound.y_coordinate)
                for bound in face.bounds.vertices])

    print('face bounds: {}'.format(','.join(vertices)))

Biblioteca de cliente do Python v0.25.1:

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

image = vision.Image(content=content)

response = client.face_detection(image=image)
faces = response.face_annotations

# Names of likelihood from google.cloud.vision.enums
likelihood_name = (
    "UNKNOWN",
    "VERY_UNLIKELY",
    "UNLIKELY",
    "POSSIBLE",
    "LIKELY",
    "VERY_LIKELY",
)
print("Faces:")

for face in faces:
    print(f"anger: {likelihood_name[face.anger_likelihood]}")
    print(f"joy: {likelihood_name[face.joy_likelihood]}")
    print(f"surprise: {likelihood_name[face.surprise_likelihood]}")

    vertices = [
        f"({vertex.x},{vertex.y})" for vertex in face.bounding_poly.vertices
    ]

    print("face bounds: {}".format(",".join(vertices)))

if response.error.message:
    raise Exception(
        "{}\nFor more info on error messages, check: "
        "https://cloud.google.com/apis/design/errors".format(response.error.message)
    )

Como fazer uma solicitação de detecção de rótulos e processar a resposta

Versões anteriores das bibliotecas de cliente:

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

image = old_client.image(content=content)

labels = image.detect_labels()

for label in labels:
    print(label.description)

Biblioteca de cliente do Python v0.25.1:

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

image = vision.Image(content=content)

response = client.label_detection(image=image)
labels = response.label_annotations
print("Labels:")

for label in labels:
    print(label.description)

if response.error.message:
    raise Exception(
        "{}\nFor more info on error messages, check: "
        "https://cloud.google.com/apis/design/errors".format(response.error.message)
    )

Como fazer uma solicitação de detecção de pontos de referência e processar a resposta

Versões anteriores das bibliotecas de cliente:

A latitude e a longitude dos locais de ponto de referência agora são armazenadas em location.lat_lng.latitude e location.lat_lng.longitude, e não em location.latitude e location.longitude.

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

image = old_client.image(content=content)

landmarks = image.detect_landmarks()

for landmark in landmarks:
    print(landmark.description, landmark.score)
    for location in landmark.locations:
        print('Latitude'.format(location.latitude))
        print('Longitude'.format(location.longitude))

Biblioteca de cliente do Python v0.25.1:

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

image = vision.Image(content=content)

response = client.landmark_detection(image=image)
landmarks = response.landmark_annotations
print("Landmarks:")

for landmark in landmarks:
    print(landmark.description)
    for location in landmark.locations:
        lat_lng = location.lat_lng
        print(f"Latitude {lat_lng.latitude}")
        print(f"Longitude {lat_lng.longitude}")

if response.error.message:
    raise Exception(
        "{}\nFor more info on error messages, check: "
        "https://cloud.google.com/apis/design/errors".format(response.error.message)
    )

Como fazer uma solicitação de detecção de logotipos e processar a resposta

Versões anteriores das bibliotecas de cliente:

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

image = old_client.image(content=content)

logos = image.detect_logos()

for logo in logos:
    print(logo.description, logo.score)

Biblioteca de cliente do Python v0.25.1:

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

image = vision.Image(content=content)

response = client.logo_detection(image=image)
logos = response.logo_annotations
print("Logos:")

for logo in logos:
    print(logo.description)

if response.error.message:
    raise Exception(
        "{}\nFor more info on error messages, check: "
        "https://cloud.google.com/apis/design/errors".format(response.error.message)
    )

Como fazer uma solicitação de detecção do SafeSearch e processar a resposta

Agora, as probabilidades do SafeSearch são retornadas como enumerações. É possível recuperar os nomes dos rótulos de probabilidade por meio da importação de google.cloud.vision.enums.Likelihood.

Versões anteriores das bibliotecas de cliente:

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

image = old_client.image(content=content)

safe = image.detect_safe_search()
print('Safe search:')
print('adult: {}'.format(safe.adult))
print('medical: {}'.format(safe.medical))
print('spoofed: {}'.format(safe.spoof))
print('violence: {}'.format(safe.violence))

Biblioteca de cliente do Python v0.25.1:

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

image = vision.Image(content=content)

response = client.safe_search_detection(image=image)
safe = response.safe_search_annotation

# Names of likelihood from google.cloud.vision.enums
likelihood_name = (
    "UNKNOWN",
    "VERY_UNLIKELY",
    "UNLIKELY",
    "POSSIBLE",
    "LIKELY",
    "VERY_LIKELY",
)
print("Safe search:")

print(f"adult: {likelihood_name[safe.adult]}")
print(f"medical: {likelihood_name[safe.medical]}")
print(f"spoofed: {likelihood_name[safe.spoof]}")
print(f"violence: {likelihood_name[safe.violence]}")
print(f"racy: {likelihood_name[safe.racy]}")

if response.error.message:
    raise Exception(
        "{}\nFor more info on error messages, check: "
        "https://cloud.google.com/apis/design/errors".format(response.error.message)
    )

Como fazer uma solicitação de detecção de texto e processar a resposta

Versões anteriores das bibliotecas de cliente:

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

image = old_client.image(content=content)

texts = image.detect_text()

for text in texts:
    print('\n"{}"'.format(text.description))

    vertices = (['({},{})'.format(bound.x_coordinate, bound.y_coordinate)
                for bound in text.bounds.vertices])

    print('bounds: {}'.format(','.join(vertices)))

Biblioteca de cliente do Python v0.25.1:

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

image = vision.Image(content=content)

response = client.text_detection(image=image)
texts = response.text_annotations
print("Texts:")

for text in texts:
    print(f'\n"{text.description}"')

    vertices = [
        f"({vertex.x},{vertex.y})" for vertex in text.bounding_poly.vertices
    ]

    print("bounds: {}".format(",".join(vertices)))

if response.error.message:
    raise Exception(
        "{}\nFor more info on error messages, check: "
        "https://cloud.google.com/apis/design/errors".format(response.error.message)
    )

Como fazer uma solicitação de detecção de texto de documentos e processar a resposta

Versões anteriores das bibliotecas de cliente:

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

image = old_client.image(content=content)

document = image.detect_full_text()

for page in document.pages:
    for block in page.blocks:
        block_words = []
        for paragraph in block.paragraphs:
            block_words.extend(paragraph.words)

        block_symbols = []
        for word in block_words:
            block_symbols.extend(word.symbols)

        block_text = ''
        for symbol in block_symbols:
            block_text = block_text + symbol.text

        print('Block Content: {}'.format(block_text))
        print('Block Bounds:\n {}'.format(block.bounding_box))

Biblioteca de cliente do Python v0.25.1:

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

image = vision.Image(content=content)

response = client.document_text_detection(image=image)

for page in response.full_text_annotation.pages:
    for block in page.blocks:
        print(f"\nBlock confidence: {block.confidence}\n")

        for paragraph in block.paragraphs:
            print("Paragraph confidence: {}".format(paragraph.confidence))

            for word in paragraph.words:
                word_text = "".join([symbol.text for symbol in word.symbols])
                print(
                    "Word text: {} (confidence: {})".format(
                        word_text, word.confidence
                    )
                )

                for symbol in word.symbols:
                    print(
                        "\tSymbol: {} (confidence: {})".format(
                            symbol.text, symbol.confidence
                        )
                    )

if response.error.message:
    raise Exception(
        "{}\nFor more info on error messages, check: "
        "https://cloud.google.com/apis/design/errors".format(response.error.message)
    )

Como fazer uma solicitação de propriedades de imagem e processar a resposta

As informações de cor dominante agora são armazenadas em props.dominant_colors.colors, e não em props.colors.

Versões anteriores das bibliotecas de cliente:

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

image = old_client.image(content=content)

props = image.detect_properties()

for color in props.colors:
    print('fraction: {}'.format(color.pixel_fraction))
    print('\tr: {}'.format(color.color.red))
    print('\tg: {}'.format(color.color.green))
    print('\tb: {}'.format(color.color.blue))
    print('\ta: {}'.format(color.color.alpha))

Biblioteca de cliente do Python v0.25.1:

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

image = vision.Image(content=content)

response = client.image_properties(image=image)
props = response.image_properties_annotation
print("Properties:")

for color in props.dominant_colors.colors:
    print(f"fraction: {color.pixel_fraction}")
    print(f"\tr: {color.color.red}")
    print(f"\tg: {color.color.green}")
    print(f"\tb: {color.color.blue}")
    print(f"\ta: {color.color.alpha}")

if response.error.message:
    raise Exception(
        "{}\nFor more info on error messages, check: "
        "https://cloud.google.com/apis/design/errors".format(response.error.message)
    )

Como fazer uma solicitação de detecção na Web e processar a resposta

Versões anteriores das bibliotecas de cliente:

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

image = old_client.image(content=content)

notes = image.detect_web()

if notes.pages_with_matching_images:
    print('\n{} Pages with matching images retrieved')

    for page in notes.pages_with_matching_images:
        print('Score : {}'.format(page.score))
        print('Url   : {}'.format(page.url))

if notes.full_matching_images:
    print ('\n{} Full Matches found: '.format(
           len(notes.full_matching_images)))

    for image in notes.full_matching_images:
        print('Score:  {}'.format(image.score))
        print('Url  : {}'.format(image.url))

if notes.partial_matching_images:
    print ('\n{} Partial Matches found: '.format(
           len(notes.partial_matching_images)))

    for image in notes.partial_matching_images:
        print('Score: {}'.format(image.score))
        print('Url  : {}'.format(image.url))

if notes.web_entities:
    print ('\n{} Web entities found: '.format(len(notes.web_entities)))

    for entity in notes.web_entities:
        print('Score      : {}'.format(entity.score))
        print('Description: {}'.format(entity.description))

Biblioteca de cliente do Python v0.25.1:

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

image = vision.Image(content=content)

response = client.web_detection(image=image)
annotations = response.web_detection

if annotations.best_guess_labels:
    for label in annotations.best_guess_labels:
        print(f"\nBest guess label: {label.label}")

if annotations.pages_with_matching_images:
    print(
        "\n{} Pages with matching images found:".format(
            len(annotations.pages_with_matching_images)
        )
    )

    for page in annotations.pages_with_matching_images:
        print(f"\n\tPage url   : {page.url}")

        if page.full_matching_images:
            print(
                "\t{} Full Matches found: ".format(len(page.full_matching_images))
            )

            for image in page.full_matching_images:
                print(f"\t\tImage url  : {image.url}")

        if page.partial_matching_images:
            print(
                "\t{} Partial Matches found: ".format(
                    len(page.partial_matching_images)
                )
            )

            for image in page.partial_matching_images:
                print(f"\t\tImage url  : {image.url}")

if annotations.web_entities:
    print("\n{} Web entities found: ".format(len(annotations.web_entities)))

    for entity in annotations.web_entities:
        print(f"\n\tScore      : {entity.score}")
        print(f"\tDescription: {entity.description}")

if annotations.visually_similar_images:
    print(
        "\n{} visually similar images found:\n".format(
            len(annotations.visually_similar_images)
        )
    )

    for image in annotations.visually_similar_images:
        print(f"\tImage url    : {image.url}")

if response.error.message:
    raise Exception(
        "{}\nFor more info on error messages, check: "
        "https://cloud.google.com/apis/design/errors".format(response.error.message)
    )

Como fazer uma solicitação de dicas de corte e processar a resposta

Versões anteriores das bibliotecas de cliente:

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

image = old_client.image(content=content)

hints = image.detect_crop_hints(aspect_ratios=[1.77])

for n, hint in enumerate(hints):
    print('\nCrop Hint: {}'.format(n))

    vertices = (['({},{})'.format(bound.x_coordinate, bound.y_coordinate)
                for bound in hint.bounds.vertices])

    print('bounds: {}'.format(','.join(vertices)))

Biblioteca de cliente do Python v0.25.1:

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

for n, hint in enumerate(hints):
    print(f"\nCrop Hint: {n}")

    vertices = [
        f"({vertex.x},{vertex.y})" for vertex in hint.bounding_poly.vertices
    ]

    print("bounds: {}".format(",".join(vertices)))

if response.error.message:
    raise Exception(
        "{}\nFor more info on error messages, check: "
        "https://cloud.google.com/apis/design/errors".format(response.error.message)
    )

As proporções precisam ser transmitidas por meio de CropHintsParams e ImageContext.