Class: Google::Cloud::Vision::Project

Inherits:

Object

• Object
• Google::Cloud::Vision::Project

Defined in:

lib/google/cloud/vision/project.rb

Overview

Project

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.

See Google::Cloud#vision

Examples:

require "google/cloud/vision"

vision = Google::Cloud::Vision.new

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

annotation = vision.annotate image, labels: true

annotation.labels.map &:description
# ["stone carving", "ancient history", "statue", "sculpture",
#  "monument", "landmark"]

Instance Method Summary

• #annotate(*images, faces: false, landmarks: false, logos: false, labels: false, text: false, document: false, safe_search: false, properties: false, crop_hints: false, web: false) {|annotate| ... } ⇒ Annotation⁺ (also: #mark, #detect)

  Performs detection of Cloud Vision features on the given image(s).

• #async_batch_annotate_files(requests, options = {}) ⇒ Google::Gax::Operation

  Run asynchronous image detection and annotation for a list of generic files, such as PDF files, which may contain multiple pages and multiple images per page.

• #image(source) ⇒ Image

  Returns a new image from the given source.

• #project_id ⇒ Object (also: #project)

  The Vision project connected to.

Instance Method Details

#annotate(*images, faces: false, landmarks: false, logos: false, labels: false, text: false, document: false, safe_search: false, properties: false, crop_hints: false, web: false) {|annotate| ... } ⇒ Annotation⁺ Also known as: mark, detect

Performs detection of Cloud Vision features on the given image(s). If no options for features are provided, all image detection features will be performed, with a default of 100 results for faces, landmarks, logos, labels, crop_hints, and web. If any feature option is provided, only the specified feature detections will be performed. Please review Pricing before use, as a separate charge is incurred for each feature performed on an image.

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.

Examples:

With a single image:

require "google/cloud/vision"

vision = Google::Cloud::Vision.new

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

annotation = vision.annotate image, labels: true

annotation.labels.map &:description
# ["stone carving", "ancient history", "statue", "sculpture",
#  "monument", "landmark"]

With multiple images:

require "google/cloud/vision"

vision = Google::Cloud::Vision.new

face_img = vision.image "path/to/face.jpg"
landmark_img = vision.image "path/to/landmark.jpg"

annotations = vision.annotate face_img, landmark_img, labels: true

annotations[0].labels.count #=> 4
annotations[1].labels.count #=> 6

With multiple images and configurations passed in a block:

require "google/cloud/vision"

vision = Google::Cloud::Vision.new

face_img = vision.image "path/to/face.jpg"
landmark_img = vision.image "path/to/landmark.jpg"
text_image = vision.image "path/to/text.png"

annotations = vision.annotate do |annotate|
   annotate.annotate face_img, faces: true, labels: true
   annotate.annotate landmark_img, 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

Maximum result values can also be provided:

require "google/cloud/vision"

vision = Google::Cloud::Vision.new

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

annotation = vision.annotate image, labels: 3

annotation.labels.map &:description
# ["stone carving", "ancient history", "statue"]

Parameters:

• images (Image, Object) —

  The image or images to annotate. This can be an Image instance, or any other type that converts to an Image: A string file path, publicly-accessible image HTTP/HTTPS URL, or Cloud Storage URI of the form "gs://bucketname/path/to/image_filename"; or a File, IO, StringIO, or Tempfile instance; or an instance of Google::Cloud::Storage::File.

• faces (Boolean, Integer) —

  Whether to perform the facial detection feature. The maximum number of results is configured in Google::Cloud::Vision.default_max_faces, or may be provided here. Optional.

• landmarks (Boolean, Integer) —

  Whether to perform the landmark detection feature. The maximum number of results is configured in Google::Cloud::Vision.default_max_landmarks, or may be provided here. Optional.

• logos (Boolean, Integer) —

  Whether to perform the logo detection feature. The maximum number of results is configured in Google::Cloud::Vision.default_max_logos, or may be provided here. Optional.

• labels (Boolean, Integer) —

  Whether to perform the label detection feature. The maximum number of results is configured in Google::Cloud::Vision.default_max_labels, or may be provided here. Optional.

• text (Boolean) —

  Whether to perform the text detection feature (OCR for shorter documents with sparse text). Optional.

• document (Boolean) —

  Whether to perform the document text detection feature (OCR for longer documents with dense text). Optional.

• safe_search (Boolean) —

  Whether to perform the safe search feature. Optional.

• properties (Boolean) —

  Whether to perform the image properties feature (currently, the image's dominant colors.) Optional.

• crop_hints (Boolean, Integer) —

  Whether to perform the crop hints feature. Optional.

• web (Boolean, Integer) —

  Whether to perform the web annotation feature. Optional.

Yields:

• (annotate) —

  A block for requests that involve multiple feature configurations. See Annotate#annotate.

Yield Parameters:

• annotate (Annotate) —

  the Annotate object

Returns:

• (Annotation, Array<Annotation>) —

  The results for all image detections, returned as a single Annotation instance for one image, or as an array of Annotation instances, one per image, for multiple images.

See Also:

• Cloud Vision API Requests and Responses
• AnnotateImageRequest
• Cloud Vision Pricing

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

def annotate *images, faces: false, landmarks: false, logos: false,
             labels: false, text: false, document: false,
             safe_search: false, properties: false, crop_hints: false,
             web: false
  a = Annotate.new self
  a.annotate(*images, faces: faces, landmarks: landmarks, logos: logos,
                      labels: labels, text: text, document: document,
                      safe_search: safe_search, properties: properties,
                      crop_hints: crop_hints, web: web)

  yield a if block_given?

  grpc = service.annotate a.requests
  annotations = Array(grpc.responses).map do |g|
    raise Error.from_error(g.error) if g.error
    Annotation.from_grpc g
  end
  return annotations.first if annotations.count == 1
  annotations
end

#async_batch_annotate_files(requests, options = {}) ⇒ Google::Gax::Operation

Run asynchronous image detection and annotation for a list of generic files, such as PDF files, which may contain multiple pages and multiple images per page. Progress and results can be retrieved through the google.longrunning.Operations interface. Operation.metadata contains OperationMetadata (metadata). Operation.response contains AsyncBatchAnnotateFilesResponse (results).

Examples:

require "google/cloud/vision"

# Create a new vision client.
vision_client = Google::Cloud::Vision.new project_id: 'project_id'
requests = [{
  input_config: {
    gcs_source: { uri: 'source_uri' },
    mime_type: "application/pdf"
  },
  features: [{ type: :DOCUMENT_TEXT_DETECTION }],
  output_config: {
    gcs_destination: { uri: 'destination_uri' },
    batch_size: 2
  }
}]

# Register a callback during the method call.
operation = vision_client
  .async_batch_annotate_files(requests) do |op|
  raise op.results.message if op.error?
  op_results = op.results
  # Process the results.

  metadata = op.metadata
  # Process the metadata.
end

# Or use the return value to register a callback.
operation.on_done do |op|
  raise op.results.message if op.error?
  op_results = op.results
  # Process the results.

  metadata = op.metadata
  # Process the metadata.
end

# Manually reload the operation.
operation.reload!

# Or block until the operation completes, triggering callbacks on
# completion.
operation.wait_until_done!

Parameters:

• requests (Array<Google::Cloud::Vision::V1::AsyncAnnotateFileRequest|Hash>) —

  Individual async file annotation requests for this batch. A hash of the same form as Google::Cloud::Vision::V1::AsyncAnnotateFileRequest can also be provided.

• options (Google::Gax::CallOptions) (defaults to: {}) —

  Overrides the default settings for this call, e.g, timeout, retries, etc.

Returns:

• (Google::Gax::Operation)

Raises:

• (Google::Gax::GaxError) —

  if the RPC is aborted.

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

def async_batch_annotate_files requests, options = {}
  service.service.async_batch_annotate_files requests, options
end

#image(source) ⇒ Image

Returns a new image from the given source.

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.

Note that an object in Google Cloud Storage is a single entity; permissions affect only that object. "Directory permissions" do not exist (though default bucket permissions do exist). Make sure the code which performs your request has access to that image.

Examples:

With a 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"

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"

With a local file path:

require "google/cloud/vision"

vision = Google::Cloud::Vision.new

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

Parameters:

• source (String, IO, StringIO, Tempfile, Google::Cloud::Storage::File) —

  A string file path, publicly-accessible image HTTP/HTTPS URL, or Cloud Storage URI of the form "gs://bucketname/path/to/image_filename"; or a File, IO, StringIO, or Tempfile instance; or an instance of Google::Cloud::Storage::File.

Returns:

• (Image) —

  An image for the Vision service.

See Also:

• Best Practices

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

def image source
  return source if source.is_a? Image
  Image.from_source source, self
end

#project_id ⇒ Object Also known as: project

The Vision project connected to.

Examples:

require "google/cloud/vision"

vision = Google::Cloud::Vision.new(
  project_id: "my-project",
  credentials: "/path/to/keyfile.json"
)

vision.project_id #=> "my-project"

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

def project_id
  service.project
end