OcrControl Class

  • Article

 

Deprecated. The OcrControl class represents a control that can take a picture, send the picture to the Bing Optical Character Recognition (OCR) Service, and receive the text returned by OCR. You can incorporate the control into your application in its default state or you can customize its appearance and behavior.

Warning

The Bing OCR Control is deprecated as of March 12, 2014.

Syntax

public sealed class OcrControl : Control

<Ocr:OcrControl .../>

Members

Constructors

The OcrEngine class has these constructors.

Name

Description

OcrControl()

Creates an instance of the Bing OcrControl.

Properties

The OcrEngine class has these properties.

Name

Description

CaptureLanguage

A two-letter language code that specifies the language to read from the captured image.

OcrControl.ClientId Property

Holds the ID of the Azure Data Marketplace account that the application developer registered the OCR Control under.
 

OcrControl.ClientSecret Property

Holds the Client Secret value of the Azure Data Marketplace account that the application developer registered the OCR Control under.
 

OcrControl.InstructionOverlay Property

Specifies a Xaml.UIElement object to display additional instructions to the end user.

Methods

Name

Description

OcrControl.CaptureFrame() Method

Captures a frame from the camera and sends it to the OCR Service for processing.

OcrControl.GetLanguagesAsync() Method

Returns the current list of supported languages from the OCR Service.

OcrControl.ResetAsync() Method

Closes the camera if it is running and resets the control to its starting state.

OcrControl.StartPreviewAsync(String) Method

Starts the camera in preview mode.

Events

Name

Description

OcrControl.Completed Event

Raised by the OcrControl.CaptureFrame() Method when the OCR Control receives a response from the OCR Service. Event arguments contain the OCR data and the captured image.

OcrControl.Failed Event

Raised when an error occurs in the control, such as when no rear facing camera is available, user has denied permissions to access the camera, or the control is unable to contact the OCR Service.

OcrControl.FrameCaptured Event

Raised by the OcrControl.CaptureFrame() Method when the OCR Control captures an image frame, just after stopping the video preview. Event arguments contain the captured image.

Remarks

The default OCR control UI includes a preview area. When you call the StartPreviewAsync() Method, the control turns on the rear facing camera in preview (video) mode. When a user clicks or taps on the preview area, the control takes a picture and sends it to the OCR Service for analysis. The service returns the identified text and its location in the picture, triggering the Completed event. The returned OCR data is stored in the OcrCompletedEventArgs Class for the event.

Before working with OCR Control, you must add it to Visual Studio from the Visual Studio Gallery, and then subscribe to the control and register your application on the Windows Azure Marketplace, as described in How to: Install and Register the Bing OCR Control with the Azure Data Marketplace. When adding the control to an application, you must explicitly enable the application to use the cameras on the users’ device. You can do this in Visual Studio by opening the Package.appxmanifest file from Solution Explorer, opening the Capabilities tab, and checking the option for Webcam.

You can add the OCR Control to any XAML-based Windows Store Application project type in C# or C++ in Visual Studio. The control works on Windows 8, Windows 8.1, and Windows RT devices with supported cameras. For more information, see Bing OCR Requirements.

Example

The following example adds an instance of the OCR control and a TextBlock to a XAML page. Then, in the code-behind, it creates event handlers for the Completed and Failed events, and starts the camera by calling the StartPreviewAsync method on load. The Completed event handler displays the text returned by OCR in the TextBlock. The Failed event handler notifies the user and then stops the camera by calling the ResetAsync() method.

Tip

The StartPreviewAsync() method calls the CaptureFrame() method internally when a user clicks or taps on the preview area of the control. Therefore, you do not need to call CaptureFrame() explicitly unless you change the control UI.

Example

<Page xmlns:Ocr="using:Bing.Ocr" >
<Grid>
    <Ocr:OcrControl x:Name="OCR" />
    <TextBlock x:Name="tbResults" />
</Grid>

public MainPage()
{
    this.InitializeComponent();
    this.Loaded += MainPage_Loaded;
}

private async void MainPage_Loaded(object sender, RoutedEventArgs e)
{
    OCR.ClientId = <your client id>;
    OCR.ClientSecret = <your client secret>;

    // Assign event handlers.
    OCR.Completed += Ocr_Completed;
    OCR.Failed += Ocr_Failed;

    await OCR.StartPreviewAsync();
}

private void OCR_OcrCompleted(object sender, OcrCompletedEventArgs e)
{
    // Make sure there is text.
    if (e.Result.Lines.Count == 0)
    {
        tbResults.Text = "No text found.";
        return;
    }

    // Read the text and print it to a TextBlock.
    string s = "";
    foreach (Line l in e.Result.Lines)
    {
        foreach (Word w in l.Words)
        {
            s += w.Value + " ";
        }
        s += "\n";
    }
    tbResults.Text = s;
}

private async void OCR_Failed (object sender, OcrErrorEventArgs e)
{
    // Display error message.
    tbResults.Text = e.ErrorMessage;

    // Give guidance on specific errors.
    switch (e.ErrorCode) 
    {
        case ErrorCode.CameraBusy:
            tbResults.Text += "\nClose any other applications that may be using the camera and try again.";
            break;
        case ErrorCode.CameraLowQuality:
            tbResults.Text += "\nThe camera on this device does not meet the resolution requirements for OCR.";
            break;
        case ErrorCode.CameraNotAvailable:
            tbResults.Text += "\Rear built-in camera is not found.";
            break;
        case ErrorCode.CameraPermissionDenied:
            tbResults.Text += "\nTurn camera permissions on in your application settings.";
            break;
        case ErrorCode.NetworkUnavailable:
            tbResults.Text += "\nCheck your Internet connection and try again.";
            break;
        default:
            tbResults.Text += "\nNotify your application provider.";
            break;
    }

    // Continue or cancel, depending on the error.
    if (e.ErrorCode == ErrorCode.Success) await OCR.StartPreviewAsync();
    else
    {
        await OCR.ResetAsync();
    }
}

For more detailed instructions and code examples, see Embedding the Bing OCR Control in an Application and How to: Extract text from an OCR result. For information on language settings, see How to: Set the text language for Windows Runtime OCR.

Requirements

Minimum Supported Client

Windows 8.1

Required Extensions

Bing OCR

Namespace

Bing.Ocr

See Also

How to extract text from an image
How to generate OCR Resources file for custom group of languages