Quickstart: Recognize digital ink with the Ink Recognizer REST API and Java

  • Article

Note

The Ink Recognizer API has ended its preview on August 26th, 2020. If you have existing Ink Recognizer resources, you can continue using them until the service is fully retired on January 31st, 2021.

Use this quickstart to begin using the Ink Recognizer API on digital ink strokes. This Java application sends an API request containing JSON-formatted ink stroke data, and gets the response.

While this application is written in Java, the API is a RESTful web service compatible with most programming languages.

Typically you would call the API from a digital inking app. This quickstart sends ink stroke data for the following handwritten sample from a JSON file.

an image of handwritten text

The source code for this quickstart can be found on GitHub.

Prerequisites

Create an Ink Recognizer resource

Note

Endpoints for resources created after July 1, 2019 use the custom subdomain format shown below. For more information and a complete list of regional endpoints, see Custom subdomain names for Cognitive Services.

Azure Cognitive Services are represented by Azure resources that you subscribe to. Create a resource for Ink Recognizer using the Azure portal.

After creating a resource, get your endpoint and key by opening your resource on the Azure portal, and clicking Quick start.

Create two environment variables:

  • INK_RECOGNITION_SUBSCRIPTION_KEY - The subscription key for authenticating your requests.

  • INK_RECOGNITION_ENDPOINT - The endpoint for your resource. It will look like this:
    https://<your-custom-subdomain>.api.cognitive.microsoft.com

Create a new application

  1. Create a new Java project in your favorite IDE or editor, and import the following libraries.

    import org.apache.http.HttpEntity;
import org.apache.http.client.methods.CloseableHttpResponse;
import org.apache.http.client.methods.HttpPut;
import org.apache.http.entity.StringEntity;
import org.apache.http.impl.client.CloseableHttpClient;
import org.apache.http.impl.client.HttpClients;
import org.apache.http.util.EntityUtils;
import com.fasterxml.jackson.core.JsonParseException;
import com.fasterxml.jackson.databind.JsonMappingException;
import com.fasterxml.jackson.databind.ObjectMapper;
import java.io.IOException;
import java.nio.file.Files;
import java.nio.file.Paths;
import java.util.HashMap;
import java.util.Map;

  2. Create variables for your subscription key, endpoint and JSON file. The endpoint will later be appended to the Ink recognizer URI.

    // Add your Azure Ink Recognition subscription key to your environment variables.
private static final String subscriptionKey = System.getenv("INK_RECOGNITION_SUBSCRIPTION_KEY");

// Add your Azure Ink Recognition endpoint to your environment variables.
public static final String rootUrl = System.getenv("INK_RECOGNITION_ENDPOINT");
public static final String inkRecognitionUrl = "/inkrecognizer/v1.0-preview/recognize";
// Replace the dataPath string with a path to the JSON formatted ink stroke data file.
private static final String dataPath = "PATH_TO_INK_STROKE_DATA";

Create a function to send requests

  1. Create a new function called sendRequest() that takes the variables created above. Then perform the following steps.

  2. Create a CloseableHttpClient object that can send requests to the API. Send the request to an HttpPut request object by combining your endpoint, and the Ink Recognizer URL.

  3. Use the request's setHeader() function to set the Content-Type header to application/json, and add your subscription key to the Ocp-Apim-Subscription-Key header.

  4. Use the request's setEntity() function to the data to be sent.

  5. Use the client's execute() function to send the request, and save it to a CloseableHttpResponse object.

  6. Create an HttpEntity object to store the response content. Get the content with getEntity(). If the response isn't empty, return it.

    static String sendRequest(String endpoint, String apiAddress, String subscriptionKey, String requestData) {
    try (CloseableHttpClient client = HttpClients.createDefault()) {
        HttpPut request = new HttpPut(endpoint + apiAddress);
        // Request headers.
        request.setHeader("Content-Type", "application/json");
        request.setHeader("Ocp-Apim-Subscription-Key", subscriptionKey);
        request.setEntity(new StringEntity(requestData));
        try (CloseableHttpResponse response = client.execute(request)) {
            HttpEntity respEntity = response.getEntity();
            if (respEntity != null) {
                return EntityUtils.toString(respEntity, "utf-8");
            }
        } catch (Exception respEx) {
            respEx.printStackTrace();
        }
    } catch (IOException ex) {
        System.err.println("Exception on Anomaly Detector: " + ex.getMessage());
        ex.printStackTrace();
    }
    return null;
}

Send an ink recognition request

Create a method called recognizeInk() to recognize your ink stroke data. Call the sendRequest() method created above with your endpoint, url, subscription key, and json data. Get the result, and print it to the console.

static void recognizeInk(String requestData) {
    System.out.println("Sending an Ink recognition request.");

    String result = sendRequest(rootUrl, inkRecognitionUrl, subscriptionKey, requestData);
    
    // Pretty-print the JSON result
    try {
        ObjectMapper objectMapper = new ObjectMapper();
        Map<String, Object> response = objectMapper.readValue(result, HashMap.class);
        System.out.println(objectMapper.writerWithDefaultPrettyPrinter().writeValueAsString(response));
    } catch (JsonParseException e) {
        e.printStackTrace();
    } catch (JsonMappingException e) {
        e.printStackTrace();
    } catch (IOException e) {
        e.printStackTrace();
    }  
}

Load your digital ink data and send the request

  1. In the main method of your application, read in the JSON file containing the data that will be added to the requests.

  2. Call the ink recognition function created above.

    public static void main(String[] args) throws Exception {

    String requestData = new String(Files.readAllBytes(Paths.get(dataPath)), "utf-8");
    recognizeInk(requestData);
}

Run the application and view the response

Run the application. A successful response is returned in JSON format. You can also find the JSON response on GitHub.

Next steps

REST API reference

To see how the Ink Recognition API works in a digital inking app, take a look at the following sample applications on GitHub: