Merge pull request googleapis#2754 from daspecster/vision-docs-cleanup

Cleaning up docs and fixing typos

Author: daspecster

docs/vision-usage.rst

@@ -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
 
@@ -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
 
@@ -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'
@@ -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'
@@ -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
+    []