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:: google.cloud.vision.entity
+  :members:
+  :undoc-members:
+  :show-inheritance:

google/cloud/vision/entity.py

@@ -0,0 +1,93 @@
+# 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 google.cloud.vision.geometry import Bounds
+
+
+class EntityAnnotation(object):
+    """Representation of an entity returned from the Vision API.
+
+    :type bounds: dict
+    :param bounds: Dictionary of bounary information of detected entity.
+
+    :type description: str
+    :param description: Description of entity detected in an image.
+
+    :type mid: str
+    :param mid: Opaque entity ID.
+
+    :type score: float
+    :param score: Overall score of the result. Range [0, 1].
+    """
+    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:`~google.cloud.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:`~google.cloud.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

google/cloud/vision/feature.py

@@ -51,18 +51,32 @@ def __init__(self, feature_type, max_results=1):
         self._max_results = int(max_results)
 
     def as_dict(self):
-        """Generate dictionary for Feature request format."""
+        """Generate dictionary for Feature request format.
+
+        :rtype: dict
+        :returns: Dictionary representation of a
+                  :class:`~google.cloud.vision.feature.FeatureType`.
+        """
         return {
             'type': self.feature_type,
             'maxResults': self.max_results
         }
 
     @property
     def feature_type(self):
-        """"Feature type string."""
+        """"Feature type string.
+
+        :rtype: :class:`~google.cloud.vision.feature.FeatureTypes`
+        :returns: Instance of
+                  :class:`~google.cloud.vision.feature.FeatureTypes`
+        """
         return self._feature_type
 
     @property
     def max_results(self):
-        """Maximum number of results for feature type."""
+        """Maximum number of results for feature type.
+
+        :rtype: int
+        :returns: Maxium results to be returned.
+        """
         return self._max_results

google/cloud/vision/geometry.py

@@ -16,7 +16,11 @@
 
 
 class BoundsBase(object):
-    """Base class for handling bounds with vertices."""
+    """Base class for handling bounds with vertices.
+
+    :type vertices: list of :class:`~google.cloud.vision.geometry.Vertex`
+    :param vertcies: List of vertcies describing points on an image.
+    """
     def __init__(self, vertices):
         self._vertices = vertices
 
@@ -40,17 +44,34 @@ def from_api_repr(cls, response_vertices):
     def vertices(self):
         """List of vertices.
 
-        :rtype: list
+        :rtype: list of :class:`~google.cloud.vision.geometry.Vertex`
         :returns: List of populated vertices.
         """
         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.
 
     See:
     https://cloud.google.com/vision/reference/rest/v1/images/annotate#Position
+
+    :type x_coordinate: float
+    :param x_coordinate: X position coordinate.
+
+    :type y_coordinate: float
+    :param y_coordinate: Y position coordinate.
+
+    :type z_coordinate: float
+    :param z_coordinate: Z position coordinate.
     """
     def __init__(self, x_coordinate, y_coordinate, z_coordinate):
         self._x_coordinate = x_coordinate
@@ -102,6 +123,12 @@ class Vertex(object):
 
     See:
     https://cloud.google.com/vision/reference/rest/v1/images/annotate#Vertex
+
+    :type x_coordinate: float
+    :param x_coordinate: X position coordinate.
+
+    :type y_coordinate: float
+    :param y_coordinate: Y position coordinate.
     """
     def __init__(self, x_coordinate, y_coordinate):
         self._x_coordinate = x_coordinate

google/cloud/vision/image.py

@@ -18,6 +18,7 @@
 from base64 import b64encode
 
 from google.cloud._helpers import _to_bytes
+from google.cloud.vision.entity import EntityAnnotation
 from google.cloud.vision.face import Face
 from google.cloud.vision.feature import Feature
 from google.cloud.vision.feature import FeatureTypes
@@ -98,3 +99,22 @@ def detect_faces(self, limit=10):
             faces.append(face)
 
         return faces
+
+    def detect_logos(self, limit=10):
+        """Detect logos in an image.
+
+        :type limit: int
+        :param limit: The maximum number of logos to find.
+
+        :rtype: list
+        :returns: List of
+                  :class:`~google.cloud.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