Vision v1.1

docs/toc.json

@@ -166,12 +166,42 @@
         {
             "title": "Vision",
             "type": "vision/visionclient",
+            "patterns": [
+                "/vision"
+            ],
             "nav": [{
                 "title": "Image",
                 "type": "vision/image"
             }, {
                 "title": "Annotation",
-                "type": "vision/annotation"
+                "type": "vision/annotation",
+                "patterns": [
+                    "/vision/annotation"
+                ],
+                "nav": [
+                    {
+                        "title": "CropHint",
+                        "type": "vision/annotation/crophint"
+                    }, {
+                        "title": "Document",
+                        "type": "vision/annotation/document"
+                    }, {
+                        "title": "Entity",
+                        "type": "vision/annotation/entity"
+                    }, {
+                        "title": "Face",
+                        "type": "vision/annotation/face"
+                    }, {
+                        "title": "ImageProperties",
+                        "type": "vision/annotation/imageproperties"
+                    }, {
+                        "title": "SafeSearch",
+                        "type": "vision/annotation/safesearch"
+                    }, {
+                        "title": "Web",
+                        "type": "vision/annotation/web"
+                    }
+                ]
             }]
         }
     ]

src/Vision/Annotation.php

@@ -17,10 +17,13 @@
 
 namespace Google\Cloud\Vision;
 
+use Google\Cloud\Vision\Annotation\CropHint;
+use Google\Cloud\Vision\Annotation\Document;
 use Google\Cloud\Vision\Annotation\Entity;
 use Google\Cloud\Vision\Annotation\Face;
 use Google\Cloud\Vision\Annotation\ImageProperties;
 use Google\Cloud\Vision\Annotation\SafeSearch;
+use Google\Cloud\Vision\Annotation\Web;
 
 /**
  * Represents a [Google Cloud Vision](https://cloud.google.com/vision) image
@@ -33,7 +36,7 @@
  * $cloud = new ServiceBuilder();
  * $vision = $cloud->vision();
  *
- * $imageResource = fopen(__DIR__ .'/assets/family-photo.jpg', 'r');
+ * $imageResource = fopen(__DIR__ . '/assets/family-photo.jpg', 'r');
  * $image = $vision->image($imageResource, [
  *     'FACE_DETECTION'
  * ]);
@@ -49,42 +52,57 @@ class Annotation
     private $info;
 
     /**
-     * @var array
+     * @var Face[]|null
      */
     private $faces;
 
     /**
-     * @var array
+     * @var Entity[]|null
      */
     private $landmarks;
 
     /**
-     * @var array
+     * @var Entity[]|null
      */
     private $logos;
 
     /**
-     * @var array
+     * @var Entity[]|null
      */
     private $labels;
 
     /**
-     * @var array
+     * @var Entity[]|null
      */
     private $text;
 
     /**
-     * @var SafeSearch
+     * @var Document|null
+     */
+    private $fullText;
+
+    /**
+     * @var SafeSearch|null
      */
     private $safeSearch;
 
     /**
-     * @var ImageProperties
+     * @var ImageProperties|null
      */
     private $imageProperties;
 
     /**
-     * @var array
+     * @var CropHint[]|null
+     */
+    private $cropHints;
+
+    /**
+     * @var Web|null
+     */
+    private $web;
+
+    /**
+     * @var array|null
      */
     private $error;
 
@@ -142,6 +160,10 @@ public function __construct($info)
             }
         }
 
+        if (isset($info['fullTextAnnotation'])) {
+            $this->fullText = new Document($info['fullTextAnnotation']);
+        }
+
         if (isset($info['safeSearchAnnotation'])) {
             $this->safeSearch = new SafeSearch($info['safeSearchAnnotation']);
         }
@@ -150,6 +172,17 @@ public function __construct($info)
             $this->imageProperties = new ImageProperties($info['imagePropertiesAnnotation']);
         }
 
+        if (isset($info['cropHintsAnnotation']) && is_array($info['cropHintsAnnotation']['cropHints'])) {
+            $this->cropHints = [];
+            foreach ($info['cropHintsAnnotation']['cropHints'] as $hint) {
+                $this->cropHints[] = new CropHint($hint);
+            }
+        }
+
+        if (isset($info['webDetection'])) {
+            $this->web = new Web($info['webDetection']);
+        }
+
         if (isset($info['error'])) {
             $this->error = $info['error'];
         }
@@ -249,6 +282,23 @@ public function text()
         return $this->text;
     }
 
+    /**
+     * Return the full text annotation.
+     *
+     * Example:
+     * ```
+     * $fullText = $annotation->fullText();
+     * ```
+     *
+     * @see https://cloud.google.com/vision/reference/rest/v1/images/annotate#fulltextannotation FullTextAnnotation
+     *
+     * @return Document|null
+     */
+    public function fullText()
+    {
+        return $this->fullText;
+    }
+
     /**
      * Get the result of a safe search detection
      *
@@ -279,6 +329,36 @@ public function imageProperties()
         return $this->imageProperties;
     }
 
+    /**
+     * Fetch Crop Hints
+     *
+     * Example:
+     * ```
+     * $hints = $annotation->cropHints();
+     * ```
+     *
+     * @return CropHint[]|null
+     */
+    public function cropHints()
+    {
+        return $this->cropHints;
+    }
+
+    /**
+     * Fetch the Web Annotatation.
+     *
+     * Example:
+     * ```
+     * $web = $annotation->web();
+     * ```
+     *
+     * @return Web|null
+     */
+    public function web()
+    {
+        return $this->web;
+    }
+
     /**
      * Get error information, if present
      *

src/Vision/Annotation/CropHint.php

@@ -0,0 +1,83 @@
+<?php
+/**
+ * Copyright 2016 Google Inc.
+ *
+ * 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.
+ */
+
+namespace Google\Cloud\Vision\Annotation;
+
+use Google\Cloud\CallTrait;
+
+/**
+ * Represents a recommended image crop.
+ *
+ * Example:
+ * ```
+ * use Google\Cloud\ServiceBuilder;
+ *
+ * $cloud = new ServiceBuilder();
+ * $vision = $cloud->vision();
+ *
+ * $imageResource = fopen(__DIR__ . '/assets/family-photo.jpg', 'r');
+ * $image = $vision->image($imageResource, [ 'CROP_HINTS' ]);
+ * $annotation = $vision->annotate($image);
+ *
+ * $hints = $annotation->cropHints();
+ * $hint = $hints[0];
+ * ```
+ *
+ * @method boundingPoly() {
+ *     The bounding polygon of the recommended crop.
+ *
+ *     Example:
+ *     ```
+ *     $poly = $hint->boundingPoly();
+ *     ```
+ *
+ *     @return array [BoundingPoly](https://cloud.google.com/vision/docs/reference/rest/v1/images/annotate#boundingpoly)
+ * }
+ * @method confidence() {
+ *     Confidence of this being a salient region.  Range [0, 1].
+ *
+ *     Example:
+ *     ```
+ *     $confidence = $hint->confidence();
+ *     ```
+ *
+ *     @return float
+ * }
+ * @method importanceFraction() {
+ *     Fraction of importance of this salient region with respect to the
+ *     original image.
+ *
+ *     Example:
+ *     ```
+ *     $importance = $hint->importanceFraction();
+ *     ```
+ *
+ *     @return float
+ * }
+ */
+class CropHint extends AbstractFeature
+{
+    use CallTrait;
+
+    /**
+     * @param array $info Crop Hint result
+     */
+    public function __construct(array $info)
+    {
+        $this->info = $info;
+    }
+}

src/Vision/Annotation/Document.php

@@ -0,0 +1,81 @@
+<?php
+/**
+ * Copyright 2016 Google Inc.
+ *
+ * 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.
+ */
+
+namespace Google\Cloud\Vision\Annotation;
+
+use Google\Cloud\CallTrait;
+
+/**
+ * Represents a Document Text Detection result.
+ *
+ * Example:
+ * ```
+ * use Google\Cloud\ServiceBuilder;
+ *
+ * $cloud = new ServiceBuilder();
+ * $vision = $cloud->vision();
+ *
+ * $imageResource = fopen(__DIR__ . '/assets/the-constitution.jpg', 'r');
+ * $image = $vision->image($imageResource, [ 'DOCUMENT_TEXT_DETECTION' ]);
+ * $annotation = $vision->annotate($image);
+ *
+ * $document = $annotation->fullText();
+ * ```
+ *
+ * @method pages() {
+ *     Get the document pages.
+ *
+ *     Example:
+ *     ```
+ *     $pages = $document->pages();
+ *     ```
+ *
+ *     @return array
+ * }
+ * @method text() {
+ *     Get the document text.
+ *
+ *     Example:
+ *     ```
+ *     $text = $document->text();
+ *     ```
+ *
+ *     @return string
+ * }
+ * @method info() {
+ *     Get the Document Text detection result.
+ *
+ *     Example:
+ *     ```
+ *     $info = $document->info();
+ *     ```
+ *
+ *     @return array
+ * }
+ */
+class Document extends AbstractFeature
+{
+    use CallTrait;
+
+    /**
+     * @param array $info Document Text Annotation response.
+     */
+    public function __construct(array $info)
+    {
+        $this->info = $info;
+    }
+}

src/Vision/Annotation/Entity.php

@@ -31,7 +31,7 @@
  * $cloud = new ServiceBuilder();
  * $vision = $cloud->vision();
  *
- * $imageResource = fopen(__DIR__ .'/assets/family-photo.jpg', 'r');
+ * $imageResource = fopen(__DIR__ . '/assets/family-photo.jpg', 'r');
  * $image = $vision->image($imageResource, [ 'text' ]);
  * $annotation = $vision->annotate($image);
  *