搭配 Python 使用 Vision API

1. 總覽

開發人員可透過 Vision API，輕鬆將視覺偵測功能整合至應用程式，包括為圖片加上標籤、臉部和地標偵測、光學字元辨識 (OCR)，以及為煽情露骨內容加上標記。

在本教學課程中，您將著重於使用 Python 搭配 Vision API。

課程內容

如何設定環境
如何執行標籤偵測
如何執行文字偵測
如何執行地標偵測
如何執行臉部偵測
如何執行物件偵測

軟硬體需求

具備 Google Cloud 專案
Chrome 或 Firefox 瀏覽器
熟悉 Python

問卷調查

您會如何使用本教學課程？

僅閱讀

閱讀並完成練習

你對 Python 的使用體驗如何？

新手

中級

熟練

你對 Google Cloud 服務的體驗滿意嗎？

新手

中級

熟練

2. 設定和需求條件

自修實驗室環境設定

登入 Google Cloud 控制台，然後建立新專案或重複使用現有專案。如果沒有 Gmail 或 Google Workspace 帳戶，請先建立帳戶。

專案名稱是這個專案參與者的顯示名稱。這是 Google API 未使用的字元字串。你隨時可以更新。
專案 ID 在所有 Google Cloud 專案中都是不重複的，而且設定後即無法變更。Cloud 控制台會自動產生專屬字串，通常您不需要在意該字串為何。在大多數程式碼研究室中，您需要參照專案 ID (通常標示為 PROJECT_ID)。如果您不喜歡產生的 ID，可以產生另一個隨機 ID。你也可以嘗試使用自己的名稱，看看是否可用。完成這個步驟後就無法變更，且專案期間會維持不變。
請注意，有些 API 會使用第三個值，也就是「專案編號」。如要進一步瞭解這三種值，請參閱說明文件。

接著，您需要在 Cloud 控制台中啟用帳單，才能使用 Cloud 資源/API。完成這個程式碼研究室的費用不高，甚至可能完全免費。如要關閉資源，避免在本教學課程結束後繼續產生費用，請刪除您建立的資源或專案。Google Cloud 新使用者可參加價值$300 美元的免費試用計畫。

啟動 Cloud Shell

雖然您可以透過筆電遠端操作 Google Cloud，但在本程式碼研究室中，您將使用 Cloud Shell，這是 Cloud 中執行的指令列環境。

啟用 Cloud Shell

在 Cloud 控制台，點選「啟用 Cloud Shell」圖示。

如果您是首次啟動 Cloud Shell，系統會顯示中繼畫面，說明這個指令列環境。如果出現中繼畫面，請按一下「繼續」。

佈建並連至 Cloud Shell 預計只需要幾分鐘。

這部虛擬機器已載入所有必要的開發工具，並提供永久的 5 GB 主目錄，而且可在 Google Cloud 運作，大幅提升網路效能並強化驗證功能。本程式碼研究室幾乎所有工作都可在瀏覽器上完成。

連至 Cloud Shell 後，您應該會看到驗證已完成，專案也已設為獲派的專案 ID。

在 Cloud Shell 中執行下列指令，確認您已通過驗證：

gcloud auth list

指令輸出

 Credentialed Accounts
ACTIVE  ACCOUNT
*       <my_account>@<my_domain.com>

To set the active account, run:
    $ gcloud config set account `ACCOUNT`

在 Cloud Shell 中執行下列指令，確認 gcloud 指令知道您的專案：

gcloud config list project

指令輸出

[core]
project = <PROJECT_ID>

如未設定，請輸入下列指令手動設定專案：

gcloud config set project <PROJECT_ID>

指令輸出

Updated property [core/project].

3. 環境設定

如要開始使用 Vision API，請在 Cloud Shell 中執行下列指令來啟用 API：

gcloud services enable vision.googleapis.com

畫面應如下所示：

Operation "operations/..." finished successfully.

您現在可以使用 Vision API 了！

前往主目錄：

cd ~

建立 Python 虛擬環境，隔離依附元件：

virtualenv venv-vision

啟動虛擬環境：

source venv-vision/bin/activate

安裝 IPython 和 Vision API 用戶端程式庫：

pip install ipython google-cloud-vision

畫面應如下所示：

...
Installing collected packages: ..., ipython, google-cloud-vision
Successfully installed ... google-cloud-vision-3.4.0 ...

您現在可以使用 Vision API 用戶端程式庫了！

在接下來的步驟中，您會使用名為 IPython 的互動式 Python 解譯器，這個解譯器已在先前的步驟中安裝。在 Cloud Shell 中執行 ipython，啟動工作階段：

ipython

畫面應如下所示：

Python 3.9.2 (default, Feb 28 2021, 17:03:44)
Type 'copyright', 'credits' or 'license' for more information
IPython 8.12.0 -- An enhanced Interactive Python. Type '?' for help.

In [1]:

您已準備好提出第一個要求...

4. 執行標籤偵測

Vision API 的核心功能之一是識別圖片中的物件或實體，也就是標籤註解。標籤偵測功能可辨識一般物體、地點、活動、動物物種和產品等內容，Vision API 會接收輸入圖片，並傳回最有可能適用於該圖片的標籤。並傳回最相符的標籤，以及與圖片相符的信心分數。

在本範例中，您將對東京熱門地區世田谷的圖片 (由 Alex Knight 提供) 執行標籤偵測：

將下列程式碼複製到 IPython 工作階段：

from typing import Sequence

from google.cloud import vision


def analyze_image_from_uri(
    image_uri: str,
    feature_types: Sequence,
) -> vision.AnnotateImageResponse:
    client = vision.ImageAnnotatorClient()

    image = vision.Image()
    image.source.image_uri = image_uri
    features = [vision.Feature(type_=feature_type) for feature_type in feature_types]
    request = vision.AnnotateImageRequest(image=image, features=features)

    response = client.annotate_image(request=request)

    return response


def print_labels(response: vision.AnnotateImageResponse):
    print("=" * 80)
    for label in response.label_annotations:
        print(
            f"{label.score:4.0%}",
            f"{label.description:5}",
            sep=" | ",
        )

請花點時間研究程式碼，瞭解程式碼如何使用 annotate_image 用戶端程式庫方法，分析一組指定特徵的圖片。

使用 LABEL_DETECTION 功能傳送要求：

image_uri = "gs://cloud-samples-data/vision/label/setagaya.jpeg"
features = [vision.Feature.Type.LABEL_DETECTION]

response = analyze_image_from_uri(image_uri, features)
print_labels(response)

您應該會看到以下輸出內容：

================================================================================
 97% | Bicycle
 96% | Tire
 94% | Wheel
 91% | Automotive lighting
 89% | Infrastructure
 87% | Bicycle wheel
 86% | Mode of transport
 85% | Building
 83% | Electricity
 82% | Neighbourhood

線上試用版會以以下方式呈現結果：

摘要

在這個步驟中，您已對圖片執行標籤偵測，並顯示與該圖片最相關的標籤。進一步瞭解標籤偵測。

5. 執行文字偵測

文字偵測功能會執行光學字元辨識 (OCR)，這項功能可偵測及擷取圖片中的文字，並支援多種語言。此外，這項功能還能自動識別語言。

在本範例中，您將對交通號誌圖片執行文字偵測：

將下列程式碼複製到 IPython 工作階段：

def print_text(response: vision.AnnotateImageResponse):
    print("=" * 80)
    for annotation in response.text_annotations:
        vertices = [f"({v.x},{v.y})" for v in annotation.bounding_poly.vertices]
        print(
            f"{repr(annotation.description):42}",
            ",".join(vertices),
            sep=" | ",
        )

使用 TEXT_DETECTION 功能傳送要求：

image_uri = "gs://cloud-samples-data/vision/ocr/sign.jpg"
features = [vision.Feature.Type.TEXT_DETECTION]

response = analyze_image_from_uri(image_uri, features)
print_text(response)

您應該會看到以下輸出內容：

================================================================================
'WAITING?\nPLEASE\nTURN OFF\nYOUR\nENGINE' | (310,821),(2225,821),(2225,1965),(310,1965)
'WAITING'                                  | (344,821),(2025,879),(2016,1127),(335,1069)
'?'                                        | (2057,881),(2225,887),(2216,1134),(2048,1128)
'PLEASE'                                   | (1208,1230),(1895,1253),(1891,1374),(1204,1351)
'TURN'                                     | (1217,1414),(1718,1434),(1713,1558),(1212,1538)
'OFF'                                      | (1787,1437),(2133,1451),(2128,1575),(1782,1561)
'YOUR'                                     | (1211,1609),(1741,1626),(1737,1747),(1207,1731)
'ENGINE'                                   | (1213,1805),(1923,1819),(1920,1949),(1210,1935)

線上試用版會以以下方式呈現結果：

摘要

在這個步驟中，您已對圖片執行文字偵測，並顯示圖片中辨識到的文字。進一步瞭解文字偵測。

6. 執行地標偵測

地標偵測功能可偵測圖片中常見的自然和人造結構。

在本例中，您將對艾菲爾鐵塔的圖片 (由 John Towner 提供) 執行地標偵測：

將下列程式碼複製到 IPython 工作階段：

def print_landmarks(response: vision.AnnotateImageResponse, min_score: float = 0.5):
    print("=" * 80)
    for landmark in response.landmark_annotations:
        if landmark.score < min_score:
            continue
        vertices = [f"({v.x},{v.y})" for v in landmark.bounding_poly.vertices]
        lat_lng = landmark.locations[0].lat_lng
        print(
            f"{landmark.description:18}",
            ",".join(vertices),
            f"{lat_lng.latitude:.5f}",
            f"{lat_lng.longitude:.5f}",
            sep=" | ",
        )

使用 LANDMARK_DETECTION 功能傳送要求：

image_uri = "gs://cloud-samples-data/vision/landmark/eiffel_tower.jpg"
features = [vision.Feature.Type.LANDMARK_DETECTION]

response = analyze_image_from_uri(image_uri, features)
print_landmarks(response)

您應該會看到以下輸出內容：

================================================================================
Trocadéro Gardens  | (303,36),(520,36),(520,371),(303,371) | 48.86160 | 2.28928
Eiffel Tower       | (458,76),(512,76),(512,263),(458,263) | 48.85846 | 2.29435

線上試用版會以以下方式呈現結果：

摘要

在這個步驟中，您已對艾菲爾鐵塔的圖片執行地標偵測。進一步瞭解地標偵測。

7. 執行臉部偵測

臉部特徵偵測功能可偵測圖片中的多個臉部，以及相關的重要臉部特徵，例如表情或頭飾。

在本範例中，您將偵測下列圖片中的臉部 (圖片由 Himanshu Singh Gurjar 提供)：

將下列程式碼複製到 IPython 工作階段：

def print_faces(response: vision.AnnotateImageResponse):
    print("=" * 80)
    for face_number, face in enumerate(response.face_annotations, 1):
        vertices = ",".join(f"({v.x},{v.y})" for v in face.bounding_poly.vertices)
        print(f"# Face {face_number} @ {vertices}")
        print(f"Joy:     {face.joy_likelihood.name}")
        print(f"Exposed: {face.under_exposed_likelihood.name}")
        print(f"Blurred: {face.blurred_likelihood.name}")
        print("-" * 80)

使用 FACE_DETECTION 功能傳送要求：

image_uri = "gs://cloud-samples-data/vision/face/faces.jpeg"
features = [vision.Feature.Type.FACE_DETECTION]

response = analyze_image_from_uri(image_uri, features)
print_faces(response)

您應該會看到以下輸出內容：

================================================================================
# Face 1 @ (1077,157),(2146,157),(2146,1399),(1077,1399)
Joy:     VERY_LIKELY
Exposed: VERY_UNLIKELY
Blurred: VERY_UNLIKELY
--------------------------------------------------------------------------------
# Face 2 @ (144,1273),(793,1273),(793,1844),(144,1844)
Joy:     VERY_UNLIKELY
Exposed: VERY_UNLIKELY
Blurred: UNLIKELY
--------------------------------------------------------------------------------
# Face 3 @ (785,167),(1100,167),(1100,534),(785,534)
Joy:     VERY_UNLIKELY
Exposed: LIKELY
Blurred: VERY_LIKELY
--------------------------------------------------------------------------------

線上試用版會以以下方式呈現結果：

摘要

在這個步驟中，您已成功執行臉部偵測。進一步瞭解臉部偵測。

8. 執行物件偵測

在本範例中，您將對先前的世田谷圖片 (由 Alex Knight 提供) 執行物件偵測：

將下列程式碼複製到 IPython 工作階段：

def print_objects(response: vision.AnnotateImageResponse):
    print("=" * 80)
    for obj in response.localized_object_annotations:
        nvertices = obj.bounding_poly.normalized_vertices
        print(
            f"{obj.score:4.0%}",
            f"{obj.name:15}",
            f"{obj.mid:10}",
            ",".join(f"({v.x:.1f},{v.y:.1f})" for v in nvertices),
            sep=" | ",
        )

使用 OBJECT_LOCALIZATION 功能傳送要求：

image_uri = "gs://cloud-samples-data/vision/label/setagaya.jpeg"
features = [vision.Feature.Type.OBJECT_LOCALIZATION]

response = analyze_image_from_uri(image_uri, features)
print_objects(response)

您應該會看到以下輸出內容：

================================================================================
 93% | Bicycle         | /m/0199g   | (0.6,0.6),(0.8,0.6),(0.8,0.9),(0.6,0.9)
 92% | Bicycle wheel   | /m/01bqk0  | (0.6,0.7),(0.7,0.7),(0.7,0.9),(0.6,0.9)
 91% | Tire            | /m/0h9mv   | (0.7,0.7),(0.8,0.7),(0.8,1.0),(0.7,1.0)
 75% | Bicycle         | /m/0199g   | (0.3,0.6),(0.4,0.6),(0.4,0.7),(0.3,0.7)
 51% | Tire            | /m/0h9mv   | (0.3,0.6),(0.4,0.6),(0.4,0.7),(0.3,0.7)

線上試用版會以以下方式呈現結果：

摘要

在這個步驟中，您已成功執行物件偵測。進一步瞭解物件偵測。

9. 多項功能

您已瞭解如何使用 Vision API 的部分功能，但這項 API 還有許多功能，而且您可以在單一要求中要求多項功能。

以下是你可以提出的要求類型，一次取得所有洞察資料：

image_uri = "gs://..."
features = [
    vision.Feature.Type.OBJECT_LOCALIZATION,
    vision.Feature.Type.FACE_DETECTION,
    vision.Feature.Type.LANDMARK_DETECTION,
    vision.Feature.Type.LOGO_DETECTION,
    vision.Feature.Type.LABEL_DETECTION,
    vision.Feature.Type.TEXT_DETECTION,
    vision.Feature.Type.DOCUMENT_TEXT_DETECTION,
    vision.Feature.Type.SAFE_SEARCH_DETECTION,
    vision.Feature.Type.IMAGE_PROPERTIES,
    vision.Feature.Type.CROP_HINTS,
    vision.Feature.Type.WEB_DETECTION,
    vision.Feature.Type.PRODUCT_SEARCH,
    vision.Feature.Type.OBJECT_LOCALIZATION,
]

# response = analyze_image_from_uri(image_uri, features)

此外，您也可以同步或非同步對一批圖片執行偵測作業。查看所有使用指南。

10. 恭喜！

您已瞭解如何透過 Python 使用 Vision API，並測試幾項圖片偵測功能！

清除所用資源

如要清除開發環境，請在 Cloud Shell 中執行下列指令：

如果仍在 IPython 工作階段中，請返回 Shell：exit
停止使用 Python 虛擬環境：deactivate
刪除虛擬環境資料夾：cd ~ ; rm -rf ./venv-vision

如要刪除 Google Cloud 專案，請在 Cloud Shell 中執行下列操作：

擷取目前的專案 ID：PROJECT_ID=$(gcloud config get-value core/project)
確認這是要刪除的專案：echo $PROJECT_ID
刪除專案：gcloud projects delete $PROJECT_ID

瞭解詳情

在瀏覽器中測試線上試用版：https://cloud.google.com/vision
Vision API 說明文件：https://cloud.google.com/vision/docs
Google Cloud 上的 Python：https://cloud.google.com/python
Python 適用的 Cloud 用戶端程式庫：https://github.com/googleapis/google-cloud-python

授權

這項內容採用的授權為 Creative Commons 姓名標示 2.0 通用授權。

搭配 Python 使用 Vision API 透過集合功能整理內容 你可以依據偏好儲存及分類內容。

1. 總覽

課程內容

軟硬體需求

問卷調查

您會如何使用本教學課程？

你對 Python 的使用體驗如何？

你對 Google Cloud 服務的體驗滿意嗎？

2. 設定和需求條件

自修實驗室環境設定

啟動 Cloud Shell

啟用 Cloud Shell

3. 環境設定

4. 執行標籤偵測

摘要

5. 執行文字偵測

摘要

6. 執行地標偵測

摘要

7. 執行臉部偵測

摘要

8. 執行物件偵測

摘要

9. 多項功能

10. 恭喜！

清除所用資源

瞭解詳情

授權

搭配 Python 使用 Vision API