lib/google/cloud/vision.rb in google-cloud-vision-0.20.2 vs lib/google/cloud/vision.rb in google-cloud-vision-0.21.0
- old
+ new
@@ -19,14 +19,14 @@
module Google
module Cloud
##
# # Google Cloud Vision
#
- # Google Cloud Vision allows easy integration of vision detection features
- # developer applications, including image labeling, face and landmark
- # detection, optical character recognition (OCR), and tagging of explicit
- # content.
+ # Google Cloud Vision allows developers to easily integrate vision
+ # detection features within applications, including image labeling, face
+ # and landmark detection, optical character recognition (OCR), and tagging
+ # of explicit content.
#
# For more information about Cloud Vision, read the [Google Cloud Vision API
# Documentation](https://cloud.google.com/vision/docs/).
#
# The goal of google-cloud is to provide an API that is comfortable to
@@ -46,32 +46,30 @@
# a ). Be aware that 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)
+ # Sizing](https://cloud.google.com/vision/docs/best-practices#image_sizing)
# for current file size limits.
#
# Use {Vision::Project#image} to create images for the Cloud Vision service.
# You can provide a file path:
#
# ```ruby
- # require "google/cloud"
+ # require "google/cloud/vision"
#
- # gcloud = Google::Cloud.new
- # vision = gcloud.vision
+ # vision = Google::Cloud::Vision.new
#
# image = vision.image "path/to/landmark.jpg"
# ```
#
# Or, you can initialize the image with a Google Cloud Storage URI:
#
# ```ruby
- # require "google/cloud"
+ # require "google/cloud/vision"
#
- # gcloud = Google::Cloud.new
- # vision = gcloud.vision
+ # vision = Google::Cloud::Vision.new
#
# image = vision.image "gs://bucket-name/path_to_image_object"
# ```
#
# Creating an Image instance does not perform an API request.
@@ -82,14 +80,13 @@
# features individually. Each method call makes an API request. (If you want
# to run multiple features in a single request, see the examples for
# {Vision::Project#annotate}, below.)
#
# ```ruby
- # require "google/cloud"
+ # require "google/cloud/vision"
#
- # gcloud = Google::Cloud.new
- # vision = gcloud.vision
+ # vision = Google::Cloud::Vision.new
#
# image = vision.image "path/to/face.jpg"
#
# face = image.face
#
@@ -102,14 +99,13 @@
#
# To run multiple features on an image in a single request, pass the image
# (or a string file path or Storage URI) to {Vision::Project#annotate}:
#
# ```ruby
- # require "google/cloud"
+ # require "google/cloud/vision"
#
- # gcloud = Google::Cloud.new
- # vision = gcloud.vision
+ # vision = Google::Cloud::Vision.new
#
# image = vision.image "path/to/face.jpg"
#
# annotation = vision.annotate image, faces: true, labels: true
# annotation.faces.count #=> 1
@@ -118,14 +114,13 @@
#
# You can also perform detection tasks on multiple images in a single
# request:
#
# ```ruby
- # require "google/cloud"
+ # require "google/cloud/vision"
#
- # gcloud = Google::Cloud.new
- # vision = gcloud.vision
+ # vision = Google::Cloud::Vision.new
#
# face_image = vision.image "path/to/face.jpg"
# landmark_image = vision.image "path/to/landmark.jpg"
#
# annotations = vision.annotate face_image,
@@ -145,14 +140,13 @@
# It is even possible to configure different features for multiple images in
# a single call using a block. The following example results in a single
# request to the Cloud Vision API:
#
# ```ruby
- # require "google/cloud"
+ # require "google/cloud/vision"
#
- # gcloud = Google::Cloud.new
- # vision = gcloud.vision
+ # vision = Google::Cloud::Vision.new
#
# face_image = vision.image "path/to/face.jpg"
# landmark_image = vision.image "path/to/landmark.jpg"
# text_image = vision.image "path/to/text.png"
#
@@ -175,14 +169,13 @@
# {Google::Cloud::Vision.default_max_logos}, and
# {Google::Cloud::Vision.default_max_labels}, respectively. To change the
# global defaults, you can update the configuration:
#
# ```ruby
- # require "google/cloud"
+ # require "google/cloud/vision"
#
- # gcloud = Google::Cloud.new
- # vision = gcloud.vision
+ # vision = Google::Cloud::Vision.new
#
# Google::Cloud::Vision.default_max_faces = 1
#
# annotation = vision.annotate "path/to/face.jpg", faces: true
# annotation.faces.count #=> 1
@@ -190,41 +183,30 @@
#
# Or, to override a default for a single method call, simply pass an
# integer instead of a flag:
#
# ```ruby
- # require "google/cloud"
+ # require "google/cloud/vision"
#
- # gcloud = Google::Cloud.new
- # vision = gcloud.vision
+ # vision = Google::Cloud::Vision.new
#
# image = vision.image "path/to/face.jpg"
#
# # Return just one face.
# annotation = vision.annotate image, faces: 1
# # Return up to 5 faces.
# annotation = vision.annotate image, faces: 5
# ```
#
- # ## Configuring retries and timeout
+ # ## Configuring timeout
#
- # You can configure how many times API requests may be automatically
- # retried. When an API request fails, the response will be inspected to see
- # if the request meets criteria indicating that it may succeed on retry,
- # such as `500` and `503` status codes or a specific internal error code
- # such as `rateLimitExceeded`. If it meets the criteria, the request will be
- # retried after a delay. If another error occurs, the delay will be
- # increased before a subsequent attempt, until the `retries` limit is
- # reached.
+ # You can configure the request `timeout` value in seconds.
#
- # You can also set the request `timeout` value in seconds.
- #
# ```ruby
- # require "google/cloud"
+ # require "google/cloud/vision"
#
- # gcloud = Google::Cloud.new
- # vision = gcloud.vision retries: 10, timeout: 120
+ # vision = Google::Cloud::Vision.new timeout: 120
# ```
#
module Vision
class << self
##
@@ -232,52 +214,48 @@
# is used on {Project#annotate} as well as {Image#faces}.
#
# The default value is `100`.
#
# @example Using the default setting on {Project#annotate}:
- # require "google/cloud"
+ # require "google/cloud/vision"
#
- # gcloud = Google::Cloud.new
- # vision = gcloud.vision
+ # vision = Google::Cloud::Vision.new
#
# Google::Cloud::Vision.default_max_faces #=> 100
#
# annotation = vision.annotate "path/to/faces.jpg", faces: true
# # This is the same as calling
# # annotation = vision.annotate "path/to/faces.jpg", faces: 100
#
# @example Updating the default setting on {Project#annotate}:
- # require "google/cloud"
+ # require "google/cloud/vision"
#
- # gcloud = Google::Cloud.new
- # vision = gcloud.vision
+ # vision = Google::Cloud::Vision.new
#
# # Set a new default
# Google::Cloud::Vision.default_max_faces = 5
#
# annotation = vision.annotate "path/to/faces.jpg", faces: true
# # This is the same as calling
# # annotation = vision.annotate "path/to/faces.jpg", faces: 5
#
#
# @example Using the default setting on {Image#faces}:
- # require "google/cloud"
+ # require "google/cloud/vision"
#
- # gcloud = Google::Cloud.new
- # vision = gcloud.vision
+ # vision = Google::Cloud::Vision.new
#
# Google::Cloud::Vision.default_max_faces #=> 100
#
# faces = vision.image("path/to/faces.jpg").faces
# # This is the same as calling
# # faces = vision.image("path/to/faces.jpg").faces 100
#
# @example Updating the default setting on {Image#faces}:
- # require "google/cloud"
+ # require "google/cloud/vision"
#
- # gcloud = Google::Cloud.new
- # vision = gcloud.vision
+ # vision = Google::Cloud::Vision.new
#
# # Set a new default
# Google::Cloud::Vision.default_max_faces = 5
#
# faces = vision.image("path/to/faces.jpg").faces
@@ -291,27 +269,25 @@
# This is used on {Project#annotate} as well as {Image#landmarks}.
#
# The default value is 100.
#
# @example Using the default setting on {Project#annotate}:
- # require "google/cloud"
+ # require "google/cloud/vision"
#
- # gcloud = Google::Cloud.new
- # vision = gcloud.vision
+ # vision = Google::Cloud::Vision.new
#
# Google::Cloud::Vision.default_max_landmarks #=> 100
#
# img = "path/to/landmarks.jpg"
# annotation = vision.annotate img, landmarks: true
# # This is the same as calling
# # annotation = vision.annotate img, landmarks: 100
#
# @example Updating the default setting on {Project#annotate}:
- # require "google/cloud"
+ # require "google/cloud/vision"
#
- # gcloud = Google::Cloud.new
- # vision = gcloud.vision
+ # vision = Google::Cloud::Vision.new
#
# # Set a new default
# Google::Cloud::Vision.default_max_landmarks = 5
#
# img = "path/to/landmarks.jpg"
@@ -319,26 +295,24 @@
# # This is the same as calling
# # annotation = vision.annotate img, landmarks: 5
#
#
# @example Using the default setting on {Image#landmarks}:
- # require "google/cloud"
+ # require "google/cloud/vision"
#
- # gcloud = Google::Cloud.new
- # vision = gcloud.vision
+ # vision = Google::Cloud::Vision.new
#
# Google::Cloud::Vision.default_max_landmarks #=> 100
#
# landmarks = vision.image("path/to/landmarks.jpg").landmarks
# # This is the same as calling
# # landmarks = vision.image("path/to/landmarks.jpg").landmarks 100
#
# @example Updating the default setting on {Image#landmarks}:
- # require "google/cloud"
+ # require "google/cloud/vision"
#
- # gcloud = Google::Cloud.new
- # vision = gcloud.vision
+ # vision = Google::Cloud::Vision.new
#
# # Set a new default
# Google::Cloud::Vision.default_max_landmarks = 5
#
# landmarks = vision.image("path/to/landmarks.jpg").landmarks
@@ -352,52 +326,48 @@
# used on {Project#annotate} as well as {Image#logos}.
#
# The default value is 100.
#
# @example Using the default setting on {Project#annotate}:
- # require "google/cloud"
+ # require "google/cloud/vision"
#
- # gcloud = Google::Cloud.new
- # vision = gcloud.vision
+ # vision = Google::Cloud::Vision.new
#
# Google::Cloud::Vision.default_max_logos #=> 100
#
# annotation = vision.annotate "path/to/logos.jpg", logos: true
# # This is the same as calling
# # annotation = vision.annotate "path/to/logos.jpg", logos: 100
#
# @example Updating the default setting on {Project#annotate}:
- # require "google/cloud"
+ # require "google/cloud/vision"
#
- # gcloud = Google::Cloud.new
- # vision = gcloud.vision
+ # vision = Google::Cloud::Vision.new
#
# # Set a new default
# Google::Cloud::Vision.default_max_logos = 5
#
# annotation = vision.annotate "path/to/logos.jpg", logos: true
# # This is the same as calling
# # annotation = vision.annotate "path/to/logos.jpg", logos: 5
#
#
# @example Using the default setting on {Image#logos}:
- # require "google/cloud"
+ # require "google/cloud/vision"
#
- # gcloud = Google::Cloud.new
- # vision = gcloud.vision
+ # vision = Google::Cloud::Vision.new
#
# Google::Cloud::Vision.default_max_logos #=> 100
#
# logos = vision.image("path/to/logos.jpg").logos
# # This is the same as calling
# # logos = vision.image("path/to/logos.jpg").logos 100
#
# @example Updating the default setting on {Image#logos}:
- # require "google/cloud"
+ # require "google/cloud/vision"
#
- # gcloud = Google::Cloud.new
- # vision = gcloud.vision
+ # vision = Google::Cloud::Vision.new
#
# # Set a new default
# Google::Cloud::Vision.default_max_logos = 5
#
# logos = vision.image("path/to/logos.jpg").logos
@@ -411,52 +381,48 @@
# is used on {Project#annotate} as well as {Image#labels}.
#
# The default value is 100.
#
# @example Using the default setting on {Project#annotate}:
- # require "google/cloud"
+ # require "google/cloud/vision"
#
- # gcloud = Google::Cloud.new
- # vision = gcloud.vision
+ # vision = Google::Cloud::Vision.new
#
# Google::Cloud::Vision.default_max_labels #=> 100
#
# annotation = vision.annotate "path/to/labels.jpg", labels: true
# # This is the same as calling
# # annotation = vision.annotate "path/to/labels.jpg", labels: 100
#
# @example Updating the default setting on {Project#annotate}:
- # require "google/cloud"
+ # require "google/cloud/vision"
#
- # gcloud = Google::Cloud.new
- # vision = gcloud.vision
+ # vision = Google::Cloud::Vision.new
#
# # Set a new default
# Google::Cloud::Vision.default_max_labels = 5
#
# annotation = vision.annotate "path/to/labels.jpg", labels: true
# # This is the same as calling
# # annotation = vision.annotate "path/to/labels.jpg", labels: 5
#
#
# @example Using the default setting on {Image#labels}:
- # require "google/cloud"
+ # require "google/cloud/vision"
#
- # gcloud = Google::Cloud.new
- # vision = gcloud.vision
+ # vision = Google::Cloud::Vision.new
#
# Google::Cloud::Vision.default_max_labels #=> 100
#
# labels = vision.image("path/to/labels.jpg").labels
# # This is the same as calling
# # labels = vision.image("path/to/labels.jpg").labels 100
#
# @example Updating the default setting on {Image#labels}:
- # require "google/cloud"
+ # require "google/cloud/vision"
#
- # gcloud = Google::Cloud.new
- # vision = gcloud.vision
+ # vision = Google::Cloud::Vision.new
#
# # Set a new default
# Google::Cloud::Vision.default_max_labels = 5
#
# labels = vision.image("path/to/labels.jpg").labels
@@ -470,8 +436,59 @@
# Update the comments documentation when these change.
self.default_max_faces = 100
self.default_max_landmarks = 100
self.default_max_logos = 100
self.default_max_labels = 100
+
+ ##
+ # Creates a new object for connecting to the Vision service.
+ # Each call creates a new connection.
+ #
+ # @param [String] project Project identifier for the Vision service you
+ # are connecting to.
+ # @param [String, Hash] keyfile Keyfile downloaded from Google Cloud. If
+ # file path the file must be readable.
+ # @param [String, Array<String>] scope The OAuth 2.0 scopes controlling
+ # the set of resources and operations that the connection can access.
+ # See [Using OAuth 2.0 to Access Google
+ # APIs](https://developers.google.com/identity/protocols/OAuth2).
+ #
+ # The default scope is:
+ #
+ # * `https://www.googleapis.com/auth/cloud-platform`
+ # @param [Integer] timeout Default timeout to use in requests. Optional.
+ # @param [Hash] client_config A hash of values to override the default
+ # behavior of the API client. Optional.
+ #
+ # @return [Google::Cloud::Vision::Project]
+ #
+ # @example
+ # require "google/cloud/vision"
+ #
+ # vision = Google::Cloud::Vision.new
+ #
+ # image = vision.image "path/to/landmark.jpg"
+ #
+ # landmark = image.landmark
+ # landmark.description #=> "Mount Rushmore"
+ #
+ def self.new project: nil, keyfile: nil, scope: nil, timeout: nil,
+ client_config: nil
+ project ||= Google::Cloud::Vision::Project.default_project
+ project = project.to_s # Always cast to a string
+ fail ArgumentError, "project is missing" if project.empty?
+
+ if keyfile.nil?
+ credentials = Google::Cloud::Vision::Credentials.default scope: scope
+ else
+ credentials = Google::Cloud::Vision::Credentials.new \
+ keyfile, scope: scope
+ end
+
+ Google::Cloud::Vision::Project.new(
+ Google::Cloud::Vision::Service.new(
+ project, credentials, timeout: timeout,
+ client_config: client_config))
+ end
end
end
end