Add Vision image properties detection.

docs/index.rst

@@ -149,6 +149,7 @@
 
   vision-usage
   vision-client
+  vision-color
   vision-entity
   vision-feature
   vision-face

docs/vision-color.rst

@@ -0,0 +1,10 @@
+Vision Image Properties
+=======================
+
+Image Properties Annotation
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. automodule:: google.cloud.vision.color
+  :members:
+  :undoc-members:
+  :show-inheritance:

google/cloud/vision/color.py

@@ -0,0 +1,191 @@
+# 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.
+
+"""Image properties class representation derived from Vision API response."""
+
+
+class ImagePropertiesAnnotation(object):
+    """Representation of image properties
+
+    :type colors: list
+    :param colors: List of
+                   :class:`~google.cloud.vision.color.ColorInformation`.
+    """
+    def __init__(self, colors):
+        self._colors = colors
+
+    @classmethod
+    def from_api_repr(cls, response):
+        """Factory: construct ``ImagePropertiesAnnotation`` from a response.
+
+        :type response: dict
+        :param response: Dictionary response from Vision API with image
+                         properties data.
+
+        :rtype: :class:`~google.cloud.vision.color.ImagePropertiesAnnotation`.
+        :returns: Populated instance of ``ImagePropertiesAnnotation``.
+        """
+        colors = [ColorInformation.from_api_repr(color) for color in
+                  response['dominantColors']['colors']]
+        return cls(colors)
+
+    @property
+    def colors(self):
+        """Colors in an image.
+
+        :rtype: list of :class:`~google.cloud.vision.color.ColorInformation`
+        :returns: Populated list of ``ColorInformation``.
+        """
+        return self._colors
+
+
+class Color(object):
+    """Representation of RGBA color information.
+
+    :type red: int
+    :param red: The amount of red in the color as a value in the interval
+                [0, 1].
+
+    :type green: int
+    :param green: The amount of green in the color as a value in the interval
+                  [0, 1].
+
+    :type blue: int
+    :param blue: The amount of blue in the color as a value in the interval
+                 [0, 1].
+
+    :type alpha: float
+    :param alpha: The fraction of this color that should be applied to the
+                  pixel.
+    """
+    def __init__(self, red, green, blue, alpha):
+        self._red = red
+        self._green = green
+        self._blue = blue
+        self._alpha = alpha
+
+    @classmethod
+    def from_api_repr(cls, response):
+        """Factory: construct a ``Color`` from a Vision API response.
+
+        :type response: dict
+        :param response: Color from API Response.
+
+        :rtype: :class:`~google.cloud.vision.color.Color`
+        :returns: Instance of :class:`~google.cloud.vision.color.Color`.
+        """
+        red = response['red']
+        green = response['green']
+        blue = response['blue']
+        alpha = response.get('alpha')
+
+        return cls(red, green, blue, alpha)
+
+    @property
+    def red(self):
+        """Red color.
+
+        :rtype: int
+        :returns: Red RGB value.
+        """
+        return self._red
+
+    @property
+    def green(self):
+        """Green color.
+
+        :rtype: int
+        :returns: Green RGB value.
+        """
+        return self._green
+
+    @property
+    def blue(self):
+        """Blue color.
+
+        :rtype: int
+        :returns: Blue RGB value.
+        """
+        return self._blue
+
+    @property
+    def alpha(self):
+        """Alpha level.
+
+        :rtype: float
+        :returns: Alpha transparency level.
+        """
+        return self._alpha
+
+
+class ColorInformation(object):
+    """Representation of color information from API response.
+
+    :type color: :class:`~google.cloud.vision.color.Color`
+    :param color: RGB components of the color.
+
+    :type score: float
+    :param score: Image-specific score for this color. Value in range [0, 1].
+
+    :type pixel_fraction: float
+    :param pixel_fraction: Stores the fraction of pixels the color occupies in
+                           the image. Value in range [0, 1].
+    """
+    def __init__(self, color, score, pixel_fraction):
+        self._color = color
+        self._score = score
+        self._pixel_fraction = pixel_fraction
+
+    @classmethod
+    def from_api_repr(cls, response):
+        """Factory: construct ``ColorInformation`` for a color found.
+
+        :type response: dict
+        :param response: Color data with extra meta information.
+
+        :rtype: :class:`~google.cloud.vision.color.ColorInformation`
+        :returns: Instance of ``ColorInformation``.
+        """
+        color = Color.from_api_repr(response['color'])
+        score = response['score']
+        pixel_fraction = response['pixelFraction']
+
+        return cls(color, score, pixel_fraction)
+
+    @property
+    def color(self):
+        """RGB components of the color.
+
+        :rtype: :class:`~google.vision.color.Color`
+        :returns: Instance of ``Color``.
+        """
+        return self._color
+
+    @property
+    def score(self):
+        """Image-specific score for this color. Value in range [0, 1].
+
+        :rtype: float
+        :returns: Image score for this color.
+        """
+        return self._score
+
+    @property
+    def pixel_fraction(self):
+        """Stores the fraction of pixels the color occupies in the image.
+
+        :rtype: float
+        :returns: Pixel fraction value in range [0, 1].
+        """
+        return self._pixel_fraction

google/cloud/vision/feature.py

@@ -27,6 +27,7 @@ class FeatureTypes(object):
     LABEL_DETECTION = 'LABEL_DETECTION'
     TEXT_DETECTION = 'TEXT_DETECTION'
     SAFE_SEARCH_DETECTION = 'SAFE_SEARCH_DETECTION'
+    IMAGE_PROPERTIES = 'IMAGE_PROPERTIES'
 
 
 class Feature(object):

google/cloud/vision/image.py

@@ -22,6 +22,7 @@
 from google.cloud.vision.face import Face
 from google.cloud.vision.feature import Feature
 from google.cloud.vision.feature import FeatureTypes
+from google.cloud.vision.color import ImagePropertiesAnnotation
 from google.cloud.vision.safe import SafeSearchAnnotation
 
 
@@ -125,22 +126,6 @@ def detect_faces(self, limit=10):
 
         return faces
 
-    def detect_safe_search(self, limit=10):
-        """Retreive safe search properties from an image.
-
-        :type limit: int
-        :param limit: The number of faces to try and detect.
-
-        :rtype: list
-        :returns: List of
-                  :class:`~google.cloud.vision.sage.SafeSearchAnnotation`.
-        """
-        safe_detection_feature = Feature(FeatureTypes.SAFE_SEARCH_DETECTION,
-                                         limit)
-        result = self.client.annotate(self, [safe_detection_feature])
-        safe_search_response = result['safeSearchAnnotation']
-        return SafeSearchAnnotation.from_api_repr(safe_search_response)
-
     def detect_labels(self, limit=10):
         """Detect labels that describe objects in an image.
 
@@ -179,6 +164,21 @@ def detect_logos(self, limit=10):
         feature = Feature(FeatureTypes.LOGO_DETECTION, limit)
         return self._detect_annotation(feature)
 
+    def detect_properties(self, limit=10):
+        """Detect the color properties of an image.
+
+        :type limit: int
+        :param limit: The maximum number of image properties to find.
+
+        :rtype: list
+        :returns: List of
+                  :class:`~google.cloud.vision.color.ImagePropertiesAnnotation`.
+        """
+        feature = Feature(FeatureTypes.IMAGE_PROPERTIES, limit)
+        result = self.client.annotate(self, [feature])
+        response = result['imagePropertiesAnnotation']
+        return ImagePropertiesAnnotation.from_api_repr(response)
+
     def detect_safe_search(self, limit=10):
         """Retreive safe search properties from an image.
 

unit_tests/vision/_fixtures.py

@@ -1,3 +1,107 @@
+IMAGE_PROPERTIES_RESPONSE = {
+    'responses': [
+        {
+            'imagePropertiesAnnotation': {
+                'dominantColors': {
+                    'colors': [
+                        {
+                            'color': {
+                                'red': 253,
+                                'green': 203,
+                                'blue': 65,
+                                'alpha': 0.0
+                            },
+                            'score': 0.42258179,
+                            'pixelFraction': 0.025376344
+                        },
+                        {
+                            'color': {
+                                'red': 216,
+                                'green': 69,
+                                'blue': 56
+                            },
+                            'score': 0.34945792,
+                            'pixelFraction': 0.026093191
+                        },
+                        {
+                            'color': {
+                                'red': 79,
+                                'green': 142,
+                                'blue': 245
+                            },
+                            'score': 0.050921876,
+                            'pixelFraction': 0.014193549
+                        },
+                        {
+                            'color': {
+                                'red': 249,
+                                'green': 246,
+                                'blue': 246
+                            },
+                            'score': 0.0059412993,
+                            'pixelFraction': 0.86896056
+                        },
+                        {
+                            'color': {
+                                'red': 222,
+                                'green': 119,
+                                'blue': 51
+                            },
+                            'score': 0.0043299114,
+                            'pixelFraction': 0.00021505376
+                        },
+                        {
+                            'color': {
+                                'red': 226,
+                                'green': 138,
+                                'blue': 130
+                            },
+                            'score': 0.0038594988,
+                            'pixelFraction': 0.00086021505
+                        },
+                        {
+                            'color': {
+                                'red': 165,
+                                'green': 194,
+                                'blue': 243
+                            },
+                            'score': 0.0029492097,
+                            'pixelFraction': 0.0015053763
+                        },
+                        {
+                            'color': {
+                                'red': 231,
+                                'green': 169,
+                                'blue': 164
+                            },
+                            'score': 0.0017002203,
+                            'pixelFraction': 0.00043010752
+                        },
+                        {
+                            'color': {
+                                'red': 137,
+                                'green': 98,
+                                'blue': 142
+                            },
+                            'score': 0.0013974205,
+                            'pixelFraction': 0.00071684585
+                        },
+                        {
+                            'color': {
+                                'red': 239,
+                                'green': 179,
+                                'blue': 56
+                            },
+                            'score': 0.050473157,
+                            'pixelFraction': 0.0022222223
+                        }
+                    ]
+                }
+            }
+        }
+    ]
+}
+
 LABEL_DETECTION_RESPONSE = {
     'responses': [
         {