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 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.
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"
gcloud = Google::Cloud.new
vision = gcloud.vision
image = vision.image "path/to/landmark.jpg"
Or, you can initialize the image with a Google Cloud Storage URI:
require "google/cloud"
gcloud = Google::Cloud.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.)
require "google/cloud"
gcloud = Google::Cloud.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:
require "google/cloud"
gcloud = Google::Cloud.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:
require "google/cloud"
gcloud = Google::Cloud.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[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"
gcloud = Google::Cloud.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
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"
gcloud = Google::Cloud.new
vision = gcloud.vision
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"
gcloud = Google::Cloud.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 retries and 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 also set the request timeout
value in seconds.
require "google/cloud"
gcloud = Google::Cloud.new
vision = gcloud.vision retries: 10, timeout: 120
Defined Under Namespace
Classes: Annotate, Annotation, Image, Location, Project
Constant Summary collapse
- VERSION =
"0.20.2"
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 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
.
287 288 289 |
# File 'lib/google/cloud/vision.rb', line 287 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.
466 467 468 |
# File 'lib/google/cloud/vision.rb', line 466 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.
348 349 350 |
# File 'lib/google/cloud/vision.rb', line 348 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.
407 408 409 |
# File 'lib/google/cloud/vision.rb', line 407 def default_max_logos @default_max_logos end |