diff --git a/docs/vision-usage.rst b/docs/vision-usage.rst index af72a168dd7b..77d7a7ad0399 100644 --- a/docs/vision-usage.rst +++ b/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 ` + :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 + []