google-cloud-vision 0.20.0

data/lib/google/cloud/vision/annotation/properties.rb

@@ -0,0 +1,222 @@
+# 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 Google
+  module Cloud
+    module Vision
+      class Annotation
+        ##
+        # # Properties
+        #
+        # A set of properties about an image, such as the image's dominant
+        # colors.
+        #
+        # See {Google::Cloud::Vision::Image#properties}.
+        #
+        # @example
+        #   require "google/cloud"
+        #
+        #   gcloud = Google::Cloud.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.dominant_colors
+            @colors ||= Array(@gapi.dominant_colors.colors).map do |c|
+              Color.from_gapi c
+            end
+          end
+
+          ##
+          # Returns the object's property values as an array.
+          #
+          # @return [Array]
+          #
+          def to_a
+            colors.map(&:rgb)
+          end
+
+          ##
+          # Deeply converts object to a hash. All keys will be symbolized.
+          #
+          # @return [Hash]
+          #
+          def to_h
+            { 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 "google/cloud"
+          #
+          #   gcloud = Google::Cloud.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.pixel_fraction
+            end
+
+            ##
+            # Converts object to a hash. All keys will be symbolized.
+            #
+            # @return [Hash]
+            #
+            def to_h
+              { 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
+end

data/lib/google/cloud/vision/annotation/safe_search.rb

@@ -0,0 +1,154 @@
+# 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 "google/cloud/vision/annotation/vertex"
+
+module Google
+  module Cloud
+    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 "google/cloud"
+        #
+        #   gcloud = Google::Cloud.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
+            { 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
+end

data/lib/google/cloud/vision/annotation/text.rb

@@ -0,0 +1,222 @@
+# 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 "google/cloud/vision/annotation/vertex"
+
+module Google
+  module Cloud
+    module Vision
+      class Annotation
+        ##
+        # # Text
+        #
+        # The result of text, or optical character recognition (OCR), detection.
+        #
+        # @example
+        #   require "google/cloud"
+        #
+        #   gcloud = Google::Cloud.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 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.bounding_poly
+            @bounds ||= Array(@gapi.bounding_poly.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
+            { 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 "google/cloud"
+          #
+          #   gcloud = Google::Cloud.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.bounding_poly
+              @bounds ||= Array(@gapi.bounding_poly.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
+              { 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
+end