google-cloud-vision 0.20.0

data/lib/google/cloud/vision/annotation/entity.rb

@@ -0,0 +1,228 @@
+# 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 "google/cloud/vision/location"
+require "google/cloud/vision/annotation/vertex"
+
+module Google
+  module Cloud
+    module Vision
+      class Annotation
+        ##
+        # # Entity
+        #
+        # Represents characteristics of an entity detected in an image. May
+        # describe a real-world entity such as a person, place, or thing. May be
+        # identified with an entity ID as an entity in the Knowledge Graph (KG).
+        #
+        # @see https://developers.google.com/knowledge-graph/ Knowledge Graph
+        #
+        # @example
+        #   require "google/cloud"
+        #
+        #   gcloud = Google::Cloud.new
+        #   vision = gcloud.vision
+        #
+        #   image = vision.image "path/to/landmark.jpg"
+        #
+        #   landmark = image.landmark
+        #   landmark.score #=> 0.91912264
+        #   landmark.description #=> "Mount Rushmore"
+        #   landmark.mid #=> "/m/019dvv"
+        #
+        # @example
+        #   require "google/cloud"
+        #
+        #   gcloud = Google::Cloud.new
+        #   vision = gcloud.vision
+        #
+        #   image = vision.image "path/to/logo.jpg"
+        #
+        #   logo = image.logo
+        #   logo.score #=> 0.70057315
+        #   logo.description #=> "Google"
+        #   logo.mid #=> "/m/0b34hf"
+        #
+        # @example
+        #   require "google/cloud"
+        #
+        #   gcloud = Google::Cloud.new
+        #   vision = gcloud.vision
+        #
+        #   image = vision.image "path/to/face.jpg"
+        #
+        #   labels = image.labels
+        #   labels.count #=> 4
+        #
+        #   label = labels.first
+        #   label.score #=> 0.9481349
+        #   label.description #=> "person"
+        #   label.mid #=> "/m/01g317"
+        #
+        class Entity
+          ##
+          # @private The EntityAnnotation Google API Client object.
+          attr_accessor :gapi
+
+          ##
+          # @private Creates a new Entity instance.
+          def initialize
+            @gapi = {}
+          end
+
+          ##
+          # Opaque entity ID. Some IDs might be available in Knowledge Graph
+          # (KG).
+          #
+          # @see https://developers.google.com/knowledge-graph/ Knowledge Graph
+          #
+          # @return [String] The opaque entity ID.
+          #
+          def mid
+            @gapi.mid
+          end
+
+          ##
+          # The language code for the locale in which the `description` is
+          # expressed.
+          #
+          # @return [String] The [ISO
+          #   639-1](https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes)
+          #   language code.
+          #
+          def locale
+            @gapi.locale
+          end
+
+          ##
+          # Entity textual description, expressed in the {#locale} language.
+          #
+          # @return [String] A description of the entity.
+          #
+          def description
+            @gapi.description
+          end
+
+          ##
+          # Overall score of the result.
+          #
+          # @return [Float] A value in the range [0, 1].
+          #
+          def score
+            @gapi.score
+          end
+
+          ##
+          # The accuracy of the entity detection in an image. For example, for
+          # an image containing 'Eiffel Tower,' this field represents the
+          # confidence that there is a tower in the query image.
+          #
+          # @return [Float] A value in the range [0, 1].
+          #
+          def confidence
+            @gapi.confidence
+          end
+
+          ##
+          # The relevancy of the ICA (Image Content Annotation) label to the
+          # image. For example, the relevancy of 'tower' to an image containing
+          # 'Eiffel Tower' is likely higher than an image containing a distant
+          # towering building, though the confidence that there is a tower may
+          # be the same.
+          #
+          # @return [Float] A value in the range [0, 1].
+          #
+          def topicality
+            @gapi.topicality
+          end
+
+          ##
+          # Image region to which this entity belongs. Not filled currently for
+          # `labels` detection.
+          #
+          # @return [Array<Vertex>] An array of vertices.
+          #
+          def bounds
+            return [] unless @gapi.bounding_poly
+            @bounds ||= Array(@gapi.bounding_poly.vertices).map do |v|
+              Vertex.from_gapi v
+            end
+          end
+
+          ##
+          # The location information for the detected entity. Multiple Location
+          # elements can be present since one location may indicate the location
+          # of the scene in the query image, and another the location of the
+          # place where the query image was taken. Location information is
+          # usually present for landmarks.
+          #
+          # @return [Array<Location>] An array of locations containing latitude
+          #   and longitude.
+          #
+          def locations
+            @locations ||= Array(@gapi.locations).map do |l|
+              Location.from_gapi l.lat_lng
+            end
+          end
+
+          ##
+          # Some entities can have additional optional Property fields. For
+          # example a different kind of score or string that qualifies the
+          # entity. present for landmarks.
+          #
+          # @return [Hash] A hash containing property names and values.
+          #
+          def properties
+            @properties ||=
+              Hash[Array(@gapi.properties).map { |p| [p.name, p.value] }]
+          end
+
+          ##
+          # Deeply converts object to a hash. All keys will be symbolized.
+          #
+          # @return [Hash]
+          #
+          def to_h
+            { mid: mid, locale: locale, description: description,
+              score: score, confidence: confidence, topicality: topicality,
+              bounds: bounds.map(&:to_h), locations: locations.map(&:to_h),
+              properties: properties }
+          end
+
+          # @private
+          def to_s
+            tmplt = "mid: %s, locale: %s, description: %s, score: %s, " \
+                    "confidence: %s, topicality: %s, bounds: %i, " \
+                    "locations: %i, properties: %s"
+            format tmplt, mid.inspect, locale.inspect, description.inspect,
+                   score.inspect, confidence.inspect, topicality.inspect,
+                   bounds.count, locations.count, properties.inspect
+          end
+
+          # @private
+          def inspect
+            "#<#{self.class.name} #{self}>"
+          end
+
+          ##
+          # @private New Annotation::Entity from a Google API Client object.
+          def self.from_gapi gapi
+            new.tap { |f| f.instance_variable_set :@gapi, gapi }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/google/cloud/vision/annotation/face.rb

@@ -0,0 +1,1512 @@
+# 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 "google/cloud/vision/annotation/vertex"
+
+module Google
+  module Cloud
+    module Vision
+      class Annotation
+        ##
+        # # Face
+        #
+        # The results of face detection.
+        #
+        # See {Annotation#faces} and {Annotation#face}.
+        #
+        # @example
+        #   require "google/cloud"
+        #
+        #   gcloud = Google::Cloud.new
+        #   vision = gcloud.vision
+        #
+        #   image = vision.image "path/to/face.jpg"
+        #
+        #   face = image.face
+        #   face.confidence #=> 0.86162376
+        #
+        class Face
+          ##
+          # @private The FaceAnnotation Google API Client object.
+          attr_accessor :gapi
+
+          ##
+          # @private Creates a new Face instance.
+          def initialize
+            @gapi = {}
+          end
+
+          ##
+          # The angles of the face, including roll, yaw, and pitch.
+          #
+          # @return [Angles]
+          #
+          def angles
+            @angles ||= Angles.from_gapi @gapi
+          end
+
+          ##
+          # The bounds of the face, including the polygons for the head and
+          # face.
+          #
+          # @return [Bounds]
+          #
+          def bounds
+            @bounds ||= Bounds.from_gapi @gapi
+          end
+
+          ##
+          # The landmarks of the face, including the points for the eyes, ears,
+          # nose and mouth.
+          #
+          # @return [Features]
+          #
+          def features
+            @features ||= Features.from_gapi @gapi
+          end
+
+          ##
+          # The likelihood of the facial detection, including joy, sorrow,
+          # anger, surprise, under_exposed, blurred, and headwear.
+          #
+          # @return [Likelihood]
+          #
+          def likelihood
+            @likelihood ||= Likelihood.from_gapi @gapi
+          end
+
+          ##
+          # The confidence of the facial detection.
+          #
+          # @return [Float] A value in the range [0, 1].
+          #
+          def confidence
+            @gapi.detection_confidence
+          end
+
+          ##
+          # Deeply converts object to a hash. All keys will be symbolized.
+          #
+          # @return [Hash]
+          #
+          def to_h
+            { angles: angles.to_h, bounds: bounds.to_h, features: features.to_h,
+              likelihood: likelihood.to_h }
+          end
+
+          # @private
+          def to_s
+            # Keep console output low by not showing all sub-objects.
+            "(angles, bounds, features, likelihood)"
+          end
+
+          # @private
+          def inspect
+            "#<#{self.class.name} #{self}>"
+          end
+
+          ##
+          # @private New Annotation::Face from a Google API Client object.
+          def self.from_gapi gapi
+            new.tap { |f| f.instance_variable_set :@gapi, gapi }
+          end
+
+          ##
+          # # Angles
+          #
+          # The orientation of the face relative to the image.
+          #
+          # See {Face}.
+          #
+          # @example
+          #   require "google/cloud"
+          #
+          #   gcloud = Google::Cloud.new
+          #   vision = gcloud.vision
+          #
+          #   image = vision.image "path/to/face.jpg"
+          #   face = image.face
+          #
+          #   face.angles.roll #=> -5.1492119
+          #   face.angles.yaw #=> -4.0695682
+          #   face.angles.pitch #=> -13.083284
+          #
+          class Angles
+            ##
+            # @private The FaceAnnotation Google API Client object.
+            attr_accessor :gapi
+
+            ##
+            # @private Creates a new Angles instance.
+            def initialize
+              @gapi = {}
+            end
+
+            ##
+            # Roll angle. Indicates the amount of clockwise/anti-clockwise
+            # rotation of the face relative to the image vertical, about the
+            # axis perpendicular to the face.
+            #
+            # @return [Float] A value in the range [-180,180].
+            #
+            def roll
+              @gapi.roll_angle
+            end
+
+            ##
+            # Yaw (pan) angle. Indicates the leftward/rightward angle that the
+            # face is pointing, relative to the vertical plane perpendicular to
+            # the image.
+            #
+            # @return [Float] A value in the range [-180,180].
+            #
+            def yaw
+              @gapi.pan_angle
+            end
+            alias_method :pan, :yaw
+
+            ##
+            # Pitch (tilt) angle. Indicates the upwards/downwards angle that the
+            # face is pointing relative to the image's horizontal plane.
+            #
+            # @return [Float] A value in the range [-180,180].
+            #
+            def pitch
+              @gapi.tilt_angle
+            end
+            alias_method :tilt, :pitch
+
+            ##
+            # Returns the object's property values as an array.
+            #
+            # @return [Array]
+            #
+            def to_a
+              [roll, yaw, pitch]
+            end
+
+            ##
+            # Converts object to a hash. All keys will be symbolized.
+            #
+            # @return [Hash]
+            #
+            def to_h
+              { roll: roll, yaw: yaw, pitch: pitch }
+            end
+
+            # @private
+            def to_s
+              format "(roll: %s, yaw: %s, pitch: %s)", roll.inspect,
+                     yaw.inspect, pitch.inspect
+            end
+
+            # @private
+            def inspect
+              "#<Angles #{self}>"
+            end
+
+            ##
+            # @private New Annotation::Face::Angles from a Google API Client
+            # object.
+            def self.from_gapi gapi
+              new.tap { |f| f.instance_variable_set :@gapi, gapi }
+            end
+          end
+
+          ##
+          # # Bounds
+          #
+          # Bounding polygons around the face.
+          #
+          # See {Face}.
+          #
+          # @example
+          #   require "google/cloud"
+          #
+          #   gcloud = Google::Cloud.new
+          #   vision = gcloud.vision
+          #
+          #   image = vision.image "path/to/face.jpg"
+          #   face = image.face
+          #
+          #   face.bounds.face.count #=> 4
+          #   face.bounds.face.first #=> #<Vertex (x: 153, y: 34)>
+          #
+          class Bounds
+            ##
+            # @private The FaceAnnotation Google API Client object.
+            attr_accessor :gapi
+
+            ##
+            # @private Creates a new Bounds instance.
+            def initialize
+              @gapi = {}
+            end
+
+            ##
+            # The bounding polygon around the face. The coordinates of the
+            # bounding box are in the original image's scale, as returned in
+            # ImageParams. The bounding box is computed to "frame" the face in
+            # accordance with human expectations. It is based on the landmarker
+            # results. Note that one or more x and/or y coordinates may not be
+            # generated in the BoundingPoly (the polygon will be unbounded) if
+            # only a partial face appears in the image to be annotated.
+            def head
+              return [] unless @gapi.bounding_poly
+              @head ||= Array(@gapi.bounding_poly.vertices).map do |v|
+                Vertex.from_gapi v
+              end
+            end
+
+            ##
+            # This bounding polygon is tighter than the {#head}, and encloses
+            # only the skin part of the face. Typically, it is used to eliminate
+            # the face from any image annotation that detects the "amount of
+            # skin" visible in an image. It is not based on the landmarks, only
+            # on the initial face detection.
+            def face
+              return [] unless @gapi.fd_bounding_poly
+              @face ||= Array(@gapi.fd_bounding_poly.vertices).map do |v|
+                Vertex.from_gapi v
+              end
+            end
+
+            ##
+            # Returns the object's property values as an array.
+            #
+            # @return [Array]
+            #
+            def to_a
+              [head.map(&:to_a), face.map(&:to_a)]
+            end
+
+            ##
+            # Deeply converts object to a hash. All keys will be symbolized.
+            #
+            # @return [Hash]
+            #
+            def to_h
+              { head: head.map(&:to_h), face: face.map(&:to_h) }
+            end
+
+            # @private
+            def to_s
+              "(head: #{head.inspect}, face: #{face.inspect})"
+            end
+
+            # @private
+            def inspect
+              "#<Bounds #{self}>"
+            end
+
+            ##
+            # @private New Annotation::Face::Angles from a Google API Client
+            # object.
+            def self.from_gapi gapi
+              new.tap { |f| f.instance_variable_set :@gapi, gapi }
+            end
+          end
+
+          ##
+          # # Features
+          #
+          # Represents facial landmarks or features. Left and right are defined
+          # from the vantage of the viewer of the image, without considering
+          # mirror projections typical of photos. So `face.features.eyes.left`
+          # typically is the person's right eye.
+          #
+          # See {Face}.
+          #
+          # @see https://cloud.google.com/vision/reference/rest/v1/images/annotate#Type_1
+          #   images.annotate Type
+          #
+          # @example
+          #   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)>
+          #
+          class Features
+            ##
+            # @private The FaceAnnotation Google API Client object.
+            attr_accessor :gapi
+
+            ##
+            # @private Creates a new Features instance.
+            def initialize
+              @gapi = {}
+            end
+
+            ##
+            # The confidence of the facial landmarks detection.
+            #
+            # @return [Float] A value in the range [0,1].
+            #
+            def confidence
+              @gapi.landmarking_confidence
+            end
+
+            ##
+            # Returns the facial landmark for the provided type code.
+            #
+            # @see https://cloud.google.com/vision/reference/rest/v1/images/annotate#Type_1
+            #   images.annotate Type
+            #
+            # @param [String, Symbol] landmark_type An `images.annotate` type
+            #   code from the [Vision
+            #   API](https://cloud.google.com/vision/reference/rest/v1/images/annotate#Type_1).
+            #
+            # @return [Landmark]
+            #
+            # @example
+            #   require "google/cloud"
+            #
+            #   gcloud = Google::Cloud.new
+            #   vision = gcloud.vision
+            #
+            #   image = vision.image "path/to/face.jpg"
+            #   face = image.face
+            #
+            #   face.features["RIGHT_EAR_TRAGION"]
+            #   #=> #<Landmark (x: 303.81198, y: 88.5782, z: 77.719193)>
+            #
+            def [] landmark_type
+              landmark = Array(@gapi.landmarks).detect do |l|
+                l.type == landmark_type
+              end
+              return nil if landmark.nil?
+              Landmark.from_gapi landmark
+            end
+
+            ##
+            # The landmarks of the chin.
+            #
+            # @return [Chin]
+            #
+            def chin
+              @chin ||= Chin.new self["CHIN_LEFT_GONION"],
+                                 self["CHIN_GNATHION"],
+                                 self["CHIN_RIGHT_GONION"]
+            end
+
+            ##
+            # The landmarks of the ears.
+            #
+            # @return [Ears]
+            #
+            def ears
+              @ears ||= Ears.new self["LEFT_EAR_TRAGION"],
+                                 self["RIGHT_EAR_TRAGION"]
+            end
+
+            ##
+            # The landmarks of the eyebrows.
+            #
+            # @return [Eyebrows]
+            #
+            def eyebrows
+              @eyebrows ||= begin
+                left = Eyebrow.new self["LEFT_OF_LEFT_EYEBROW"],
+                                   self["LEFT_EYEBROW_UPPER_MIDPOINT"],
+                                   self["RIGHT_OF_LEFT_EYEBROW"]
+                right = Eyebrow.new self["LEFT_OF_RIGHT_EYEBROW"],
+                                    self["RIGHT_EYEBROW_UPPER_MIDPOINT"],
+                                    self["RIGHT_OF_RIGHT_EYEBROW"]
+                Eyebrows.new left, right
+              end
+            end
+
+            ##
+            # The landmarks of the eyes.
+            #
+            # @return [Eyes]
+            #
+            def eyes
+              @eyes ||= begin
+                left = Eye.new self["LEFT_EYE_LEFT_CORNER"],
+                               self["LEFT_EYE_BOTTOM_BOUNDARY"],
+                               self["LEFT_EYE"], self["LEFT_EYE_PUPIL"],
+                               self["LEFT_EYE_TOP_BOUNDARY"],
+                               self["LEFT_EYE_RIGHT_CORNER"]
+                right = Eye.new self["RIGHT_EYE_LEFT_CORNER"],
+                                self["RIGHT_EYE_BOTTOM_BOUNDARY"],
+                                self["RIGHT_EYE"], self["RIGHT_EYE_PUPIL"],
+                                self["RIGHT_EYE_TOP_BOUNDARY"],
+                                self["RIGHT_EYE_RIGHT_CORNER"]
+                Eyes.new left, right
+              end
+            end
+
+            ##
+            # The landmark for the forehead glabella.
+            #
+            # @return [Landmark]
+            #
+            def forehead
+              @forehead ||= self["FOREHEAD_GLABELLA"]
+            end
+
+            ##
+            # The landmarks of the lips.
+            #
+            # @return [Lips]
+            #
+            def lips
+              @lips ||= Lips.new self["UPPER_LIP"], self["LOWER_LIP"]
+            end
+
+            ##
+            # The landmarks of the mouth.
+            #
+            # @return [Mouth]
+            #
+            def mouth
+              @mouth ||= Mouth.new self["MOUTH_LEFT"], self["MOUTH_CENTER"],
+                                   self["MOUTH_RIGHT"]
+            end
+
+            ##
+            # The landmarks of the nose.
+            #
+            # @return [Nose]
+            #
+            def nose
+              @nose ||= Nose.new self["NOSE_BOTTOM_LEFT"],
+                                 self["NOSE_BOTTOM_CENTER"], self["NOSE_TIP"],
+                                 self["MIDPOINT_BETWEEN_EYES"],
+                                 self["NOSE_BOTTOM_RIGHT"]
+            end
+
+            ##
+            # Deeply converts object to a hash. All keys will be symbolized.
+            #
+            # @return [Hash]
+            #
+            def to_h
+              { confidence: confidence, chin: chin.to_h, ears: ears.to_h,
+                eyebrows: eyebrows.to_h, eyes: eyes.to_h,
+                forehead: forehead.to_h, lips: lips.to_h, mouth: mouth.to_h,
+                nose: nose.to_h }
+            end
+
+            # @private
+            def to_s
+              # Keep console output low by not showing all sub-objects.
+              "(confidence, chin, ears, eyebrows, eyes, " \
+                "forehead, lips, mouth, nose)"
+            end
+
+            # @private
+            def inspect
+              "#<Features #{self}>"
+            end
+
+            ##
+            # @private New Annotation::Face::Features from a Google API Client
+            # object.
+            def self.from_gapi gapi
+              new.tap { |f| f.instance_variable_set :@gapi, gapi }
+            end
+
+            ##
+            # # Landmark
+            #
+            # A face-specific landmark (for example, a face feature). Landmark
+            # positions may fall outside the bounds of the image when the face
+            # is near one or more edges of the image. Therefore it is NOT
+            # guaranteed that `0 <= x < width` or `0 <= y < height`.
+            #
+            # See {Features} and {Face}.
+            #
+            # @example
+            #   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)>
+            #
+            class Landmark
+              ##
+              # @private The Landmark Google API Client object.
+              attr_accessor :gapi
+
+              ##
+              # @private Creates a new Landmark instance.
+              def initialize
+                @gapi = {}
+              end
+
+              ##
+              # The landmark type code.
+              #
+              # @see https://cloud.google.com/vision/reference/rest/v1/images/annotate#Type_1
+              #   images.annotate Type
+              #
+              # @return [String]
+              #
+              # @example
+              #   require "google/cloud"
+              #
+              #   gcloud = Google::Cloud.new
+              #   vision = gcloud.vision
+              #
+              #   image = vision.image "path/to/face.jpg"
+              #   face = image.face
+              #
+              #   face.features.forehead.type #=> "FOREHEAD_GLABELLA"
+              #
+              def type
+                @gapi.type
+              end
+
+              ##
+              # The X (horizontal) coordinate.
+              #
+              # @return [Float]
+              #
+              def x
+                return nil unless @gapi.position
+                @gapi.position.x
+              end
+
+              ##
+              # The Y (vertical) coordinate.
+              #
+              # @return [Float]
+              #
+              def y
+                return nil unless @gapi.position
+                @gapi.position.y
+              end
+
+              ##
+              # The Z (depth) coordinate.
+              #
+              # @return [Float]
+              #
+              def z
+                return nil unless @gapi.position
+                @gapi.position.z
+              end
+
+              ##
+              # Returns the object's property values as an array.
+              #
+              # @return [Array]
+              #
+              def to_a
+                [x, y, z]
+              end
+
+              ##
+              # Converts object to a hash. All keys will be symbolized.
+              #
+              # @return [Hash]
+              #
+              def to_h
+                { x: x, y: y, z: z }
+              end
+
+              # @private
+              def to_s
+                "(x: #{x.inspect}, y: #{y.inspect}, z: #{z.inspect})"
+              end
+
+              # @private
+              def inspect
+                "#<Landmark #{self}>"
+              end
+
+              ##
+              # @private New Annotation::Face::Features from a Google API Client
+              # object.
+              def self.from_gapi gapi
+                new.tap { |f| f.instance_variable_set :@gapi, gapi }
+              end
+            end
+
+            ##
+            # # Chin
+            #
+            # The landmarks of the chin in the features of a face.
+            #
+            # Left and right are defined from the vantage of the viewer of the
+            # image, without considering mirror projections typical of photos.
+            # So `face.features.eyes.left` typically is the person's right eye.
+            #
+            # See {Features} and {Face}.
+            #
+            # @attr_reader [Landmark] left The chin, left gonion.
+            # @attr_reader [Landmark] center The chin, gnathion.
+            # @attr_reader [Landmark] right The chin, right gonion.
+            #
+            # @example
+            #   require "google/cloud"
+            #
+            #   gcloud = Google::Cloud.new
+            #   vision = gcloud.vision
+            #
+            #   image = vision.image "path/to/face.jpg"
+            #   face = image.face
+            #
+            #   chin = face.features.chin
+            #
+            #   chin.center
+            #   #=> #<Landmark (x: 233.21977, y: 189.47475, z: 19.487228)>
+            #
+            class Chin
+              attr_reader :left, :center, :right
+
+              ##
+              # @private Creates a new Chin instance.
+              def initialize left, center, right
+                @left   = left
+                @center = center
+                @right  = right
+              end
+
+              ##
+              # Returns the object's property values as an array.
+              #
+              # @return [Array]
+              #
+              def to_a
+                [left, center, right]
+              end
+
+              ##
+              # Deeply converts object to a hash. All keys will be symbolized.
+              #
+              # @return [Hash]
+              #
+              def to_h
+                { left: left.to_h, center: center.to_h, right: right.to_h }
+              end
+
+              # @private
+              def to_s
+                format "(left: %s, center: %s, right: %s)", left.inspect,
+                       center.inspect, right.inspect
+              end
+
+              # @private
+              def inspect
+                "#<Chin #{self}>"
+              end
+            end
+
+            ##
+            # # Ears
+            #
+            # The landmarks for the ear tragions.
+            #
+            # Left and right are defined from the vantage of the viewer of the
+            # image, without considering mirror projections typical of photos.
+            # So `face.features.eyes.left` typically is the person's right eye.
+            #
+            # See {Features} and {Face}.
+            #
+            # @attr_reader [Landmark] left The left ear tragion.
+            # @attr_reader [Landmark] right The right ear tragion.
+            #
+            # @see https://cloud.google.com/vision/reference/rest/v1/images/annotate#Type_1
+            #   images.annotate Type
+            #
+            # @example
+            #   require "google/cloud"
+            #
+            #   gcloud = Google::Cloud.new
+            #   vision = gcloud.vision
+            #
+            #   image = vision.image "path/to/face.jpg"
+            #   face = image.face
+            #
+            #   ears = face.features.ears
+            #   ears.right
+            #   #=> #<Landmark (x: 303.81198, y: 88.5782, z: 77.719193)>
+            #
+            class Ears
+              attr_reader :left, :right
+
+              ##
+              # @private Creates a new Ears instance.
+              def initialize left, right
+                @left  = left
+                @right = right
+              end
+
+              ##
+              # Returns the object's property values as an array.
+              #
+              # @return [Array]
+              #
+              def to_a
+                [left, right]
+              end
+
+              ##
+              # Deeply converts object to a hash. All keys will be symbolized.
+              #
+              # @return [Hash]
+              #
+              def to_h
+                { left: left.to_h, right: right.to_h }
+              end
+
+              # @private
+              def to_s
+                "(left: #{left.inspect}, right: #{right.inspect})"
+              end
+
+              # @private
+              def inspect
+                "#<Ears #{self}>"
+              end
+            end
+
+            ##
+            # # Eyebrows
+            #
+            # The landmarks of the eyebrows in the features of a face.
+            #
+            # Left and right are defined from the vantage of the viewer of the
+            # image, without considering mirror projections typical of photos.
+            # So `face.features.eyes.left` typically is the person's right eye.
+            #
+            # See {Features} and {Face}.
+            #
+            # @attr_reader [Eyebrow] left The left eyebrow.
+            # @attr_reader [Eyebrow] right The right eyebrow.
+            #
+            # @see https://cloud.google.com/vision/reference/rest/v1/images/annotate#Type_1
+            #   images.annotate Type
+            #
+            # @example
+            #   require "google/cloud"
+            #
+            #   gcloud = Google::Cloud.new
+            #   vision = gcloud.vision
+            #
+            #   image = vision.image "path/to/face.jpg"
+            #   face = image.face
+            #
+            #   eyebrows = face.features.eyebrows
+            #
+            #   right_eyebrow = eyebrows.right
+            #   right_eyebrow.top
+            #   #=> #<Landmark (x: 256.3194, y: 58.222664, z: -17.299419)>
+            #
+            class Eyebrows
+              attr_reader :left, :right
+
+              ##
+              # @private Creates a new Eyebrows instance.
+              def initialize left, right
+                @left  = left
+                @right = right
+              end
+
+              ##
+              # Returns the object's property values as an array.
+              #
+              # @return [Array]
+              #
+              def to_a
+                [left, right]
+              end
+
+              ##
+              # Deeply converts object to a hash. All keys will be symbolized.
+              #
+              # @return [Hash]
+              #
+              def to_h
+                { left: left.to_h, right: right.to_h }
+              end
+
+              # @private
+              def to_s
+                "(left: #{left.inspect}, right: #{right.inspect})"
+              end
+
+              # @private
+              def inspect
+                "#<Eyebrows #{self}>"
+              end
+            end
+
+            ##
+            # # Eyebrow
+            #
+            # The landmarks of an eyebrow in the features of a face.
+            #
+            # Left and right are defined from the vantage of the viewer of the
+            # image, without considering mirror projections typical of photos.
+            # So `face.features.eyes.left` typically is the person's right eye.
+            #
+            # See {Eyebrows}, {Features} and {Face}.
+            #
+            # @see https://cloud.google.com/vision/reference/rest/v1/images/annotate#Type_1
+            #   images.annotate Type
+            #
+            # @attr_reader [Landmark] left The eyebrow, left.
+            # @attr_reader [Landmark] top The eyebrow, upper midpoint.
+            # @attr_reader [Landmark] right The eyebrow, right.
+            #
+            # @example
+            #   require "google/cloud"
+            #
+            #   gcloud = Google::Cloud.new
+            #   vision = gcloud.vision
+            #
+            #   image = vision.image "path/to/face.jpg"
+            #   face = image.face
+            #
+            #   eyebrows = face.features.eyebrows
+            #
+            #   right_eyebrow = eyebrows.right
+            #   right_eyebrow.top
+            #   #=> #<Landmark (x: 256.3194, y: 58.222664, z: -17.299419)>
+            #
+            class Eyebrow
+              attr_reader :left, :top, :right
+
+              ##
+              # @private Creates a new Eyebrow instance.
+              def initialize left, top, right
+                @left  = left
+                @top   = top
+                @right = right
+              end
+
+              ##
+              # Returns the object's property values as an array.
+              #
+              # @return [Array]
+              #
+              def to_a
+                [left, top, right]
+              end
+
+              ##
+              # Deeply converts object to a hash. All keys will be symbolized.
+              #
+              # @return [Hash]
+              #
+              def to_h
+                { left: left.to_h, top: top.to_h, right: right.to_h }
+              end
+
+              # @private
+              def to_s
+                format "(left: %s, top: %s, right: %s)", left.inspect,
+                       top.inspect, right.inspect
+              end
+
+              # @private
+              def inspect
+                "#<Eyebrow #{self}>"
+              end
+            end
+
+            ##
+            # # Eyes
+            #
+            # The landmarks of the eyes in the features of a face.
+            #
+            # Left and right are defined from the vantage of the viewer of the
+            # image, without considering mirror projections typical of photos.
+            # So `face.features.eyes.left` typically is the person's right eye.
+            #
+            # See {Features} and {Face}.
+            #
+            # @see https://cloud.google.com/vision/reference/rest/v1/images/annotate#Type_1
+            #   images.annotate Type
+            #
+            # @attr_reader [Eye] left The left eye.
+            # @attr_reader [Eye] right The right eye.
+            #
+            # @example
+            #   require "google/cloud"
+            #
+            #   gcloud = Google::Cloud.new
+            #   vision = gcloud.vision
+            #
+            #   image = vision.image "path/to/face.jpg"
+            #   face = image.face
+            #
+            #   eyes = face.features.eyes
+            #
+            #   right_eye = eyes.right
+            #   right_eye.pupil
+            #   #=> #<Landmark (x: 256.63464, y: 79.641411, z: -6.0731235)>
+            #
+            class Eyes
+              attr_reader :left, :right
+
+              ##
+              # @private Creates a new Eyes instance.
+              def initialize left, right
+                @left  = left
+                @right = right
+              end
+
+              ##
+              # Returns the object's property values as an array.
+              #
+              # @return [Array]
+              #
+              def to_a
+                [left, right]
+              end
+
+              ##
+              # Deeply converts object to a hash. All keys will be symbolized.
+              #
+              # @return [Hash]
+              #
+              def to_h
+                { left: left.to_h, right: right.to_h }
+              end
+
+              # @private
+              def to_s
+                "(left: #{left.inspect}, right: #{right.inspect})"
+              end
+
+              # @private
+              def inspect
+                "#<Eyes #{self}>"
+              end
+            end
+
+            ##
+            # # Eye
+            #
+            # The landmarks of an eye in the features of a face.
+            #
+            # Left and right are defined from the vantage of the viewer of the
+            # image, without considering mirror projections typical of photos.
+            # So `face.features.eyes.left` typically is the person's right eye.
+            #
+            # See {Eyes}, {Features} and {Face}.
+            #
+            # @see https://cloud.google.com/vision/reference/rest/v1/images/annotate#Type_1
+            #   images.annotate Type
+            #
+            # @attr_reader [Landmark] left The eye, left corner.
+            # @attr_reader [Landmark] bottom The eye, bottom boundary.
+            # @attr_reader [Landmark] center The eye, center.
+            # @attr_reader [Landmark] pupil The eye pupil.
+            # @attr_reader [Landmark] top The eye, top boundary.
+            # @attr_reader [Landmark] right The eye, right corner.
+            #
+            # @example
+            #   require "google/cloud"
+            #
+            #   gcloud = Google::Cloud.new
+            #   vision = gcloud.vision
+            #
+            #   image = vision.image "path/to/face.jpg"
+            #   face = image.face
+            #
+            #   right_eye = face.features.eyes.right
+            #
+            #   right_eye.pupil
+            #   #=> #<Landmark (x: 256.63464, y: 79.641411, z: -6.0731235)>
+            #
+            class Eye
+              attr_reader :left, :bottom, :center, :pupil, :top, :right
+
+              ##
+              # @private Creates a new Eye instance.
+              def initialize left, bottom, center, pupil, top, right
+                @left   = left
+                @bottom = bottom
+                @center = center
+                @pupil  = pupil
+                @top    = top
+                @right  = right
+              end
+
+              ##
+              # Returns the object's property values as an array.
+              #
+              # @return [Array]
+              #
+              def to_a
+                [left, top, right]
+              end
+
+              ##
+              # Deeply converts object to a hash. All keys will be symbolized.
+              #
+              # @return [Hash]
+              #
+              def to_h
+                { left: left.to_h, bottom: bottom.to_h, center: center.to_h,
+                  pupil: pupil.to_h, top: top.to_h, right: right.to_h }
+              end
+
+              # @private
+              def to_s
+                tmplt = "(left: %s, bottom: %s, center: %s, " \
+                          "pupil: %s, top: %s, right: %s)"
+                format tmplt, left.inspect, bottom.inspect, center.inspect,
+                       pupil.inspect, top.inspect, right.inspect
+              end
+
+              # @private
+              def inspect
+                "#<Eye #{self}>"
+              end
+            end
+
+            ##
+            # # Lips
+            #
+            # The landmarks of the lips in the features of a face.
+            #
+            # See {Features} and {Face}.
+            #
+            # @see https://cloud.google.com/vision/reference/rest/v1/images/annotate#Type_1
+            #   images.annotate Type
+            #
+            # @attr_reader [Landmark] top The upper lip.
+            # @attr_reader [Landmark] bottom The lower lip.
+            #
+            # @example
+            #   require "google/cloud"
+            #
+            #   gcloud = Google::Cloud.new
+            #   vision = gcloud.vision
+            #
+            #   image = vision.image "path/to/face.jpg"
+            #   face = image.face
+            #
+            #   lips = face.features.lips
+            #
+            #   lips.top
+            #   #=> #<Landmark (x: 228.54768, y: 143.2952, z: -5.6550336)>
+            #
+            class Lips
+              attr_reader :top, :bottom
+
+              alias_method :upper, :top
+              alias_method :lower, :bottom
+
+              ##
+              # @private Creates a new Lips instance.
+              def initialize top, bottom
+                @top = top
+                @bottom = bottom
+              end
+
+              ##
+              # Returns the object's property values as an array.
+              #
+              # @return [Array]
+              #
+              def to_a
+                [top, bottom]
+              end
+
+              ##
+              # Deeply converts object to a hash. All keys will be symbolized.
+              #
+              # @return [Hash]
+              #
+              def to_h
+                { top: top.to_h, bottom: bottom.to_h }
+              end
+
+              # @private
+              def to_s
+                "(top: #{top.inspect}, bottom: #{bottom.inspect})"
+              end
+
+              # @private
+              def inspect
+                "#<Lips #{self}>"
+              end
+            end
+
+            ##
+            # # Mouth
+            #
+            # The landmarks of the mouth in the features of a face.
+            #
+            # Left and right are defined from the vantage of the viewer of the
+            # image, without considering mirror projections typical of photos.
+            # So `face.features.eyes.left` typically is the person's right eye.
+            #
+            # See {Features} and {Face}.
+            #
+            # @see https://cloud.google.com/vision/reference/rest/v1/images/annotate#Type_1
+            #   images.annotate Type
+            #
+            # @attr_reader [Landmark] left The mouth, left.
+            # @attr_reader [Landmark] center The mouth, center.
+            # @attr_reader [Landmark] right TThe mouth, right.
+            #
+            # @example
+            #   require "google/cloud"
+            #
+            #   gcloud = Google::Cloud.new
+            #   vision = gcloud.vision
+            #
+            #   image = vision.image "path/to/face.jpg"
+            #   face = image.face
+            #
+            #   mouth = face.features.mouth
+            #
+            #   mouth.center
+            #   #=> #<Landmark (x: 228.53499, y: 150.29066, z: 1.1069832)>
+            #
+            class Mouth
+              attr_reader :left, :center, :right
+
+              ##
+              # @private Creates a new Mouth instance.
+              def initialize left, center, right
+                @left   = left
+                @center = center
+                @right  = right
+              end
+
+              ##
+              # Returns the object's property values as an array.
+              #
+              # @return [Array]
+              #
+              def to_a
+                [left, center, right]
+              end
+
+              ##
+              # Deeply converts object to a hash. All keys will be symbolized.
+              #
+              # @return [Hash]
+              #
+              def to_h
+                { left: left.to_h, center: center.to_h, right: right.to_h }
+              end
+
+              # @private
+              def to_s
+                format "(left: %s, center: %s, right: %s)", left.inspect,
+                       center.inspect, right.inspect
+              end
+
+              # @private
+              def inspect
+                "#<Mouth #{self}>"
+              end
+            end
+
+            ##
+            # # Nose
+            #
+            # The landmarks of the nose in the features of a face.
+            #
+            # Left and right are defined from the vantage of the viewer of the
+            # image, without considering mirror projections typical of photos.
+            # So `face.features.eyes.left` typically is the person's right eye.
+            #
+            # See {Features} and {Face}.
+            #
+            # @see https://cloud.google.com/vision/reference/rest/v1/images/annotate#Type_1
+            #   images.annotate Type
+            #
+            # @attr_reader [Landmark] left The nose, bottom left.
+            # @attr_reader [Landmark] bottom The nose, bottom center.
+            # @attr_reader [Landmark] tip The nose tip.
+            # @attr_reader [Landmark] top The midpoint between the eyes.
+            # @attr_reader [Landmark] right The nose, bottom right.
+            #
+            # @example
+            #   require "google/cloud"
+            #
+            #   gcloud = Google::Cloud.new
+            #   vision = gcloud.vision
+            #
+            #   image = vision.image "path/to/face.jpg"
+            #   face = image.face
+            #
+            #   nose = face.features.nose
+            #
+            #   nose.tip
+            #   #=> #<Landmark (x: 225.23511, y: 122.47372, z: -25.817825)>
+            #
+            class Nose
+              attr_reader :left, :bottom, :tip, :top, :right
+
+              ##
+              # @private Creates a new Nose instance.
+              def initialize left, bottom, tip, top, right
+                @left   = left
+                @bottom = bottom
+                @tip    = tip
+                @top    = top
+                @right  = right
+              end
+
+              ##
+              # Returns the object's property values as an array.
+              #
+              # @return [Array]
+              #
+              def to_a
+                [left, bottom, tip, top, right]
+              end
+
+              ##
+              # Deeply converts object to a hash. All keys will be symbolized.
+              #
+              # @return [Hash]
+              #
+              def to_h
+                { left: left.to_h, bottom: bottom.to_h, tip: tip.to_h,
+                  top: top.to_h, right: right.to_h }
+              end
+
+              # @private
+              def to_s
+                tmplt = "(left: %s, bottom: %s, tip: %s, " \
+                          "top: %s, right: %s)"
+                format tmplt, left.inspect, bottom.inspect, tip.inspect,
+                       top.inspect, right.inspect
+              end
+
+              # @private
+              def inspect
+                "#<Nose #{self}>"
+              end
+            end
+          end
+
+          ##
+          # # Likelihood
+          #
+          # A bucketized representation of likelihood of various separate facial
+          # characteristics, meant to give highly stable results across model
+          # upgrades.
+          #
+          # See {Face}.
+          #
+          # @see https://cloud.google.com/vision/reference/rest/v1/images/annotate#Likelihood
+          #   images.annotate Likelihood
+          #
+          # @example
+          #   require "google/cloud"
+          #
+          #   gcloud = Google::Cloud.new
+          #   vision = gcloud.vision
+          #
+          #   image = vision.image "path/to/face.jpg"
+          #   face = image.face
+          #
+          #   face.likelihood.to_h.count #=> 7
+          #   face.likelihood.sorrow? #=> false
+          #   face.likelihood.sorrow #=> "VERY_UNLIKELY"
+          #
+          class Likelihood
+            POSITIVE_RATINGS = %w(POSSIBLE LIKELY VERY_LIKELY)
+
+            ##
+            # @private The FaceAnnotation Google API Client object.
+            attr_accessor :gapi
+
+            ##
+            # @private Creates a new Likelihood instance.
+            def initialize
+              @gapi = {}
+            end
+
+            ##
+            # Joy likelihood rating. Possible values are `VERY_UNLIKELY`,
+            # `UNLIKELY`, `POSSIBLE`, `LIKELY`, and `VERY_LIKELY`.
+            def joy
+              @gapi.joy_likelihood
+            end
+
+            ##
+            # Joy likelihood. Returns `true` if {#joy} is `POSSIBLE`, `LIKELY`,
+            # or `VERY_LIKELY`.
+            #
+            # @return [Boolean]
+            #
+            def joy?
+              POSITIVE_RATINGS.include? joy
+            end
+
+            ##
+            # Sorrow likelihood rating. Possible values are `VERY_UNLIKELY`,
+            # `UNLIKELY`, `POSSIBLE`, `LIKELY`, and `VERY_LIKELY`.
+            def sorrow
+              @gapi.sorrow_likelihood
+            end
+
+            ##
+            # Sorrow likelihood. Returns `true` if {#sorrow} is `POSSIBLE`,
+            # `LIKELY`, or `VERY_LIKELY`.
+            #
+            # @return [Boolean]
+            #
+            def sorrow?
+              POSITIVE_RATINGS.include? sorrow
+            end
+
+            ##
+            # Joy likelihood rating. Possible values are `VERY_UNLIKELY`,
+            # `UNLIKELY`, `POSSIBLE`, `LIKELY`, and `VERY_LIKELY`.
+            def anger
+              @gapi.anger_likelihood
+            end
+
+            ##
+            # Anger likelihood. Returns `true` if {#anger} is `POSSIBLE`,
+            # `LIKELY`, or `VERY_LIKELY`.
+            #
+            # @return [Boolean]
+            #
+            def anger?
+              POSITIVE_RATINGS.include? anger
+            end
+
+            ##
+            # Surprise likelihood rating. Possible values are `VERY_UNLIKELY`,
+            # `UNLIKELY`, `POSSIBLE`, `LIKELY`, and `VERY_LIKELY`.
+            def surprise
+              @gapi.surprise_likelihood
+            end
+
+            ##
+            # Surprise likelihood. Returns `true` if {#surprise} is `POSSIBLE`,
+            # `LIKELY`, or `VERY_LIKELY`.
+            #
+            # @return [Boolean]
+            #
+            def surprise?
+              POSITIVE_RATINGS.include? surprise
+            end
+
+            ##
+            # Under Exposed likelihood rating. Possible values are
+            # `VERY_UNLIKELY`, `UNLIKELY`, `POSSIBLE`, `LIKELY`, and
+            # `VERY_LIKELY`.
+            def under_exposed
+              @gapi.under_exposed_likelihood
+            end
+
+            ##
+            # Under Exposed likelihood. Returns `true` if {#under_exposed} is
+            # `POSSIBLE`, `LIKELY`, or `VERY_LIKELY`.
+            #
+            # @return [Boolean]
+            #
+            def under_exposed?
+              POSITIVE_RATINGS.include? under_exposed
+            end
+
+            ##
+            # Blurred likelihood rating. Possible values are `VERY_UNLIKELY`,
+            # `UNLIKELY`, `POSSIBLE`, `LIKELY`, and `VERY_LIKELY`.
+            def blurred
+              @gapi.blurred_likelihood
+            end
+
+            ##
+            # Blurred likelihood. Returns `true` if {#blurred} is `POSSIBLE`,
+            # `LIKELY`, or `VERY_LIKELY`.
+            #
+            # @return [Boolean]
+            #
+            def blurred?
+              POSITIVE_RATINGS.include? blurred
+            end
+
+            ##
+            # Headwear likelihood rating. Possible values are `VERY_UNLIKELY`,
+            # `UNLIKELY`, `POSSIBLE`, `LIKELY`, and `VERY_LIKELY`.
+            def headwear
+              @gapi.headwear_likelihood
+            end
+
+            ##
+            # Headwear likelihood. Returns `true` if {#headwear} is `POSSIBLE`,
+            # `LIKELY`, or `VERY_LIKELY`.
+            #
+            # @return [Boolean]
+            #
+            def headwear?
+              POSITIVE_RATINGS.include? headwear
+            end
+
+            ##
+            # Converts object to a hash. All keys will be symbolized.
+            #
+            # @return [Hash]
+            #
+            def to_h
+              { joy: joy?, sorrow: sorrow?, anger: anger?, surprise: surprise?,
+                under_exposed: under_exposed?, blurred: blurred?,
+                headwear: headwear? }
+            end
+
+            # @private
+            def to_s
+              tmplt = "(joy?: %s, sorrow?: %s, anger?: %s, " \
+                        "surprise?: %s, under_exposed?: %s, blurred?: %s, " \
+                        "headwear: %s)"
+              format tmplt, joy?.inspect, sorrow?.inspect, anger?.inspect,
+                     surprise?.inspect, under_exposed?.inspect,
+                     blurred?.inspect, headwear?.inspect
+            end
+
+            # @private
+            def inspect
+              "#<Likelihood #{self}>"
+            end
+
+            ##
+            # @private New Annotation::Face::Likelihood from a Google API Client
+            # object.
+            def self.from_gapi gapi
+              new.tap { |f| f.instance_variable_set :@gapi, gapi }
+            end
+          end
+        end
+      end
+    end
+  end
+end