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

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

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

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

מה תלמדו

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

מה תצטרכו

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

סקר

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

רק לקרוא

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

איך היית מדרג את חוויית השימוש שלך ב-Python?

מתחילים

ביניים

מומחים

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

מתחילים

ביניים

מומחים

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

הגדרת סביבה בקצב אישי

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

שם הפרויקט הוא השם המוצג של הפרויקט הזה למשתתפים. זו מחרוזת תווים שלא נמצאת בשימוש ב-Google APIs. תמיד אפשר לעדכן את המיקום.
מזהה הפרויקט הוא ייחודי לכל הפרויקטים ב-Google Cloud, והוא קבוע (אי אפשר לשנות אותו אחרי שהוא מוגדר). מסוף Cloud יוצר באופן אוטומטי מחרוזת ייחודית, ובדרך כלל לא צריך לדעת מה היא. ברוב ה-Codelabs, תצטרכו להפנות למזהה הפרויקט (בדרך כלל מסומן כ-PROJECT_ID). אם אתם לא אוהבים את המזהה שנוצר, אתם יכולים ליצור מזהה אקראי אחר. אפשר גם לנסות שם משתמש משלכם ולבדוק אם הוא זמין. אי אפשר לשנות את ההגדרה הזו אחרי השלב הזה, והיא תישאר לאורך הפרויקט.
לידיעתכם, יש ערך שלישי, מספר פרויקט, שחלק מממשקי ה-API משתמשים בו. במאמרי העזרה מפורט מידע נוסף על שלושת הערכים האלה.

בשלב הבא, תצטרכו להפעיל את החיוב במסוף Cloud כדי להשתמש במשאבי Cloud או בממשקי API של Cloud. השלמת ה-codelab הזה לא תעלה לכם הרבה, אם בכלל. כדי להשבית את המשאבים ולמנוע חיובים נוספים אחרי שתסיימו את המדריך הזה, תוכלו למחוק את המשאבים שיצרתם או למחוק את הפרויקט. משתמשים חדשים ב-Google Cloud זכאים לתוכנית תקופת ניסיון בחינם בשווי 300$.

מפעילים את Cloud Shell

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

הפעלת Cloud Shell

ב-Cloud Console, לוחצים על Activate Cloud Shell .

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

הקצאת המשאבים והחיבור ל-Cloud Shell נמשכים רק כמה רגעים.

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

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

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

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

בדוגמה הזו, תבצעו זיהוי תוויות בתמונה (באדיבות 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, אבל יש עוד הרבה תכונות ואפשר לבקש כמה תכונות בבקשה אחת.

זו דוגמה לבקשה שאפשר לשלוח כדי לקבל את כל התובנות בבת אחת:

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. מעולה!

למדתם איך להשתמש ב-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

מידע נוסף

אפשר לבדוק את ההדגמה באינטרנט בדפדפן: https://cloud.google.com/vision
מאמרי העזרה של Vision API: ‏ https://cloud.google.com/vision/docs
‫Python ב-Google Cloud: https://cloud.google.com/python
ספריות לקוח של Cloud ל-Python: ‏ https://github.com/googleapis/google-cloud-python

רישיון

עבודה זו מורשית תחת רישיון Creative Commons שמותנה בייחוס 2.0 כללי.