Skip to content

Commit

Permalink
Merge pull request #2754 from daspecster/vision-docs-cleanup
Browse files Browse the repository at this point in the history 
Cleaning up docs and fixing typos
  • Loading branch information
@daspecster
daspecster authored Nov 29, 2016
2 parents c40e0d4 + 00ff643 commit f0950ca
Showing 1 changed file with 89 additions and 99 deletions.
188 changes: 89 additions & 99 deletions docs/vision-usage.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -8,98 +8,37 @@ Authentication and Configuration
see :doc:`google-cloud-auth`.

- In addition to any authentication configuration, you should also set the
:envvar:`GOOGLE_CLOUD_PROJECT` environment variable for the project you'd like
to interact with. If the GOOGLE_CLOUD_PROJECT environment variable is not present,
the project ID from JSON file credentials is used.
:envvar:`GOOGLE_CLOUD_PROJECT` environment variable for the project you'd
like to interact with. If the GOOGLE_CLOUD_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 <google.cloud.vision.client.Client>`
:class:`~google.cloud.vision.client.Client`.

.. code-block:: python
>>> from google.cloud import vision
>>> client = vision.Client()
or pass in ``credentials`` and ``project`` explicitly
or pass in ``credentials`` and ``project`` explicitly.

.. code-block:: python
>>> from google.cloud import vision
>>> client = vision.Client(project='my-project', credentials=creds)
Annotating an Image
-------------------

Annotate a single image
~~~~~~~~~~~~~~~~~~~~~~~

.. code-block:: python
>>> import io
>>> from google.cloud import vision
>>> client = vision.Client()
>>> with io.open('./image.png', 'rb') as image_file:
... image = client.image(content=image_file.read())
>>> faces = image.detect_faces(limit=10)
>>> faces[0].landmarks.left_eye.position.x_coordinate
... 1004.8003
Annotate multiple images
~~~~~~~~~~~~~~~~~~~~~~~~

.. code-block:: python
>>> import io
>>> from google.cloud import vision
>>> client = vision.Client()
>>> with io.open('./image.png', 'rb') as image_file:
... image_one = client.image(content=image_file.read())
>>> image_two = client.image(source_uri='gs://my-storage-bucket/image.jpg')
>>> with client.batch():
... labels = image_one.detect_labels()
... faces = image_two.detect_faces(limit=10)
No results returned
~~~~~~~~~~~~~~~~~~~

Failing annotations return no results for the feature type requested.

.. code-block:: python
>>> from google.cloud import vision
>>> client = vision.Client()
>>> image = client.image(source_uri='gs://my-storage-bucket/image.jpg')
>>> logos = image.detect_logos(limit=10)
>>> logos
[]
Manual Detection
~~~~~~~~~~~~~~~~

You can call the detection method manually.

.. code-block:: python
>>> from google.cloud import vision
>>> from google.cloud.vision.image import Feature
>>> from google.cloud.vision.image import FeatureTypes
>>> client = vision.Client()
>>> image = client.image(source_uri='gs://my-test-bucket/image.jpg')
>>> features = [Feature(FeatureTypes.FACE_DETECTION, 5),
... Feature(FeatureTypes.LOGO_DETECTION, 3)]
>>> annotations = image.detect(features)
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
:meth:`~google.cloud.vision.image.Image.detect_faces` will search for faces in
an image and return the coordinates in the image of each `landmark type`_ that
was detected.

.. _landmark type: https://cloud.google.com/vision/reference/rest/v1/images/annotate#type_1

.. code-block:: python
Expand All @@ -119,13 +58,13 @@ see: https://cloud.google.com/vision/reference/rest/v1/images/annotate#type_1
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.
:meth:`~google.cloud.vision.image.Image.detect_labels` will attempt to label
objects in an image. If there is a car, person and a dog in the image, label
detection will attempt to identify those objects and score the level of
certainty from ``0.0 to 1.0``.

.. code-block:: python
Expand All @@ -142,15 +81,16 @@ attempt to identify those objects.
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.
:meth:`~google.cloud.vision.image.Image.detect_landmarks` will attempt 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 google.cloud import vision
>>> client = vision.Client()
>>> image = client.image('./image.jpg')
>>> with open('./image.jpg', 'rb') as image_file:
... image = client.image(content=image_file.read())
>>> landmarks = image.detect_landmarks()
>>> landmarks[0].description
'Sydney Opera House'
Expand All @@ -163,52 +103,78 @@ locations if available.
>>> landmarks[0].bounding_poly.vertices[0].y_coordinate
162
Logo Detection
~~~~~~~~~~~~~~

Google Vision can also attempt to detect company and brand logos in images.
With :meth:`~google.cloud.vision.image.Image.detect_logos`, you can identify
brand logos in an image. Their shape and location in the image can be found by
iterating through the detected logo's ``vertices``.

.. code-block:: python
>>> from google.cloud import vision
>>> client = vision.Client()
>>> image = client.image('./image.jpg')
>>> logos = image.detect_logos(limit=1)
>>> results.logos[0].description
>>> with open('./image.jpg', 'rb') as image_file:
... image = client.image(content=image_file.read())
>>> logos = image.detect_logos(limit=3)
>>> print(len(logos))
3
>>> first_logo = logos[0]
>>> first_logo.description
'Google'
>>> logos[0].score
>>> first_logo.score
0.9795432
>>> logos[0].bounding_poly.vertices[0].x_coordinate
>>> print(len(first_logo.bounding_poly.vertices))
4
>>> first_logo.bounding_poly.vertices[0].x_coordinate
78
>>> logos[0].bounding_poly.vertices[0].y_coordinate
>>> first_logo.bounding_poly.vertices[0].y_coordinate
62
Safe Search Detection
~~~~~~~~~~~~~~~~~~~~~

Detecting safe search properties of an image.
:meth:`~google.cloud.vision.image.Image.detect_safe_search` will try to
categorize the entire contents of the image under four categories.

- adult: Represents the likelihood that the image contains adult content.
- spoof: The likelihood that an obvious modification was made to the image's
canonical version to make it appear funny or offensive.
- medical: Likelihood this is a medical image.
- violence: Violence likelihood.

.. code-block:: python
>>> from google.cloud import vision
>>> client = vision.Client()
>>> image = client.image('./image.jpg')
>>> safe_search = image.detect_safe_search()
>>> safe_search[0].adult
>>> with open('./image.jpg', 'rb') as image_file:
... image = client.image(content=image_file.read())
>>> safe_search_results = image.detect_safe_search()
>>> safe_search = safe_search_results[0]
>>> safe_search.adult
'VERY_UNLIKELY'
>>> safe_search[0].medical
'UNLIKELY'
>>> safe_search.spoof
'POSSIBLE'
>>> safe_search.medical
'VERY_LIKELY'
>>> safe_search.violence
'LIKELY'
Text Detection
~~~~~~~~~~~~~~

Detecting text with ORC from an image.
:meth:`~google.cloud.vision.image.Image.detect_text` performs OCR to find text
in an image.

.. code-block:: python
>>> from google.cloud import vision
>>> client = vision.Client()
>>> image = client.image('./image.jpg')
>>> with open('./image.jpg', 'rb') as image_file:
... image = client.image(content=image_file.read())
>>> texts = image.detect_text()
>>> texts[0].locale
'en'
Expand All @@ -217,23 +183,47 @@ Detecting text with ORC from an image.
>>> texts[1].description
'some other text in the image'
Image Properties
~~~~~~~~~~~~~~~~

Detecting image color properties.
:meth:`~google.cloud.vision.image.Image.detect_properties` will process the
image and determine the dominant colors in the image.

.. code-block:: python
>>> from google.cloud import vision
>>> client = vision.Client()
>>> image = client.image('./image.jpg')
>>> with open('./image.jpg', 'rb') as image_file:
... image = client.image(content=image_file.read())
>>> results = image.detect_properties()
>>> colors = results[0]
>>> colors[0].red
>>> first_color = colors[0]
>>> first_color.red
244
>>> colors[0].blue
>>> first_color.blue
134
>>> colors[0].score
>>> first_color.score
0.65519291
>>> colors[0].pixel_fraction
>>> first_color.pixel_fraction
0.758658
No results found
~~~~~~~~~~~~~~~~

If no results for the detection performed can be extracted from the image, then
an empty list is returned. This behavior is similiar with all detection types.


Example with :meth:`~google.cloud.vision.image.Image.detect_logos`:

.. code-block:: python
>>> from google.cloud import vision
>>> client = vision.Client()
>>> with open('./image.jpg', 'rb') as image_file:
... image = client.image(content=image_file.read())
>>> logos = image.detect_logos(limit=3)
>>> logos
[]

0 comments on commit f0950ca

Please sign in to comment.