Module: Google::Cloud::Vision

Defined in:
lib/google/cloud/vision.rb,
lib/google/cloud/vision/v1.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/web.rb,
lib/google/cloud/vision/v1/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/crop_hint.rb,
lib/google/cloud/vision/annotation/properties.rb,
lib/google/cloud/vision/annotation/safe_search.rb,
lib/google/cloud/vision/v1/image_annotator_client.rb,
lib/google/cloud/vision/v1/doc/google/cloud/vision/v1/geometry.rb,
lib/google/cloud/vision/v1/doc/google/cloud/vision/v1/web_detection.rb,
lib/google/cloud/vision/v1/doc/google/cloud/vision/v1/image_annotator.rb,
lib/google/cloud/vision/v1/doc/google/cloud/vision/v1/text_annotation.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. Your authentication credentials are detected automatically in Google Cloud Platform environments such as Google Compute Engine, Google App Engine and Google Kubernetes Engine. In other environments you can configure authentication easily, either directly in your code or via environment variables. Read more about the options for connecting in the Authentication Guide.

Enabling Logging

To enable logging for this library, set the logger for the underlying gRPC library. The logger that you set may be a Ruby stdlib Logger as shown below, or a Google::Cloud::Logging::Logger that will write logs to Stackdriver Logging. See grpc/logconfig.rb and the gRPC spec_helper.rb for additional information.

Configuring a Ruby stdlib logger:

require "logger"

module MyLogger
  LOGGER = Logger.new $stderr, level: Logger::WARN
  def logger
    LOGGER
  end
end

# Define a gRPC module-level logger method before grpc/logconfig.rb loads.
module GRPC
  extend MyLogger
end

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 any publicly-accessible image HTTP/HTTPS URL:

require "google/cloud/vision"

vision = Google::Cloud::Vision.new

image = vision.image "https://www.example.com/images/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, publicly-accessible image HTTP/HTTPS URL, 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.pages.count #=> 1

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

Modules: V1 Classes: Annotate, Annotation, Credentials, Image, Location, Project

Constant Summary collapse

VERSION = 
"0.30.1".freeze

Class Method Summary collapse

Class Method Details

.configure {|Google::Cloud.configure.vision| ... } ⇒ Google::Cloud::Config

Configure the Google Cloud Vision library.

The following Vision configuration parameters are supported:

  • project_id - (String) Identifier for a Vision project. (The parameter project is considered deprecated, but may also be used.)
  • credentials - (String, Hash, Google::Auth::Credentials) The path to the keyfile as a String, the contents of the keyfile as a Hash, or a Google::Auth::Credentials object. (See Credentials) (The parameter keyfile is considered deprecated, but may also be used.)
  • scope - (String, Array) The OAuth 2.0 scopes controlling the set of resources and operations that the connection can access.
  • timeout - (Integer) Default timeout to use in requests.
  • client_config - (Hash) A hash of values to override the default behavior of the API client.
  • default_max_faces - (Integer) The default max results to return for facial detection requests. See default_max_faces=.
  • default_max_landmarks - (Integer) The default max results to return for landmark detection requests. See default_max_landmarks=.
  • default_max_logos - (Integer) The default max results to return for logo detection requests. See default_max_logos=.
  • default_max_labels - (Integer) The default max results to return for label detection requests. See default_max_labels=.
  • default_max_crop_hints - (Integer) The default max results to return for crop hints detection requests. See default_max_crop_hints=.
  • default_max_web - (Integer) The default max results to return for web detection requests. See default_max_faces=.

Yields:

Returns:

  • (Google::Cloud::Config) —

    The configuration object the Google::Cloud::Vision library uses.



760
761
762
763
764
 
# File 'lib/google/cloud/vision.rb', line 760

def self.configure
  yield Google::Cloud.configure.vision if block_given?

  Google::Cloud.configure.vision
end

.default_max_crop_hints ⇒ Object

The default max results to return for crop hints detection requests.



594
595
596
 
# File 'lib/google/cloud/vision.rb', line 594

def default_max_crop_hints
  configure.default_max_crop_hints
end

.default_max_crop_hints=(value) ⇒ Object

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

The default value is 100.

This is also available on the configuration as Google::Cloud::Vision.configure.default_max_crop_hints

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_crop_hints #=> 100

img = "path/to/landmarks.jpg"
annotation = vision.annotate img, crop_hints: true
# This is the same as calling
# annotation = vision.annotate img, crop_hints: 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_crop_hints = 5

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

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

require "google/cloud/vision"

vision = Google::Cloud::Vision.new

Google::Cloud::Vision.default_max_crop_hints #=> 100

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

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

require "google/cloud/vision"

vision = Google::Cloud::Vision.new

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

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


587
588
589
 
# File 'lib/google/cloud/vision.rb', line 587

def default_max_crop_hints= value
  configure.default_max_crop_hints = value
end

.default_max_faces ⇒ Object

The default max results to return for face detection requests.



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

def default_max_faces
  configure.default_max_faces
end

.default_max_faces=(value) ⇒ 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.

This is also available on the configuration as Google::Cloud::Vision.configure.default_max_faces

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


315
316
317
 
# File 'lib/google/cloud/vision.rb', line 315

def default_max_faces= value
  configure.default_max_faces = value
end

.default_max_labels ⇒ Object

The default max results to return for label detection requests.



525
526
527
 
# File 'lib/google/cloud/vision.rb', line 525

def default_max_labels
  configure.default_max_labels
end

.default_max_labels=(value) ⇒ 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.

This is also available on the configuration as Google::Cloud::Vision.configure.default_max_labels

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


518
519
520
 
# File 'lib/google/cloud/vision.rb', line 518

def default_max_labels= value
  configure.default_max_labels = value
end

.default_max_landmarks ⇒ Object

The default max results to return for landmark detection requests.



391
392
393
 
# File 'lib/google/cloud/vision.rb', line 391

def default_max_landmarks
  configure.default_max_landmarks
end

.default_max_landmarks=(value) ⇒ 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.

This is also available on the configuration as Google::Cloud::Vision.configure.default_max_landmarks

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


384
385
386
 
# File 'lib/google/cloud/vision.rb', line 384

def default_max_landmarks= value
  configure.default_max_landmarks = value
end

.default_max_logos ⇒ Object

The default max results to return for logo detection requests.



458
459
460
 
# File 'lib/google/cloud/vision.rb', line 458

def default_max_logos
  configure.default_max_logos
end

.default_max_logos=(value) ⇒ 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.

This is also available on the configuration as Google::Cloud::Vision.configure.default_max_logos

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


451
452
453
 
# File 'lib/google/cloud/vision.rb', line 451

def default_max_logos= value
  configure.default_max_logos = value
end

.default_max_web ⇒ Object

The default max results to return for web detection requests.



663
664
665
 
# File 'lib/google/cloud/vision.rb', line 663

def default_max_web
  configure.default_max_web
end

.default_max_web=(value) ⇒ Object

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

The default value is 100.

This is also available on the configuration as Google::Cloud::Vision.configure.default_max_web

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_web #=> 100

img = "path/to/landmarks.jpg"
annotation = vision.annotate img, web: true
# This is the same as calling
# annotation = vision.annotate img, web: 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_web = 5

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

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

require "google/cloud/vision"

vision = Google::Cloud::Vision.new

Google::Cloud::Vision.default_max_web #=> 100

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

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

require "google/cloud/vision"

vision = Google::Cloud::Vision.new

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

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


656
657
658
 
# File 'lib/google/cloud/vision.rb', line 656

def default_max_web= value
  configure.default_max_web = value
end

.new(project_id: nil, credentials: nil, scope: nil, timeout: nil, client_config: nil, project: nil, keyfile: 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_id (String) —

    Project identifier for the Vision service you are connecting to. If not present, the default project for the credentials is used.

  • credentials (String, Hash, Google::Auth::Credentials) —

    The path to the keyfile as a String, the contents of the keyfile as a Hash, or a Google::Auth::Credentials object. (See Credentials)

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

  • project (String) —

    Alias for the project_id argument. Deprecated.

  • keyfile (String) —

    Alias for the credentials argument. Deprecated.

Returns:

Raises:

  • (ArgumentError) 


705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
 
# File 'lib/google/cloud/vision.rb', line 705

def self.new project_id: nil, credentials: nil, scope: nil, timeout: nil,
             client_config: nil, project: nil, keyfile: nil
  project_id ||= (project || default_project_id)
  project_id = project_id.to_s # Always cast to a string
  raise ArgumentError, "project_id is missing" if project_id.empty?

  scope ||= configure.scope
  timeout ||= configure.timeout
  client_config ||= configure.client_config
  credentials ||= (keyfile || default_credentials(scope: scope))
  unless credentials.is_a? Google::Auth::Credentials
    credentials = Vision::Credentials.new credentials, scope: scope
  end

  Vision::Project.new(
    Vision::Service.new(
      project_id, credentials, timeout: timeout,
                               client_config: client_config
    )
  )
end