Class: Google::Cloud::Vision::Image

Inherits:
Object
  • Object
show all
Defined in:
lib/google/cloud/vision/image.rb,
lib/google/cloud/vision/image.rb

Overview

Image

Represents an image for the Vision service.

An Image instance can be created from 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.

See Project#image.

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 for the list of formats. Be aware that Cloud Vision sets upper limits on file size as well as 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:

require "google/cloud/vision"

vision = Google::Cloud::Vision.new

image = vision.image "path/to/text.png"

image.context.languages = ["en"]

text = image.text
text.pages.count #=> 1

See Also:

Defined Under Namespace

Classes: Context

Instance Attribute Summary collapse

Instance Method Summary collapse

Instance Attribute Details

#context ⇒ Context (readonly)

Returns the image context for the image, which accepts metadata values such as location and language hints.

Returns:

  • (Context) —

    The context instance for the image.



66
67
68
 
# File 'lib/google/cloud/vision/image.rb', line 66

def context
  @context
end

Instance Method Details

#annotate(faces: false, landmarks: false, logos: false, labels: false, text: false, document: false, safe_search: false, properties: false, crop_hints: false, web: false) ⇒ Annotation Also known as: mark, detect

Performs detection of Cloud Vision features on the image. 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.

Examples:

require "google/cloud/vision"

vision = Google::Cloud::Vision.new

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

annotation = image.annotate labels: true, landmarks: true

annotation.labels.map &:description
# ["stone carving", "ancient history", "statue", "sculpture",
#  "monument", "landmark"]
annotation.landmarks.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 = image.annotate labels: 3, landmarks: 3

annotation.labels.map &:description
# ["stone carving", "ancient history", "statue"]
annotation.landmarks.count #=> 1

Parameters:

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

Returns:

See Also:



514
515
516
517
518
519
520
521
522
523
 
# File 'lib/google/cloud/vision/image.rb', line 514

def annotate faces: false, landmarks: false, logos: false,
             labels: false, text: false, document: false,
             safe_search: false, properties: false, crop_hints: false,
             web: false
  @vision.annotate(self, faces: faces, landmarks: landmarks,
                         logos: logos, labels: labels, text: text,
                         document: document, safe_search: safe_search,
                         properties: properties, crop_hints: crop_hints,
                         web: web)
end

#crop_hints(max_results = Vision.default_max_crop_hints) ⇒ Array<Annotation::CropHint>

Performs the CROP_HINTS feature on the image.

Examples:

require "google/cloud/vision"

vision = Google::Cloud::Vision.new
image = vision.image "path/to/face.jpg"

crop_hints = image.crop_hints
crop_hints.count #=> 1
crop_hint = crop_hints.first

crop_hint.bounds.count #=> 4
crop_hint.confidence #=> 1.0
crop_hint.importance_fraction #=> 1.0399999618530273

Returns:

See Also:



397
398
399
400
401
 
# File 'lib/google/cloud/vision/image.rb', line 397

def crop_hints max_results = Vision.default_max_crop_hints
  ensure_vision!
  annotation = @vision.mark self, crop_hints: max_results
  annotation.crop_hints
end

#document ⇒ Annotation::Text

Performs the DOCUMENT_TEXT_DETECTION feature (OCR for longer documents with dense text) on the image.

Examples:

require "google/cloud/vision"

vision = Google::Cloud::Vision.new
image = vision.image "path/to/text.png"

text = image.document

text.text
# "Google Cloud Client for Ruby an idiomatic, intuitive... "

text.words[0].text #=> "Google"
text.words[0].bounds.count #=> 4
vertex = text.words[0].bounds.first
vertex.x #=> 13
vertex.y #=> 8

# Use `pages` to access a full structural representation
page = text.pages.first
page.blocks[0].paragraphs[0].words[0].symbols[0].text #=> "G"

Returns:

See Also:



317
318
319
320
321
 
# File 'lib/google/cloud/vision/image.rb', line 317

def document
  ensure_vision!
  annotation = @vision.mark self, document: true
  annotation.text
end

#face ⇒ Annotation::Face

Performs the FACE_DETECTION feature on the image and returns only the first result.

Returns:



127
128
129
 
# File 'lib/google/cloud/vision/image.rb', line 127

def face
  faces(1).first
end

#faces(max_results = Vision.default_max_faces) ⇒ Array<Annotation::Face>

Performs the FACE_DETECTION feature on the image.

Examples:

require "google/cloud/vision"

vision = Google::Cloud::Vision.new
image = vision.image "path/to/face.jpg"

faces = image.faces

face = faces.first
face.bounds.face.count #=> 4
vertex = face.bounds.face.first
vertex.x #=> 28
vertex.y #=> 40

Parameters:

Returns:

See Also:



115
116
117
118
119
 
# File 'lib/google/cloud/vision/image.rb', line 115

def faces max_results = Vision.default_max_faces
  ensure_vision!
  annotation = @vision.mark self, faces: max_results
  annotation.faces
end

#label ⇒ Annotation::Entity

Performs the LABEL_DETECTION feature on the image and returns only the first result.

Returns:



245
246
247
 
# File 'lib/google/cloud/vision/image.rb', line 245

def label
  labels(1).first
end

#labels(max_results = Vision.default_max_labels) ⇒ Array<Annotation::Entity>

Performs the LABEL_DETECTION feature on the image.

Examples:

require "google/cloud/vision"

vision = Google::Cloud::Vision.new
image = vision.image "path/to/landmark.jpg"

labels = image.labels

labels.count #=> 4
label = labels.first
label.score #=> 0.9481348991394043
label.description #=> "stone carving"
label.mid #=> "/m/02wtjj"

Parameters:

Returns:

See Also:



233
234
235
236
237
 
# File 'lib/google/cloud/vision/image.rb', line 233

def labels max_results = Vision.default_max_labels
  ensure_vision!
  annotation = @vision.mark self, labels: max_results
  annotation.labels
end

#landmark ⇒ Annotation::Entity

Performs the LANDMARK_DETECTION feature on the image and returns only the first result.

Returns:



166
167
168
 
# File 'lib/google/cloud/vision/image.rb', line 166

def landmark
  landmarks(1).first
end

#landmarks(max_results = Vision.default_max_landmarks) ⇒ Array<Annotation::Entity>

Performs the LANDMARK_DETECTION feature on the image.

Examples:

require "google/cloud/vision"

vision = Google::Cloud::Vision.new
image = vision.image "path/to/landmark.jpg"

landmarks = image.landmarks

landmark = landmarks.first
landmark.score #=> 0.9191226363182068
landmark.description #=> "Mount Rushmore"
landmark.mid #=> "/m/019dvv"

Parameters:

Returns:

See Also:



154
155
156
157
158
 
# File 'lib/google/cloud/vision/image.rb', line 154

def landmarks max_results = Vision.default_max_landmarks
  ensure_vision!
  annotation = @vision.mark self, landmarks: max_results
  annotation.landmarks
end

#logo ⇒ Annotation::Entity

Performs the LOGO_DETECTION feature on the image and returns only the first result.

Returns:



205
206
207
 
# File 'lib/google/cloud/vision/image.rb', line 205

def 
  logos(1).first
end

#logos(max_results = Vision.default_max_logos) ⇒ Array<Annotation::Entity>

Performs the LOGO_DETECTION feature on the image.

Examples:

require "google/cloud/vision"

vision = Google::Cloud::Vision.new
image = vision.image "path/to/logo.jpg"

logos = image.logos

 = logos.first
.score #=> 0.7005731463432312
.description #=> "Google"
.mid #=> "/m/0b34hf"

Parameters:

Returns:

See Also:



193
194
195
196
197
 
# File 'lib/google/cloud/vision/image.rb', line 193

def logos max_results = Vision.default_max_logos
  ensure_vision!
  annotation = @vision.mark self, logos: max_results
  annotation.logos
end

#properties ⇒ Annotation::Properties

Performs the IMAGE_PROPERTIES feature on the image.

Examples:

require "google/cloud/vision"

vision = Google::Cloud::Vision.new
image = vision.image "path/to/logo.jpg"

properties = image.properties

properties.colors.count #=> 10
color = properties.colors.first
color.red #=> 247.0
color.green #=> 236.0
color.blue #=> 20.0

Returns:

See Also:



369
370
371
372
373
 
# File 'lib/google/cloud/vision/image.rb', line 369

def properties
  ensure_vision!
  annotation = @vision.mark self, properties: true
  annotation.properties
end

#safe_search ⇒ Annotation::SafeSearch

Performs the SAFE_SEARCH_DETECTION feature on the image.

Examples:

require "google/cloud/vision"

vision = Google::Cloud::Vision.new
image = vision.image "path/to/face.jpg"

safe_search = image.safe_search

safe_search.spoof? #=> false
safe_search.spoof #=> :VERY_UNLIKELY

Returns:

See Also:



341
342
343
344
345
 
# File 'lib/google/cloud/vision/image.rb', line 341

def safe_search
  ensure_vision!
  annotation = @vision.mark self, safe_search: true
  annotation.safe_search
end

#text ⇒ Annotation::Text

Performs the TEXT_DETECTION feature (OCR for shorter documents with sparse text) on the image.

Examples:

require "google/cloud/vision"

vision = Google::Cloud::Vision.new
image = vision.image "path/to/text.png"

text = image.text

text.text
# "Google Cloud Client for Ruby an idiomatic, intuitive... "

text.locale #=> "en"
text.words.count #=> 28
text.words[0].text #=> "Google"
text.words[0].bounds.count #=> 4
vertex = text.words[0].bounds.first
vertex.x #=> 13
vertex.y #=> 8

# Use `pages` to access a full structural representation
page = text.pages.first
page.blocks[0].paragraphs[0].words[0].symbols[0].text #=> "G"

Returns:

See Also:



281
282
283
284
285
 
# File 'lib/google/cloud/vision/image.rb', line 281

def text
  ensure_vision!
  annotation = @vision.mark self, text: true
  annotation.text
end

#web(max_results = Vision.default_max_web) ⇒ Annotation::Web

Performs the WEB_ANNOTATION feature on the image.

Examples:

require "google/cloud/vision"

vision = Google::Cloud::Vision.new
image = vision.image "path/to/face.jpg"

web = image.web

entity = web.entities.first
entity.entity_id #=> "/m/019dvv"
entity.score #=> 107.34591674804688
entity.description #=> "Mount Rushmore National Memorial"

full_matching_image = web.full_matching_images.first
full_matching_image.url #=> "http://example.com/images/123.jpg"
full_matching_image.score #=> 0.10226666927337646

page_with_matching_images = web.pages_with_matching_images.first
page_with_matching_images.url #=> "http://example.com/posts/123"
page_with_matching_images.score #=> 8.114753723144531

Returns:

See Also:



431
432
433
434
435
 
# File 'lib/google/cloud/vision/image.rb', line 431

def web max_results = Vision.default_max_web
  ensure_vision!
  annotation = @vision.mark self, web: max_results
  annotation.web
end