gcloud 0.12.2 → 0.20.0

data/lib/gcloud/translate/translation.rb

@@ -1,112 +0,0 @@
-# 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 Translate
-    ##
-    # # Translation
-    #
-    # Represents a translation query result. Returned by
-    # {Gcloud::Translate::Api#translate}.
-    #
-    # @see https://cloud.google.com/translate/v2/using_rest#Translate Translate
-    #   Text
-    #
-    # @example
-    #   require "gcloud"
-    #
-    #   gcloud = Gcloud.new
-    #   translate = gcloud.translate
-    #
-    #   translation = translate.translate "Hello world!", to: "la"
-    #
-    #   puts translation #=> Salve mundi!
-    #
-    #   translation.from #=> "en"
-    #   translation.origin #=> "Hello world!"
-    #   translation.to #=> "la"
-    #   translation.text #=> "Salve mundi!"
-    #
-    class Translation
-      ##
-      # The translated result.
-      #
-      # @return [String]
-      attr_reader :text
-      alias_method :to_s, :text
-      alias_method :to_str, :text
-
-      ##
-      # The original query text that was translated.
-      #
-      # @return [String]
-      attr_reader :origin
-
-      ##
-      # The target language into which the text was translated.
-      #
-      # @return [String]
-      attr_reader :to
-      alias_method :language, :to
-      alias_method :target, :to
-
-      ##
-      # The source language from which the text was translated.
-      attr_reader :from
-      alias_method :source, :from
-
-      ##
-      # @private Create a new object.
-      def initialize text, to, origin, from, detected
-        @text = text
-        @to = to
-        @origin = origin
-        @from = from
-        @detected = detected
-      end
-
-      ##
-      # Determines if the source language was detected by the Google Cloud
-      # Translate API.
-      #
-      # @return [Boolean] `true` if the source language was detected by the
-      #   Translate service, `false` if the source language was provided in the
-      #   request
-      def detected?
-        @detected
-      end
-
-      ##
-      # @private New Translation from a TranslationsListResponse object as
-      # defined by the Google API Client object.
-      def self.from_gapi_list gapi, text, to, from
-        res = text.zip(Array(gapi.translations)).map do |origin, g|
-          from_gapi g, to, origin, from
-        end
-        return res.first if res.size == 1
-        res
-      end
-
-      ##
-      # @private New Translation from a TranslationsResource object as defined
-      # by the Google API Client object.
-      def self.from_gapi gapi, to, origin, from
-        from ||= gapi.detected_source_language
-        detected = !gapi.detected_source_language.nil?
-        new gapi.translated_text, to, origin, from, detected
-      end
-    end
-  end
-end

data/lib/gcloud/vision/annotate.rb

@@ -1,224 +0,0 @@
-# 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/image"
-require "google/apis/vision_v1"
-
-module Gcloud
-  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 "gcloud"
-    #
-    #   gcloud = Gcloud.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
-      #   {Gcloud::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
-      #   {Gcloud::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
-      #   {Gcloud::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
-      #   {Gcloud::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 "gcloud"
-      #
-      #   gcloud = Gcloud.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", Gcloud::Vision.default_max_faces),
-          feature("LANDMARK_DETECTION", Gcloud::Vision.default_max_landmarks),
-          feature("LOGO_DETECTION", Gcloud::Vision.default_max_logos),
-          feature("LABEL_DETECTION", Gcloud::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, Gcloud::Vision.default_max_faces
-        landmarks = validate_max_value landmarks,
-                                       Gcloud::Vision.default_max_landmarks
-        logos     = validate_max_value logos, Gcloud::Vision.default_max_logos
-        labels    = validate_max_value labels, Gcloud::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

data/lib/gcloud/vision/annotation.rb

@@ -1,455 +0,0 @@
-# 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/face"
-require "gcloud/vision/annotation/entity"
-require "gcloud/vision/annotation/text"
-require "gcloud/vision/annotation/safe_search"
-require "gcloud/vision/annotation/properties"
-
-module Gcloud
-  module Vision
-    ##
-    # # Annotation
-    #
-    # The results of all requested image annotations.
-    #
-    # See {Project#annotate} and {Image}.
-    #
-    # @example
-    #   require "gcloud"
-    #
-    #   gcloud = Gcloud.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 "gcloud"
-      #
-      #   gcloud = Gcloud.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 "gcloud"
-      #
-      #   gcloud = Gcloud.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 "gcloud"
-      #
-      #   gcloud = Gcloud.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 "gcloud"
-      #
-      #   gcloud = Gcloud.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 "gcloud"
-      #
-      #   gcloud = Gcloud.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 "gcloud"
-      #
-      #   gcloud = Gcloud.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 "gcloud"
-      #
-      #   gcloud = Gcloud.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 "gcloud"
-      #
-      #   gcloud = Gcloud.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 "gcloud"
-      #
-      #   gcloud = Gcloud.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 "gcloud"
-      #
-      #   gcloud = Gcloud.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 "gcloud"
-      #
-      #   gcloud = Gcloud.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 "gcloud"
-      #
-      #   gcloud = Gcloud.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 "gcloud"
-      #
-      #   gcloud = Gcloud.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 "gcloud"
-      #
-      #   gcloud = Gcloud.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 "gcloud"
-      #
-      #   gcloud = Gcloud.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 "gcloud"
-      #
-      #   gcloud = Gcloud.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 "gcloud"
-      #
-      #   gcloud = Gcloud.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 "gcloud"
-      #
-      #   gcloud = Gcloud.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
-        to_hash
-      end
-
-      ##
-      # Deeply converts object to a hash. All keys will be symbolized.
-      #
-      # @return [Hash]
-      #
-      def to_hash
-        { 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