-
Notifications
You must be signed in to change notification settings - Fork 1.5k
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Add Vision API usage documentation. #2148
Changes from all commits
File filter
Filter by extension
Conversations
Jump to
Diff view
Diff view
There are no files selected for viewing
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,233 @@ | ||
Using the Vision API | ||
==================== | ||
|
||
Authentication and Configuration | ||
-------------------------------- | ||
|
||
- For an overview of authentication in ``gcloud-python``, | ||
see :doc:`gcloud-auth`. | ||
|
||
- In addition to any authentication configuration, you should also set the | ||
:envvar:`GCLOUD_PROJECT` environment variable for the project you'd like | ||
to interact with. If the GCLOUD_PROJECT environment variable is not present, | ||
the project ID from JSON file credentials is used. | ||
|
||
If you are using Google App Engine or Google Compute Engine | ||
this will be detected automatically. | ||
|
||
- After configuring your environment, create a | ||
:class:`Client <gcloud.vision.client.Client>` | ||
|
||
.. code-block:: python | ||
|
||
>>> from gcloud import vision | ||
>>> client = vision.Client() | ||
|
||
or pass in ``credentials`` and ``project`` explicitly | ||
|
||
.. code-block:: python | ||
|
||
>>> from gcloud import vision | ||
>>> client = vision.Client(project='my-project', credentials=creds) | ||
|
||
Annotating an Image | ||
------------------- | ||
|
||
Annotate a single image | ||
This comment was marked as spam.
Sorry, something went wrong. |
||
~~~~~~~~~~~~~~~~~~~~~~~ | ||
|
||
.. code-block:: python | ||
|
||
>>> from gcloud import vision | ||
>>> client = vision.Client() | ||
>>> image = client.image('./image.png') | ||
>>> faces = image.detect_faces(limit=10) | ||
This comment was marked as spam.
Sorry, something went wrong. |
||
|
||
Annotate multiple images | ||
This comment was marked as spam.
Sorry, something went wrong. |
||
~~~~~~~~~~~~~~~~~~~~~~~~ | ||
|
||
.. code-block:: python | ||
|
||
>>> first_image = client.image('./image.jpg') | ||
>>> second_image = client.image('gs://my-storage-bucket/image2.jpg') | ||
>>> with client.batch(): | ||
This comment was marked as spam.
Sorry, something went wrong.
This comment was marked as spam.
Sorry, something went wrong. |
||
... labels = first_image.detect_labels() | ||
... faces = second_image.detect_faces(limit=10) | ||
|
||
or | ||
|
||
.. code-block:: python | ||
|
||
>>> images = [] | ||
This comment was marked as spam.
Sorry, something went wrong. |
||
>>> images.append(client.image('./image.jpg')) | ||
>>> images.append(client.image('gs://my-storage-bucket/image2.jpg')) | ||
>>> faces = client.detect_faces_multi(images, limit=10) | ||
This comment was marked as spam.
Sorry, something went wrong.
This comment was marked as spam.
Sorry, something went wrong. |
||
|
||
This comment was marked as spam.
Sorry, something went wrong. |
||
No results returned | ||
~~~~~~~~~~~~~~~~~~~ | ||
|
||
Failing annotations return no results for the feature type requested. | ||
This comment was marked as spam.
Sorry, something went wrong.
This comment was marked as spam.
Sorry, something went wrong. |
||
|
||
.. code-block:: python | ||
|
||
>>> from gcloud import vision | ||
>>> client = vision.Client() | ||
>>> image = client.image('./image.jpg') | ||
>>> logos = image.detect_logos(limit=10) | ||
>>> logos | ||
[] | ||
|
||
|
||
Manual Detection | ||
~~~~~~~~~~~~~~~~ | ||
|
||
You can call the detection method manually. | ||
|
||
.. code-block:: python | ||
|
||
>>> from gcloud import vision | ||
>>> client = vision.Client() | ||
>>> image = client.image('gs://my-test-bucket/image.jpg') | ||
>>> faces = image.detect(type=vision.FACE_DETECTION, limit=10) | ||
This comment was marked as spam.
Sorry, something went wrong.
This comment was marked as spam.
Sorry, something went wrong. |
||
|
||
Face Detection | ||
~~~~~~~~~~~~~~ | ||
|
||
Detecting a face or faces in an image. | ||
For a list of the possible facial landmarks | ||
see: https://cloud.google.com/vision/reference/rest/v1/images/annotate#type_1 | ||
|
||
|
||
.. code-block:: python | ||
|
||
>>> from gcloud import vision | ||
>>> client = vision.Client() | ||
>>> image = client.image('./image.jpg') | ||
>>> faces = image.detect_faces(limit=10) | ||
>>> faces[0].landmarks[0].type | ||
This comment was marked as spam.
Sorry, something went wrong.
This comment was marked as spam.
Sorry, something went wrong. |
||
'LEFT_EYE' | ||
>>> faces[0].landmarks[0].position.x | ||
1301.2404 | ||
>>> faces[0].detection_confidence | ||
0.9863683 | ||
>>> faces[0].joy_likelihood | ||
0.54453093 | ||
>>> faces[0].anger_likelihood | ||
0.02545464 | ||
|
||
|
||
|
||
Label Detection | ||
~~~~~~~~~~~~~~~ | ||
|
||
Image labels are a way to help categorize the contents of an image. | ||
If you have an image with a car, person and a dog it, label detection will | ||
attempt to identify those objects. | ||
|
||
.. code-block:: python | ||
|
||
>>> from gcloud import vision | ||
>>> client = vision.Client() | ||
>>> image = client.image('./image.jpg') | ||
>>> labels = image.detect_labels(limit=3) | ||
>>> labels[0].description | ||
'automobile' | ||
>>> labels[0].score | ||
This comment was marked as spam.
Sorry, something went wrong.
This comment was marked as spam.
Sorry, something went wrong. |
||
0.9863683 | ||
|
||
|
||
Landmark Detection | ||
~~~~~~~~~~~~~~~~~~ | ||
|
||
The API will attemtp to detect landmarks such as Mount Rushmore and | ||
the Sydney Opera House. The API will also provide their known geographical | ||
locations if available. | ||
|
||
.. code-block:: python | ||
|
||
>>> from gcloud import vision | ||
>>> client = vision.Client() | ||
>>> image = client.image('./image.jpg') | ||
>>> landmarks = image.detect_landmarks() | ||
>>> landmarks[0].description | ||
'Sydney Opera House' | ||
>>> landmarks[0].locations[0].latitude | ||
-33.857123 | ||
>>> landmarks[0].locations[0].longitude | ||
151.213921 | ||
>>> landmarks[0].bounding_poly.vertices[0].x | ||
78 | ||
>>> landmarks[0].bounding_poly.vertices[0].y | ||
162 | ||
|
||
Logo Detection | ||
~~~~~~~~~~~~~~ | ||
|
||
Google Vision can also attempt to detect company and brand logos in images. | ||
|
||
.. code-block:: python | ||
|
||
>>> from gcloud import vision | ||
>>> client = vision.Client() | ||
>>> image = client.image('./image.jpg') | ||
>>> logos = image.detect_logos(limit=1) | ||
>>> results.logos[0].description | ||
'Google' | ||
>>> logos[0].score | ||
This comment was marked as spam.
Sorry, something went wrong. |
||
0.9795432 | ||
>>> logos[0].bounding_poly.vertices[0].x | ||
78 | ||
>>> logos[0].bounding_poly.vertices[0].y | ||
62 | ||
|
||
Safe Search Detection | ||
~~~~~~~~~~~~~~~~~~~~~ | ||
|
||
Detecting safe search properties of an image. | ||
|
||
.. code-block:: python | ||
|
||
>>> from gcloud import vision | ||
>>> client = vision.Client() | ||
>>> image = client.image('./image.jpg') | ||
>>> safe_search = image.detect_safe_search() | ||
>>> safe_search.adult | ||
This comment was marked as spam.
Sorry, something went wrong.
This comment was marked as spam.
Sorry, something went wrong. |
||
'VERY_UNLIKELY' | ||
>>> safe_search.medical | ||
'UNLIKELY' | ||
|
||
Text Detection | ||
~~~~~~~~~~~~~~ | ||
|
||
Detecting text with ORC from an image. | ||
This comment was marked as spam.
Sorry, something went wrong.
This comment was marked as spam.
Sorry, something went wrong. |
||
|
||
.. code-block:: python | ||
|
||
>>> from gcloud import vision | ||
>>> client = vision.Client() | ||
>>> image = client.image('./image.jpg') | ||
>>> text = image.detect_text() | ||
>>> text.locale | ||
This comment was marked as spam.
Sorry, something went wrong.
This comment was marked as spam.
Sorry, something went wrong. |
||
'en' | ||
>>> text.description | ||
This comment was marked as spam.
Sorry, something went wrong.
This comment was marked as spam.
Sorry, something went wrong. |
||
'the full text of the image.' | ||
|
||
Image Properties | ||
~~~~~~~~~~~~~~~~ | ||
|
||
Detecting image color properties. | ||
|
||
.. code-block:: python | ||
|
||
>>> from gcloud import vision | ||
>>> client = vision.Client() | ||
>>> image = client.image('./image.jpg') | ||
>>> colors = image.detect_properties() | ||
This comment was marked as spam.
Sorry, something went wrong. |
||
>>> colors[0].red | ||
244 | ||
>>> colors[0].blue | ||
134 | ||
>>> colors[0].score | ||
0.65519291 | ||
>>> colors[0].pixel_fraction | ||
0.758658 |
This comment was marked as spam.
Sorry, something went wrong.
This comment was marked as spam.
Sorry, something went wrong.