Module: Gcloud::Vision

Defined in:
lib/gcloud/vision.rb,
lib/gcloud/vision/image.rb,
lib/gcloud/vision/errors.rb,
lib/gcloud/vision/project.rb,
lib/gcloud/vision/annotate.rb,
lib/gcloud/vision/location.rb,
lib/gcloud/vision/annotation.rb,
lib/gcloud/vision/connection.rb,
lib/gcloud/vision/credentials.rb,
lib/gcloud/vision/annotation/face.rb,
lib/gcloud/vision/annotation/text.rb,
lib/gcloud/vision/annotation/entity.rb,
lib/gcloud/vision/annotation/vertex.rb,
lib/gcloud/vision/annotation/properties.rb,
lib/gcloud/vision/annotation/safe_search.rb

Overview

# 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.

For more information about Cloud Vision, read the [Google Cloud Vision API Documentation](cloud.google.com/vision/docs/).

Gcloud’s goal is to provide an API that is familiar and comfortable to Rubyists. Authentication is handled by #vision. You can provide the project and credential information to connect to the Cloud Vision service, or if you are running on Google Compute Engine this configuration is taken care of for you. You can read more about the options for connecting in the [Authentication Guide](googlecloudplatform.github.io/gcloud-ruby/#/docs/guides/authentication).

## Creating images

The Cloud Vision API supports a variety of image file formats, including JPEG, PNG8, PNG24, Animated GIF (first frame only), and RAW. See [Best Practices - Image Types](cloud.google.com/vision/docs/image-best-practices#image_types) for the complete list of formats. 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](cloud.google.com/vision/docs/image-best-practices#image_sizing) for current file size limits.

Use Project#image to create images for the Cloud Vision service. You can provide a file path:

“‘ruby require “gcloud”

gcloud = Gcloud.new vision = gcloud.vision

image = vision.image “path/to/landmark.jpg” “‘

Or, you can initialize the image with a Google Cloud Storage URI:

“‘ruby require “gcloud”

gcloud = Gcloud.new vision = gcloud.vision

image = vision.image “gs://bucket-name/path_to_image_object” “‘

Creating an Image instance does not perform an API request.

## Annotating images

The instance methods on Image invoke Cloud Vision’s detection features individually. Each method call makes an API request. (If you want to run multiple features in a single request, see the examples for Project#annotate, below.)

“‘ruby require “gcloud”

gcloud = Gcloud.new vision = gcloud.vision

image = vision.image “path/to/face.jpg”

face = image.face

face.features.to_h.count #=> 9 face.features.eyes.left.pupil #=> #<Landmark (x: 190.41544, y: 84.4557, z: -1.3682901)> face.features.chin.center #=> #<Landmark (x: 233.21977, y: 189.47475, z: 19.487228)> “‘

To run multiple features on an image in a single request, pass the image (or a string file path or Storage URI) to Project#annotate:

“‘ruby 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 “‘

You can also perform detection tasks on multiple images in a single request:

“‘ruby require “gcloud”

gcloud = Gcloud.new vision = gcloud.vision

face_image = vision.image “path/to/face.jpg” landmark_image = vision.image “path/to/landmark.jpg”

annotations = vision.annotate face_image,

landmark_image,
faces: true,
landmarks: true,
labels: true

annotations.faces.count #=> 1 annotations.landmarks.count #=> 0 annotations.labels.count #=> 4 annotations.faces.count #=> 1 annotations.landmarks.count #=> 1 annotations.labels.count #=> 6 “‘

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 “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.faces.count #=> 1 annotations.labels.count #=> 4 annotations.landmarks.count #=> 1 annotations.text.words.count #=> 28 “‘

The maximum number of results returned when performing face, landmark, logo, and label detection are defined by Vision.default_max_faces, Vision.default_max_landmarks, Vision.default_max_logos, and Vision.default_max_labels, respectively. To change the global defaults, you can update the configuration:

“‘ruby require “gcloud”

gcloud = Gcloud.new vision = gcloud.vision

Gcloud::Vision.default_max_faces = 1

annotation = vision.annotate “path/to/face.jpg”, faces: true annotation.faces.count #=> 1 “‘

Or, to override a default for a single method call, simply pass an integer instead of a flag:

“‘ruby require “gcloud”

gcloud = Gcloud.new vision = gcloud.vision

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 Backoff

The Backoff class allows users to globally configure how Cloud API requests are automatically retried in the case of some errors, such as a 500 or 503 status code, or a specific internal error code such as rateLimitExceeded.

If an API call fails, the response will be inspected to see if the call should be retried. If the response matches the criteria, then the request will be retried after a delay. If another error occurs, the delay will be increased incrementally before a subsequent attempt. The first retry will be delayed one second, the second retry two seconds, and so on.

“‘ruby require “gcloud” require “gcloud/backoff”

Gcloud::Backoff.retries = 5 # Raise the maximum number of retries from 3 “‘

Defined Under Namespace

Classes: Annotate, Annotation, ApiError, Connection, Credentials, Error, Image, Location, Project

Class Attribute Summary collapse

Class Attribute Details

.default_max_faces ⇒ Object

The default max results to return for facial detection requests. This is used on Gcloud::Vision::Project#annotate as well as Gcloud::Vision::Image#faces.

The default value is 100.

Examples:

Using the default setting on Gcloud::Vision::Project#annotate:

require "gcloud"

gcloud = Gcloud.new
vision = gcloud.vision

Gcloud::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

Updating the default setting on Gcloud::Vision::Project#annotate:

require "gcloud"

gcloud = Gcloud.new
vision = gcloud.vision

# Set a new default
Gcloud::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

Using the default setting on Gcloud::Vision::Image#faces:

require "gcloud"

gcloud = Gcloud.new
vision = gcloud.vision

Gcloud::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

Updating the default setting on Gcloud::Vision::Image#faces:

require "gcloud"

gcloud = Gcloud.new
vision = gcloud.vision

# Set a new default
Gcloud::Vision.default_max_faces = 5

faces = vision.image("path/to/faces.jpg").faces
# This is the same as calling
# faces = vision.image("path/to/faces.jpg").faces 5



321
322
323
 
# File 'lib/gcloud/vision.rb', line 321

def default_max_faces
  @default_max_faces
end

.default_max_labels ⇒ Object

The default max results to return for label detection requests. This is used on Gcloud::Vision::Project#annotate as well as Gcloud::Vision::Image#labels.

The default value is 100.

Examples:

Using the default setting on Gcloud::Vision::Project#annotate:

require "gcloud"

gcloud = Gcloud.new
vision = gcloud.vision

Gcloud::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

Updating the default setting on Gcloud::Vision::Project#annotate:

require "gcloud"

gcloud = Gcloud.new
vision = gcloud.vision

# Set a new default
Gcloud::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

Using the default setting on Gcloud::Vision::Image#labels:

require "gcloud"

gcloud = Gcloud.new
vision = gcloud.vision

Gcloud::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

Updating the default setting on Gcloud::Vision::Image#labels:

require "gcloud"

gcloud = Gcloud.new
vision = gcloud.vision

# Set a new default
Gcloud::Vision.default_max_labels = 5

labels = vision.image("path/to/labels.jpg").labels
# This is the same as calling
# labels = vision.image("path/to/labels.jpg").labels 5



498
499
500
 
# File 'lib/gcloud/vision.rb', line 498

def default_max_labels
  @default_max_labels
end

.default_max_landmarks ⇒ Object

The default max results to return for landmark detection requests. This is used on Gcloud::Vision::Project#annotate as well as Gcloud::Vision::Image#landmarks.

The default value is 100.

Examples:

Using the default setting on Gcloud::Vision::Project#annotate:

require "gcloud"

gcloud = Gcloud.new
vision = gcloud.vision

Gcloud::Vision.default_max_landmarks #=> 100

annotation = vision.annotate "path/to/landmarks.jpg", landmarks: true
# This is the same as calling
# annotation = vision.annotate "path/to/landmarks.jpg", landmarks: 100

Updating the default setting on Gcloud::Vision::Project#annotate:

require "gcloud"

gcloud = Gcloud.new
vision = gcloud.vision

# Set a new default
Gcloud::Vision.default_max_landmarks = 5

annotation = vision.annotate "path/to/landmarks.jpg", landmarks: true
# This is the same as calling
# annotation = vision.annotate "path/to/landmarks.jpg", landmarks: 5

Using the default setting on Gcloud::Vision::Image#landmarks:

require "gcloud"

gcloud = Gcloud.new
vision = gcloud.vision

Gcloud::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

Updating the default setting on Gcloud::Vision::Image#landmarks:

require "gcloud"

gcloud = Gcloud.new
vision = gcloud.vision

# Set a new default
Gcloud::Vision.default_max_landmarks = 5

landmarks = vision.image("path/to/landmarks.jpg").landmarks
# This is the same as calling
# landmarks = vision.image("path/to/landmarks.jpg").landmarks 5



380
381
382
 
# File 'lib/gcloud/vision.rb', line 380

def default_max_landmarks
  @default_max_landmarks
end

.default_max_logos ⇒ Object

The default max results to return for logo detection requests. This is used on Gcloud::Vision::Project#annotate as well as Gcloud::Vision::Image#logos.

The default value is 100.

Examples:

Using the default setting on Gcloud::Vision::Project#annotate:

require "gcloud"

gcloud = Gcloud.new
vision = gcloud.vision

Gcloud::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

Updating the default setting on Gcloud::Vision::Project#annotate:

require "gcloud"

gcloud = Gcloud.new
vision = gcloud.vision

# Set a new default
Gcloud::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

Using the default setting on Gcloud::Vision::Image#logos:

require "gcloud"

gcloud = Gcloud.new
vision = gcloud.vision

Gcloud::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

Updating the default setting on Gcloud::Vision::Image#logos:

require "gcloud"

gcloud = Gcloud.new
vision = gcloud.vision

# Set a new default
Gcloud::Vision.default_max_logos = 5

logos = vision.image("path/to/logos.jpg").logos
# This is the same as calling
# logos = vision.image("path/to/logos.jpg").logos 5



439
440
441
 
# File 'lib/gcloud/vision.rb', line 439

def default_max_logos
  @default_max_logos
end