[Computer Vision] Add read to CV OCR API.

specification/cognitiveservices/data-plane/ComputerVision/stable/v2.0/Ocr.json

@@ -110,6 +110,85 @@
           }
         }
       }
+    },
+    "/read/core/asyncBatchAnalyze": {
+      "post": {
+        "description": "Use this interface to get the result of a Read operation, employing the state-of-the-art Optical Character Recognition (OCR) algorithms optimized for text-heavy documents. When you use the Read File interface, the response contains a field called \"Operation-Location\". The \"Operation-Location\" field contains the URL that you must use for your \"Read Operation Result\" operation to access OCR results.​",
+        "operationId": "BatchReadFile",
+        "parameters": [
+          {
+            "$ref": "#/parameters/ImageUrl"
+          },
+          {
+            "$ref": "#/parameters/TextRecognitionMode"
+          }
+        ],
+        "consumes": [
+          "application/json"
+        ],
+        "produces": [
+          "application/json"
+        ],
+        "responses": {
+          "202": {
+            "description": "The service has accepted the request and will start processing later.",
+            "headers": {
+              "Operation-Location": {
+                "description": "URL to query for status of the operation. The operation ID will expire in 48 hours. ",
+                "type": "string"
+              }
+            }
+          },
+          "default": {
+            "description": "Error response.",
+            "schema": {
+              "$ref": "#/definitions/ComputerVisionError"
+            }
+          }
+        },
+        "x-ms-examples": {
+          "Successful Domain Model analysis request": {
+            "$ref": "./examples/SuccessfulBatchReadFileWithUrl.json"
+          }
+        }
+      }
+    },
+    "/read/operations/{operationId}": {
+      "get": {
+        "description": "This interface is used for getting OCR results of Read operation. The URL to this interface should be retrieved from \"Operation-Location\" field returned from Batch Read File interface.",
+        "operationId": "GetReadOperationResult",
+        "parameters": [
+          {
+            "name": "operationId",
+            "in": "path",
+            "description": "Id of read operation returned in the response of the \"Batch Read File\" interface.",
+            "required": true,
+            "type": "string"
+          }
+        ],
+        "produces": [
+          "application/json"
+        ],
+        "responses": {
+          "200": {
+            "description": "Returns the read operation status.",
+            "schema": {
+              "$ref": "#/definitions/ReadOperationResult"
+            }
+          },
+          "default": {
+            "description": "Error response.",
+            "schema": {
+              "$ref": "#/definitions/ComputerVisionError"
+            }
+          }
+        },
+        "x-ms-examples": {
+          "Successful Domain Model analysis request": {
+            "$ref": "./examples/SuccessfulReadOperationResult.json"
+          }
+        }
+      }
     }
   },
   "x-ms-paths": {
@@ -154,36 +233,135 @@
           }
         }
       }
+    },
+    "/read/core/asyncBatchAnalyze?overload=stream": {
+      "post": {
+        "description": "Use this interface to get the result of a Read Document operation, employing the state-of-the-art Optical Character Recognition (OCR) algorithms optimized for text-heavy documents. When you use the Read Document interface, the response contains a field called \"Operation-Location\". The \"Operation-Location\" field contains the URL that you must use for your \"Get Read Result operation\" to access OCR results.​",
+        "operationId": "BatchReadFileInStream",
+        "parameters": [
+          {
+            "$ref": "#/parameters/ImageStream"
+          },
+          {
+            "$ref": "#/parameters/TextRecognitionMode"
+          }
+        ],
+        "consumes": [
+          "application/octet-stream"
+        ],
+        "produces": [
+          "application/json"
+        ],
+        "responses": {
+          "202": {
+            "description": "The service has accepted the request and will start processing later.",
+            "headers": {
+              "Operation-Location": {
+                "description": "URL to query for status of the operation. The operation ID will expire in 48 hours. ",
+                "type": "string"
+              }
+            }
+          },
+          "default": {
+            "description": "Error response.",
+            "schema": {
+              "$ref": "#/definitions/ComputerVisionError"
+            }
+          }
+        },
+        "x-ms-examples": {
+          "Successful Domain Model analysis request": {
+            "$ref": "./examples/SuccessfulBatchReadFileWithStream.json"
+          }
+        }
+      }
     }
   },
   "definitions": {
     "TextOperationResult": {
       "type": "object",
+      "description": "Result of recognition text operation.",
       "properties": {
         "status": {
-          "type": "string",
           "description": "Status of the text operation.",
-          "enum": [
-            "Not Started",
-            "Running",
-            "Failed",
-            "Succeeded"
-          ],
-          "x-ms-enum": {
-            "name": "TextOperationStatusCodes",
-            "modelAsString": false
-          },
-          "x-nullable": false
+          "$ref": "#/definitions/OperationStatus"
         },
         "recognitionResult": {
-          "$ref": "#/definitions/RecognitionResult"
+          "$ref": "#/definitions/TextRecognitionResult",
+          "description": "Text recognition result of the text operation."
         }
       }
     },
-    "RecognitionResult": {
+    "ReadOperationResult": {
       "type": "object",
+      "description": "OCR result of the read operation.",
       "properties": {
+        "status": {
+          "description": "Status of the read operation.",
+          "$ref": "#/definitions/OperationStatus"
+        },
+        "recognitionResults": {
+          "description": "A array of text recognition result of the read operation.",
+          "type": "array",
+          "items": {
+            "$ref": "#/definitions/TextRecognitionResult"
+          }
+        }
+      }
+    },
+    "OperationStatus": {
+      "type": "string",
+      "description": "Status code of the text operation.",
+      "enum": [
+        "Not Started",
+        "Running",
+        "Failed",
+        "Succeeded"
+      ],
+      "x-ms-enum": {
+        "name": "TextOperationStatusCodes",
+        "modelAsString": false
+      },
+      "x-nullable": false
+    },
+    "TextRecognitionResult": {
+      "description": "Json object representing a recognized text region",
+      "type": "object",
+      "required": [
+        "lines"
+      ],
+      "properties": {
+        "page": {
+          "description": "The 1-based page number of the recognition result.",
+          "type": "integer"
+        },
+        "clockwiseOrientation": {
+          "description": "The orientation of the image in degrees in the clockwise direction. Range between [0, 360).",
+          "type": "number"
+        },
+         "width": {
+          "description": "The width of the image in pixels or the PDF in inches.",
+          "type": "number"
+        },
+        "height": {
+          "description": "The height of the image in pixels or the PDF in inches.",
+          "type": "number"
+        },
+       "unit": {
+          "description": "The unit used in the Width, Height and BoundingBox. For images, the unit is \"pixel\". For PDF, the unit is \"inch\".",
+          "type": "string",
+          "enum": [
+            "pixel",
+            "inch"
+          ],
+          "x-ms-enum": {
+            "name": "TextRecognitionResultDimensionUnit",
+            "modelAsString": false
+          },
+          "x-nullable": true
+        },
         "lines": {
+          "description": "A list of recognized text lines.",
           "type": "array",
           "items": {
             "$ref": "#/definitions/Line"
@@ -192,15 +370,19 @@
       }
     },
     "Line": {
+      "description": "Json object representing a recognized text line.",
       "type": "object",
       "properties": {
         "boundingBox": {
+          "description": "Bounding box of a recognized line.",
           "$ref": "#/definitions/BoundingBox"
         },
         "text": {
+          "description": "The text content of the line.",
           "type": "string"
         },
         "words": {
+          "description": "List of words in the text line.",
           "type": "array",
           "items": {
             "$ref": "#/definitions/Word"
@@ -209,17 +391,38 @@
       }
     },
     "Word": {
+      "description": "Json object representing a recognized word.",
       "type": "object",
+      "required": [
+        "boundingBox",
+        "text"
+      ],
       "properties": {
         "boundingBox": {
+          "description": "Bounding box of a recognized word.",
           "$ref": "#/definitions/BoundingBox"
         },
         "text": {
+          "description": "The text content of the word.",
           "type": "string"
+        },
+        "confidence": {
+          "description": "Qualitative confidence measure.",
+          "type": "string",
+          "enum": [
+            "High",
+            "Low"
+          ],
+          "x-ms-enum": {
+            "name": "TextRecognitionResultConfidenceClass",
+            "modelAsString": false
+          },
+          "x-nullable": true
         }
       }
     },
     "BoundingBox": {
+      "description": "Quadrangle bounding box, with coordinates in original image. The eight numbers represent the four points (x-coordinate, y-coordinate from the left-top corner of the image) of the detected rectangle from the left-top corner in the clockwise direction. For images, coordinates are in pixels. For PDF, coordinates are in inches.",
       "type": "array",
       "items": {
         "type": "integer",
@@ -334,4 +537,4 @@
       "x-ms-skip-url-encoding": true
     }
   }
-}
+}

specification/cognitiveservices/data-plane/ComputerVision/stable/v2.0/examples/SuccessfulBatchReadFileWithStream.json

@@ -0,0 +1,15 @@
+{
+  "parameters": {
+    "Endpoint": "{Endpoint}",
+    "Ocp-Apim-Subscription-Key": "{API key}",
+    "mode": "Printed",
+    "Image": "{binary}"
+  },
+  "responses": {
+    "202": {
+      "header": {
+        "Operation-Location": "https://{domain}/vision/v2.0/getReadResult/e56ffa6e-1ee4-4042-bc07-993db706c95f"
+      }
+    }
+  }
+}

specification/cognitiveservices/data-plane/ComputerVision/stable/v2.0/examples/SuccessfulBatchReadFileWithUrl.json

@@ -0,0 +1,15 @@
+{
+  "parameters": {
+    "Endpoint": "{Endpoint}",
+    "Ocp-Apim-Subscription-Key": "{API key}",
+    "mode": "Printed",
+    "ImageUrl": "{url}"
+  },
+  "responses": {
+    "202": {
+      "header": {
+        "Operation-Location": "https://{domain}/vision/v2.0/getReadResult/e56ffa6e-1ee4-4042-bc07-993db706c95f"
+      }
+    }
+  }
+}