[FR] Added business card features (Azure#15829)

* added business card features
AzureSDKAutomation · Oct 15, 2020 · 3a37c04 · 3a37c04
1 parent 6eed58a
commit 3a37c04
Show file tree

Hide file tree

Showing 44 changed files with 3,254 additions and 142 deletions.
diff --git a/sdk/formrecognizer/azure-ai-formrecognizer/CHANGELOG.md b/sdk/formrecognizer/azure-ai-formrecognizer/CHANGELOG.md
@@ -8,6 +8,7 @@
 - Added property `modelId` to `CustomFormSubmodel` and `TrainingDocumentInfo`.
 - Added properties `modelId` and `formTypeConfidence` to `RecognizedForm`. 
 `modelId` has a null value on `RecognizedForm` for prebuilt APIs.
+- Added support for pre-built business card recognition.
 
 ### Breaking changes
 - Defaults to the latest supported API version, which currently is `2.1-preview.1`.
@@ -24,7 +25,7 @@
 First stable release of the azure-ai-formrecognizer client library supporting Azure Form Recognizer service API version v2.0.
 
 ### Breaking Changes
-- Renamed `BoundingBox` model to `FieldBoundingBox`
+- Renamed `BoundingBox` model to `FieldBoundingBox`.
 
 ## 3.0.0-beta.1 (2020-08-11)
 This beta version targets Azure Form Recognizer service API version v2.0.
@@ -133,11 +134,11 @@ https://azure.github.io/azure-sdk/releases/latest/java.html.
 
 - It uses the Form Recognizer service `v2.0-preview.1` API.
 - Two client design:
-  -  `FormRecognizerClient` to analyze fields/values on custom forms, receipts, and form content/layout
-  -  `FormTrainingClient` to train custom models (with/without labels), and manage the custom models on your account
+  - `FormRecognizerClient` to analyze fields/values on custom forms, receipts, and form content/layout
+  - `FormTrainingClient` to train custom models (with/without labels), and manage the custom models on your account
 - Different analyze methods based on input type: file stream or URL.
-  -  URL input should use the method with suffix `fromUrl`
-  -  Stream methods will automatically detect content-type of the input file if not provided.
+  - URL input should use the method with suffix `fromUrl`
+  - Stream methods will automatically detect content-type of the input file if not provided.
 - Authentication with API key supported using `AzureKeyCredential("<api_key>")` from `com.azure.core.credential`
 - All service errors use the base type: `com.azure.ai.formrecognizer.models.ErrorResponseException`
 - Reactive streams support using [Project Reactor](https://projectreactor.io/).

diff --git a/sdk/formrecognizer/azure-ai-formrecognizer/README.md b/sdk/formrecognizer/azure-ai-formrecognizer/README.md
@@ -315,11 +315,76 @@ for (int i = 0; i < receiptPageResults.size(); i++) {
 }
 ```
 
+### Recognize business cards
+Recognize data from business cards using a prebuilt model. Business card fields recognized by the service
+can be found [here][service_recognize_business_card].
+See [StronglyTypedRecognizedForm][strongly_typed_sample] for a suggested approach to extract
+information from a business card. The given sample is for `receipt` but the same approach applies to `business card`.
+
+<!-- embedme ./src/samples/java/com/azure/ai/formrecognizer/ReadmeSamples.java#L203-L257-->
+```java
+String businessCardUrl =
+    "https://raw.githubusercontent.com/Azure/azure-sdk-for-java/master/sdk/formrecognizer"
+        + "/azure-ai-formrecognizer/src/samples/java/sample-forms/businessCards/businessCard.jpg";
+
+SyncPoller<FormRecognizerOperationResult, List<RecognizedForm>> analyzeBusinessCardPoller =
+    formRecognizerClient.beginRecognizeBusinessCardsFromUrl(businessCardUrl);
+
+List<RecognizedForm> businessCardPageResults = analyzeBusinessCardPoller.getFinalResult();
+
+for (int i = 0; i < businessCardPageResults.size(); i++) {
+    RecognizedForm recognizedForm = businessCardPageResults.get(i);
+    Map<String, FormField> recognizedFields = recognizedForm.getFields();
+    System.out.printf("----------- Recognized business card info for page %d -----------%n", i);
+    FormField contactNamesFormField = recognizedFields.get("ContactNames");
+    if (contactNamesFormField != null) {
+        if (FieldValueType.LIST == contactNamesFormField.getValue().getValueType()) {
+            List<FormField> contactNamesList = contactNamesFormField.getValue().asList();
+            contactNamesList.stream()
+                .filter(contactName -> FieldValueType.MAP == contactName.getValue().getValueType())
+                .map(contactName -> {
+                    System.out.printf("Contact name: %s%n", contactName.getValueData().getText());
+                    return contactName.getValue().asMap();
+                })
+                .forEach(contactNamesMap -> contactNamesMap.forEach((key, contactName) -> {
+                    if ("FirstName".equals(key)) {
+                        if (FieldValueType.STRING == contactName.getValue().getValueType()) {
+                            String firstName = contactName.getValue().asString();
+                            System.out.printf("\tFirst Name: %s, confidence: %.2f%n",
+                                firstName, contactName.getConfidence());
+                        }
+                    }
+                    if ("LastName".equals(key)) {
+                        if (FieldValueType.STRING == contactName.getValue().getValueType()) {
+                            String lastName = contactName.getValue().asString();
+                            System.out.printf("\tLast Name: %s, confidence: %.2f%n",
+                                lastName, contactName.getConfidence());
+                        }
+                    }
+                }));
+        }
+    }
+    FormField jobTitles = recognizedFields.get("JobTitles");
+    if (jobTitles != null) {
+        if (FieldValueType.LIST == jobTitles.getValue().getValueType()) {
+            List<FormField> jobTitlesItems = jobTitles.getValue().asList();
+            jobTitlesItems.stream().forEach(jobTitlesItem -> {
+                if (FieldValueType.STRING == jobTitlesItem.getValue().getValueType()) {
+                    String jobTitle = jobTitlesItem.getValue().asString();
+                    System.out.printf("Job Title: %s, confidence: %.2f%n",
+                        jobTitle, jobTitlesItem.getConfidence());
+                }
+            });
+        }
+    }
+}
+```
+
 ### Train a model
 Train a machine-learned model on your own form type. The resulting model will be able to recognize values from the types of forms it was trained on.
 Provide a container SAS url to your Azure Storage Blob container where you're storing the training documents. See details on setting this up
 in the [service quickstart documentation][quickstart_training].
-<!-- embedme ./src/samples/java/com/azure/ai/formrecognizer/ReadmeSamples.java#L203-L229 -->
+<!-- embedme ./src/samples/java/com/azure/ai/formrecognizer/ReadmeSamples.java#L261-L287 -->
 ```java
 String trainingFilesUrl = "{SAS_URL_of_your_container_in_blob_storage}";
 SyncPoller<FormRecognizerOperationResult, CustomFormModel> trainingPoller =
@@ -352,7 +417,7 @@ customFormModel.getSubmodels().forEach(customFormSubmodel -> {
 
 ### Manage your models
 Manage the custom models in your Form Recognizer account.
-<!-- embedme ./src/samples/java/com/azure/ai/formrecognizer/ReadmeSamples.java#L233-L261 -->
+<!-- embedme ./src/samples/java/com/azure/ai/formrecognizer/ReadmeSamples.java#L291-L319 -->
 ```java
 // First, we see how many custom models we have, and what our limit is
 AccountProperties accountProperties = formTrainingClient.getAccountProperties();
@@ -393,7 +458,7 @@ to provide an invalid file source URL an `HttpResponseException` would be raised
 In the following code snippet, the error is handled
 gracefully by catching the exception and display the additional information about the error.
 
-<!-- embedme ./src/samples/java/com/azure/ai/formrecognizer/ReadmeSamples.java#L268-L272 -->
+<!-- embedme ./src/samples/java/com/azure/ai/formrecognizer/ReadmeSamples.java#L326-L330 -->
 ```java
 try {
     formRecognizerClient.beginRecognizeContentFromUrl("invalidSourceUrl");
@@ -428,7 +493,7 @@ These code samples show common scenario operations with the Azure Form Recognize
 #### Async APIs
 All the examples shown so far have been using synchronous APIs, but we provide full support for async APIs as well.
 You'll need to use `FormRecognizerAsyncClient`
-<!-- embedme ./src/samples/java/com/azure/ai/formrecognizer/ReadmeSamples.java#L279-L282 -->
+<!-- embedme ./src/samples/java/com/azure/ai/formrecognizer/ReadmeSamples.java#L337-L340 -->
 ```java
 FormRecognizerAsyncClient formRecognizerAsyncClient = new FormRecognizerClientBuilder()
     .credential(new AzureKeyCredential("{key}"))
@@ -510,6 +575,7 @@ This project has adopted the [Microsoft Open Source Code of Conduct][coc]. For m
 [copy_model]: https://github.com/Azure/azure-sdk-for-java/blob/master/sdk/formrecognizer/azure-ai-formrecognizer/src/samples/java/com/azure/ai/formrecognizer/CopyModel.java
 [copy_model_async]: https://github.com/Azure/azure-sdk-for-java/blob/master/sdk/formrecognizer/azure-ai-formrecognizer/src/samples/java/com/azure/ai/formrecognizer/CopyModelAsync.java
 [service_access]: https://docs.microsoft.com/azure/cognitive-services/cognitive-services-apis-create-account?tabs=multiservice%2Cwindows
+[service_recognize_business_card]: https://aka.ms/formrecognizer/businesscardfields
 [service_recognize_receipt]: https://aka.ms/formrecognizer/receiptfields
 [strongly_typed_sample]: https://github.com/Azure/azure-sdk-for-java/blob/master/sdk/formrecognizer/azure-ai-formrecognizer/src/samples/java/com/azure/ai/formrecognizer/StronglyTypedRecognizedForm.java
 [source_code]: https://github.com/Azure/azure-sdk-for-java/blob/master/sdk/formrecognizer/azure-ai-formrecognizer/src