استخدام Vision API مع Python

1. نظرة عامة

تتيح واجهة Vision API للمطوّرين دمج ميزات التعرّف البصري بسهولة في التطبيقات، بما في ذلك تصنيف الصور، والتعرّف على الوجوه والمعالم، والتعرّف البصري على الأحرف (OCR)، ووضع علامات على المحتوى الفاضح.

في هذا البرنامج التعليمي، ستركز على استخدام Vision API مع لغة Python.

ما ستتعلمه

كيفية إعداد بيئتك
كيفية تنفيذ عملية رصد التصنيفات
كيفية إجراء عملية رصد النص
كيفية تنفيذ عملية رصد المعالم
كيفية إجراء عملية التعرّف على الوجوه
كيفية إجراء عملية رصد العناصر

المتطلبات

مشروع على السحابة الإلكترونية من Google
متصفّح، مثل Chrome أو Firefox
الإلمام باستخدام لغة Python

استطلاع الرأي

كيف ستستخدم هذا البرنامج التعليمي؟

قراءة المحتوى فقط

قراءة المحتوى وإكمال التمارين

كيف تقيّم تجربتك مع Python؟

مبتدئ

متوسط

متمكّن

كيف تقيّم تجربتك مع خدمات Google Cloud؟

مبتدئ

متوسط

متقدّم

2. الإعداد والمتطلبات

إعداد البيئة بالسرعة التي تناسبك

سجِّل الدخول إلى Google Cloud Console وأنشِئ مشروعًا جديدًا أو أعِد استخدام مشروع حالي. إذا لم يكن لديك حساب على Gmail أو Google Workspace، عليك إنشاء حساب.

اسم المشروع هو الاسم المعروض للمشاركين في هذا المشروع. وهي سلسلة أحرف لا تستخدمها Google APIs. ويمكنك تعديلها في أي وقت.
رقم تعريف المشروع هو معرّف فريد في جميع مشاريع Google Cloud ولا يمكن تغييره بعد ضبطه. تنشئ Cloud Console تلقائيًا سلسلة فريدة، ولا يهمّك عادةً ما هي. في معظم دروس البرمجة، عليك الرجوع إلى رقم تعريف مشروعك (يُشار إليه عادةً باسم PROJECT_ID). إذا لم يعجبك المعرّف الذي تم إنشاؤه، يمكنك إنشاء معرّف عشوائي آخر. يمكنك بدلاً من ذلك تجربة اسم مستخدم من اختيارك ومعرفة ما إذا كان متاحًا. لا يمكن تغيير هذا الخيار بعد هذه الخطوة وسيظل ساريًا طوال مدة المشروع.
للعلم، هناك قيمة ثالثة، وهي رقم المشروع، تستخدمها بعض واجهات برمجة التطبيقات. يمكنك الاطّلاع على مزيد من المعلومات عن كل هذه القيم الثلاث في المستندات.

بعد ذلك، عليك تفعيل الفوترة في Cloud Console لاستخدام موارد/واجهات برمجة تطبيقات Cloud. لن تكلفك تجربة هذا الدرس التطبيقي حول الترميز الكثير، إن وُجدت أي تكلفة على الإطلاق. لإيقاف الموارد وتجنُّب تحمّل تكاليف تتجاوز هذا البرنامج التعليمي، يمكنك حذف الموارد التي أنشأتها أو حذف المشروع. يمكن لمستخدمي Google Cloud الجدد الاستفادة من برنامج الفترة التجريبية المجانية بقيمة 300 دولار أمريكي.

بدء Cloud Shell

على الرغم من إمكانية تشغيل Google Cloud عن بُعد من الكمبيوتر المحمول، ستستخدم في هذا الدرس العملي Cloud Shell، وهي بيئة سطر أوامر تعمل في السحابة الإلكترونية.

تفعيل Cloud Shell

من Cloud Console، انقر على تفعيل Cloud Shell .

إذا كانت هذه هي المرة الأولى التي تبدأ فيها Cloud Shell، ستظهر لك شاشة وسيطة توضّح ماهية هذه الخدمة. إذا ظهرت لك شاشة وسيطة، انقر على متابعة.

يستغرق توفير Cloud Shell والاتصال به بضع لحظات فقط.

يتم تحميل هذا الجهاز الافتراضي بجميع أدوات التطوير اللازمة. توفّر هذه الخدمة دليلًا رئيسيًا دائمًا بسعة 5 غيغابايت وتعمل في Google Cloud، ما يؤدي إلى تحسين أداء الشبكة والمصادقة بشكل كبير. يمكن إنجاز معظم عملك في هذا الدرس التطبيقي حول الترميز، إن لم يكن كله، باستخدام متصفح.

بعد الاتصال بـ 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 لتفعيل واجهة برمجة التطبيقات:

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
مكتبات العملاء على السحابة الإلكترونية للغة Python: https://github.com/googleapis/google-cloud-python

الترخيص

يخضع هذا العمل لترخيص المشاع الإبداعي مع نسب العمل إلى مؤلفه 2.0 Generic License.