前言

计算机视觉所涉及的面很广泛，Computer Vision API中提供了几个常用的分析功能，可实现解读图片内容信息，对图片进行OCR识别，生成缩略图，未来也许会增加更多功能。本文将针对其分别是本文将针对Cognitive Services中提供的功能的调用方法做一些讲解。

Computer Vision API

微软认知服务中的计算机视觉分析主要是针对一张静态图片进行分析，当然图片的格式会有一定的要求，

1. 图片的格式需要是JPEG、PNG、GIF以及BMP
2. 图片尺寸不可以大于4MB
3. 图片像素需要大于50*50（px）

针对API调用中图片的提交方式不限于上传图片，还可以通过给定一个网络上图片的URL的方式进行图片提交。

Computer Vision API 中提供了7个API供调用：

1. Analyze Image
2. Describe Image
3. Tag Image
4. List Domain Specific Models
5. Recognize Domain Specific Content
6. Get Thumbnail
7. OCR

Analyze Image

这个API可以理解为一个总的调用API，可以通过这个API获取所有有关图片的信息（除了OCR信息），首先是接口URL：

https://api.projectoxford.ai/vision/v1.0/analyze[?visualFeatures][&details]

URL中包含两个可选参数visualFeatures以及details，
- visualFeatures，字符型，当需要使用多个值的时候，使用逗号进行分割。

- details，字符型，当需要使用多个值的时候，使用逗号进行分割。

Analyze Image这个API通过POST的方式进行调用，除了URL部分的参数外，微软认知服务中还包括了请求的Header的一些参数需要我们在调用前设置，这个API中包括2个，（基本每个API中都需要这2个）

根据Header中Content-Type设置的方式不同，我们可以通过两种方式提交图片数据，一种是直接就是图片的内容通过POST直接提交，另外一种方式是将图片在网络的URL地址放入一个JSON字符串中提交。

当设置为application/octet-stream、multipart/form-data时， POST中的数据直接就是Binary流，
当设置为application/json时，POST中的数据按如下格式实现，

{"url":"http://example.com/images/test.jpg"}

最后介绍的是这个API的返回值，返回信息为一串JSON字符串。格式如下：

{
  "categories": [
    {
      "name": "abstract_",
      "score": 0.00390625
    },
    {
      "name": "people_",
      "score": 0.83984375,
      "detail": {
        "celebrities": [
          {
            "name": "Satya Nadella",
            "faceRectangle": {
              "left": 597,
              "top": 162,
              "width": 248,
              "height": 248
            },
            "confidence": 0.999028444
          }
        ]
      }
    }
  ],
  "adult": {
    "isAdultContent": false,
    "isRacyContent": false,
    "adultScore": 0.0934349000453949,
    "racyScore": 0.068613491952419281
  },
  "tags": [
    {
      "name": "person",
      "confidence": 0.98979085683822632
    },
    {
      "name": "man",
      "confidence": 0.94493889808654785
    },
    {
      "name": "outdoor",
      "confidence": 0.938492476940155
    },
    {
      "name": "window",
      "confidence": 0.89513939619064331
    }
  ],
  "description": {
    "tags": [
      "person",
      "man",
      "outdoor",
      "window",
      "glasses"
    ],
    "captions": [
      {
        "text": "Satya Nadella sitting on a bench",
        "confidence": 0.48293603002174407
      }
    ]
  },
  "requestId": "0dbec5ad-a3d3-4f7e-96b4-dfd57efe967d",
  "metadata": {
    "width": 1500,
    "height": 1000,
    "format": "Jpeg"
  },
  "faces": [
    {
      "age": 44,
      "gender": "Male",
      "faceRectangle": {
        "left": 593,
        "top": 160,
        "width": 250,
        "height": 250
      }
    }
  ],
  "color": {
    "dominantColorForeground": "Brown",
    "dominantColorBackground": "Brown",
    "dominantColors": [
      "Brown",
      "Black"
    ],
    "accentColor": "873B59",
    "isBWImg": false
  },
  "imageType": {
    "clipArtType": 0,
    "lineDrawingType": 0
  }
}

其中在imageType这部分的两个参数(clipArtType和lineDrawingType）的值是枚举类型，

ClipartType:
- Non-clipart = 0
- ambiguous = 1
- normal-clipart = 2
- good-clipart = 3

LineDrawingType
- Non-LineDrawing = 0
- LineDrawing = 1

这里针对category信息做下说明，目前微软感知服务中的计算机视觉可以自动识别并归类出如下86类内容，

在调用过程中如果有异常产生，可以根据Response来识别出来，同时也会返回的异常的具体内容，类似格式如下：

{
        "code":"BadArgument",
        "message":"Invalid Media Type"
}

整个API的具体调用示例，C#可以参考如下：

async void MakeRequest()
{
    var client = new HttpClient();
    var queryString = HttpUtility.ParseQueryString(string.Empty);

    // Request headers
    client.DefaultRequestHeaders.Add("Ocp-Apim-Subscription-Key", "{subscription key}");

    // Request parameters
    queryString["visualFeatures"] = "Categories";
    queryString["details"] = "{string}";
    var uri = "https://api.projectoxford.ai/vision/v1.0/analyze?" + queryString;

    HttpResponseMessage response;

    // Request body
    byte[] byteData = Encoding.UTF8.GetBytes("{body}");

    using (var content = new ByteArrayContent(byteData))
    {
        content.Headers.ContentType = new MediaTypeHeaderValue("< your content type, i.e. application/json >");
        response = await client.PostAsync(uri, content);
    }

}

Describe Image

描述图片这个API是用于获取针对图片中的内容返回一段适合的句子（当然现在只是支持英语）。Describe Image其实是Analyze Image中其中的一个功能，但是可以通过单独调用Describe Image的API来获取更详细的针对图片内容的描述字符串。

首先是接口URL：

https://api.projectoxford.ai/vision/v1.0/describe[?maxCandidates]

URL中包含一个可选参数maxCandidates，这个参数用于指定最大返回多少个候选的描述字符串，默认值是1。

这个API也是POST方式提交图片信息，所需要的RequestHeader以及Post图片信息的方法同AnalyzeImage相同，这里就不再进行说明了，请参考AnalyzeImage部分的解释。

当发送完Post的调用请求后，如果提交的内容正确，则返回如下格式的JSON数据，

{
  "description": {
    "tags": [
      "person",
      "man",
      "outdoor",
      "window",
      "glasses"
    ],
    "captions": [
      {
        "text": "Satya Nadella sitting on a bench",
        "confidence": 0.48293603002174407
      },
      {
        "text": "Satya Nadella is sitting on a bench",
        "confidence": 0.40037006815422832
      },
      {
        "text": "Satya Nadella sitting in front of a building",
        "confidence": 0.38035155997373377
      }
    ]
  },
  "requestId": "ed2de1c6-fb55-4686-b0da-4da6e05d283f",
  "metadata": {
    "width": 1500,
    "height": 1000,
    "format": "Jpeg"
  }
}

其中captions中的内容就是我们所需要获取的有关提交的图片的内容描述。根据其中的confidence的值我们能够知道其相关的准确程度。

API调用过程的C#示例如下：

static async void MakeRequest()
{
    var client = new HttpClient();
    var queryString = HttpUtility.ParseQueryString(string.Empty);

    // Request headers
    client.DefaultRequestHeaders.Add("Ocp-Apim-Subscription-Key", "{subscription key}");

    // Request parameters
    queryString["maxCandidates"] = "1";
    var uri = "https://api.projectoxford.ai/vision/v1.0/describe?" + queryString;

    HttpResponseMessage response;

    // Request body
    byte[] byteData = Encoding.UTF8.GetBytes("{body}");

    using (var content = new ByteArrayContent(byteData))
    {
        content.Headers.ContentType = new MediaTypeHeaderValue("< your content type, i.e. application/json >");
        response = await client.PostAsync(uri, content);
    }

}

Tag Image

Tag Image用于根据所提交的图片中的内容，自动生成tag信息，这类似于我们现在的blog系统，可以根据目前文章中的内容自动生成tag信息是一样的。这个功能可以实现图片自动分类功能。

首先是接口URL：

https://api.projectoxford.ai/vision/v1.0/tag

这个API也是POST方式提交图片信息，所需要的RequestHeader以及Post图片信息的方法同AnalyzeImage相同，这里就不再进行说明了，请参考AnalyzeImage部分的解释。

当发送完Post的调用请求后，如果提交的内容正确，则返回如下格式的JSON数据，

{
  "tags": [
    {
      "name": "grass",
      "confidence": 0.9999997615814209
    },
    {
      "name": "outdoor",
      "confidence": 0.99997067451477051
    },
    {
      "name": "sky",
      "confidence": 0.99928975105285645
    },
    {
      "name": "building",
      "confidence": 0.99646323919296265
    },
    {
      "name": "house",
      "confidence": 0.99279803037643433
    },
    {
      "name": "lawn",
      "confidence": 0.82268029451370239
    },
    {
      "name": "green",
      "confidence": 0.64122253656387329
    },
    {
      "name": "residential",
      "confidence": 0.31403225660324097
    }
  ],
  "requestId": "1ad0e45e-b7b4-4be3-8042-53be96103337",
  "metadata": {
    "width": 400,
    "height": 400,
    "format": "Jpeg"
  }
}

其中tags节点下的内容就是我们所请求的结果，依然是可以根据confidence信息来获取结果的准确程度。

API调用过程的C#示例如下：

static async void MakeRequest()
{
    var client = new HttpClient();

    // Request headers
    client.DefaultRequestHeaders.Add("Ocp-Apim-Subscription-Key", "{subscription key}");

    var uri = "https://api.projectoxford.ai/vision/v1.0/tag";

    HttpResponseMessage response;

    // Request body
    byte[] byteData = Encoding.UTF8.GetBytes("{body}");

    using (var content = new ByteArrayContent(byteData))
    {
        content.Headers.ContentType = new MediaTypeHeaderValue("< your content type, i.e. application/json >");
        response = await client.PostAsync(uri, content);
    }

}

List Domain Specific Models

这个API的功能其实不是用于做图片的计算机视觉的操作，而是请求当前微软认知服务图片分析中可使用的领域模型列表，可以通过这个列表来了解领域特定模型。
使用其返回值结合后面要介绍的Recognize Domain Specific Content共同使用。

首先是接口URL：

https://api.projectoxford.ai/vision/v1.0/models

虽然这只是一个Domain Specific Models查询功能的API，但是也需要在Request的Header中指定您微软感知服务订阅的Ocp-Apim-Subscription-Key。

在RequestHeader中设置好Ocp-Apim-Subscription-Key后通过Get方式请求数据即可，如果提交的内容正确，则返回如下格式的JSON数据，

{
  "models": [
    {
      "name": "celebrities",
      "categories": [
        "people_"
      ]
    }
  ]
}

目前微软计算机视觉中的Model只是支持celebrities这一种， 所以在下面介绍的“名人识别”API中，参数只能传入celebrities这一种目前。

API调用过程的C#示例如下：

static async void MakeRequest()
{
    var client = new HttpClient();
    var queryString = HttpUtility.ParseQueryString(string.Empty);

    // Request headers
    client.DefaultRequestHeaders.Add("Ocp-Apim-Subscription-Key", "{subscription key}");

    var uri = "https://api.projectoxford.ai/vision/v1.0/models?" + queryString;

    var response = await client.GetAsync(uri);
}

Recognize Domain Specific Content

“识别领域特定物体”这个就是传入一个图片，能够针对图片内的内容，在指定领域模型内识别出领域模型内的物体。目前只支持一种模型（名人模型），可以通过上传一张包括名人的图片，并设定为celebrities并调用该API即可返回图片中人物的名称（当然必须是名人）。

首先是接口URL：

https://api.projectoxford.ai/vision/v1.0/models/{model}/analyze

URL中包含一个可变参数{model}必须指定，

model参数的内容需要根据之前介绍的List Domain Specific Models所返回的内容来进行设定，目前List的API中只返回了一个模型celebrities，所以目前只支持这一种。

这个API也是POST方式提交图片信息，所需要的RequestHeader以及Post图片信息的方法同AnalyzeImage相同，这里就不再进行说明了，请参考AnalyzeImage部分的解释。

当发送完Post的调用请求后，如果提交的内容正确，则返回如下格式的JSON数据，

{
  "requestId": "f0027b4b-dc0d-4082-9228-1545ed246b03",
  "metadata": {
    "width": 1500,
    "height": 1000,
    "format": "Jpeg"
  },
  "result": {
    "celebrities": [
      {
        "name": "Satya Nadella",
        "faceRectangle": {
          "left": 597,
          "top": 162,
          "width": 248,
          "height": 248
        },
        "confidence": 0.999028444
      }
    ]
  }
}

每个模型具体的返回参数中都有什么内容，可能并非一样，但是就目前所了解的来看，celebrities的识别结果是根据脸部特征来进行识别的，包括了人物的名称，脸部特征在图片中的区域，以及准确度。

API调用过程的C#示例如下：

static async void MakeRequest()
{
    var client = new HttpClient();
    var queryString = HttpUtility.ParseQueryString(string.Empty);

    // Request headers
    client.DefaultRequestHeaders.Add("Ocp-Apim-Subscription-Key", "{subscription key}");

    var uri = "https://api.projectoxford.ai/vision/v1.0/models/{model}/analyze?" + queryString;

    HttpResponseMessage response;

    // Request body
    byte[] byteData = Encoding.UTF8.GetBytes("{body}");

    using (var content = new ByteArrayContent(byteData))
    {
        content.Headers.ContentType = new MediaTypeHeaderValue("< your content type, i.e. application/json >");
        response = await client.PostAsync(uri, content);
    }

}

Get Thumbnail

Get Thumbnail这个功能就如标题所说的，可以为所提交的图片生成缩略图，与传统意义上的生成缩略图有所不同，认知服务中首先会分析这张图片中具有意义的区域（the region of interest (ROI)），最后会根据ROI进行SmartCropping（笔者理解为是智能剪切？）操作，最后返回缩略图，相比于传统意义上的缩略图更能体现出主体内容。

首先是接口URL：

https://api.projectoxford.ai/vision/v1.0/generateThumbnail[?width][&height][&smartCropping]

URL中包含3个可选参数，width与height必须给定，smartCropping则为可选参数，

这个API也是POST方式提交图片信息，所需要的RequestHeader以及Post图片信息的方法同AnalyzeImage相同，这里就不再进行说明了，请参考AnalyzeImage部分的解释。

当发送完Post的调用请求后，如果提交的内容正确，则直接返回图片的二进制数据，图片格式应该为image/jpeg。

API调用过程的C#示例如下：

static async void MakeRequest()
{
    var client = new HttpClient();
    var queryString = HttpUtility.ParseQueryString(string.Empty);

    // Request headers
    client.DefaultRequestHeaders.Add("Ocp-Apim-Subscription-Key", "{subscription key}");

    // Request parameters
    queryString["width"] = "{number}";
    queryString["height"] = "{number}";
    queryString["smartCropping"] = "true";
    var uri = "https://api.projectoxford.ai/vision/v1.0/generateThumbnail?" + queryString;

    HttpResponseMessage response;

    // Request body
    byte[] byteData = Encoding.UTF8.GetBytes("{body}");

    using (var content = new ByteArrayContent(byteData))
    {
        content.Headers.ContentType = new MediaTypeHeaderValue("< your content type, i.e. application/json >");
        response = await client.PostAsync(uri, content);
    }

}

OCR

OCR这个我们并不陌生，但在微软认知服务出来前，基本上所有的OCR功能都是由本机完成，程序中如果需要使用这种功能，则需要一定的领域知识并进行开发实现。微软在认知服务中，将OCR作为计算机视觉额一部分一同提供服务，这使得我们在程序中不需要再为OCR功能而大动干戈，直接的进行简单的接口调用即可实现功能。

首先是接口URL：

https://api.projectoxford.ai/vision/v1.0/ocr[?language][&detectOrientation ]

URL中包含2个可选参数，language以及detectOrientantion。
langurage参数用于指定识别的语种，采用BCP-47，默认值为unk(自动检测），我们可以通过该参数来设定具体的语种信息，可选择的有如下几种，

    unk (AutoDetect)
    zh-Hans (ChineseSimplified)
    zh-Hant (ChineseTraditional)
    cs (Czech)
    da (Danish)
    nl (Dutch)
    en (English)
    fi (Finnish)
    fr (French)
    de (German)
    el (Greek)
    hu (Hungarian)
    it (Italian)
    Ja (Japanese)
    ko (Korean)
    nb (Norwegian)
    pl (Polish)
    pt (Portuguese)
    ru (Russian)
    es (Spanish)
    sv (Swedish)
    tr (Turkish)

detectOrientantion参数用于指定是否检测文字方向，默认值为true，当启动检测文字方向功能后，提交的图片内容将首先尝试检测方向信息，然后根据方向信息并进行一些纠正后，在进行进一步的文字识别操作。

这个API也是POST方式提交图片信息，所需要的RequestHeader以及Post图片信息的方法同AnalyzeImage相同，这里就不再进行说明了，请参考AnalyzeImage部分的解释。

当发送完Post的调用请求后，如果提交的内容正确，则返回如下格式的JSON数据，

{
  "language": "en",
  "textAngle": -2.0000000000000338,
  "orientation": "Up",
  "regions": [
    {
      "boundingBox": "462,379,497,258",
      "lines": [
        {
          "boundingBox": "462,379,497,74",
          "words": [
            {
              "boundingBox": "462,379,41,73",
              "text": "A"
            },
            {
              "boundingBox": "523,379,153,73",
              "text": "GOAL"
            },
            {
              "boundingBox": "694,379,265,74",
              "text": "WITHOUT"
            }
          ]
        },
        {
          "boundingBox": "565,471,289,74",
          "words": [
            {
              "boundingBox": "565,471,41,73",
              "text": "A"
            },
            {
              "boundingBox": "626,471,150,73",
              "text": "PLAN"
            },
            {
              "boundingBox": "801,472,53,73",
              "text": "IS"
            }
          ]
        },
        {
          "boundingBox": "519,563,375,74",
          "words": [
            {
              "boundingBox": "519,563,149,74",
              "text": "JUST"
            },
            {
              "boundingBox": "683,564,41,72",
              "text": "A"
            },
            {
              "boundingBox": "741,564,153,73",
              "text": "WISH"
            }
          ]
        }
      ]
    }
  ]
}

返回值中包括了几部分内容，包括了一些识别的基本信息以及具体每个区域中所识别出来的文字信息
首先是language用于标记语种信息，textAngle与orientation功能的指明了图片中文字的方向信息以及具体的角度，

其次是regions中的内容，图片中的每个文字的都通过regions中使用boundingBox给标记（或者说是整理）出来，包括words级别和text级别，words中包括若干个text，通过boundingBox来标识出在图片中的坐标信息，每个text则是具体识别出来的字符，也通过boundingBox标识出在图片中的坐标信息。

API调用过程的C#示例如下：

static async void MakeRequest()
{
    var client = new HttpClient();
    var queryString = HttpUtility.ParseQueryString(string.Empty);

    // Request headers
    client.DefaultRequestHeaders.Add("Ocp-Apim-Subscription-Key", "{subscription key}");

    // Request parameters
    queryString["language"] = "unk";
    queryString["detectOrientation "] = "true";
    var uri = "https://api.projectoxford.ai/vision/v1.0/ocr?" + queryString;

    HttpResponseMessage response;

    // Request body
    byte[] byteData = Encoding.UTF8.GetBytes("{body}");

    using (var content = new ByteArrayContent(byteData))
    {
        content.Headers.ContentType = new MediaTypeHeaderValue("< your content type, i.e. application/json >");
        response = await client.PostAsync(uri, content);
    }

}

总结

本文中对微软认知服务中的计算机视觉部分做了一些简单的介绍，并针对其所提供的API进行了一些调用相关的说明。微软在计算机视觉中提供的7个API可以实现3方面功能，

1. 图片分析
   图片分析功能可以帮助用户提供针对图片中的内容进行解读，不仅仅是获取基本的图片信息，还能获取更高层面的感知相关的信息，
2. 生成缩略图
   而生成缩略图功能，也是增加了对ROI进行识别的相关处理操作，这样获得的缩略图也较传统实现获得的缩略图更有使用价值，
3. OCR文字识别
   最后所提供的OCR功能更是能减轻一些涉及到文字识别软件的开发难度，让用户能够更加贴近于具体的业务逻辑而不纠结于具体的技术实现上。

目前主流的软件开发过程中经常是天马行空的功能设计，而在实现过程中发现各种边角功能需要大量的研发以及实现等相关工作。微软的认知服务正是针对这一点，将一些常用并且实现起来复杂的功能细节封装成API供调用，将软件开发过程从某个具体实现解放出来，使其能更加专注于具体的业务逻辑实现。