您现在访问的是微软AZURE全球版技术文档网站,若需要访问由世纪互联运营的MICROSOFT AZURE中国区技术文档网站,请访问 https://docs.azure.cn.

快速入门:适用于 .NET 的计算机视觉客户端库Quickstart: Computer Vision client library for .NET

适用于 .NET 的计算机视觉客户端库入门。Get started with the Computer Vision client library for .NET. 请按照以下步骤安装程序包并试用基本任务的示例代码。Follow these steps to install the package and try out the example code for basic tasks. 使用计算机视觉可以访问用于处理图像并返回信息的高级算法。Computer Vision provides you with access to advanced algorithms for processing images and returning information.

使用适用于 .NET 的计算机视觉客户端库可以:Use the Computer Vision client library for .NET to:

  • 分析图像中的标记、文本说明、人脸、成人内容,等等。Analyze an image for tags, text description, faces, adult content, and more.
  • 使用批量读取 API 识别印刷体文本和手写文本。Recognize printed and handwritten text with the Batch Read API.

参考文档 | 库源代码 | 包 (NuGet) | 示例Reference documentation | Library source code | Package (NuGet) | Samples

先决条件Prerequisites

设置Setting up

创建计算机视觉 Azure 资源Create a Computer Vision Azure resource

Azure 认知服务由你订阅的 Azure 资源表示。Azure Cognitive Services are represented by Azure resources that you subscribe to. 在本地计算机上使用 Azure 门户Azure CLI 创建计算机视觉的资源。Create a resource for Computer Vision using the Azure portal or Azure CLI on your local machine. 还可以:You can also:

获取试用订阅或资源的密钥后,请为该密钥和终结点 URL 创建环境变量,分别名为 COMPUTER_VISION_SUBSCRIPTION_KEYCOMPUTER_VISION_ENDPOINTAfter you get a key from your trial subscription or resource, create environment variableS for the key and endpoint URL, named COMPUTER_VISION_SUBSCRIPTION_KEY and COMPUTER_VISION_ENDPOINT, respectively.

新建 C# 应用程序Create a new C# application

在首选编辑器或 IDE 中创建新的 .NET Core 应用程序。Create a new .NET Core application in your preferred editor or IDE.

在控制台窗口(例如 cmd、PowerShell 或 Bash)中,使用 dotnet new 命令创建名为 computer-vision-quickstart 的新控制台应用。In a console window (such as cmd, PowerShell, or Bash), use the dotnet new command to create a new console app with the name computer-vision-quickstart. 此命令将创建包含单个源文件的简单“Hello World”C# 项目:Program.csThis command creates a simple "Hello World" C# project with a single source file: Program.cs.

dotnet new console -n computer-vision-quickstart

将目录更改为新创建的应用文件夹。Change your directory to the newly created app folder. 可使用以下代码生成应用程序:You can build the application with:

dotnet build

生成输出不应包含警告或错误。The build output should contain no warnings or errors.

...
Build succeeded.
 0 Warning(s)
 0 Error(s)
...

在首选的编辑器或 IDE 中,从项目目录打开 Program.cs 文件。From the project directory, open the Program.cs file in your preferred editor or IDE. 然后,添加以下 using 指令:Add the following using directives:

using System;
using System.Collections.Generic;
using Microsoft.Azure.CognitiveServices.Vision.ComputerVision;
using Microsoft.Azure.CognitiveServices.Vision.ComputerVision.Models;
using System.Threading.Tasks;
using System.IO;
using Newtonsoft.Json;
using Newtonsoft.Json.Linq;

在应用程序的 Program 类中,为资源的 Azure 终结点和密钥创建变量。In the application's Program class, create variables for your resource's Azure endpoint and key.

// Get your COMPUTER_VISION_SUBSCRIPTION_KEY and COMPUTER_VISION_REGION values from your Face resource,
// in the Azure portal, and set your local environment variables accordingly.
// Close/reopen your project for them to take effect.
// Free trial subscription keys are generated in the westcentralus region.
// If you use a free trial subscription key, you shouldn't need to change the region.
static string SubscriptionKey = Environment.GetEnvironmentVariable("COMPUTER_VISION_SUBSCRIPTION_KEY");
static string Endpoint = Environment.GetEnvironmentVariable("COMPUTER_VISION_ENDPOINT");

安装客户端库Install the client library

在应用程序目录中,使用以下命令安装适用于 .NET 的计算机视觉客户端库:Within the application directory, install the Computer Vision client library for .NET with the following command:

dotnet add package Microsoft.Azure.CognitiveServices.Vision.ComputerVision --version 5.0.0

如果你使用的是 Visual Studio IDE,客户端库可用作可下载的 NuGet 包。If you're using the Visual Studio IDE, the client library is available as a downloadable NuGet package.

对象模型Object model

以下类和接口将处理计算机视觉 .NET SDK 的某些主要功能。The following classes and interfaces handle some of the major features of the Computer Vision .NET SDK.

NameName 说明Description
ComputerVisionClientComputerVisionClient 所有计算机视觉功能都需要此类。This class is needed for all Computer Vision functionality. 可以使用订阅信息实例化此类,然后使用它来执行大多数图像操作。You instantiate it with your subscription information, and you use it to do most image operations.
ComputerVisionClientExtensionsComputerVisionClientExtensions 此类包含 ComputerVisionClient 的其他方法。This class contains additional methods for the ComputerVisionClient.
VisualFeatureTypesVisualFeatureTypes 此枚举定义可在标准分析操作中执行的不同类型的图像分析。This enum defines the different types of image analysis that can be done in a standard Analyze operation. 请根据需求指定一组 VisualFeatureTypes 值。You specify a set of VisualFeatureTypes values depending on your needs.

代码示例Code examples

这些代码片段演示如何使用适用于 .NET 的计算机视觉客户端库执行以下任务:These code snippets show you how to do the following tasks with the Computer Vision client library for .NET:

验证客户端Authenticate the client

备注

本快速入门假设你已为计算机视觉密钥创建了名为 COMPUTER_VISION_SUBSCRIPTION_KEY环境变量This quickstart assumes you've created an environment variable for your Computer Vision key, named COMPUTER_VISION_SUBSCRIPTION_KEY.

在新方法中,使用终结点和密钥实例化客户端。In a new method, instantiate a client with your endpoint and key. 使用密钥创建 CognitiveServicesCredentials 对象,然后在终结点上使用该对象创建 ComputerVisionClient 对象。Create a CognitiveServicesCredentials object with your key, and use it with your endpoint to create an ComputerVisionClient object.

/*
 * AUTHENTICATE
 * Creates a Computer Vision client used by each example.
 */
public static ComputerVisionClient Authenticate(string endpoint, string key)
{
    ComputerVisionClient client =
        new ComputerVisionClient(new ApiKeyServiceClientCredentials(key))
        { Endpoint = endpoint };
    return client;
}

你可能想要在 Main 方法中调用此方法。You'll likely want to call this method in the Main method.

// Create a client
ComputerVisionClient client = Authenticate(Endpoint, SubscriptionKey);

分析图像Analyze an image

以下代码定义方法 AnalyzeImageUrl,该方法使用客户端对象分析远程图像并输出结果。The following code defines a method, AnalyzeImageUrl, which uses the client object to analyze a remote image and print the results. 该方法返回文本说明、分类、标记列表、检测到的人脸、成人内容标志、主颜色和图像类型。The method returns a text description, categorization, list of tags, detected faces, adult content flags, main colors, and image type.

Main 方法中添加方法调用。Add the method call in your Main method.

// Analyze an image to get features and other properties.
AnalyzeImageUrl(client, ANALYZE_URL_IMAGE).Wait();

设置测试图像Set up test image

Program 类中,保存要分析的图像的 URL 的引用。In your Program class, save a reference the URL of the image you want to analyze.

// URL image used for analyzing an image (image of puppy)
private const string ANALYZE_URL_IMAGE = "https://moderatorsampleimages.blob.core.windows.net/samples/sample16.png";

备注

还可以分析本地图像。You can also analyze a local image. 请参阅 GitHub 上的示例代码以了解涉及本地图像的方案。See the sample code on GitHub for scenarios involving local images.

指定视觉特性Specify visual features

定义新的图像分析方法。Define your new method for image analysis. 添加下面的代码,它指定要在分析中提取的视觉特征。Add the code below, which specifies visual features you'd like to extract in your analysis. 有关完整列表,请参阅 VisualFeatureTypes 枚举。See the VisualFeatureTypes enum for a complete list.

   /*
    * ANALYZE IMAGE - URL IMAGE
* Analyze URL image. Extracts captions, categories, tags, objects, faces, racy/adult content,
* brands, celebrities, landmarks, color scheme, and image types.
    */
   public static async Task AnalyzeImageUrl(ComputerVisionClient client, string imageUrl)
   {
       Console.WriteLine("----------------------------------------------------------");
       Console.WriteLine("ANALYZE IMAGE - URL");
       Console.WriteLine();

       // Creating a list that defines the features to be extracted from the image.
       List<VisualFeatureTypes> features = new List<VisualFeatureTypes>()
           {
               VisualFeatureTypes.Categories, VisualFeatureTypes.Description,
               VisualFeatureTypes.Faces, VisualFeatureTypes.ImageType,
               VisualFeatureTypes.Tags, VisualFeatureTypes.Adult,
               VisualFeatureTypes.Color, VisualFeatureTypes.Brands,
               VisualFeatureTypes.Objects
           };

分析Analyze

AnalyzeImageAsync 方法将返回包含所有提取信息的 ImageAnalysis 对象。The AnalyzeImageAsync method returns an ImageAnalysis object that contains all of extracted information.

Console.WriteLine($"Analyzing the image {Path.GetFileName(imageUrl)}...");
Console.WriteLine();
// Analyze the URL image
ImageAnalysis results = await client.AnalyzeImageAsync(imageUrl, features);

以下部分说明如何详细分析此信息。The following sections show how to parse this information in detail.

获取图像说明Get image description

下面的代码获取为图像生成的描述文字列表。The following code gets the list of generated captions for the image. 有关更多详细信息,请参阅描述图像See Describe images for more details.

// Summarizes the image content.
Console.WriteLine("Summary:");
foreach (var caption in results.Description.Captions)
{
    Console.WriteLine($"{caption.Text} with confidence {caption.Confidence}");
}
Console.WriteLine();

获取图像类别Get image category

下面的代码获取所检测到的图像类别。The following code gets the detected category of the image. 有关更多详细信息,请参阅对图像进行分类See Categorize images for more details.

// Display categories the image is divided into.
Console.WriteLine("Categories:");
foreach (var category in results.Categories)
{
    Console.WriteLine($"{category.Name} with confidence {category.Score}");
}
Console.WriteLine();

获取图像标记Get image tags

以下代码获取图像中检测到的标记集。The following code gets the set of detected tags in the image. 有关更多详细信息,请参阅内容标记See Content tags for more details.

// Image tags and their confidence score
Console.WriteLine("Tags:");
foreach (var tag in results.Tags)
{
    Console.WriteLine($"{tag.Name} {tag.Confidence}");
}
Console.WriteLine();

检测物体Detect objects

以下代码检测图像中的常见物体并将其输出到控制台。The following code detects common objects in the image and prints them to the console. 有关更多详细信息,请参阅物体检测See Object detection for more details.

// Objects
Console.WriteLine("Objects:");
foreach (var obj in results.Objects)
{
    Console.WriteLine($"{obj.ObjectProperty} with confidence {obj.Confidence} at location {obj.Rectangle.X}, " +
        $"{obj.Rectangle.X + obj.Rectangle.W}, {obj.Rectangle.Y}, {obj.Rectangle.Y + obj.Rectangle.H}");
}
Console.WriteLine();

检测品牌Detect brands

以下代码检测图像中的公司品牌和徽标,并将其输出到控制台。The following code detects corporate brands and logos in the image and prints them to the console. 有关更多详细信息,请参阅品牌检测See Brand detection for more details.

// Well-known (or custom, if set) brands.
Console.WriteLine("Brands:");
foreach (var brand in results.Brands)
{
    Console.WriteLine($"Logo of {brand.Name} with confidence {brand.Confidence} at location {brand.Rectangle.X}, " +
        $"{brand.Rectangle.X + brand.Rectangle.W}, {brand.Rectangle.Y}, {brand.Rectangle.Y + brand.Rectangle.H}" );
}
Console.WriteLine();

检测人脸Detect faces

下面的代码返回图像中检测到的人脸及其矩形坐标,以及选择面属性。The following code returns the detected faces in the image with their rectangle coordinates and select face attributes. 有关更多详细信息,请参阅人脸检测See Face detection for more details.

// Faces
Console.WriteLine("Faces:");
foreach (var face in results.Faces)
{
    Console.WriteLine($"A {face.Gender} of age {face.Age} at location {face.FaceRectangle.Left}, " +
        $"{face.FaceRectangle.Left}, {face.FaceRectangle.Top + face.FaceRectangle.Width}, " +
        $"{face.FaceRectangle.Top + face.FaceRectangle.Height}");
}
Console.WriteLine();

检测成人、色情或血腥内容Detect adult, racy, or gory content

以下代码输出图像中检测到的成人内容。The following code prints the detected presence of adult content in the image. 有关更多详细信息,请参阅成人、色情或血腥内容See Adult, racy, gory content for more details.

// Adult or racy content, if any.
Console.WriteLine("Adult:");
Console.WriteLine($"Has adult content: {results.Adult.IsAdultContent} with confidence {results.Adult.AdultScore}");
Console.WriteLine($"Has racy content: {results.Adult.IsRacyContent} with confidence {results.Adult.RacyScore}");
Console.WriteLine();

获取图像配色方案Get image color scheme

以下代码输出图像中检测到的颜色属性,如主色和主题色。The following code prints the detected color attributes in the image, like the dominant colors and accent color. 有关更多详细信息,请参阅配色方案See Color schemes for more details.

// Identifies the color scheme.
Console.WriteLine("Color Scheme:");
Console.WriteLine("Is black and white?: " + results.Color.IsBWImg);
Console.WriteLine("Accent color: " + results.Color.AccentColor);
Console.WriteLine("Dominant background color: " + results.Color.DominantColorBackground);
Console.WriteLine("Dominant foreground color: " + results.Color.DominantColorForeground);
Console.WriteLine("Dominant colors: " + string.Join(",", results.Color.DominantColors));
Console.WriteLine();

获取特定于域的内容Get domain-specific content

计算机视觉可以使用专用模型对图像进行进一步分析。Computer Vision can use specialized model to do further analysis on images. 有关更多详细信息,请参阅特定于域的内容See Domain-specific content for more details.

以下代码分析了图像中检测到的名人的相关数据。The following code parses data about detected celebrities in the image.

// Celebrities in image, if any.
Console.WriteLine("Celebrities:");
foreach (var category in results.Categories)
{
    if (category.Detail?.Celebrities != null)
    {
        foreach (var celeb in category.Detail.Celebrities)
        {
            Console.WriteLine($"{celeb.Name} with confidence {celeb.Confidence} at location {celeb.FaceRectangle.Left}, " +
                $"{celeb.FaceRectangle.Top}, {celeb.FaceRectangle.Height}, {celeb.FaceRectangle.Width}");
        }
    }
}
Console.WriteLine();

以下代码分析了图像中检测到的地标的相关数据。The following code parses data about detected landmarks in the image.

// Popular landmarks in image, if any.
Console.WriteLine("Landmarks:");
foreach (var category in results.Categories)
{
    if (category.Detail?.Landmarks != null)
    {
        foreach (var landmark in category.Detail.Landmarks)
        {
            Console.WriteLine($"{landmark.Name} with confidence {landmark.Confidence}");
        }
    }
}
Console.WriteLine();

获取图像类型Get the image type

以下代码输出有关图像类型的信息—无论它是剪贴画还是线条图。The following code prints information about the type of image—whether it is clip art or line drawing.

// Detects the image types.
Console.WriteLine("Image Type:");
Console.WriteLine("Clip Art Type: " + results.ImageType.ClipArtType);
Console.WriteLine("Line Drawing Type: " + results.ImageType.LineDrawingType);
Console.WriteLine();

读取印刷体文本和手写文本Read printed and handwritten text

计算机视觉可以读取图像中的可见文本,并将其转换为字符流。Computer Vision can read visible text in an image and convert it to a character stream. 本部分中的代码定义了方法 ExtractTextUrl,该方法使用客户端对象检测并提取图像中的印刷体文本或手写文本。The code in this section defines a method, ExtractTextUrl, which uses the client object to detect and extract printed or handwritten text in the image.

Main 方法中添加方法调用。Add the method call in your Main method.

// Read the batch text from an image (handwriting and/or printed).
BatchReadFileUrl(client, EXTRACT_TEXT_URL_IMAGE).Wait();
BatchReadFileLocal(client, EXTRACT_TEXT_LOCAL_IMAGE).Wait();

设置测试图像Set up test image

Program 类中,保存要从中提取文本的图像的 URL 的引用。In your Program class, save a reference the URL of the image you want to extract text from.

private const string EXTRACT_TEXT_URL_IMAGE = "https://moderatorsampleimages.blob.core.windows.net/samples/sample2.jpg";

备注

还可以从本地图像提取文本。You can also extract text from a local image. 请参阅 GitHub 上的示例代码以了解涉及本地图像的方案。See the sample code on GitHub for scenarios involving local images.

调用读取 APICall the Read API

定义用于读取文本的新方法。Define the new method for reading text. 添加以下代码,该代码对给定图像调用 BatchReadFileAsync 方法。Add the code below, which calls the BatchReadFileAsync method for the given image. 这会返回一个操作 ID 并启动异步进程来读取图像的内容。This returns an operation ID and starts an asynchronous process to read the content of the image.

   /*
* BATCH READ FILE - URL IMAGE
* Recognizes handwritten text. 
    * This API call offers an improvement of results over the Recognize Text calls.
*/
   public static async Task BatchReadFileUrl(ComputerVisionClient client, string urlImage)
   {
       Console.WriteLine("----------------------------------------------------------");
       Console.WriteLine("BATCH READ FILE - URL IMAGE");
       Console.WriteLine();

       // Read text from URL
       BatchReadFileHeaders textHeaders = await client.BatchReadFileAsync(urlImage);
       // After the request, get the operation location (operation ID)
       string operationLocation = textHeaders.OperationLocation;

获取读取结果Get Read results

接下来,获取从 BatchReadFileAsync 调用返回的操作 ID,并使用它查询服务以获取操作结果。Next, get the operation ID returned from the BatchReadFileAsync call, and use it to query the service for operation results. 下面的代码每隔一秒钟检查一次操作,直到返回结果。The following code checks the operation at one-second intervals until the results are returned. 然后,它将提取的文本数据输出到控制台。It then prints the extracted text data to the console.

// Retrieve the URI where the recognized text will be stored from the Operation-Location header.
// We only need the ID and not the full URL
const int numberOfCharsInOperationId = 36;
string operationId = operationLocation.Substring(operationLocation.Length - numberOfCharsInOperationId);

// Extract the text
// Delay is between iterations and tries a maximum of 10 times.
int i = 0;
int maxRetries = 10;
ReadOperationResult results;
Console.WriteLine($"Extracting text from URL image {Path.GetFileName(urlImage)}...");
Console.WriteLine();
do
{
    results = await client.GetReadOperationResultAsync(operationId);
    Console.WriteLine("Server status: {0}, waiting {1} seconds...", results.Status, i);
    await Task.Delay(1000);
}
while ((results.Status == TextOperationStatusCodes.Running ||
        results.Status == TextOperationStatusCodes.NotStarted) && i++ < maxRetries);

显示读取结果Display Read results

添加以下代码来分析和显示检索到的文本数据,并完成方法定义。Add the following code to parse and display the retrieved text data, and finish the method definition.

    // Display the found text.
    Console.WriteLine();
    var recognitionResults = results.RecognitionResults;
    foreach (TextRecognitionResult result in recognitionResults)
    {
        foreach (Line line in result.Lines)
        {
            Console.WriteLine(line.Text);
        }
    }
    Console.WriteLine();
}

运行应用程序Run the application

从应用程序目录使用 dotnet run 命令运行应用程序。Run the application from your application directory with the dotnet run command.

dotnet run

清理资源Clean up resources

如果想要清理并删除认知服务订阅,可以删除资源或资源组。If you want to clean up and remove a Cognitive Services subscription, you can delete the resource or resource group. 删除资源组同时也会删除与之相关联的任何其他资源。Deleting the resource group also deletes any other resources associated with it.

后续步骤Next steps