swagger: '2.0'
info:
  version: 2020-08-01-preview
  title: Microsoft Azure AccessControlClient AccessConnector Ocr API
schemes:
- https
tags:
- name: Ocr
paths:
  /ocr:
    post:
      description: Optical Character Recognition (OCR) detects printed text in an image and extracts the recognized characters into a machine-usable character stream.   Upon success, the OCR results will be returned. Upon failure, the error code together with an error message will be returned. The error code can be one of InvalidImageUrl, InvalidImageFormat, InvalidImageSize, NotSupportedImage,  NotSupportedLanguage, or InternalServerError.
      operationId: microsoftAzureRecognizeprintedtext
      consumes:
      - application/json
      produces:
      - application/json
      parameters:
      - $ref: '#/parameters/DetectOrientation'
      - $ref: ../../../Common/Parameters.json#/parameters/ImageUrl
      - $ref: '#/parameters/OcrLanguage'
      responses:
        '200':
          description: The OCR results in the hierarchy of region/line/word. The results include text, bounding box for regions, lines and words.textAngleThe angle, in degrees, of the detected text with respect to the closest horizontal or vertical direction. After rotating the input image clockwise by this angle, the recognized text lines become horizontal or vertical. In combination with the orientation property it can be used to overlay recognition results correctly on the original image, by rotating either the original image or recognition results by a suitable angle around the center of the original image. If the angle cannot be confidently detected, this property is not present. If the image contains text at different angles, only part of the text will be recognized correctly.
          schema:
            $ref: '#/definitions/OcrResult'
        default:
          description: Error response.
          schema:
            $ref: '#/definitions/ComputerVisionError'
      x-ms-examples:
        Successful Ocr request:
          $ref: ./examples/SuccessfulOcrWithUrl.json
      summary: Microsoft Azure Post Ocr
      tags:
      - Ocr
definitions:
  OcrResult:
    type: object
    properties:
      language:
        type: string
        description: The BCP-47 language code of the text in the image.
      textAngle:
        type: number
        format: double
        description: The angle, in degrees, of the detected text with respect to the closest horizontal or vertical direction. After rotating the input image clockwise by this angle, the recognized text lines become horizontal or vertical. In combination with the orientation property it can be used to overlay recognition results correctly on the original image, by rotating either the original image or recognition results by a suitable angle around the center of the original image. If the angle cannot be confidently detected, this property is not present. If the image contains text at different angles, only part of the text will be recognized correctly.
      orientation:
        type: string
        description: Orientation of the text recognized in the image. The value (up,down,left, or right) refers to the direction that the top of the recognized text is facing, after the image has been rotated around its center according to the detected text angle (see textAngle property).
      regions:
        type: array
        description: An array of objects, where each object represents a region of recognized text.
        items:
          $ref: '#/definitions/OcrRegion'
  OcrRegion:
    type: object
    description: A region consists of multiple lines (e.g. a column of text in a multi-column document).
    properties:
      boundingBox:
        type: string
        description: Bounding box of a recognized region. The four integers represent the x-coordinate of the left edge, the y-coordinate of the top edge, width, and height of the bounding box, in the coordinate system of the input image, after it has been rotated around its center according to the detected text angle (see textAngle property), with the origin at the top-left corner, and the y-axis pointing down.
      lines:
        type: array
        items:
          $ref: '#/definitions/OcrLine'
  ComputerVisionError:
    type: object
    required:
    - code
    - message
    properties:
      code:
        type: string
        description: The error code.
        enum:
        - InvalidImageUrl
        - InvalidImageFormat
        - InvalidImageSize
        - NotSupportedVisualFeature
        - NotSupportedImage
        - InvalidDetails
        - NotSupportedLanguage
        - BadArgument
        - FailedToProcess
        - Timeout
        - InternalServerError
        - Unspecified
        - StorageException
        x-ms-enum:
          name: ComputerVisionErrorCodes
          modelAsString: false
      message:
        type: string
        description: A message explaining the error reported by the service.
      requestId:
        type: string
        description: A unique request identifier.
  OcrLine:
    type: object
    description: An object describing a single recognized line of text.
    properties:
      boundingBox:
        type: string
        description: Bounding box of a recognized line. The four integers represent the x-coordinate of the left edge, the y-coordinate of the top edge, width, and height of the bounding box, in the coordinate system of the input image, after it has been rotated around its center according to the detected text angle (see textAngle property), with the origin at the top-left corner, and the y-axis pointing down.
      words:
        type: array
        description: An array of objects, where each object represents a recognized word.
        items:
          $ref: '#/definitions/OcrWord'
  OcrWord:
    type: object
    description: Information on a recognized word.
    properties:
      boundingBox:
        type: string
        description: Bounding box of a recognized word. The four integers represent the x-coordinate of the left edge, the y-coordinate of the top edge, width, and height of the bounding box, in the coordinate system of the input image, after it has been rotated around its center according to the detected text angle (see textAngle property), with the origin at the top-left corner, and the y-axis pointing down.
      text:
        type: string
        description: String value of a recognized word.
parameters:
  OcrLanguage:
    name: language
    in: query
    description: The BCP-47 language code of the text to be detected in the image. The default value is 'unk'
    type: string
    required: false
    x-ms-parameter-location: method
    x-nullable: false
    x-ms-enum:
      name: OcrLanguages
      modelAsString: false
    default: unk
    enum:
    - unk
    - zh-Hans
    - zh-Hant
    - cs
    - da
    - nl
    - en
    - fi
    - fr
    - de
    - el
    - hu
    - it
    - ja
    - ko
    - nb
    - pl
    - pt
    - ru
    - es
    - sv
    - tr
    - ar
    - ro
    - sr-Cyrl
    - sr-Latn
    - sk
  DetectOrientation:
    name: detectOrientation
    in: query
    description: 'Whether detect the text orientation in the image. With detectOrientation=true the OCR service tries to detect the image orientation and correct it before further processing (e.g. if it''s upside-down). '
    required: true
    x-ms-parameter-location: method
    type: boolean
    default: true
x-ms-parameterized-host:
  hostTemplate: '{endpoint}'
  useSchemePrefix: false
  parameters:
  - $ref: '#/parameters/Endpoint'