Crop hints tutorial (#861)

* Adds crop hints tutorial.

* Uses aspect ratio so that we actually crop.

* Addresses review feedback

* nits

* Restructures samples for CI

Author: gguuss

vision/cloud-client/crop_hints/.gitignore

@@ -0,0 +1,2 @@
+output-crop.jpg
+output-hint.jpg

vision/cloud-client/crop_hints/README.rst

@@ -0,0 +1,111 @@
+.. This file is automatically generated. Do not edit this file directly.
+
+Google Cloud Vision API Python Samples
+===============================================================================
+
+This directory contains samples for Google Cloud Vision API. `Google Cloud Vision API`_ allows developers to easily integrate vision detection features within applications, including image labeling, face and landmark detection, optical character recognition (OCR), and tagging of explicit content
+
+
+
+
+.. _Google Cloud Vision API: https://cloud.google.com/vision/docs 
+
+Setup
+-------------------------------------------------------------------------------
+
+
+Authentication
+++++++++++++++
+
+Authentication is typically done through `Application Default Credentials`_,
+which means you do not have to change the code to authenticate as long as
+your environment has credentials. You have a few options for setting up
+authentication:
+
+#. When running locally, use the `Google Cloud SDK`_
+
+    .. code-block:: bash
+
+        gcloud beta auth application-default login
+
+
+#. When running on App Engine or Compute Engine, credentials are already
+   set-up. However, you may need to configure your Compute Engine instance
+   with `additional scopes`_.
+
+#. You can create a `Service Account key file`_. This file can be used to
+   authenticate to Google Cloud Platform services from any environment. To use
+   the file, set the ``GOOGLE_APPLICATION_CREDENTIALS`` environment variable to
+   the path to the key file, for example:
+
+    .. code-block:: bash
+
+        export GOOGLE_APPLICATION_CREDENTIALS=/path/to/service_account.json
+
+.. _Application Default Credentials: https://cloud.google.com/docs/authentication#getting_credentials_for_server-centric_flow
+.. _additional scopes: https://cloud.google.com/compute/docs/authentication#using
+.. _Service Account key file: https://developers.google.com/identity/protocols/OAuth2ServiceAccount#creatinganaccount
+
+Install Dependencies
+++++++++++++++++++++
+
+#. Install `pip`_ and `virtualenv`_ if you do not already have them.
+
+#. Create a virtualenv. Samples are compatible with Python 2.7 and 3.4+.
+
+    .. code-block:: bash
+
+        $ virtualenv env
+        $ source env/bin/activate
+
+#. Install the dependencies needed to run the samples.
+
+    .. code-block:: bash
+
+        $ pip install -r requirements.txt
+
+.. _pip: https://pip.pypa.io/
+.. _virtualenv: https://virtualenv.pypa.io/
+
+Samples
+-------------------------------------------------------------------------------
+
+Crop Hints Tutorial
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
+
+
+
+To run this sample:
+
+.. code-block:: bash
+
+    $ python crop_hints.py
+
+    usage: crop_hints.py [-h] image_file mode
+    
+    positional arguments:
+      image_file  The image you'd like to crop.
+      mode        Set to "crop" or "draw".
+    
+    optional arguments:
+      -h, --help  show this help message and exit
+
+
+
+
+The client library
+-------------------------------------------------------------------------------
+
+This sample uses the `Google Cloud Client Library for Python`_.
+You can read the documentation for more details on API usage and use GitHub
+to `browse the source`_ and  `report issues`_.
+
+.. Google Cloud Client Library for Python:
+    https://googlecloudplatform.github.io/google-cloud-python/
+.. browse the source:
+    https://github.com/GoogleCloudPlatform/google-cloud-python
+.. report issues:
+    https://github.com/GoogleCloudPlatform/google-cloud-python/issues
+
+
+.. _Google Cloud SDK: https://cloud.google.com/sdk/

vision/cloud-client/crop_hints/README.rst.in

@@ -0,0 +1,22 @@
+# This file is used to generate README.rst
+
+product:
+  name: Google Cloud Vision API
+  short_name: Cloud Vision API
+  url: https://cloud.google.com/vision/docs
+  description: >
+    `Google Cloud Vision API`_ allows developers to easily integrate vision
+    detection features within applications, including image labeling, face and
+    landmark detection, optical character recognition (OCR), and tagging of
+    explicit content
+
+setup:
+- auth
+- install_deps
+
+samples:
+- name: Crop Hints Tutorial
+  file: crop_hints.py
+  show_help: True
+
+cloud_client_library: true

vision/cloud-client/crop_hints/crop_hints.py

@@ -0,0 +1,97 @@
+#!/usr/bin/env python
+
+# Copyright 2017 Google Inc. All Rights Reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Outputs a cropped image or an image highlighting crop regions on an image.
+
+Examples:
+    python crop_hints.py resources/cropme.jpg draw
+    python crop_hints.py resources/cropme.jpg crop
+"""
+# [START full_tutorial]
+# [START imports]
+import argparse
+import io
+
+from google.cloud import vision
+from PIL import Image, ImageDraw
+# [END imports]
+
+
+def get_crop_hint(path):
+    # [START get_crop_hint]
+    """Detect crop hints on a single image and return the first result."""
+    vision_client = vision.Client()
+
+    with io.open(path, 'rb') as image_file:
+        content = image_file.read()
+
+    image = vision_client.image(content=content)
+
+    # Return bounds for the first crop hint using an aspect ratio of 1.77.
+    return image.detect_crop_hints({1.77})[0].bounds.vertices
+    # [END get_crop_hint]
+
+
+def draw_hint(image_file):
+    """Draw a border around the image using the hints in the vector list."""
+    # [START draw_hint]
+    vects = get_crop_hint(image_file)
+
+    im = Image.open(image_file)
+    draw = ImageDraw.Draw(im)
+    draw.line([vects[0].x_coordinate, vects[0].y_coordinate,
+              vects[1].x_coordinate, vects[1].y_coordinate],
+              fill='red', width=3)
+    draw.line([vects[1].x_coordinate, vects[1].y_coordinate,
+              vects[2].x_coordinate, vects[2].y_coordinate],
+              fill='red', width=3)
+    draw.line([vects[2].x_coordinate, vects[2].y_coordinate,
+              vects[3].x_coordinate, vects[3].y_coordinate],
+              fill='red', width=3)
+    draw.line([vects[3].x_coordinate, vects[3].y_coordinate,
+              vects[0].x_coordinate, vects[0].y_coordinate],
+              fill='red', width=3)
+    im.save('output-hint.jpg', 'JPEG')
+    # [END draw_hint]
+
+
+def crop_to_hint(image_file):
+    """Crop the image using the hints in the vector list."""
+    # [START crop_to_hint]
+    vects = get_crop_hint(image_file)
+
+    im = Image.open(image_file)
+    im2 = im.crop((vects[0].x_coordinate, vects[0].y_coordinate,
+                  vects[2].x_coordinate - 1, vects[2].y_coordinate - 1))
+    im2.save('output-crop.jpg', 'JPEG')
+    # [END crop_to_hint]
+
+
+if __name__ == '__main__':
+    # [START run_crop]
+    parser = argparse.ArgumentParser()
+    parser.add_argument('image_file', help='The image you\'d like to crop.')
+    parser.add_argument('mode', help='Set to "crop" or "draw".')
+    args = parser.parse_args()
+
+    parser = argparse.ArgumentParser()
+
+    if args.mode == 'crop':
+        crop_to_hint(args.image_file)
+    elif args.mode == 'draw':
+        draw_hint(args.image_file)
+    # [END run_crop]
+# [END full_tutorial]

vision/cloud-client/crop_hints/crop_hints_test.py

@@ -0,0 +1,37 @@
+# Copyright 2017 Google Inc. All Rights Reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+import os
+
+import crop_hints
+
+
+def test_crop(cloud_config, capsys):
+    """Checks the output image for cropping the image is created."""
+    file_name = os.path.join(
+        os.path.dirname(__file__),
+        'resources/cropme.jpg')
+    crop_hints.crop_to_hint(file_name)
+    out, _ = capsys.readouterr()
+    assert os.path.isfile('output-crop.jpg')
+
+
+def test_draw(cloud_config, capsys):
+    """Checks the output image for drawing the crop hint is created."""
+    file_name = os.path.join(
+        os.path.dirname(__file__),
+        'resources/cropme.jpg')
+    crop_hints.draw_hint(file_name)
+    out, _ = capsys.readouterr()
+    assert os.path.isfile('output-hint.jpg')

vision/cloud-client/crop_hints/requirements.txt

@@ -0,0 +1,2 @@
+google-cloud-vision==0.23.2
+pillow==4.0.0

vision/cloud-client/crop_hints/resources/cropme.jpg

@@ -70,18 +70,6 @@ Install Dependencies
 Samples
 -------------------------------------------------------------------------------
 
-Quickstart
-+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
-
-
-
-To run this sample:
-
-.. code-block:: bash
-
-    $ python quickstart.py
-
-
 Detect
 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 

vision/cloud-client/README.rst renamed to vision/cloud-client/detect/README.rst

@@ -0,0 +1,22 @@
+# This file is used to generate README.rst
+
+product:
+  name: Google Cloud Vision API
+  short_name: Cloud Vision API
+  url: https://cloud.google.com/vision/docs
+  description: >
+    `Google Cloud Vision API`_ allows developers to easily integrate vision
+    detection features within applications, including image labeling, face and
+    landmark detection, optical character recognition (OCR), and tagging of
+    explicit content
+
+setup:
+- auth
+- install_deps
+
+samples:
+- name: Detect
+  file: detect.py
+  show_help: True
+
+cloud_client_library: true

vision/cloud-client/detect/README.rst.in

@@ -356,7 +356,7 @@ def detect_crop_hints(path):
         content = image_file.read()
     image = vision_client.image(content=content)
 
-    hints = image.detect_crop_hints()
+    hints = image.detect_crop_hints({1.77})
 
     for n, hint in enumerate(hints):
         print('\nCrop Hint: {}'.format(n))
@@ -372,7 +372,7 @@ def detect_crop_hints_uri(uri):
     vision_client = vision.Client()
     image = vision_client.image(source_uri=uri)
 
-    hints = image.detect_crop_hints()
+    hints = image.detect_crop_hints({1.77})
     for n, hint in enumerate(hints):
         print('\nCrop Hint: {}'.format(n))