Add Vision Logo detection.

Author: daspecster

docs/index.rst

@@ -150,6 +150,7 @@
   vision-usage
   vision-client
   vision-image
+  vision-entity
   vision-feature
   vision-face
 

docs/vision-entity.rst

@@ -0,0 +1,10 @@
+Vision Entity
+=============
+
+Entity
+~~~~~~
+
+.. automodule:: gcloud.vision.entity
+  :members:
+  :undoc-members:
+  :show-inheritance:

gcloud/vision/_fixtures.py

@@ -1,21 +1,56 @@
-LABEL_DETECTION_RESPONSE = {
+LOGO_DETECTION_RESPONSE = {
     "responses": [
         {
-            "labelAnnotations": [
+            "logoAnnotations": [
                 {
-                    "mid": "/m/0k4j",
-                    "description": "automobile",
-                    "score": 0.9776855
+                    "mid": "/m/05b5c",
+                    "description": "Brand1",
+                    "score": 0.63192177,
+                    "boundingPoly": {
+                        "vertices": [
+                            {
+                                "x": 78,
+                                "y": 162
+                            },
+                            {
+                                "x": 282,
+                                "y": 162
+                            },
+                            {
+                                "x": 282,
+                                "y": 211
+                            },
+                            {
+                                "x": 78,
+                                "y": 211
+                            }
+                        ]
+                    }
                 },
                 {
-                    "mid": "/m/07yv9",
-                    "description": "vehicle",
-                    "score": 0.947987
-                },
-                {
-                    "mid": "/m/07r04",
-                    "description": "truck",
-                    "score": 0.88429511
+                    "mid": "/m/0fpzzp",
+                    "description": "Brand2",
+                    "score": 0.5492993,
+                    "boundingPoly": {
+                        "vertices": [
+                            {
+                                "x": 310,
+                                "y": 209
+                            },
+                            {
+                                "x": 477,
+                                "y": 209
+                            },
+                            {
+                                "x": 477,
+                                "y": 282
+                            },
+                            {
+                                "x": 310,
+                                "y": 282
+                            }
+                        ]
+                    }
                 }
             ]
         }

gcloud/vision/entity.py

@@ -0,0 +1,80 @@
+# Copyright 2016 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.
+
+"""Entity class for holding information returned from annotating an image."""
+
+
+from gcloud.vision.geometry import Bounds
+
+
+class EntityAnnotation(object):
+    """Representation of an entity returned from the Vision API."""
+    def __init__(self, bounds, description, mid, score):
+        self._bounds = bounds
+        self._description = description
+        self._mid = mid
+        self._score = score
+
+    @classmethod
+    def from_api_repr(cls, response):
+        """Factory: construct entity from Vision API response.
+
+        :type response: dict
+        :param response: Dictionary response from Vision API with entity data.
+
+        :rtype: :class:`gcloud.vision.entiy.EntityAnnotation`
+        :returns: Instance of ``EntityAnnotation``.
+        """
+        bounds = Bounds.from_api_repr(response['boundingPoly'])
+        description = response['description']
+        mid = response['mid']
+        score = response['score']
+
+        return cls(bounds, description, mid, score)
+
+    @property
+    def bounds(self):
+        """Bounding polygon of detected image feature.
+
+        :rtype: :class:`gcloud.vision.geometry.Bounds`
+        :returns: Instance of ``Bounds`` with populated vertices.
+        """
+        return self._bounds
+
+    @property
+    def description(self):
+        """Description of feature detected in image.
+
+        :rtype: str
+        :returns: String description of feature detected in image.
+        """
+        return self._description
+
+    @property
+    def mid(self):
+        """MID of feature detected in image.
+
+        :rtype: str
+        :returns: String MID of feature detected in image.
+        """
+        return self._mid
+
+    @property
+    def score(self):
+        """Overall score of the result. Range [0, 1].
+
+        :rtype: float
+        :returns: Overall score of the result. Range [0, 1].
+        """
+        return self._score

gcloud/vision/face.py

@@ -15,7 +15,8 @@
 """Face class representing the Vision API's face detection response."""
 
 
-from gcloud.vision.geometry import BoundsBase
+from gcloud.vision.geometry import Bounds
+from gcloud.vision.geometry import FDBounds
 from gcloud.vision.likelihood import Likelihood
 from gcloud.vision.geometry import Position
 
@@ -68,10 +69,6 @@ def tilt(self):
         return self._tilt
 
 
-class Bounds(BoundsBase):
-    """The bounding polygon of the entire face."""
-
-
 class Emotions(object):
     """Emotions displayed by the face detected in an image."""
     def __init__(self, joy_likelihood, sorrow_likelihood,
@@ -348,10 +345,6 @@ class FaceLandmarkTypes(object):
     CHIN_RIGHT_GONION = 'CHIN_RIGHT_GONION'
 
 
-class FDBounds(BoundsBase):
-    """The bounding polygon of just the skin portion of the face."""
-
-
 class Landmark(object):
     """A face-specific landmark (for example, a face feature, left eye)."""
     def __init__(self, position, landmark_type):

gcloud/vision/geometry.py

@@ -46,6 +46,14 @@ def vertices(self):
         return self._vertices
 
 
+class Bounds(BoundsBase):
+    """A polygon boundry of the detected feature."""
+
+
+class FDBounds(BoundsBase):
+    """The bounding polygon of just the skin portion of the face."""
+
+
 class Position(object):
     """A 3D position in the image.
 

gcloud/vision/image.py

@@ -19,6 +19,7 @@
 
 from gcloud._helpers import _to_bytes
 from gcloud._helpers import _bytes_to_unicode
+from gcloud.vision.entity import EntityAnnotation
 from gcloud.vision.face import Face
 from gcloud.vision.feature import Feature
 from gcloud.vision.feature import FeatureTypes
@@ -105,4 +106,13 @@ def detect_logos(self, limit=10):
         :param limit: The maximum number of logos to find.
 
         :rtype: list
-        :returns: List of
+        :returns: List of :class:`gcloud.vision.entity.EntityAnnotation`.
+        """
+        logos = []
+        logo_detection_feature = Feature(FeatureTypes.LOGO_DETECTION, limit)
+        result = self.client.annotate(self, [logo_detection_feature])
+        for logo_response in result['logoAnnotations']:
+            logo = EntityAnnotation.from_api_repr(logo_response)
+            logos.append(logo)
+
+        return logos

gcloud/vision/test_client.py

@@ -110,6 +110,38 @@ def test_face_detection_from_content(self):
                          image_request['image']['content'])
         self.assertEqual(5, image_request['features'][0]['maxResults'])
 
+    def test_logo_detection_from_source(self):
+        from gcloud.vision.entity import EntityAnnotation
+        from gcloud.vision._fixtures import LOGO_DETECTION_RESPONSE as RETURNED
+        credentials = _Credentials()
+        client = self._makeOne(project=self.PROJECT, credentials=credentials)
+        client.connection = _Connection(RETURNED)
+
+        image = client.image(_IMAGE_SOURCE)
+        logos = image.detect_logos(limit=3)
+        self.assertEqual(2, len(logos))
+        self.assertTrue(isinstance(logos[0], EntityAnnotation))
+        image_request = client.connection._requested[0]['data']['requests'][0]
+        self.assertEqual(_IMAGE_SOURCE,
+                         image_request['image']['source']['gcs_image_uri'])
+        self.assertEqual(3, image_request['features'][0]['maxResults'])
+
+    def test_logo_detection_from_content(self):
+        from gcloud.vision.entity import EntityAnnotation
+        from gcloud.vision._fixtures import LOGO_DETECTION_RESPONSE as RETURNED
+        credentials = _Credentials()
+        client = self._makeOne(project=self.PROJECT, credentials=credentials)
+        client.connection = _Connection(RETURNED)
+
+        image = client.image(_IMAGE_CONTENT)
+        logos = image.detect_logos(limit=5)
+        self.assertEqual(2, len(logos))
+        self.assertTrue(isinstance(logos[0], EntityAnnotation))
+        image_request = client.connection._requested[0]['data']['requests'][0]
+        self.assertEqual(self.B64_IMAGE_CONTENT,
+                         image_request['image']['content'])
+        self.assertEqual(5, image_request['features'][0]['maxResults'])
+
 
 class TestVisionRequest(unittest.TestCase):
     def _getTargetClass(self):

gcloud/vision/test_entity.py

@@ -0,0 +1,33 @@
+# Copyright 2016 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 unittest
+
+
+class TestEntityAnnotation(unittest.TestCase):
+    def _getTargetClass(self):
+        from gcloud.vision.entity import EntityAnnotation
+        return EntityAnnotation
+
+    def test_logo_annotation(self):
+        from gcloud.vision._fixtures import LOGO_DETECTION_RESPONSE
+
+        LOGO = LOGO_DETECTION_RESPONSE['responses'][0]['logoAnnotations'][0]
+        entity_class = self._getTargetClass()
+        logo = entity_class.from_api_repr(LOGO)
+
+        self.assertEqual('/m/05b5c', logo.mid)
+        self.assertEqual('Brand1', logo.description)
+        self.assertEqual(0.63192177, logo.score)
+        self.assertEqual(162, logo.bounds.vertices[0].y_coordinate)