שימוש ב-Vision API עם Python

1. סקירה כללית

5ab7829fc22b21c4.png

Vision API מאפשר למפתחים לשלב בקלות תכונות של זיהוי ראייה באפליקציות, כולל הוספת תוויות לתמונות, זיהוי פנים וציוני דרך, זיהוי תווים אופטי (OCR) ותיוג של תוכן בוטה.

במדריך הזה תתמקדו בשימוש ב-Vision API עם Python.

מה תלמדו

  • איך מגדירים את הסביבה
  • איך לבצע זיהוי תוויות
  • איך לבצע זיהוי טקסט
  • איך לבצע זיהוי של ציוני דרך
  • איך לבצע זיהוי פנים
  • איך לבצע זיהוי אובייקטים

מה צריך להכין

  • פרויקט ב-Google Cloud
  • דפדפן כמו Chrome או Firefox
  • היכרות עם Python

סקר

איך תשתמשו במדריך הזה?

לקריאה בלבד לקרוא אותו ולבצע את התרגילים

איזה דירוג מגיע לדעתך לחוויה שלך עם Python?

מתחילים בינונית בקיאים

איזה דירוג מגיע לחוויה שלך בשירותי Google Cloud?

מתחילים בינונית בקיאים

2. הגדרה ודרישות

הגדרת סביבה בקצב עצמאי

  1. נכנסים למסוף Google Cloud ויוצרים פרויקט חדש או עושים שימוש חוזר בפרויקט קיים. אם אין לכם עדיין חשבון Gmail או חשבון Google Workspace, עליכם ליצור חשבון.

b35bf95b8bf3d5d8.png

a99b7ace416376c4.png

bd84a6d3004737c5.png

  • Project name הוא השם המוצג של המשתתפים בפרויקט. זו מחרוזת תווים שלא משמשת את Google APIs. תמיד אפשר לעדכן.
  • Project ID הוא ייחודי בכל הפרויקטים ב-Google Cloud ואי אפשר לשנות אותו (אי אפשר לשנות אותו אחרי שמגדירים אותו). מסוף Cloud יוצר מחרוזת ייחודית באופן אוטומטי; בדרך כלל לא מעניין אותך מה זה. ברוב ה-codelabs תצטרכו להפנות למזהה הפרויקט שלכם (בדרך כלל מזוהה כ-PROJECT_ID). אם המזהה שנוצר לא מוצא חן בעיניכם, אתם יכולים ליצור מזהה אקראי אחר. לחלופין, אפשר לנסות שם משלך ולראות אם הוא זמין. לא ניתן לשנות אותו אחרי השלב הזה, והוא נשאר למשך הפרויקט.
  • לידיעתך, יש ערך שלישי, Project Number, שבו משתמשים בחלק מממשקי ה-API. מידע נוסף על כל שלושת הערכים האלה זמין במסמכי התיעוד.
  1. בשלב הבא צריך להפעיל את החיוב במסוף Cloud כדי להשתמש במשאבים או בממשקי API של Cloud. מעבר ב-Codelab הזה לא יעלה הרבה כסף, אם בכלל. כדי להשבית משאבים ולא לצבור חיובים מעבר למדריך הזה, אתם יכולים למחוק את המשאבים שיצרתם או למחוק את הפרויקט. משתמשים חדשים ב-Google Cloud זכאים להשתתף בתוכנית תקופת ניסיון בחינם בשווי 1,200 ש"ח.

הפעלת Cloud Shell

אומנם אפשר להפעיל את Google Cloud מרחוק מהמחשב הנייד, אבל ב-Codelab הזה משתמשים ב-Cloud Shell, סביבת שורת הפקודה שפועלת ב-Cloud.

הפעלת Cloud Shell

  1. במסוף Cloud, לוחצים על Activate Cloud Shell 853e55310c205094.png.

55efc1aaa7a4d3ad.png

אם זו הפעם הראשונה שאתם מפעילים את Cloud Shell, יוצג לכם מסך ביניים שמתוארת בו. אם הוצג לכם מסך ביניים, לוחצים על המשך.

9c92662c6a846a5c.png

ההקצאה וההתחברות ל-Cloud Shell נמשכת כמה דקות.

9f0e51b578fecce5.png

במכונה הווירטואלית הזו נמצאים כל כלי הפיתוח הדרושים. יש בה ספריית בית בנפח מתמיד של 5GB והיא פועלת ב-Google Cloud, מה שמשפר משמעותית את ביצועי הרשת והאימות. אם לא את כולן, ניתן לבצע חלק גדול מהעבודה ב-Codelab הזה באמצעות דפדפן.

אחרי ההתחברות ל-Cloud Shell, אתם אמורים לראות שהפרויקט מאומת ושהפרויקט מוגדר לפי מזהה הפרויקט שלכם.

  1. מריצים את הפקודה הבאה ב-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`
  1. מריצים את הפקודה הבאה ב-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.

בשלבים הבאים תשתמשו במפענח אינטראקטיבי של Python בשם IPython, שהתקנתם בשלב הקודם. כדי להתחיל סשן מריצים את ipython ב-Cloud Shell:

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 מקבל תמונת קלט ומחזיר את התוויות בעלות הסבירות הגבוהה ביותר שרלוונטיות לאותה תמונה. היא מחזירה את התוויות המתאימות ביותר יחד עם ציון ודאות של ההתאמה לתמונה.

בדוגמה הזו, תבוצע זיהוי תוויות בתמונה (באדיבות אלכס Knight) בסטאגאיה, מחוז פופולרי בטוקיו:

756f97f0b1e46c38.jpeg

מעתיקים את הקוד הבא לסשן 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

כך מוצגות התוצאות בהדגמה אונליין:

2191b0425c9c148f.png

סיכום

בשלב הזה הייתה לכם אפשרות לבצע זיהוי תוויות בתמונה ולהציג את התוויות שיש בהן סבירות גבוהה ביותר שמשויכות לאותה תמונה. מידע נוסף על זיהוי תוויות.

5. ביצוע זיהוי טקסט

התכונה הזו מבצעת זיהוי תווים אופטי (OCR). הוא מזהה ומחלץ טקסט בתוך תמונה, תוך תמיכה במגוון שפות. הוא כולל גם זיהוי שפה אוטומטי.

בדוגמה הבאה תבצע זיהוי טקסט בתמונה של תמרור:

4dedd3fcfd9ad99b.jpeg

מעתיקים את הקוד הבא לסשן 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)

כך מוצגות התוצאות בהדגמה אונליין:

9c70fbce871c5fe5.png

סיכום

בשלב הזה הצלחתם לזהות טקסט בתמונה ולהציג את הטקסט שזוהה מהתמונה. מידע נוסף על זיהוי טקסט.

6. ביצוע זיהוי של ציוני דרך

במסגרת זיהוי ציוני דרך, המערכת מזהה בתוך תמונה מבנים פופולריים ומבנים מעשה ידי אדם.

בדוגמה הזו, תבצעו זיהוי של ציון דרך בתמונה (באדיבות ג'ון טאונר) של מגדל אייפל:

fb7801e36884b875.jpeg

מעתיקים את הקוד הבא לסשן 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

כך מוצגות התוצאות בהדגמה אונליין:

2788697365670985.png

סיכום

בשלב הזה הצלחת לבצע זיהוי של ציוני דרך בתמונה של מגדל אייפל. מידע נוסף על זיהוי סימני קרקע.

7. ביצוע זיהוי פנים

זיהוי תווי פנים מזהה פנים מרובות בתוך תמונה, יחד עם מאפייני הפנים העיקריים הקשורים, כמו מצב רגשי או שימוש בכיסוי ראש.

בדוגמה הזו תוכלו לזהות פנים בתמונה הבאה (באדיבות הימנשו סינג גורג'ר):

58c578ece524cf32.jpeg

מעתיקים את הקוד הבא לסשן 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
--------------------------------------------------------------------------------

כך מוצגות התוצאות בהדגמה אונליין:

cbb7f59299651b83.png

סיכום

בשלב הזה הצלחת לבצע זיהוי פנים. מידע נוסף על זיהוי פנים

8. ביצוע זיהוי אובייקטים

בדוגמה הזו, תבצעו זיהוי אובייקטים באותה תמונה קודמת (באדיבות Alex Knight) של Setagaya:

756f97f0b1e46c38.jpeg

מעתיקים את הקוד הבא לסשן 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)

כך מוצגות התוצאות בהדגמה אונליין:

e1c2ca803d874a6b.png

סיכום

בשלב הזה הצלחתם לבצע זיהוי אובייקטים. מידע נוסף על זיהוי אובייקטים.

9. מספר ישויות

ראית איך להשתמש בחלק מהתכונות ב-Vision 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. מעולה!

5ab7829fc22b21c4.png

למדתם איך להשתמש ב-Vision API עם Python ובדקתם כמה תכונות של זיהוי תמונות.

הסרת המשאבים

כדי לנקות את סביבת הפיתוח, מבצעים את הפעולות הבאות ב-Cloud Shell:

  • אם אתם עדיין נמצאים בסשן של IPython, עליכם לחזור למעטפת: exit
  • מפסיקים להשתמש בסביבה הווירטואלית של Python: deactivate
  • מוחקים את התיקייה של הסביבה הווירטואלית: cd ~ ; rm -rf ./venv-vision

כדי למחוק את הפרויקט ב-Google Cloud, צריך לבצע מתוך Cloud Shell:

  • אחזור של מזהה הפרויקט הנוכחי: PROJECT_ID=$(gcloud config get-value core/project)
  • צריך לוודא שזה הפרויקט שרוצים למחוק: echo $PROJECT_ID
  • מוחקים את הפרויקט: gcloud projects delete $PROJECT_ID

מידע נוסף

רישיון

היצירה הזו בשימוש ברישיון Creative Commons Attribution 2.0 גנרי.