google-cloud-vision 0.20.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
checksums.yaml ADDED
@@ -0,0 +1,7 @@
1
+ ---
2
+ SHA1:
3
+ metadata.gz: 28929deca6370c56d05b09b483fff6770deb6f83
4
+ data.tar.gz: ae691948673ad91305ebb0453d8e83761cb54703
5
+ SHA512:
6
+ metadata.gz: 227247c075b86cb6dfef096461e3deb3f7f5d74f0cbaae94d4f7055735eec1861328e3d2568789541eedc440c8215c5119e50073ff8a4df03676fdd1dcfca54e
7
+ data.tar.gz: ef2af9f8d7bf04555bc97d87fc260fbb5da54c27bd3f5092040ea2032f506d40c87341fac831d091d6ebb3886fc62a177dd5fe64fe0ded1daa61c08176c846fa
@@ -0,0 +1,120 @@
1
+ # Copyright 2016 Google Inc. All rights reserved.
2
+ #
3
+ # Licensed under the Apache License, Version 2.0 (the "License");
4
+ # you may not use this file except in compliance with the License.
5
+ # You may obtain a copy of the License at
6
+ #
7
+ # http://www.apache.org/licenses/LICENSE-2.0
8
+ #
9
+ # Unless required by applicable law or agreed to in writing, software
10
+ # distributed under the License is distributed on an "AS IS" BASIS,
11
+ # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12
+ # See the License for the specific language governing permissions and
13
+ # limitations under the License.
14
+
15
+ ##
16
+ # This file is here to be autorequired by bundler, so that the .bigquery and
17
+ # #bigquery methods can be available, but the library and all dependencies won't
18
+ # be loaded until required and used.
19
+
20
+
21
+ gem "google-cloud-core"
22
+ require "google/cloud"
23
+
24
+ module Google
25
+ module Cloud
26
+ ##
27
+ # Creates a new object for connecting to the Vision service.
28
+ # Each call creates a new connection.
29
+ #
30
+ # @param [String, Array<String>] scope The OAuth 2.0 scopes controlling the
31
+ # set of resources and operations that the connection can access. See
32
+ # [Using OAuth 2.0 to Access Google
33
+ # APIs](https://developers.google.com/identity/protocols/OAuth2).
34
+ #
35
+ # The default scope is:
36
+ #
37
+ # * `https://www.googleapis.com/auth/cloud-platform`
38
+ # @param [Integer] retries Number of times to retry requests on server
39
+ # error. The default value is `3`. Optional.
40
+ # @param [Integer] timeout Default timeout to use in requests. Optional.
41
+ #
42
+ # @return [Google::Cloud::Vision::Project]
43
+ #
44
+ # @example
45
+ # require "google/cloud"
46
+ #
47
+ # gcloud = Google::Cloud.new
48
+ # vision = gcloud.vision
49
+ #
50
+ # image = vision.image "path/to/landmark.jpg"
51
+ #
52
+ # landmark = image.landmark
53
+ # landmark.description #=> "Mount Rushmore"
54
+ #
55
+ # @example The default scope can be overridden with the `scope` option:
56
+ # require "google/cloud"
57
+ #
58
+ # gcloud = Google::Cloud.new
59
+ # platform_scope = "https://www.googleapis.com/auth/cloud-platform"
60
+ # vision = gcloud.vision scope: platform_scope
61
+ #
62
+ def vision scope: nil, retries: nil, timeout: nil
63
+ Google::Cloud.vision @project, @keyfile, scope: scope,
64
+ retries: (retries || @retries),
65
+ timeout: (timeout || @timeout)
66
+ end
67
+
68
+ ##
69
+ # Creates a new object for connecting to the Vision service.
70
+ # Each call creates a new connection.
71
+ #
72
+ # @param [String] project Project identifier for the Vision service you are
73
+ # connecting to.
74
+ # @param [String, Hash] keyfile Keyfile downloaded from Google Cloud. If
75
+ # file path the file must be readable.
76
+ # @param [String, Array<String>] scope The OAuth 2.0 scopes controlling the
77
+ # set of resources and operations that the connection can access. See
78
+ # [Using OAuth 2.0 to Access Google
79
+ # APIs](https://developers.google.com/identity/protocols/OAuth2).
80
+ #
81
+ # The default scope is:
82
+ #
83
+ # * `https://www.googleapis.com/auth/cloud-platform`
84
+ # @param [Integer] retries Number of times to retry requests on server
85
+ # error. The default value is `3`. Optional.
86
+ # @param [Integer] timeout Default timeout to use in requests. Optional.
87
+ #
88
+ # @return [Google::Cloud::Vision::Project]
89
+ #
90
+ # @example
91
+ # require "google/cloud/vision"
92
+ #
93
+ # gcloud = Google::Cloud.new
94
+ # vision = gcloud.vision
95
+ #
96
+ # image = vision.image "path/to/landmark.jpg"
97
+ #
98
+ # landmark = image.landmark
99
+ # landmark.description #=> "Mount Rushmore"
100
+ #
101
+ def self.vision project = nil, keyfile = nil, scope: nil, retries: nil,
102
+ timeout: nil
103
+ require "google/cloud/vision"
104
+ project ||= Google::Cloud::Vision::Project.default_project
105
+ project = project.to_s # Always cast to a string
106
+ fail ArgumentError, "project is missing" if project.empty?
107
+
108
+ if keyfile.nil?
109
+ credentials = Google::Cloud::Vision::Credentials.default scope: scope
110
+ else
111
+ credentials = Google::Cloud::Vision::Credentials.new \
112
+ keyfile, scope: scope
113
+ end
114
+
115
+ Google::Cloud::Vision::Project.new(
116
+ Google::Cloud::Vision::Service.new(
117
+ project, credentials, retries: retries, timeout: timeout))
118
+ end
119
+ end
120
+ end
@@ -0,0 +1,477 @@
1
+ # Copyright 2016 Google Inc. All rights reserved.
2
+ #
3
+ # Licensed under the Apache License, Version 2.0 (the "License");
4
+ # you may not use this file except in compliance with the License.
5
+ # You may obtain a copy of the License at
6
+ #
7
+ # http://www.apache.org/licenses/LICENSE-2.0
8
+ #
9
+ # Unless required by applicable law or agreed to in writing, software
10
+ # distributed under the License is distributed on an "AS IS" BASIS,
11
+ # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12
+ # See the License for the specific language governing permissions and
13
+ # limitations under the License.
14
+
15
+
16
+ require "google-cloud-vision"
17
+ require "google/cloud/vision/project"
18
+
19
+ module Google
20
+ module Cloud
21
+ ##
22
+ # # Google Cloud Vision
23
+ #
24
+ # Google Cloud Vision allows easy integration of vision detection features
25
+ # developer applications, including image labeling, face and landmark
26
+ # detection, optical character recognition (OCR), and tagging of explicit
27
+ # content.
28
+ #
29
+ # For more information about Cloud Vision, read the [Google Cloud Vision API
30
+ # Documentation](https://cloud.google.com/vision/docs/).
31
+ #
32
+ # The goal of google-cloud is to provide an API that is comfortable to
33
+ # Rubyists. Authentication is handled by {Google::Cloud#vision}. You can
34
+ # provide the project and credential information to connect to the Cloud
35
+ # Vision service, or if you are running on Google Compute Engine this
36
+ # configuration is taken care of for you. You can read more about the
37
+ # options for connecting in the [Authentication
38
+ # Guide](https://googlecloudplatform.github.io/google-cloud-ruby/#/docs/guides/authentication).
39
+ #
40
+ # ## Creating images
41
+ #
42
+ # The Cloud Vision API supports UTF-8, UTF-16, and UTF-32 text encodings.
43
+ # (Ruby uses UTF-8 natively, which is the default sent to the API, so unless
44
+ # you're working with text processed in different platform, you should not
45
+ # need to set the encoding type.)
46
+ # a ). Be aware that Cloud Vision sets upper
47
+ # limits on file size as well as on the total combined size of all images in
48
+ # a request. Reducing your file size can significantly improve throughput;
49
+ # however, be careful not to reduce image quality in the process. See [Best
50
+ # Practices - Image
51
+ # Sizing](https://cloud.google.com/vision/docs/image-best-practices#image_sizing)
52
+ # for current file size limits.
53
+ #
54
+ # Use {Vision::Project#image} to create images for the Cloud Vision service.
55
+ # You can provide a file path:
56
+ #
57
+ # ```ruby
58
+ # require "google/cloud"
59
+ #
60
+ # gcloud = Google::Cloud.new
61
+ # vision = gcloud.vision
62
+ #
63
+ # image = vision.image "path/to/landmark.jpg"
64
+ # ```
65
+ #
66
+ # Or, you can initialize the image with a Google Cloud Storage URI:
67
+ #
68
+ # ```ruby
69
+ # require "google/cloud"
70
+ #
71
+ # gcloud = Google::Cloud.new
72
+ # vision = gcloud.vision
73
+ #
74
+ # image = vision.image "gs://bucket-name/path_to_image_object"
75
+ # ```
76
+ #
77
+ # Creating an Image instance does not perform an API request.
78
+ #
79
+ # ## Annotating images
80
+ #
81
+ # The instance methods on {Vision::Image} invoke Cloud Vision's detection
82
+ # features individually. Each method call makes an API request. (If you want
83
+ # to run multiple features in a single request, see the examples for
84
+ # {Vision::Project#annotate}, below.)
85
+ #
86
+ # ```ruby
87
+ # require "google/cloud"
88
+ #
89
+ # gcloud = Google::Cloud.new
90
+ # vision = gcloud.vision
91
+ #
92
+ # image = vision.image "path/to/face.jpg"
93
+ #
94
+ # face = image.face
95
+ #
96
+ # face.features.to_h.count #=> 9
97
+ # face.features.eyes.left.pupil
98
+ # #=> #<Landmark (x: 190.41544, y: 84.4557, z: -1.3682901)>
99
+ # face.features.chin.center
100
+ # #=> #<Landmark (x: 233.21977, y: 189.47475, z: 19.487228)>
101
+ # ```
102
+ #
103
+ # To run multiple features on an image in a single request, pass the image
104
+ # (or a string file path or Storage URI) to {Vision::Project#annotate}:
105
+ #
106
+ # ```ruby
107
+ # require "google/cloud"
108
+ #
109
+ # gcloud = Google::Cloud.new
110
+ # vision = gcloud.vision
111
+ #
112
+ # image = vision.image "path/to/face.jpg"
113
+ #
114
+ # annotation = vision.annotate image, faces: true, labels: true
115
+ # annotation.faces.count #=> 1
116
+ # annotation.labels.count #=> 4
117
+ # ```
118
+ #
119
+ # You can also perform detection tasks on multiple images in a single
120
+ # request:
121
+ #
122
+ # ```ruby
123
+ # require "google/cloud"
124
+ #
125
+ # gcloud = Google::Cloud.new
126
+ # vision = gcloud.vision
127
+ #
128
+ # face_image = vision.image "path/to/face.jpg"
129
+ # landmark_image = vision.image "path/to/landmark.jpg"
130
+ #
131
+ # annotations = vision.annotate face_image,
132
+ # landmark_image,
133
+ # faces: true,
134
+ # landmarks: true,
135
+ # labels: true
136
+ #
137
+ # annotations[0].faces.count #=> 1
138
+ # annotations[0].landmarks.count #=> 0
139
+ # annotations[0].labels.count #=> 4
140
+ # annotations[1].faces.count #=> 1
141
+ # annotations[1].landmarks.count #=> 1
142
+ # annotations[1].labels.count #=> 6
143
+ # ```
144
+ #
145
+ # It is even possible to configure different features for multiple images in
146
+ # a single call using a block. The following example results in a single
147
+ # request to the Cloud Vision API:
148
+ #
149
+ # ```ruby
150
+ # require "google/cloud"
151
+ #
152
+ # gcloud = Google::Cloud.new
153
+ # vision = gcloud.vision
154
+ #
155
+ # face_image = vision.image "path/to/face.jpg"
156
+ # landmark_image = vision.image "path/to/landmark.jpg"
157
+ # text_image = vision.image "path/to/text.png"
158
+ #
159
+ # annotations = vision.annotate do |annotate|
160
+ # annotate.annotate face_image, faces: true, labels: true
161
+ # annotate.annotate landmark_image, landmarks: true
162
+ # annotate.annotate text_image, text: true
163
+ # end
164
+ #
165
+ # annotations[0].faces.count #=> 1
166
+ # annotations[0].labels.count #=> 4
167
+ # annotations[1].landmarks.count #=> 1
168
+ # annotations[2].text.words.count #=> 28
169
+ # ```
170
+ #
171
+ # The maximum number of results returned when performing face, landmark,
172
+ # logo, and label detection are defined by
173
+ # {Google::Cloud::Vision.default_max_faces},
174
+ # {Google::Cloud::Vision.default_max_landmarks},
175
+ # {Google::Cloud::Vision.default_max_logos}, and
176
+ # {Google::Cloud::Vision.default_max_labels}, respectively. To change the
177
+ # global defaults, you can update the configuration:
178
+ #
179
+ # ```ruby
180
+ # require "google/cloud"
181
+ #
182
+ # gcloud = Google::Cloud.new
183
+ # vision = gcloud.vision
184
+ #
185
+ # Google::Cloud::Vision.default_max_faces = 1
186
+ #
187
+ # annotation = vision.annotate "path/to/face.jpg", faces: true
188
+ # annotation.faces.count #=> 1
189
+ # ```
190
+ #
191
+ # Or, to override a default for a single method call, simply pass an
192
+ # integer instead of a flag:
193
+ #
194
+ # ```ruby
195
+ # require "google/cloud"
196
+ #
197
+ # gcloud = Google::Cloud.new
198
+ # vision = gcloud.vision
199
+ #
200
+ # image = vision.image "path/to/face.jpg"
201
+ #
202
+ # # Return just one face.
203
+ # annotation = vision.annotate image, faces: 1
204
+ # # Return up to 5 faces.
205
+ # annotation = vision.annotate image, faces: 5
206
+ # ```
207
+ #
208
+ # ## Configuring retries and timeout
209
+ #
210
+ # You can configure how many times API requests may be automatically
211
+ # retried. When an API request fails, the response will be inspected to see
212
+ # if the request meets criteria indicating that it may succeed on retry,
213
+ # such as `500` and `503` status codes or a specific internal error code
214
+ # such as `rateLimitExceeded`. If it meets the criteria, the request will be
215
+ # retried after a delay. If another error occurs, the delay will be
216
+ # increased before a subsequent attempt, until the `retries` limit is
217
+ # reached.
218
+ #
219
+ # You can also set the request `timeout` value in seconds.
220
+ #
221
+ # ```ruby
222
+ # require "google/cloud"
223
+ #
224
+ # gcloud = Google::Cloud.new
225
+ # vision = gcloud.vision retries: 10, timeout: 120
226
+ # ```
227
+ #
228
+ module Vision
229
+ class << self
230
+ ##
231
+ # The default max results to return for facial detection requests. This
232
+ # is used on {Project#annotate} as well as {Image#faces}.
233
+ #
234
+ # The default value is `100`.
235
+ #
236
+ # @example Using the default setting on {Project#annotate}:
237
+ # require "google/cloud"
238
+ #
239
+ # gcloud = Google::Cloud.new
240
+ # vision = gcloud.vision
241
+ #
242
+ # Google::Cloud::Vision.default_max_faces #=> 100
243
+ #
244
+ # annotation = vision.annotate "path/to/faces.jpg", faces: true
245
+ # # This is the same as calling
246
+ # # annotation = vision.annotate "path/to/faces.jpg", faces: 100
247
+ #
248
+ # @example Updating the default setting on {Project#annotate}:
249
+ # require "google/cloud"
250
+ #
251
+ # gcloud = Google::Cloud.new
252
+ # vision = gcloud.vision
253
+ #
254
+ # # Set a new default
255
+ # Google::Cloud::Vision.default_max_faces = 5
256
+ #
257
+ # annotation = vision.annotate "path/to/faces.jpg", faces: true
258
+ # # This is the same as calling
259
+ # # annotation = vision.annotate "path/to/faces.jpg", faces: 5
260
+ #
261
+ #
262
+ # @example Using the default setting on {Image#faces}:
263
+ # require "google/cloud"
264
+ #
265
+ # gcloud = Google::Cloud.new
266
+ # vision = gcloud.vision
267
+ #
268
+ # Google::Cloud::Vision.default_max_faces #=> 100
269
+ #
270
+ # faces = vision.image("path/to/faces.jpg").faces
271
+ # # This is the same as calling
272
+ # # faces = vision.image("path/to/faces.jpg").faces 100
273
+ #
274
+ # @example Updating the default setting on {Image#faces}:
275
+ # require "google/cloud"
276
+ #
277
+ # gcloud = Google::Cloud.new
278
+ # vision = gcloud.vision
279
+ #
280
+ # # Set a new default
281
+ # Google::Cloud::Vision.default_max_faces = 5
282
+ #
283
+ # faces = vision.image("path/to/faces.jpg").faces
284
+ # # This is the same as calling
285
+ # # faces = vision.image("path/to/faces.jpg").faces 5
286
+ #
287
+ attr_accessor :default_max_faces
288
+
289
+ ##
290
+ # The default max results to return for landmark detection requests.
291
+ # This is used on {Project#annotate} as well as {Image#landmarks}.
292
+ #
293
+ # The default value is 100.
294
+ #
295
+ # @example Using the default setting on {Project#annotate}:
296
+ # require "google/cloud"
297
+ #
298
+ # gcloud = Google::Cloud.new
299
+ # vision = gcloud.vision
300
+ #
301
+ # Google::Cloud::Vision.default_max_landmarks #=> 100
302
+ #
303
+ # img = "path/to/landmarks.jpg"
304
+ # annotation = vision.annotate img, landmarks: true
305
+ # # This is the same as calling
306
+ # # annotation = vision.annotate img, landmarks: 100
307
+ #
308
+ # @example Updating the default setting on {Project#annotate}:
309
+ # require "google/cloud"
310
+ #
311
+ # gcloud = Google::Cloud.new
312
+ # vision = gcloud.vision
313
+ #
314
+ # # Set a new default
315
+ # Google::Cloud::Vision.default_max_landmarks = 5
316
+ #
317
+ # img = "path/to/landmarks.jpg"
318
+ # annotation = vision.annotate img, landmarks: true
319
+ # # This is the same as calling
320
+ # # annotation = vision.annotate img, landmarks: 5
321
+ #
322
+ #
323
+ # @example Using the default setting on {Image#landmarks}:
324
+ # require "google/cloud"
325
+ #
326
+ # gcloud = Google::Cloud.new
327
+ # vision = gcloud.vision
328
+ #
329
+ # Google::Cloud::Vision.default_max_landmarks #=> 100
330
+ #
331
+ # landmarks = vision.image("path/to/landmarks.jpg").landmarks
332
+ # # This is the same as calling
333
+ # # landmarks = vision.image("path/to/landmarks.jpg").landmarks 100
334
+ #
335
+ # @example Updating the default setting on {Image#landmarks}:
336
+ # require "google/cloud"
337
+ #
338
+ # gcloud = Google::Cloud.new
339
+ # vision = gcloud.vision
340
+ #
341
+ # # Set a new default
342
+ # Google::Cloud::Vision.default_max_landmarks = 5
343
+ #
344
+ # landmarks = vision.image("path/to/landmarks.jpg").landmarks
345
+ # # This is the same as calling
346
+ # # landmarks = vision.image("path/to/landmarks.jpg").landmarks 5
347
+ #
348
+ attr_accessor :default_max_landmarks
349
+
350
+ ##
351
+ # The default max results to return for logo detection requests. This is
352
+ # used on {Project#annotate} as well as {Image#logos}.
353
+ #
354
+ # The default value is 100.
355
+ #
356
+ # @example Using the default setting on {Project#annotate}:
357
+ # require "google/cloud"
358
+ #
359
+ # gcloud = Google::Cloud.new
360
+ # vision = gcloud.vision
361
+ #
362
+ # Google::Cloud::Vision.default_max_logos #=> 100
363
+ #
364
+ # annotation = vision.annotate "path/to/logos.jpg", logos: true
365
+ # # This is the same as calling
366
+ # # annotation = vision.annotate "path/to/logos.jpg", logos: 100
367
+ #
368
+ # @example Updating the default setting on {Project#annotate}:
369
+ # require "google/cloud"
370
+ #
371
+ # gcloud = Google::Cloud.new
372
+ # vision = gcloud.vision
373
+ #
374
+ # # Set a new default
375
+ # Google::Cloud::Vision.default_max_logos = 5
376
+ #
377
+ # annotation = vision.annotate "path/to/logos.jpg", logos: true
378
+ # # This is the same as calling
379
+ # # annotation = vision.annotate "path/to/logos.jpg", logos: 5
380
+ #
381
+ #
382
+ # @example Using the default setting on {Image#logos}:
383
+ # require "google/cloud"
384
+ #
385
+ # gcloud = Google::Cloud.new
386
+ # vision = gcloud.vision
387
+ #
388
+ # Google::Cloud::Vision.default_max_logos #=> 100
389
+ #
390
+ # logos = vision.image("path/to/logos.jpg").logos
391
+ # # This is the same as calling
392
+ # # logos = vision.image("path/to/logos.jpg").logos 100
393
+ #
394
+ # @example Updating the default setting on {Image#logos}:
395
+ # require "google/cloud"
396
+ #
397
+ # gcloud = Google::Cloud.new
398
+ # vision = gcloud.vision
399
+ #
400
+ # # Set a new default
401
+ # Google::Cloud::Vision.default_max_logos = 5
402
+ #
403
+ # logos = vision.image("path/to/logos.jpg").logos
404
+ # # This is the same as calling
405
+ # # logos = vision.image("path/to/logos.jpg").logos 5
406
+ #
407
+ attr_accessor :default_max_logos
408
+
409
+ ##
410
+ # The default max results to return for label detection requests. This
411
+ # is used on {Project#annotate} as well as {Image#labels}.
412
+ #
413
+ # The default value is 100.
414
+ #
415
+ # @example Using the default setting on {Project#annotate}:
416
+ # require "google/cloud"
417
+ #
418
+ # gcloud = Google::Cloud.new
419
+ # vision = gcloud.vision
420
+ #
421
+ # Google::Cloud::Vision.default_max_labels #=> 100
422
+ #
423
+ # annotation = vision.annotate "path/to/labels.jpg", labels: true
424
+ # # This is the same as calling
425
+ # # annotation = vision.annotate "path/to/labels.jpg", labels: 100
426
+ #
427
+ # @example Updating the default setting on {Project#annotate}:
428
+ # require "google/cloud"
429
+ #
430
+ # gcloud = Google::Cloud.new
431
+ # vision = gcloud.vision
432
+ #
433
+ # # Set a new default
434
+ # Google::Cloud::Vision.default_max_labels = 5
435
+ #
436
+ # annotation = vision.annotate "path/to/labels.jpg", labels: true
437
+ # # This is the same as calling
438
+ # # annotation = vision.annotate "path/to/labels.jpg", labels: 5
439
+ #
440
+ #
441
+ # @example Using the default setting on {Image#labels}:
442
+ # require "google/cloud"
443
+ #
444
+ # gcloud = Google::Cloud.new
445
+ # vision = gcloud.vision
446
+ #
447
+ # Google::Cloud::Vision.default_max_labels #=> 100
448
+ #
449
+ # labels = vision.image("path/to/labels.jpg").labels
450
+ # # This is the same as calling
451
+ # # labels = vision.image("path/to/labels.jpg").labels 100
452
+ #
453
+ # @example Updating the default setting on {Image#labels}:
454
+ # require "google/cloud"
455
+ #
456
+ # gcloud = Google::Cloud.new
457
+ # vision = gcloud.vision
458
+ #
459
+ # # Set a new default
460
+ # Google::Cloud::Vision.default_max_labels = 5
461
+ #
462
+ # labels = vision.image("path/to/labels.jpg").labels
463
+ # # This is the same as calling
464
+ # # labels = vision.image("path/to/labels.jpg").labels 5
465
+ #
466
+ attr_accessor :default_max_labels
467
+ end
468
+
469
+ # Set the default values.
470
+ # Update the comments documentation when these change.
471
+ self.default_max_faces = 100
472
+ self.default_max_landmarks = 100
473
+ self.default_max_logos = 100
474
+ self.default_max_labels = 100
475
+ end
476
+ end
477
+ end