gcloud 0.9.0 → 0.10.0

checksums.yaml

@@ -1,15 +1,15 @@
 ---
 !binary "U0hBMQ==":
   metadata.gz: !binary |-
-    OGM0OTdkYTJmYjlhOTU0NWFjYjEzZmI2ZGJmZDBhMGQ5NzJhODY1OQ==
+    ZDg1NjYxMTkxZjIxYmUzNmMyZGMzNDNlY2Y1MGZiZWYwNWYzZTdjOQ==
   data.tar.gz: !binary |-
-    NDgxNGI1OTM3MTMwZGY5ZmQ4NzcxZWZkMjg4YTM2MTg1ZDMyMWRjMw==
+    ZDQwZjAxZGRmZmY4MmNlNGE1NmJiMTc3MTFkYWVmODkzNmFkZmU4Yw==
 SHA512:
   metadata.gz: !binary |-
-    YTFmYTY4YmRhOWJiMjJmMWU5OWM2YmZmODE1ZGQ0NmQ0MTgyNmExOTdhN2E1
-    NGU4OTAyODg3NTUwOWM1YzVmYjQwNThmMDdmNmQzYjU0YTA3NGVhOGQ5ZmFk
-    ZjE1OGFiMDcxZjFmZGFhNzkzMjhmMGIxZGNhYjhmMWQ0YzRlOTU=
+    YzkwYWVjYWZhYTJjMjY2NWM0ZWFjYmNkZDI3YzBiZjc4YTcwOTVjYjhkZTBk
+    ZmVjMDE4YmQ5Mjc3YmViMzZlNWExOTllMzRmYTE0NTJiMDNkYjI2MDlmMmJk
+    OWU0N2UzODJlYWI3NjU5NDAwODQ2MjAzMDZkODAwMjVmYTEzYTk=
   data.tar.gz: !binary |-
-    NDQxZmMxNTk5NjAwODA3ZDg5NGM5NjVkZDBmY2Q1OWIxYWM3OGIwNzQ2OTE0
-    ZDA5MjNlNzgxODMyY2MyNWM3NmJmZGZjZjdhZGJlYTNlZWQ4MmRkNzA2NTk1
-    OGYxNTVlNjk4ZWUzN2M0YTFkNDY2Yjk3MDY4MTUzNDM1MWVlOTI=
+    ZTEzMjg3Y2M5ZTAzNjk5MGRjYzZjOTE2ZGQyZjljOTljYjI2NDczMjhkMTgw
+    OWZiZTZiNTg1YjI3ODU3NGY3NzIxMTBjN2Y2YmI1N2IzNTViMjc4MTNhOTFl
+    MWZjMzFkZjFkOTM1NDM2YjU4MWM5ODEwNDdmMWJjNDVhOWQ3MGY=

data/CHANGELOG.md

@@ -1,5 +1,22 @@
 # Release History
 
+### 0.10.0 / 2016-05-19
+
+#### Major Changes
+
+* Add Vision service implementation
+
+#### Minor Changes
+
+* BigQuery
+  * Restore chunk_size argument on Gcloud::Bigquery::Table#load (gramos74)
+* Storage
+  * Gcloud::Storage::Bucket#create_file now uses default chunk_size
+* Datastore
+  * Fixed documentation (bmclean)
+* Add Gcloud::Upload.default_chunk_size
+* Pegged dependency to google-protobuf version 3.0.0.alpha.5.0.5.1
+
 ### 0.9.0 / 2016-05-11
 
 #### Major Changes

data/OVERVIEW.md

@@ -239,3 +239,21 @@ translation.to #=> "la"
 translation.text #=> "Salve mundi!"
 ```
 
+# Vision
+
+[Google Cloud Vision](https://cloud.google.com/vision/) ([docs](https://cloud.google.com/vision/docs)) 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 the {Gcloud::Vision gcloud-ruby Cloud Vision API documentation} to learn how to connect to Google Cloud Vision using this library.
+
+```ruby
+require "gcloud"
+
+gcloud = Gcloud.new
+vision = gcloud.vision
+
+image = vision.image "path/to/landmark.jpg"
+
+landmark = image.landmark
+landmark.description #=> "Mount Rushmore"
+```
+

data/lib/gcloud.rb

@@ -387,4 +387,42 @@ module Gcloud
     require "gcloud/translate"
     Gcloud.translate key
   end
+
+  ##
+  # Creates a new object for connecting to the Vision service.
+  # Each call creates a new connection.
+  #
+  # @param [String, Array<String>] scope 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](https://developers.google.com/identity/protocols/OAuth2).
+  #
+  #   The default scope is:
+  #
+  #   * `https://www.googleapis.com/auth/cloud-platform`
+  #
+  # @return [Gcloud::Vision::Project]
+  #
+  # @example
+  #   require "gcloud"
+  #
+  #   gcloud = Gcloud.new
+  #   vision = gcloud.vision
+  #
+  #   image = vision.image "path/to/landmark.jpg"
+  #
+  #   landmark = image.landmark
+  #   landmark.description #=> "Mount Rushmore"
+  #
+  # @example The default scope can be overridden with the `scope` option:
+  #   require "gcloud"
+  #
+  #   gcloud  = Gcloud.new
+  #   platform_scope = "https://www.googleapis.com/auth/cloud-platform"
+  #   vision = gcloud.vision scope: platform_scope
+  #
+  def vision scope: nil
+    require "gcloud/vision"
+    Gcloud.vision @project, @keyfile, scope: scope
+  end
 end

data/lib/gcloud/bigquery/table.rb

@@ -600,6 +600,11 @@ module Gcloud
       # See [Loading Data with a POST Request](
       # https://cloud.google.com/bigquery/loading-data-post-request#multipart).
       #
+      # A `chunk_size` value can be provided in the options to be used in
+      # resumable uploads. This value is the number of bytes per chunk and must
+      # be divisible by 256KB. If it is not divisible by 256KB then it will be
+      # lowered to the nearest acceptable value.
+      #
       # @param [File, Gcloud::Storage::File, String] file A file or the URI of a
       #   Google Cloud Storage file containing data to load into the table.
       # @param [String] format The exported file format. The default value is
@@ -678,6 +683,10 @@ module Gcloud
       #   file that BigQuery will skip when loading the data. The default value
       #   is `0`. This property is useful if you have header rows in the file
       #   that should be skipped.
+      # @param [Integer] chunk_size The number of bytes per chunk in a resumable
+      #   upload. Must be divisible by 256KB. If it is not divisible by 265KB
+      #   then it will be lowered to the nearest acceptable value. If no value
+      #   is provided it will use {Gcloud::Upload.default_chunk_size}. Optional.
       #
       # @return [Gcloud::Bigquery::LoadJob]
       #
@@ -748,13 +757,14 @@ module Gcloud
       def load file, format: nil, create: nil, write: nil,
                projection_fields: nil, jagged_rows: nil, quoted_newlines: nil,
                encoding: nil, delimiter: nil, ignore_unknown: nil,
-               max_bad_records: nil, quote: nil, skip_leading: nil, dryrun: nil
+               max_bad_records: nil, quote: nil, skip_leading: nil, dryrun: nil,
+               chunk_size: nil
         ensure_connection!
         options = { format: format, create: create, write: write,
                     projection_fields: projection_fields,
                     jagged_rows: jagged_rows, quoted_newlines: quoted_newlines,
                     encoding: encoding, delimiter: delimiter,
-                    ignore_unknown: ignore_unknown,
+                    ignore_unknown: ignore_unknown, chunk_size: chunk_size,
                     max_bad_records: max_bad_records, quote: quote,
                     skip_leading: skip_leading, dryrun: dryrun }
         return load_storage(file, options) if storage_url? file
@@ -906,7 +916,8 @@ module Gcloud
       end
 
       def load_resumable file, options = {}
-        chunk_size = verify_chunk_size! options[:chunk_size]
+        chunk_size = Gcloud::Upload.verify_chunk_size options[:chunk_size],
+                                                      file.length
         resp = connection.load_resumable table_ref, file, chunk_size, options
         if resp.success?
           Job.from_gapi resp.data, connection
@@ -942,18 +953,6 @@ module Gcloud
         false
       end
 
-      ##
-      # Determines if a chunk_size is valid.
-      def verify_chunk_size! chunk_size
-        chunk_size = chunk_size.to_i
-        chunk_mod = 256 * 1024 # 256KB
-        if (chunk_size.to_i % chunk_mod) != 0
-          chunk_size = (chunk_size / chunk_mod) * chunk_mod
-        end
-        return if chunk_size.zero?
-        chunk_size
-      end
-
       ##
       # Load the complete representation of the table if it has been
       # only partially loaded by a request to the API list method.

data/lib/gcloud/datastore/dataset/query_results.rb

@@ -121,11 +121,11 @@ module Gcloud
         end
 
         ##
-        # Retrieves all log entries by repeatedly loading {#next} until
+        # Retrieves all query results by repeatedly loading {#next} until
         # {#next?} returns `false`. Returns the list instance for method
         # chaining.
         #
-        # This method may make several API calls until all log entries are
+        # This method may make several API calls until all query results are
         # retrieved. Be sure to use as narrow a search criteria as possible.
         # Please use with caution.
         #
@@ -133,10 +133,9 @@ module Gcloud
         #   require "gcloud"
         #
         #   gcloud = Gcloud.new
-        #   logging = gcloud.logging
-        #   hour_ago = (Time.now - 60*60).utc.strftime('%FT%TZ')
-        #   recent_errors = "timestamp >= \"#{hour_ago}\" severity >= ERROR"
-        #   entries = logging.entries(filter: recent_errors).all
+        #   datastore = gcloud.datastore
+        #   query = datastore.query("Tasks")
+        #   all_tasks = datastore.run(query).all
         #
         def all
           while next?

data/lib/gcloud/storage/bucket.rb

@@ -515,7 +515,8 @@ module Gcloud
       #   response header to be returned when the file is downloaded.
       # @param [Integer] chunk_size The number of bytes per chunk in a resumable
       #   upload. Must be divisible by 256KB. If it is not divisible by 265KB
-      #   then it will be lowered to the nearest acceptable value.
+      #   then it will be lowered to the nearest acceptable value. If no value
+      #   is provided it will use {Gcloud::Upload.default_chunk_size}. Optional.
       # @param [String] crc32c The CRC32c checksum of the file data, as
       #   described in [RFC 4960, Appendix
       #   B](http://tools.ietf.org/html/rfc4960#appendix-B).

data/lib/gcloud/storage/connection.rb

@@ -16,6 +16,7 @@
 require "pathname"
 require "gcloud/version"
 require "gcloud/backoff"
+require "gcloud/upload"
 require "google/api_client"
 require "mime/types"
 
@@ -382,8 +383,9 @@ module Gcloud
       def file_media local_path, options, resumable
         media = Google::APIClient::UploadIO.new local_path,
                                                 options[:content_type]
-        return media unless resumable && options[:chunk_size]
-        media.chunk_size = verify_chunk_size!(options.delete(:chunk_size))
+        return media unless resumable
+        media.chunk_size = Gcloud::Upload.verify_chunk_size(
+          options.delete(:chunk_size), media.length)
         media
       end
 
@@ -413,18 +415,6 @@ module Gcloud
           yield
         end
       end
-
-      ##
-      # Determines if a chunk_size is valid.
-      def verify_chunk_size! chunk_size
-        chunk_size = chunk_size.to_i
-        chunk_mod = 256 * 1024 # 256KB
-        if (chunk_size.to_i % chunk_mod) != 0
-          chunk_size = (chunk_size / chunk_mod) * chunk_mod
-        end
-        return if chunk_size.zero?
-        chunk_size
-      end
     end
   end
 end

data/lib/gcloud/upload.rb

@@ -40,12 +40,56 @@ module Gcloud
     end
 
     ##
-    # Sets a new resumable threshold value.
+    # Sets a new resumable threshold value in number of bytes.
     def self.resumable_threshold= new_resumable_threshold
       @@resumable_threshold = new_resumable_threshold.to_i
     end
 
-    # Set the default threshold to 5 MiB.
-    self.resumable_threshold = 5_000_000
+    ##
+    # Default chunk size used on resumable uploads.
+    #
+    # The default value is 10 MB (10,485,760 bytes).
+    def self.default_chunk_size
+      @@default_chunk_size
+    end
+
+    ##
+    # Sets a new default chunk_size value in number of bytes. Must be a multiple
+    # of 256KB (262,144).
+    def self.default_chunk_size= new_chunk_size
+      new_chunk_size = normalize_chunk_size new_chunk_size
+      @@default_chunk_size = new_chunk_size if new_chunk_size
+    end
+
+    ##
+    # @private Determines if a chunk_size is valid. Must be a multiple of 256KB.
+    # Returns lowest possible chunk_size if given a very small value.
+    def self.normalize_chunk_size chunk_size
+      chunk_size = chunk_size.to_i
+      chunk_mod = 256 * 1024 # 256KB
+      if (chunk_size.to_i % chunk_mod) != 0
+        chunk_size = (chunk_size / chunk_mod) * chunk_mod
+      end
+      return chunk_mod if chunk_size.zero?
+      chunk_size
+    end
+
+    ##
+    # @private Determines if a chunk_size is valid. Must be a multiple of 256KB.
+    # Returns the default chunk_size if one is not provided.
+    def self.verify_chunk_size chunk_size, file_size
+      if chunk_size.to_i.zero?
+        return nil if file_size < default_chunk_size
+        return default_chunk_size
+      else
+        chunk_size = normalize_chunk_size chunk_size
+        return nil if file_size < chunk_size
+        return chunk_size
+      end
+    end
+
+    # Set the default values for threshold and chunk_size.
+    self.resumable_threshold = 5_000_000  # 5 MiB
+    self.default_chunk_size  = 10_485_760 # 10 MB
   end
 end

data/lib/gcloud/version.rb

@@ -14,5 +14,5 @@
 
 
 module Gcloud
-  VERSION = "0.9.0"
+  VERSION = "0.10.0"
 end

data/lib/gcloud/vision.rb

@@ -0,0 +1,488 @@
+# Copyright 2016 Google Inc. All rights reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+
+require "gcloud"
+require "gcloud/vision/project"
+
+module Gcloud
+  ##
+  # Creates a new object for connecting to the Vision service.
+  # Each call creates a new connection.
+  #
+  # @param [String] project Project identifier for the Vision service you are
+  #   connecting to.
+  # @param [String, Hash] keyfile Keyfile downloaded from Google Cloud. If file
+  #   path the file must be readable.
+  # @param [String, Array<String>] scope 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](https://developers.google.com/identity/protocols/OAuth2).
+  #
+  #   The default scope is:
+  #
+  #   * `https://www.googleapis.com/auth/cloud-platform`
+  #
+  # @return [Gcloud::Vision::Project]
+  #
+  # @example
+  #   require "gcloud/vision"
+  #
+  #   gcloud = Gcloud.new
+  #   vision = gcloud.vision
+  #
+  #   image = vision.image "path/to/landmark.jpg"
+  #
+  #   landmark = image.landmark
+  #   landmark.description #=> "Mount Rushmore"
+  #
+  def self.vision project = nil, keyfile = nil, scope: nil
+    project ||= Gcloud::Vision::Project.default_project
+    if keyfile.nil?
+      credentials = Gcloud::Vision::Credentials.default scope: scope
+    else
+      credentials = Gcloud::Vision::Credentials.new keyfile, scope: scope
+    end
+    Gcloud::Vision::Project.new project, credentials
+  end
+
+  ##
+  # # 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](https://cloud.google.com/vision/docs/).
+  #
+  # Gcloud's goal is to provide an API that is familiar and comfortable to
+  # Rubyists. Authentication is handled by {Gcloud#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](https://googlecloudplatform.github.io/gcloud-ruby/#/docs/guides/authentication).
+  #
+  # ## Creating images
+  #
+  # 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](https://cloud.google.com/vision/docs/image-best-practices#image_types)
+  # for the complete list of formats. 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](https://cloud.google.com/vision/docs/image-best-practices#image_sizing)
+  # for current file size limits.
+  #
+  # Use {Vision::Project#image} to create images for the Cloud Vision service.
+  # You can provide a file path:
+  #
+  # ```ruby
+  # require "gcloud"
+  #
+  # gcloud = Gcloud.new
+  # vision = gcloud.vision
+  #
+  # image = vision.image "path/to/landmark.jpg"
+  # ```
+  #
+  # Or, you can initialize the image with a Google Cloud Storage URI:
+  #
+  # ```ruby
+  # require "gcloud"
+  #
+  # gcloud = Gcloud.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 {Vision::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
+  # {Vision::Project#annotate}, below.)
+  #
+  # ```ruby
+  # require "gcloud"
+  #
+  # gcloud = Gcloud.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 {Vision::Project#annotate}:
+  #
+  # ```ruby
+  # require "gcloud"
+  #
+  # gcloud = Gcloud.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:
+  #
+  # ```ruby
+  # require "gcloud"
+  #
+  # gcloud = Gcloud.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:
+  #
+  # ```ruby
+  # require "gcloud"
+  #
+  # gcloud = Gcloud.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 {Gcloud::Vision.default_max_faces},
+  # {Gcloud::Vision.default_max_landmarks}, {Gcloud::Vision.default_max_logos},
+  # and {Gcloud::Vision.default_max_labels}, respectively. To change the global
+  # defaults, you can update the configuration:
+  #
+  # ```ruby
+  # require "gcloud"
+  #
+  # gcloud = Gcloud.new
+  # vision = gcloud.vision
+  #
+  # Gcloud::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:
+  #
+  # ```ruby
+  # require "gcloud"
+  #
+  # gcloud = Gcloud.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
+  # ```
+  #
+  module Vision
+    class << self
+      ##
+      # The default max results to return for facial detection requests. This is
+      # used on {Project#annotate} as well as {Image#faces}.
+      #
+      # The default value is `100`.
+      #
+      # @example Using the default setting on {Project#annotate}:
+      #   require "gcloud"
+      #
+      #   gcloud = Gcloud.new
+      #   vision = gcloud.vision
+      #
+      #   Gcloud::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
+      #
+      # @example Updating the default setting on {Project#annotate}:
+      #   require "gcloud"
+      #
+      #   gcloud = Gcloud.new
+      #   vision = gcloud.vision
+      #
+      #   # Set a new default
+      #   Gcloud::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
+      #
+      #
+      # @example Using the default setting on {Image#faces}:
+      #   require "gcloud"
+      #
+      #   gcloud = Gcloud.new
+      #   vision = gcloud.vision
+      #
+      #   Gcloud::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
+      #
+      # @example Updating the default setting on {Image#faces}:
+      #   require "gcloud"
+      #
+      #   gcloud = Gcloud.new
+      #   vision = gcloud.vision
+      #
+      #   # Set a new default
+      #   Gcloud::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
+      #
+      attr_accessor :default_max_faces
+
+      ##
+      # The default max results to return for landmark detection requests. This
+      # is used on {Project#annotate} as well as {Image#landmarks}.
+      #
+      # The default value is 100.
+      #
+      # @example Using the default setting on {Project#annotate}:
+      #   require "gcloud"
+      #
+      #   gcloud = Gcloud.new
+      #   vision = gcloud.vision
+      #
+      #   Gcloud::Vision.default_max_landmarks #=> 100
+      #
+      #   annotation = vision.annotate "path/to/landmarks.jpg", landmarks: true
+      #   # This is the same as calling
+      #   # annotation = vision.annotate "path/to/landmarks.jpg", landmarks: 100
+      #
+      # @example Updating the default setting on {Project#annotate}:
+      #   require "gcloud"
+      #
+      #   gcloud = Gcloud.new
+      #   vision = gcloud.vision
+      #
+      #   # Set a new default
+      #   Gcloud::Vision.default_max_landmarks = 5
+      #
+      #   annotation = vision.annotate "path/to/landmarks.jpg", landmarks: true
+      #   # This is the same as calling
+      #   # annotation = vision.annotate "path/to/landmarks.jpg", landmarks: 5
+      #
+      #
+      # @example Using the default setting on {Image#landmarks}:
+      #   require "gcloud"
+      #
+      #   gcloud = Gcloud.new
+      #   vision = gcloud.vision
+      #
+      #   Gcloud::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
+      #
+      # @example Updating the default setting on {Image#landmarks}:
+      #   require "gcloud"
+      #
+      #   gcloud = Gcloud.new
+      #   vision = gcloud.vision
+      #
+      #   # Set a new default
+      #   Gcloud::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
+      #
+      attr_accessor :default_max_landmarks
+
+      ##
+      # The default max results to return for logo detection requests. This is
+      # used on {Project#annotate} as well as {Image#logos}.
+      #
+      # The default value is 100.
+      #
+      # @example Using the default setting on {Project#annotate}:
+      #   require "gcloud"
+      #
+      #   gcloud = Gcloud.new
+      #   vision = gcloud.vision
+      #
+      #   Gcloud::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
+      #
+      # @example Updating the default setting on {Project#annotate}:
+      #   require "gcloud"
+      #
+      #   gcloud = Gcloud.new
+      #   vision = gcloud.vision
+      #
+      #   # Set a new default
+      #   Gcloud::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
+      #
+      #
+      # @example Using the default setting on {Image#logos}:
+      #   require "gcloud"
+      #
+      #   gcloud = Gcloud.new
+      #   vision = gcloud.vision
+      #
+      #   Gcloud::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
+      #
+      # @example Updating the default setting on {Image#logos}:
+      #   require "gcloud"
+      #
+      #   gcloud = Gcloud.new
+      #   vision = gcloud.vision
+      #
+      #   # Set a new default
+      #   Gcloud::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
+      #
+      attr_accessor :default_max_logos
+
+      ##
+      # The default max results to return for label detection requests. This is
+      # used on {Project#annotate} as well as {Image#labels}.
+      #
+      # The default value is 100.
+      #
+      # @example Using the default setting on {Project#annotate}:
+      #   require "gcloud"
+      #
+      #   gcloud = Gcloud.new
+      #   vision = gcloud.vision
+      #
+      #   Gcloud::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
+      #
+      # @example Updating the default setting on {Project#annotate}:
+      #   require "gcloud"
+      #
+      #   gcloud = Gcloud.new
+      #   vision = gcloud.vision
+      #
+      #   # Set a new default
+      #   Gcloud::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
+      #
+      #
+      # @example Using the default setting on {Image#labels}:
+      #   require "gcloud"
+      #
+      #   gcloud = Gcloud.new
+      #   vision = gcloud.vision
+      #
+      #   Gcloud::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
+      #
+      # @example Updating the default setting on {Image#labels}:
+      #   require "gcloud"
+      #
+      #   gcloud = Gcloud.new
+      #   vision = gcloud.vision
+      #
+      #   # Set a new default
+      #   Gcloud::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
+      #
+      attr_accessor :default_max_labels
+    end
+
+    # Set the default values.
+    # Update the comments documentation when these change.
+    self.default_max_faces     = 100
+    self.default_max_landmarks = 100
+    self.default_max_logos     = 100
+    self.default_max_labels    = 100
+  end
+end