google-cloud-vision 0.20.0

data/lib/google/cloud/vision/annotate.rb

@@ -0,0 +1,235 @@
+# 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/image"
+require "google/apis/vision_v1"
+
+module Google
+  module Cloud
+    module Vision
+      ##
+      # # Annotate
+      #
+      # Accumulates configuration for an image annotation request. Users
+      # describe the type of Google Cloud Vision API tasks to perform over
+      # images by configuring features such as `faces`, `landmarks`, `text`,
+      # etc. This configuration captures the Cloud Vision API vertical to
+      # operate on and the number of top-scoring results to return.
+      #
+      # See {Project#annotate}.
+      #
+      # @example
+      #   require "google/cloud"
+      #
+      #   gcloud = Google::Cloud.new
+      #   vision = gcloud.vision
+      #
+      #   face_image = vision.image "path/to/face.jpg"
+      #   landmark_image = vision.image "path/to/landmark.jpg"
+      #
+      #   annotation = vision.annotate do |annotate|
+      #      annotate.annotate face_image, faces: true, labels: true
+      #      annotate.annotate landmark_image, landmarks: true
+      #   end
+      #
+      #   annotation.faces.count #=> 1
+      #   annotation.labels.count #=> 4
+      #   annotation.landmarks.count #=> 1
+      #
+      class Annotate
+        # @private
+        attr_accessor :requests
+
+        ##
+        # @private Creates a new Annotate instance.
+        def initialize project
+          @project = project
+          @requests = []
+        end
+
+        ##
+        # Performs detection of Cloud Vision
+        # [features](https://cloud.google.com/vision/reference/rest/v1/images/annotate#Feature)
+        # on the given images. If no options for features are provided, **all**
+        # image detection features will be performed, with a default of `100`
+        # results for faces, landmarks, logos, and labels. If any feature option
+        # is provided, only the specified feature detections will be performed.
+        # Please review [Pricing](https://cloud.google.com/vision/docs/pricing)
+        # before use, as a separate charge is incurred for each feature
+        # performed on an image.
+        #
+        # Cloud Vision sets upper limits on file size as well as on the total
+        # combined size of all images in a request. Reducing your file size can
+        # significantly improve throughput; however, be careful not to reduce
+        # image quality in the process. See [Best Practices - Image
+        # Sizing](https://cloud.google.com/vision/docs/image-best-practices#image_sizing)
+        # for current file size limits.
+        #
+        # See {Project#annotate} for requests that do not involve multiple
+        # feature configurations.
+        #
+        # @see https://cloud.google.com/vision/docs/requests-and-responses Cloud
+        #   Vision API Requests and Responses
+        # @see https://cloud.google.com/vision/reference/rest/v1/images/annotate#AnnotateImageRequest
+        #   AnnotateImageRequest
+        # @see https://cloud.google.com/vision/docs/pricing Cloud Vision Pricing
+        #
+        # @param [Image, Object] images The image or images to annotate. This
+        #   can be an {Image} instance, or any other type that converts to an
+        #   {Image}. See {#image} for details.
+        # @param [Boolean, Integer] faces Whether to perform the facial
+        #   detection feature. The maximum number of results is configured in
+        #   {Google::Cloud::Vision.default_max_faces}, or may be provided here.
+        #   Optional.
+        # @param [Boolean, Integer] landmarks Whether to perform the landmark
+        #   detection feature. The maximum number of results is configured in
+        #   {Google::Cloud::Vision.default_max_landmarks}, or may be provided
+        #   here. Optional.
+        # @param [Boolean, Integer] logos Whether to perform the logo detection
+        #   feature. The maximum number of results is configured in
+        #   {Google::Cloud::Vision.default_max_logos}, or may be provided here.
+        #   Optional.
+        # @param [Boolean, Integer] labels Whether to perform the label
+        #   detection feature. The maximum number of results is configured in
+        #   {Google::Cloud::Vision.default_max_labels}, or may be provided here.
+        #   Optional.
+        # @param [Boolean] text Whether to perform the text (OCR) feature.
+        #   Optional.
+        # @param [Boolean] safe_search Whether to perform the safe search
+        #   feature. Optional.
+        # @param [Boolean] properties Whether to perform the image properties
+        #   feature (currently, the image's dominant colors.) Optional.
+        #
+        # @return [Annotation, Array<Annotation>] The results for all image
+        #   detections, returned as a single {Annotation} instance for one
+        #   image, or as an array of {Annotation} instances, one per image, for
+        #   multiple images.
+        #
+        # @example
+        #   require "google/cloud"
+        #
+        #   gcloud = Google::Cloud.new
+        #   vision = gcloud.vision
+        #
+        #   face_image = vision.image "path/to/face.jpg"
+        #   landmark_image = vision.image "path/to/landmark.jpg"
+        #   text_image = vision.image "path/to/text.png"
+        #
+        #   annotations = vision.annotate do |annotate|
+        #      annotate.annotate face_image, faces: true, labels: true
+        #      annotate.annotate landmark_image, landmarks: true
+        #      annotate.annotate text_image, text: true
+        #   end
+        #
+        #   annotations[0].faces.count #=> 1
+        #   annotations[0].labels.count #=> 4
+        #   annotations[1].landmarks.count #=> 1
+        #   annotations[2].text.words.count #=> 28
+        #
+        def annotate *images, faces: false, landmarks: false, logos: false,
+                     labels: false, text: false, safe_search: false,
+                     properties: false
+          add_requests(images, faces, landmarks, logos, labels, text,
+                       safe_search, properties)
+        end
+
+        protected
+
+        def image source
+          return source if source.is_a? Image
+          Image.from_source source, @project
+        end
+
+        def add_requests images, faces, landmarks, logos, labels, text,
+                         safe_search, properties
+          features = annotate_features(faces, landmarks, logos, labels, text,
+                                       safe_search, properties)
+
+          Array(images).flatten.each do |img|
+            i = image(img)
+            @requests << Google::Apis::VisionV1::AnnotateImageRequest.new(
+              image: i.to_gapi,
+              features: features,
+              imageContext: i.context.to_gapi
+            )
+          end
+        end
+
+        def annotate_features faces, landmarks, logos, labels, text,
+                              safe_search, properties
+          return default_features if default_features?(
+            faces, landmarks, logos, labels, text, safe_search, properties)
+
+          faces, landmarks, logos, labels = validate_max_values(
+            faces, landmarks, logos, labels)
+
+          f = []
+          f << feature("FACE_DETECTION", faces) unless faces.zero?
+          f << feature("LANDMARK_DETECTION", landmarks) unless landmarks.zero?
+          f << feature("LOGO_DETECTION", logos) unless logos.zero?
+          f << feature("LABEL_DETECTION", labels) unless labels.zero?
+          f << feature("TEXT_DETECTION", 1) if text
+          f << feature("SAFE_SEARCH_DETECTION", 1) if safe_search
+          f << feature("IMAGE_PROPERTIES", 1) if properties
+          f
+        end
+
+        def feature type, max_results
+          Google::Apis::VisionV1::Feature.new(
+            type: type, max_results: max_results)
+        end
+
+        def default_features? faces, landmarks, logos, labels, text,
+                              safe_search, properties
+          faces == false && landmarks == false && logos == false &&
+            labels == false && text == false && safe_search == false &&
+            properties == false
+        end
+
+        def default_features
+          [
+            feature("FACE_DETECTION", Google::Cloud::Vision.default_max_faces),
+            feature("LANDMARK_DETECTION",
+                    Google::Cloud::Vision.default_max_landmarks),
+            feature("LOGO_DETECTION", Google::Cloud::Vision.default_max_logos),
+            feature("LABEL_DETECTION",
+                    Google::Cloud::Vision.default_max_labels),
+            feature("TEXT_DETECTION", 1),
+            feature("SAFE_SEARCH_DETECTION", 1),
+            feature("IMAGE_PROPERTIES", 1)
+          ]
+        end
+
+        def validate_max_values faces, landmarks, logos, labels
+          faces     = validate_max_value(
+            faces, Google::Cloud::Vision.default_max_faces)
+          landmarks = validate_max_value(
+            landmarks, Google::Cloud::Vision.default_max_landmarks)
+          logos     = validate_max_value(
+            logos, Google::Cloud::Vision.default_max_logos)
+          labels    = validate_max_value(
+            labels, Google::Cloud::Vision.default_max_labels)
+          [faces, landmarks, logos, labels]
+        end
+
+        def validate_max_value value, default_value
+          return value.to_int if value.respond_to? :to_int
+          return default_value if value
+          0 # not a number, not a truthy value
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,449 @@
+# 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/face"
+require "google/cloud/vision/annotation/entity"
+require "google/cloud/vision/annotation/text"
+require "google/cloud/vision/annotation/safe_search"
+require "google/cloud/vision/annotation/properties"
+
+module Google
+  module Cloud
+    module Vision
+      ##
+      # # Annotation
+      #
+      # The results of all requested image annotations.
+      #
+      # See {Project#annotate} and {Image}.
+      #
+      # @example
+      #   require "google/cloud"
+      #
+      #   gcloud = Google::Cloud.new
+      #   vision = gcloud.vision
+      #   image = vision.image "path/to/face.jpg"
+      #
+      #   annotation = vision.annotate image, faces: true, labels: true
+      #   annotation.faces.count #=> 1
+      #   annotation.labels.count #=> 4
+      #   annotation.text #=> nil
+      #
+      class Annotation
+        ##
+        # @private The AnnotateImageResponse Google API Client object.
+        attr_accessor :gapi
+
+        ##
+        # @private Creates a new Annotation instance.
+        def initialize
+          @gapi = nil
+        end
+
+        ##
+        # The results of face detection.
+        #
+        # @return [Array<Face>]
+        #
+        # @example
+        #   require "google/cloud"
+        #
+        #   gcloud = Google::Cloud.new
+        #   vision = gcloud.vision
+        #   image = vision.image "path/to/face.jpg"
+        #
+        #   annotation = vision.annotate image, faces: true
+        #   annotation.faces.count #=> 1
+        #   face = annotation.faces.first
+        #
+        def faces
+          @faces ||= Array(@gapi.face_annotations).map do |fa|
+            Face.from_gapi fa
+          end
+        end
+
+        ##
+        # The first face result, if there is one.
+        #
+        # @return [Face]
+        #
+        # @example
+        #   require "google/cloud"
+        #
+        #   gcloud = Google::Cloud.new
+        #   vision = gcloud.vision
+        #   image = vision.image "path/to/face.jpg"
+        #
+        #   annotation = vision.annotate image, faces: 1
+        #   face = annotation.face
+        #
+        def face
+          faces.first
+        end
+
+        ##
+        # Whether there is at least one result from face detection.
+        #
+        # @return [Boolean]
+        #
+        # @example
+        #   require "google/cloud"
+        #
+        #   gcloud = Google::Cloud.new
+        #   vision = gcloud.vision
+        #   image = vision.image "path/to/face.jpg"
+        #
+        #   annotation = vision.annotate image, faces: 1
+        #   annotation.face? #=> true
+        #
+        def face?
+          faces.count > 0
+        end
+
+        ##
+        # The results of landmark detection.
+        #
+        # @return [Array<Entity>]
+        #
+        # @example
+        #   require "google/cloud"
+        #
+        #   gcloud = Google::Cloud.new
+        #   vision = gcloud.vision
+        #   image = vision.image "path/to/landmark.jpg"
+        #
+        #   annotation = vision.annotate image, landmarks: 1
+        #   annotation.landmarks.count #=> 1
+        #   landmark = annotation.landmarks.first
+        #
+        def landmarks
+          @landmarks ||= Array(@gapi.landmark_annotations).map do |lm|
+            Entity.from_gapi lm
+          end
+        end
+
+        ##
+        # The first landmark result, if there is one.
+        #
+        # @return [Entity]
+        #
+        # @example
+        #   require "google/cloud"
+        #
+        #   gcloud = Google::Cloud.new
+        #   vision = gcloud.vision
+        #   image = vision.image "path/to/landmark.jpg"
+        #
+        #   annotation = vision.annotate image, landmarks: 1
+        #   landmark = annotation.landmark
+        #
+        def landmark
+          landmarks.first
+        end
+
+        ##
+        # Whether there is at least one result from landmark detection.
+        # detection.
+        #
+        # @return [Boolean]
+        #
+        # @example
+        #   require "google/cloud"
+        #
+        #   gcloud = Google::Cloud.new
+        #   vision = gcloud.vision
+        #   image = vision.image "path/to/landmark.jpg"
+        #
+        #   annotation = vision.annotate image, landmarks: 1
+        #   annotation.landmark? #=> true
+        #
+        def landmark?
+          landmarks.count > 0
+        end
+
+        ##
+        # The results of logo detection.
+        #
+        # @return [Array<Entity>]
+        #
+        # @example
+        #   require "google/cloud"
+        #
+        #   gcloud = Google::Cloud.new
+        #   vision = gcloud.vision
+        #   image = vision.image "path/to/logo.jpg"
+        #
+        #   annotation = vision.annotate image, logos: 1
+        #   annotation.logos.count #=> 1
+        #   logo = annotation.logos.first
+        #
+        def logos
+          @logos ||= Array(@gapi.logo_annotations).map do |lg|
+            Entity.from_gapi lg
+          end
+        end
+
+        ##
+        # The first logo result, if there is one.
+        #
+        # @return [Entity]
+        #
+        # @example
+        #   require "google/cloud"
+        #
+        #   gcloud = Google::Cloud.new
+        #   vision = gcloud.vision
+        #   image = vision.image "path/to/logo.jpg"
+        #
+        #   annotation = vision.annotate image, logos: 1
+        #   logo = annotation.logo
+        #
+        def logo
+          logos.first
+        end
+
+        ##
+        # Whether there is at least one result from logo detection.
+        # detection.
+        #
+        # @return [Boolean]
+        #
+        # @example
+        #   require "google/cloud"
+        #
+        #   gcloud = Google::Cloud.new
+        #   vision = gcloud.vision
+        #   image = vision.image "path/to/logo.jpg"
+        #
+        #   annotation = vision.annotate image, logos: 1
+        #   annotation.logo? #=> true
+        #
+        def logo?
+          logos.count > 0
+        end
+
+        ##
+        # The results of label detection.
+        #
+        # @return [Array<Entity>]
+        #
+        # @example
+        #   require "google/cloud"
+        #
+        #   gcloud = Google::Cloud.new
+        #   vision = gcloud.vision
+        #   image = vision.image "path/to/face.jpg"
+        #
+        #   annotation = vision.annotate image, labels: 1
+        #   annotation.labels.count #=> 1
+        #   label = annotation.labels.first
+        #
+        def labels
+          @labels ||= Array(@gapi.label_annotations).map do |lb|
+            Entity.from_gapi lb
+          end
+        end
+
+        ##
+        # The first label result, if there is one.
+        #
+        # @return [Entity]
+        #
+        # @example
+        #   require "google/cloud"
+        #
+        #   gcloud = Google::Cloud.new
+        #   vision = gcloud.vision
+        #   image = vision.image "path/to/face.jpg"
+        #
+        #   annotation = vision.annotate image, labels: 1
+        #   label = annotation.label
+        #
+        def label
+          labels.first
+        end
+
+        ##
+        # Whether there is at least one result from label detection.
+        # detection.
+        #
+        # @return [Boolean]
+        #
+        # @example
+        #   require "google/cloud"
+        #
+        #   gcloud = Google::Cloud.new
+        #   vision = gcloud.vision
+        #   image = vision.image "path/to/face.jpg"
+        #
+        #   annotation = vision.annotate image, labels: 1
+        #   annotation.label? #=> true
+        #
+        def label?
+          labels.count > 0
+        end
+
+        ##
+        # The results of text (OCR) detection.
+        #
+        # @return [Text]
+        #
+        # @example
+        #   require "google/cloud"
+        #
+        #   gcloud = Google::Cloud.new
+        #   vision = gcloud.vision
+        #   image = vision.image "path/to/text.png"
+        #
+        #   annotation = vision.annotate image, text: true
+        #   text = annotation.text
+        #
+        def text
+          @text ||= Text.from_gapi(@gapi.text_annotations)
+        end
+
+        ##
+        # Whether there is a result from text (OCR) detection.
+        #
+        # @return [Boolean]
+        #
+        # @example
+        #   require "google/cloud"
+        #
+        #   gcloud = Google::Cloud.new
+        #   vision = gcloud.vision
+        #   image = vision.image "path/to/text.png"
+        #
+        #   annotation = vision.annotate image, text: true
+        #   annotation.text? #=> true
+        #
+        def text?
+          !text.nil?
+        end
+
+        ##
+        # The results of safe_search detection.
+        #
+        # @return [SafeSearch]
+        #
+        # @example
+        #   require "google/cloud"
+        #
+        #   gcloud = Google::Cloud.new
+        #   vision = gcloud.vision
+        #   image = vision.image "path/to/face.jpg"
+        #
+        #   annotation = vision.annotate image, safe_search: true
+        #   safe_search = annotation.safe_search
+        #
+        def safe_search
+          return nil unless @gapi.safe_search_annotation
+          @safe_search ||= SafeSearch.from_gapi(@gapi.safe_search_annotation)
+        end
+
+        ##
+        # Whether there is a result for safe_search detection.
+        # detection.
+        #
+        # @return [Boolean]
+        #
+        # @example
+        #   require "google/cloud"
+        #
+        #   gcloud = Google::Cloud.new
+        #   vision = gcloud.vision
+        #   image = vision.image "path/to/face.jpg"
+        #
+        #   annotation = vision.annotate image, safe_search: true
+        #   annotation.safe_search? #=> true
+        #
+        def safe_search?
+          !safe_search.nil?
+        end
+
+        ##
+        # The results of properties detection.
+        #
+        # @return [Properties]
+        #
+        # @example
+        #   require "google/cloud"
+        #
+        #   gcloud = Google::Cloud.new
+        #   vision = gcloud.vision
+        #   image = vision.image "path/to/face.jpg"
+        #
+        #   annotation = vision.annotate image, properties: true
+        #   properties = annotation.properties
+        #
+        def properties
+          return nil unless @gapi.image_properties_annotation
+          @properties ||= Properties.from_gapi(
+            @gapi.image_properties_annotation)
+        end
+
+        ##
+        # Whether there is a result for properties detection.
+        #
+        # @return [Boolean]
+        #
+        # @example
+        #   require "google/cloud"
+        #
+        #   gcloud = Google::Cloud.new
+        #   vision = gcloud.vision
+        #   image = vision.image "path/to/face.jpg"
+        #
+        #   annotation = vision.annotate image, properties: true
+        #   annotation.properties? #=> true
+        #
+        def properties?
+          !properties.nil?
+        end
+
+        ##
+        # Deeply converts object to a hash. All keys will be symbolized.
+        #
+        # @return [Hash]
+        #
+        def to_h
+          { faces: faces.map(&:to_h), landmarks: landmarks.map(&:to_h),
+            logos: logos.map(&:to_h), labels: labels.map(&:to_h),
+            text: text.map(&:to_h), safe_search: safe_search.to_h,
+            properties: properties.to_h }
+        end
+
+        # @private
+        def to_s
+          tmplt = "(faces: %i, landmarks: %i, logos: %i, labels: %i," \
+                  " text: %s, safe_search: %s, properties: %s)"
+          format tmplt, faces.count, landmarks.count, logos.count, labels.count,
+                 text?, safe_search?, properties?
+        end
+
+        # @private
+        def inspect
+          "#<#{self.class.name} #{self}>"
+        end
+
+        ##
+        # @private New Annotation from a Google API Client object.
+        def self.from_gapi gapi
+          new.tap { |a| a.instance_variable_set :@gapi, gapi }
+        end
+      end
+    end
+  end
+end