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

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

适用于 Java 的计算机视觉客户端库入门。Get started with the Computer Vision client library for Java. 请按照以下步骤安装程序包并试用基本任务的示例代码。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.

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

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

参考文档 | 项目 (Maven) | 示例Reference documentation | Artifact (Maven) | 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:

然后,为密钥和服务终结点字符串创建环境变量,分别名为 COMPUTER_VISION_SUBSCRIPTION_KEYCOMPUTER_VISION_ENDPOINTThen, create environment variables for the key and service endpoint string, named COMPUTER_VISION_SUBSCRIPTION_KEY and COMPUTER_VISION_ENDPOINT, respectively.

创建新的 Gradle 项目Create a new Gradle project

在控制台窗口(例如 cmd、PowerShell 或 Bash)中,为应用创建一个新目录并导航到该目录。In a console window (such as cmd, PowerShell, or Bash), create a new directory for your app, and navigate to it.

mkdir myapp && cd myapp

从工作目录运行 gradle init 命令。Run the gradle init command from your working directory. 此命令将创建 Gradle 的基本生成文件,包括 build.gradle.kts,在运行时将使用该文件创建并配置应用程序。This command will create essential build files for Gradle, including build.gradle.kts, which is used at runtime to create and configure your application.

gradle init --type basic

当提示你选择一个 DSL 时,选择 KotlinWhen prompted to choose a DSL, select Kotlin.

找到 build.gradle.kts,并使用喜好的 IDE 或文本编辑器将其打开。Locate build.gradle.kts and open it with your preferred IDE or text editor. 然后在该文件中复制以下生成配置。Then copy in the following build configuration. 此配置将项目定义一个 Java 应用程序,其入口点为 ComputerVisionQuickstarts 类。This configuration defines the project as a Java application whose entry point is the class ComputerVisionQuickstarts. 它将导入计算机视觉库。It imports the Computer Vision library.

plugins {
    java
    application
}
application { 
    mainClassName = "ComputerVisionQuickstarts"
}
repositories {
    mavenCentral()
}

从工作目录运行以下命令,以创建项目源文件夹:From your working directory, run the following command to create a project source folder:

mkdir -p src/main/java

导航到新文件夹,创建名为 ComputerVisionQuickstarts.java 的文件。Navigate to the new folder and create a file called ComputerVisionQuickstarts.java. 在喜好的编辑器或 IDE 中打开该文件并添加以下 import 语句:Open it in your preferred editor or IDE and add the following import statements:

import com.microsoft.azure.cognitiveservices.vision.computervision.*;
import com.microsoft.azure.cognitiveservices.vision.computervision.models.*;

import java.io.File;
import java.io.FileInputStream;
import java.nio.file.Files;

import java.util.ArrayList;
import java.util.List;

然后添加 ComputerVisionQuickstarts 的类定义。Then add a class definition for ComputerVisionQuickstarts.

安装客户端库Install the client library

本快速入门使用 Gradle 依赖项管理器。This quickstart uses the Gradle dependency manager. 可以在 Maven 中央存储库中找到客户端库以及其他依赖项管理器的信息。You can find the client library and information for other dependency managers on the Maven Central Repository.

在项目的 build.gradle.kts 文件中,包含计算机视觉客户端库作为依赖项。In your project's build.gradle.kts file, include the Computer Vision client library as a dependency.

dependencies {
    compile(group = "com.microsoft.azure.cognitiveservices", name = "azure-cognitiveservices-computervision", version = "1.0.2-beta")
}

对象模型Object model

以下类和接口将处理人脸计算机视觉 Java SDK 的某些主要功能。The following classes and interfaces handle some of the major features of the Computer Vision Java 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 produce instances of other classes.
ComputerVisionComputerVision 此类来自客户端对象,它直接处理所有图像操作,例如图像分析、文本检测和缩略图生成。This class comes from the client object and directly handles all of the image operations, such as image analysis, text detection, and thumbnail generation.
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

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

验证客户端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.

以下代码将 main 方法添加到类,并为资源的 Azure 终结点和密钥创建变量。The following code adds a main method to your class and creates variables for your resource's Azure endpoint and key. 你需要输入自己的终结点字符串,可以在 Azure 门户的概述部分找到该字符串。You'll need to enter your own endpoint string, which you can find by checking the Overview section of the Azure portal.

public static void main(String[] args) {
    // Add your Computer Vision subscription key and endpoint to your environment
    // variables.
    // After setting, close and then re-open your command shell or project for the
    // changes to take effect.
    String subscriptionKey = System.getenv("COMPUTER_VISION_SUBSCRIPTION_KEY");
    String endpoint = System.getenv("COMPUTER_VISION_ENDPOINT");

接下来添加以下代码,以创建 ComputerVisionClient 对象并将其传递给稍后要定义的其他方法。Next, add the following code to create a ComputerVisionClient object and passes it into other method(s), which you'll define later.

ComputerVisionClient compVisClient = ComputerVisionManager.authenticate(subscriptionKey).withEndpoint(endpoint);
// END - Create an authenticated Computer Vision client.

System.out.println("\nAzure Cognitive Services Computer Vision - Java Quickstart Sample");

// Analyze local and remote images
AnalyzeLocalImage(compVisClient);

// Recognize printed text with OCR for a local and remote (URL) image
RecognizeTextOCRLocal(compVisClient);

备注

如果在启动应用程序后创建了环境变量,则需要关闭再重新打开运行该应用程序的编辑器、IDE 或 shell 才能访问该变量。If you created the environment variable after you launched the application, you'll need to close and reopen the editor, IDE, or shell running it to access the variable.

分析图像Analyze an image

以下代码定义方法 AnalyzeLocalImage,该方法使用客户端对象分析本地图像并输出结果。The following code defines a method, AnalyzeLocalImage, which uses the client object to analyze a local 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.

设置测试图像Set up test image

首先,在项目的 src/main/ 文件夹中创建 resources/ 文件夹,并添加要分析的图像。First, create a resources/ folder in the src/main/ folder of your project, and add an image you'd like to analyze. 然后,将以下方法定义添加到 ComputerVisionQuickstarts 类。Then add the following method definition to your ComputerVisionQuickstarts class. 如有必要,请更改 pathToLocalImage 的值,使之与图像文件相匹配。If necessary, change the value of the pathToLocalImage to match your image file.

public static void AnalyzeLocalImage(ComputerVisionClient compVisClient) {
    /*
     * Analyze a local image:
     *
     * Set a string variable equal to the path of a local image. The image path
     * below is a relative path.
     */
    String pathToLocalImage = "src\\main\\resources\\myImage.jpg";

备注

还可以使用其 URL 分析远程图像。You can also analyze a remote image using its URL. 请参阅 GitHub上的示例代码以了解涉及远程图像的方案。See the sample code on GitHub for scenarios involving remote images.

指定视觉特性Specify visual features

接下来,指定要在分析中提取的视觉特征。Next, specify which visual features you'd like to extract in your analysis. 有关完整列表,请参阅 VisualFeatureTypes 枚举。See the VisualFeatureTypes enum for a complete list.

// This list defines the features to be extracted from the image.
List<VisualFeatureTypes> featuresToExtractFromLocalImage = new ArrayList<>();
featuresToExtractFromLocalImage.add(VisualFeatureTypes.DESCRIPTION);
featuresToExtractFromLocalImage.add(VisualFeatureTypes.CATEGORIES);
featuresToExtractFromLocalImage.add(VisualFeatureTypes.TAGS);
featuresToExtractFromLocalImage.add(VisualFeatureTypes.FACES);
featuresToExtractFromLocalImage.add(VisualFeatureTypes.ADULT);
featuresToExtractFromLocalImage.add(VisualFeatureTypes.COLOR);
featuresToExtractFromLocalImage.add(VisualFeatureTypes.IMAGE_TYPE);

分析Analyze

此方法根据每个图像分析范围将详细结果输出到控制台。This method prints detailed results to the console for each scope of image analysis. 建议将此方法调用包含在 Try/Catch 块中。We recommend you surround this method call in a Try/Catch block. analyzeImageInStream 方法将返回包含所有提取信息的 ImageAnalysis 对象。The analyzeImageInStream method returns an ImageAnalysis object that contains all of extracted information.

// Need a byte array for analyzing a local image.
File rawImage = new File(pathToLocalImage);
byte[] imageByteArray = Files.readAllBytes(rawImage.toPath());

// Call the Computer Vision service and tell it to analyze the loaded image.
ImageAnalysis analysis = compVisClient.computerVision().analyzeImageInStream().withImage(imageByteArray)
        .withVisualFeatures(featuresToExtractFromLocalImage).execute();

以下部分说明如何详细分析此信息。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.

// Display image captions and confidence values.
System.out.println("\nCaptions: ");
for (ImageCaption caption : analysis.description().captions()) {
    System.out.printf("\'%s\' with confidence %f\n", caption.text(), caption.confidence());
}

获取图像类别Get image category

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

// Display image category names and confidence values.
System.out.println("\nCategories: ");
for (Category category : analysis.categories()) {
    System.out.printf("\'%s\' with confidence %f\n", category.name(), category.score());
}

获取图像标记Get image tags

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

// Display image tags and confidence values.
System.out.println("\nTags: ");
for (ImageTag tag : analysis.tags()) {
    System.out.printf("\'%s\' with confidence %f\n", tag.name(), tag.confidence());
}

检测人脸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.

// Display any faces found in the image and their location.
System.out.println("\nFaces: ");
for (FaceDescription face : analysis.faces()) {
    System.out.printf("\'%s\' of age %d at location (%d, %d), (%d, %d)\n", face.gender(), face.age(),
            face.faceRectangle().left(), face.faceRectangle().top(),
            face.faceRectangle().left() + face.faceRectangle().width(),
            face.faceRectangle().top() + face.faceRectangle().height());
}

检测成人、色情或血腥内容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.

// Display whether any adult or racy content was detected and the confidence
// values.
System.out.println("\nAdult: ");
System.out.printf("Is adult content: %b with confidence %f\n", analysis.adult().isAdultContent(),
        analysis.adult().adultScore());
System.out.printf("Has racy content: %b with confidence %f\n", analysis.adult().isRacyContent(),
        analysis.adult().racyScore());

获取图像配色方案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.

// Display the image color scheme.
System.out.println("\nColor scheme: ");
System.out.println("Is black and white: " + analysis.color().isBWImg());
System.out.println("Accent color: " + analysis.color().accentColor());
System.out.println("Dominant background color: " + analysis.color().dominantColorBackground());
System.out.println("Dominant foreground color: " + analysis.color().dominantColorForeground());
System.out.println("Dominant colors: " + String.join(", ", analysis.color().dominantColors()));

获取特定于域的内容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.

// Display any celebrities detected in the image and their locations.
System.out.println("\nCelebrities: ");
for (Category category : analysis.categories()) {
    if (category.detail() != null && category.detail().celebrities() != null) {
        for (CelebritiesModel celeb : category.detail().celebrities()) {
            System.out.printf("\'%s\' with confidence %f at location (%d, %d), (%d, %d)\n", celeb.name(),
                    celeb.confidence(), celeb.faceRectangle().left(), celeb.faceRectangle().top(),
                    celeb.faceRectangle().left() + celeb.faceRectangle().width(),
                    celeb.faceRectangle().top() + celeb.faceRectangle().height());
        }
    }
}

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

// Display any landmarks detected in the image and their locations.
System.out.println("\nLandmarks: ");
for (Category category : analysis.categories()) {
    if (category.detail() != null && category.detail().landmarks() != null) {
        for (LandmarksModel landmark : category.detail().landmarks()) {
            System.out.printf("\'%s\' with confidence %f\n", landmark.name(), landmark.confidence());
        }
    }
}

获取图像类型Get the image type

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

// Display what type of clip art or line drawing the image is.
System.out.println("\nImage type:");
System.out.println("Clip art type: " + analysis.imageType().clipArtType());
System.out.println("Line drawing type: " + analysis.imageType().lineDrawingType());

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

计算机视觉可以读取图像中的可见文本,并将其转换为字符流。Computer Vision can read visible text in an image and convert it to a character stream.

备注

还可以使用其 URL 读取远程图像中的文本。You can also read text in a remote image using its URL. 请参阅 GitHub上的示例代码以了解涉及远程图像的方案。See the sample code on GitHub for scenarios involving remote images.

调用识别 APICall the Recognize API

首先,使用以下代码对给定图像调用 recognizePrintedTextInStream 方法。First, use the following code to call the recognizePrintedTextInStream method for the given image. 将此代码添加到项目中时,需要将 localTextImagePath 的值替换为本地图像的路径。When you add this code to your project, you need to replace the value of localTextImagePath with the path to your local image.

// Display what type of clip art or line drawing the image is.
System.out.println("\nImage type:");
System.out.println("Clip art type: " + analysis.imageType().clipArtType());
System.out.println("Line drawing type: " + analysis.imageType().lineDrawingType());

以下代码块处理返回的文本并对其进行分析,以输出每行的第一个单词。The following block of code processes the returned text and parses it to print out the first word in each line. 可以使用此代码快速了解 OcrResult 实例的结构。You can use this code to quickly understand the structure of an OcrResult instance.

// Print results of local image
System.out.println();
System.out.println("Recognizing printed text from a local image with OCR ...");
System.out.println("\nLanguage: " + ocrResultLocal.language());
System.out.printf("Text angle: %1.3f\n", ocrResultLocal.textAngle());
System.out.println("Orientation: " + ocrResultLocal.orientation());

boolean firstWord = true;
// Gets entire region of text block
for (OcrRegion reg : ocrResultLocal.regions()) {
    // Get one line in the text block
    for (OcrLine line : reg.lines()) {
        for (OcrWord word : line.words()) {
            // get bounding box of first word recognized (just to demo)
            if (firstWord) {
                System.out.println("\nFirst word in first line is \"" + word.text()
                        + "\" with  bounding box: " + word.boundingBox());
                firstWord = false;
                System.out.println();
            }
            System.out.print(word.text() + " ");
        }
        System.out.println();
    }
}

最后,结束 try/catch 块和方法定义。Finally, close out the try/catch block and the method definition.

    } catch (Exception e) {
        System.out.println(e.getMessage());
        e.printStackTrace();
    }
}

运行应用程序Run the application

可使用以下命令生成应用:You can build the app with:

gradle build

使用 gradle run 命令运行应用程序:Run the application with the gradle run command:

gradle 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

本快速入门已介绍如何使用计算机视觉 Java 库执行基本任务。In this quickstart, you learned how to use the Computer Vision Java library to do basis tasks. 接下来,请在参考文档中详细了解该库。Next, explore the reference documentation to learn more about the library.