gcloud 0.9.0 → 0.10.0

data/lib/gcloud/vision/annotation/properties.rb

@@ -0,0 +1,245 @@
+# 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.
+
+
+module Gcloud
+  module Vision
+    class Annotation
+      ##
+      # # Properties
+      #
+      # A set of properties about an image, such as the image's dominant colors.
+      #
+      # See {Gcloud::Vision::Image#properties}.
+      #
+      # @example
+      #   require "gcloud"
+      #
+      #   gcloud = Gcloud.new
+      #   vision = gcloud.vision
+      #
+      #   image = vision.image "path/to/logo.jpg"
+      #
+      #   properties = image.properties
+      #   properties.colors.count #=> 10
+      #
+      class Properties
+        ##
+        # @private The ImageProperties Google API Client object.
+        attr_accessor :gapi
+
+        ##
+        # @private Creates a new Properties instance.
+        def initialize
+          @gapi = {}
+        end
+
+        ##
+        # The image's dominant colors, including their corresponding scores.
+        #
+        # @return [Array<Color>] An array of the image's dominant colors.
+        #
+        def colors
+          return [] unless @gapi["dominantColors"]
+          @colors ||= Array(@gapi["dominantColors"]["colors"]).map do |c|
+            Color.from_gapi c
+          end
+        end
+
+        ##
+        # Returns the object's property values as an array.
+        #
+        # @return [Array]
+        #
+        def to_a
+          to_ary
+        end
+
+        ##
+        # Returns the object's property values as an array.
+        #
+        # @return [Array]
+        #
+        def to_ary
+          colors.map(&:rgb)
+        end
+
+        ##
+        # Deeply converts object to a hash. All keys will be symbolized.
+        #
+        # @return [Hash]
+        #
+        def to_h
+          to_hash
+        end
+
+        ##
+        # Deeply converts object to a hash. All keys will be symbolized.
+        #
+        # @return [Hash]
+        #
+        def to_hash
+          { colors: colors.map(&:to_h) }
+        end
+
+        # @private
+        def to_s
+          "(colors: #{colors.count})"
+        end
+
+        # @private
+        def inspect
+          "#<Properties #{self}>"
+        end
+
+        ##
+        # @private New Annotation::Properties from a Google API Client object.
+        def self.from_gapi gapi
+          new.tap { |f| f.instance_variable_set :@gapi, gapi }
+        end
+
+        ##
+        # # Color
+        #
+        # Color information consisting of RGB channels, score, and fraction of
+        # image the color occupies in the image.
+        #
+        # @example
+        #   require "gcloud"
+        #
+        #   gcloud = Gcloud.new
+        #   vision = gcloud.vision
+        #
+        #   image = vision.image "path/to/logo.jpg"
+        #   properties = image.properties
+        #
+        #   color = properties.colors.first
+        #   color.red #=> 247.0
+        #   color.green #=> 236.0
+        #   color.blue #=> 20.0
+        #   color.rgb #=> "f7ec14"
+        #   color.alpha #=> 1.0
+        #   color.score #=> 0.20301804
+        #   color.pixel_fraction #=> 0.0072649573
+        #
+        class Color
+          ##
+          # @private The ColorInfo Google API Client object.
+          attr_accessor :gapi
+
+          ##
+          # @private Creates a new Color instance.
+          def initialize
+            @gapi = {}
+          end
+
+          ##
+          # The amount of red in the color.
+          #
+          # @return [Float] A value in the interval [0, 255].
+          #
+          def red
+            @gapi["color"]["red"]
+          end
+
+          ##
+          # The amount of green in the color.
+          #
+          # @return [Float] A value in the interval [0, 255].
+          #
+          def green
+            @gapi["color"]["green"]
+          end
+
+          ##
+          # The amount of blue in the color.
+          #
+          # @return [Float] A value in the interval [0, 255].
+          #
+          def blue
+            @gapi["color"]["blue"]
+          end
+
+          ##
+          # The amount this color that should be applied to the pixel. A value
+          # of 1.0 corresponds to a solid color, whereas a value of 0.0
+          # corresponds to a completely transparent color.
+          #
+          # @return [Float] A value in the range [0, 1].
+          #
+          def alpha
+            @gapi["color"]["alpha"] || 1.0
+          end
+
+          def rgb
+            red.to_i.to_s(16).rjust(2, "0") +
+              green.to_i.to_s(16).rjust(2, "0") +
+              blue.to_i.to_s(16).rjust(2, "0")
+          end
+
+          ##
+          # Image-specific score for this color.
+          #
+          # @return [Float] A value in the range [0, 1].
+          #
+          def score
+            @gapi["score"]
+          end
+
+          ##
+          # Stores the fraction of pixels the color occupies in the image.
+          #
+          # @return [Float] A value in the range [0, 1].
+          #
+          def pixel_fraction
+            @gapi["pixelFraction"]
+          end
+
+          ##
+          # Converts object to a hash. All keys will be symbolized.
+          #
+          # @return [Hash]
+          #
+          def to_h
+            to_hash
+          end
+
+          ##
+          # Converts object to a hash. All keys will be symbolized.
+          #
+          # @return [Hash]
+          #
+          def to_hash
+            { red: red, green: green, blue: blue, alpha: alpha, rgb: rgb,
+              score: score, pixel_fraction: pixel_fraction }
+          end
+
+          def to_s
+            "(colors: #{rgb})"
+          end
+
+          def inspect
+            "#<Color #{self}>"
+          end
+
+          ##
+          # @private New Annotation::Properties from a Google API Client object.
+          def self.from_gapi gapi
+            new.tap { |f| f.instance_variable_set :@gapi, gapi }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/gcloud/vision/annotation/safe_search.rb

@@ -0,0 +1,161 @@
+# 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.
+
+
+require "gcloud/vision/annotation/vertex"
+
+module Gcloud
+  module Vision
+    class Annotation
+      ##
+      # # SafeSearch
+      #
+      # A set of features pertaining to the image, computed by various computer
+      # vision methods over safe-search verticals (for example, adult, spoof,
+      # medical, violence).
+      #
+      # @example
+      #   require "gcloud"
+      #
+      #   gcloud = Gcloud.new
+      #   vision = gcloud.vision
+      #
+      #   image = vision.image "path/to/face.jpg"
+      #
+      #   safe_search = image.safe_search
+      #   safe_search.spoof? #=> false
+      #   safe_search.spoof #=> "VERY_UNLIKELY"
+      #
+      class SafeSearch
+        POSITIVE_RATINGS = %w(POSSIBLE LIKELY VERY_LIKELY)
+
+        ##
+        # @private The SafeSearchAnnotation Google API Client object.
+        attr_accessor :gapi
+
+        ##
+        # @private Creates a new SafeSearch instance.
+        def initialize
+          @gapi = {}
+        end
+
+        ##
+        # Adult likelihood rating. Possible values are `VERY_UNLIKELY`,
+        # `UNLIKELY`, `POSSIBLE`, `LIKELY`, and `VERY_LIKELY`.
+        def adult
+          @gapi["adult"]
+        end
+
+        ##
+        # Adult likelihood. Returns `true` if {#adult} is `POSSIBLE`, `LIKELY`,
+        # or `VERY_LIKELY`.
+        #
+        # @return [Boolean]
+        #
+        def adult?
+          POSITIVE_RATINGS.include? adult
+        end
+
+        ##
+        # Spoof likelihood rating. Possible values are `VERY_UNLIKELY`,
+        # `UNLIKELY`, `POSSIBLE`, `LIKELY`, and `VERY_LIKELY`.
+        def spoof
+          @gapi["spoof"]
+        end
+
+        ##
+        # Spoof likelihood. Returns `true` if {#spoof} is `POSSIBLE`, `LIKELY`,
+        # or `VERY_LIKELY`.
+        #
+        # @return [Boolean]
+        #
+        def spoof?
+          POSITIVE_RATINGS.include? spoof
+        end
+
+        ##
+        # Medical likelihood rating. Possible values are `VERY_UNLIKELY`,
+        # `UNLIKELY`, `POSSIBLE`, `LIKELY`, and `VERY_LIKELY`.
+        def medical
+          @gapi["medical"]
+        end
+
+        ##
+        # Medical likelihood. Returns `true` if {#medical} is `POSSIBLE`,
+        # `LIKELY`, or `VERY_LIKELY`.
+        #
+        # @return [Boolean]
+        #
+        def medical?
+          POSITIVE_RATINGS.include? medical
+        end
+
+        ##
+        # Violence likelihood rating. Possible values are `VERY_UNLIKELY`,
+        # `UNLIKELY`, `POSSIBLE`, `LIKELY`, and `VERY_LIKELY`.
+        def violence
+          @gapi["violence"]
+        end
+
+        ##
+        # Violence likelihood. Returns `true` if {#violence} is `POSSIBLE`,
+        # `LIKELY`, or `VERY_LIKELY`.
+        #
+        # @return [Boolean]
+        #
+        def violence?
+          POSITIVE_RATINGS.include? violence
+        end
+
+        ##
+        # Converts object to a hash. All keys will be symbolized.
+        #
+        # @return [Hash]
+        #
+        def to_h
+          to_hash
+        end
+
+        ##
+        # Converts object to a hash. All keys will be symbolized.
+        #
+        # @return [Hash]
+        #
+        def to_hash
+          { adult: adult?, spoof: spoof?, medical: medical?,
+            violence: violence? }
+        end
+
+        # @private
+        def to_s
+          tmplt = "(adult?: %s, spoof?: %s, medical?: %s, " \
+                    "violence?: %s)"
+          format tmplt, adult?.inspect, spoof?.inspect, medical?.inspect,
+                 violence?.inspect
+        end
+
+        # @private
+        def inspect
+          "#<SafeSearch #{self}>"
+        end
+
+        ##
+        # @private New Annotation::SafeSearch from a Google API Client object.
+        def self.from_gapi gapi
+          new.tap { |f| f.instance_variable_set :@gapi, gapi }
+        end
+      end
+    end
+  end
+end

data/lib/gcloud/vision/annotation/text.rb

@@ -0,0 +1,236 @@
+# 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.
+
+
+require "gcloud/vision/annotation/vertex"
+
+module Gcloud
+  module Vision
+    class Annotation
+      ##
+      # # Text
+      #
+      # The result of text, or optical character recognition (OCR), detection.
+      #
+      # @example
+      #   require "gcloud"
+      #
+      #   gcloud = Gcloud.new
+      #   vision = gcloud.vision
+      #
+      #   image = vision.image "path/to/text.png"
+      #
+      #   text = image.text
+      #   text.locale #=> "en"
+      #   text.words.count #=> 28
+      #   text.text
+      #   #=> "Google Cloud Client Library for Ruby an idiomatic, intuitive... "
+      #
+      class Text
+        ##
+        # @private The EntityAnnotation Google API Client object.
+        attr_accessor :gapi
+
+        ##
+        # @private Creates a new Text instance.
+        def initialize
+          @gapi = {}
+          @words = []
+        end
+
+        ##
+        # The text detected in an image.
+        #
+        # @return [String] The entire text including newline characters.
+        #
+        def text
+          @gapi["description"]
+        end
+
+        ##
+        # The language code detected for `text`.
+        #
+        # @return [String] The [ISO
+        #   639-1](https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes)
+        #   language code.
+        #
+        def locale
+          @gapi["locale"]
+        end
+
+        ##
+        # The bounds for the detected text in the image.
+        #
+        # @return [Array<Vertex>]
+        #
+        def bounds
+          return [] unless @gapi["boundingPoly"]
+          @bounds ||= Array(@gapi["boundingPoly"]["vertices"]).map do |v|
+            Vertex.from_gapi v
+          end
+        end
+
+        ##
+        # Each word in the detected text, with the bounds for each word.
+        #
+        # @return [Array<Word>]
+        #
+        def words
+          @words
+        end
+
+        ##
+        # Deeply converts object to a hash. All keys will be symbolized.
+        #
+        # @return [Hash]
+        #
+        def to_h
+          to_hash
+        end
+
+        ##
+        # Deeply converts object to a hash. All keys will be symbolized.
+        #
+        # @return [Hash]
+        #
+        def to_hash
+          { text: text, locale: locale, bounds: bounds.map(&:to_h),
+            words: words.map(&:to_h) }
+        end
+
+        # @private
+        def to_s
+          to_str
+        end
+
+        # @private
+        def to_str
+          text
+        end
+
+        # @private
+        def inspect
+          format "#<Text text: %s, locale: %s, bounds: %i, words: %i>",
+                 text.inspect, locale.inspect, bounds.count, words.count
+        end
+
+        ##
+        # @private New Annotation::Text from an array of Google API Client
+        # objects.
+        def self.from_gapi gapi_list
+          text, *words = Array gapi_list
+          return nil if text.nil?
+          new.tap do |t|
+            t.instance_variable_set :@gapi, text
+            t.instance_variable_set :@words, words.map { |w| Word.from_gapi w }
+          end
+        end
+
+        ##
+        # # Word
+        #
+        # A word within a detected text (OCR). See {Text}.
+        #
+        # @example
+        #   require "gcloud"
+        #
+        #   gcloud = Gcloud.new
+        #   vision = gcloud.vision
+        #
+        #   image = vision.image "path/to/text.png"
+        #   text = image.text
+        #
+        #   words = text.words
+        #   words.count #=> 28
+        #
+        #   word = words.first
+        #   word.text #=> "Google"
+        #   word.bounds.count #=> 4
+        #   word.bounds.first #=> #<Vertex (x: 13, y: 8)>
+        #
+        class Word
+          ##
+          # @private The EntityAnnotation Google API Client object.
+          attr_accessor :gapi
+
+          ##
+          # @private Creates a new Word instance.
+          def initialize
+            @gapi = {}
+          end
+
+          ##
+          # The text of the word.
+          #
+          # @return [String]
+          #
+          def text
+            @gapi["description"]
+          end
+
+          ##
+          # The bounds of the word within the detected text.
+          #
+          # @return [Array<Vertex>]
+          #
+          def bounds
+            return [] unless @gapi["boundingPoly"]
+            @bounds ||= Array(@gapi["boundingPoly"]["vertices"]).map do |v|
+              Vertex.from_gapi v
+            end
+          end
+
+          ##
+          # Deeply converts object to a hash. All keys will be symbolized.
+          #
+          # @return [Hash]
+          #
+          def to_h
+            to_hash
+          end
+
+          ##
+          # Deeply converts object to a hash. All keys will be symbolized.
+          #
+          # @return [Hash]
+          #
+          def to_hash
+            { text: text, bounds: bounds.map(&:to_h) }
+          end
+
+          # @private
+          def to_s
+            to_str
+          end
+
+          # @private
+          def to_str
+            text
+          end
+
+          # @private
+          def inspect
+            format "#<Word text: %s, bounds: %i>", text.inspect, bounds.count
+          end
+
+          ##
+          # @private New Annotation::Text::Word from a Google API Client object.
+          def self.from_gapi gapi
+            new.tap { |w| w.instance_variable_set :@gapi, gapi }
+          end
+        end
+      end
+    end
+  end
+end