Module: Google::Cloud::Vision

Defined in:: lib/google/cloud/vision.rb,
lib/google/cloud/vision/image.rb,
lib/google/cloud/vision/project.rb,
lib/google/cloud/vision/service.rb,
lib/google/cloud/vision/version.rb,
lib/google/cloud/vision/annotate.rb,
lib/google/cloud/vision/location.rb,
lib/google/cloud/vision/annotation.rb,
lib/google/cloud/vision/credentials.rb,
lib/google/cloud/vision/annotation/face.rb,
lib/google/cloud/vision/annotation/text.rb,
lib/google/cloud/vision/annotation/entity.rb,
lib/google/cloud/vision/annotation/vertex.rb,
lib/google/cloud/vision/annotation/properties.rb,
lib/google/cloud/vision/annotation/safe_search.rb

Overview

Google Cloud Vision

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.

The goal of google-cloud is to provide an API that is 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.

Creating images

The Cloud Vision API supports UTF-8, UTF-16, and UTF-32 text encodings. (Ruby uses UTF-8 natively, which is the default sent to the API, so unless you're working with text processed in different platform, you should not need to set the encoding type.) 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 for current file size limits.

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

require "google/cloud/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:

require "google/cloud/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.

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

require "google/cloud/vision"

vision = Google::Cloud::Vision.new

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:

require "google/cloud/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
annotation.labels.count #=> 4

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

require "google/cloud/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,
                              landmark_image,
                              faces: true,
                              landmarks: true,
                              labels: true

annotations[0].faces.count #=> 1
annotations[0].landmarks.count #=> 0
annotations[0].labels.count #=> 4
annotations[1].faces.count #=> 1
annotations[1].landmarks.count #=> 1
annotations[1].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:

require "google/cloud/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"

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

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:

require "google/cloud/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

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

require "google/cloud/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 timeout

You can configure the request timeout value in seconds.

require "google/cloud/vision"

vision = Google::Cloud::Vision.new timeout: 120

Defined Under Namespace

Classes: Annotate, Annotation, Image, Location, Project

Constant Summary collapse

VERSION =

"0.21.1"

Class Attribute Summary collapse

.default_max_faces ⇒ Object
The default max results to return for facial detection requests.
.default_max_labels ⇒ Object
The default max results to return for label detection requests.
.default_max_landmarks ⇒ Object
The default max results to return for landmark detection requests.
.default_max_logos ⇒ Object
The default max results to return for logo detection requests.

Class Method Summary collapse

.new(project: nil, keyfile: nil, scope: nil, timeout: nil, client_config: nil) ⇒ Google::Cloud::Vision::Project
Creates a new object for connecting to the Vision service.

Class Attribute Details

.default_max_faces ⇒ `Object`

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

The default value is 100.

Examples:

Using the default setting on Google::Cloud::Vision::Project#annotate:

require "google/cloud/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

Updating the default setting on Google::Cloud::Vision::Project#annotate:

require "google/cloud/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

Using the default setting on Google::Cloud::Vision::Image#faces:

require "google/cloud/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

Updating the default setting on Google::Cloud::Vision::Image#faces:

require "google/cloud/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
# This is the same as calling
# faces = vision.image("path/to/faces.jpg").faces 5



265
266
267

# File 'lib/google/cloud/vision.rb', line 265

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 Google::Cloud::Vision::Project#annotate as well as Google::Cloud::Vision::Image#labels.

The default value is 100.

Examples:

Using the default setting on Google::Cloud::Vision::Project#annotate:

require "google/cloud/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

Updating the default setting on Google::Cloud::Vision::Project#annotate:

require "google/cloud/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

Using the default setting on Google::Cloud::Vision::Image#labels:

require "google/cloud/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

Updating the default setting on Google::Cloud::Vision::Image#labels:

require "google/cloud/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
# This is the same as calling
# labels = vision.image("path/to/labels.jpg").labels 5



432
433
434

# File 'lib/google/cloud/vision.rb', line 432

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 Google::Cloud::Vision::Project#annotate as well as Google::Cloud::Vision::Image#landmarks.

The default value is 100.

Examples:

Using the default setting on Google::Cloud::Vision::Project#annotate:

require "google/cloud/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

Updating the default setting on Google::Cloud::Vision::Project#annotate:

require "google/cloud/vision"

vision = Google::Cloud::Vision.new

# Set a new default
Google::Cloud::Vision.default_max_landmarks = 5

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

Using the default setting on Google::Cloud::Vision::Image#landmarks:

require "google/cloud/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

Updating the default setting on Google::Cloud::Vision::Image#landmarks:

require "google/cloud/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
# This is the same as calling
# landmarks = vision.image("path/to/landmarks.jpg").landmarks 5



322
323
324

# File 'lib/google/cloud/vision.rb', line 322

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 Google::Cloud::Vision::Project#annotate as well as Google::Cloud::Vision::Image#logos.

The default value is 100.

Examples:

Using the default setting on Google::Cloud::Vision::Project#annotate:

require "google/cloud/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

Updating the default setting on Google::Cloud::Vision::Project#annotate:

require "google/cloud/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

Using the default setting on Google::Cloud::Vision::Image#logos:

require "google/cloud/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

Updating the default setting on Google::Cloud::Vision::Image#logos:

require "google/cloud/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
# This is the same as calling
# logos = vision.image("path/to/logos.jpg").logos 5



377
378
379

# File 'lib/google/cloud/vision.rb', line 377

def default_max_logos
  @default_max_logos
end

Class Method Details

.new(project: nil, keyfile: nil, scope: nil, timeout: nil, client_config: nil) ⇒ `Google::Cloud::Vision::Project`

Creates a new object for connecting to the Vision service. Each call creates a new connection.

Examples:

require "google/cloud/vision"

vision = Google::Cloud::Vision.new

image = vision.image "path/to/landmark.jpg"

landmark = image.landmark
landmark.description #=> "Mount Rushmore"

Parameters:

project (String) —
Project identifier for the Vision service you are connecting to.
keyfile (String, Hash) —
Keyfile downloaded from Google Cloud. If file path the file must be readable.
scope (String, Array<String>) —
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.

The default scope is:
- https://www.googleapis.com/auth/cloud-platform
timeout (Integer) —
Default timeout to use in requests. Optional.
client_config (Hash) —
A hash of values to override the default behavior of the API client. Optional.

Returns:

(Google::Cloud::Vision::Project)

# File 'lib/google/cloud/vision.rb', line 474

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

Module: Google::Cloud::Vision

Overview

Google Cloud Vision

Creating images

Annotating images

Configuring timeout

Defined Under Namespace

Constant Summary collapse

Class Attribute Summary collapse

Class Method Summary collapse

Class Attribute Details

.default_max_faces ⇒ Object

.default_max_labels ⇒ Object

.default_max_landmarks ⇒ Object

.default_max_logos ⇒ Object

Class Method Details

.new(project: nil, keyfile: nil, scope: nil, timeout: nil, client_config: nil) ⇒ Google::Cloud::Vision::Project

.default_max_faces ⇒ `Object`

.default_max_labels ⇒ `Object`

.default_max_landmarks ⇒ `Object`

.default_max_logos ⇒ `Object`

.new(project: nil, keyfile: nil, scope: nil, timeout: nil, client_config: nil) ⇒ `Google::Cloud::Vision::Project`