Skip to main content

Optical Character Recognition (OCR) enables applications to extract plain text and structured OCR information from document images. At the 3.8 release, the ArcGIS Pro SDK exposes an OCR API that is implemented using the Tesseract open-source OCR engine. Unlike traditional OCR integrations, add-in developers do not need to reference, deploy, or manage a separate OCR library. The OCR classes are provided by ArcGIS.Core.dll and are accessed through the ArcGIS.Core.OCR namespace.

ArcGIS.Core.dll

Language:      C#
Subject:       OCR
Contributor:   ArcGIS Pro SDK Team arcgisprosdk@esri.com
Organization:  Esri, https://www.esri.com
Date:          11/05/2026
ArcGIS Pro:    3.8
IDE:           Visual Studio 2026, Visual Studio Code  

In this topic

Overview

The OCR API in the ArcGIS Pro SDK provides access to OCR processing through the ArcGIS.Core.OCR namespace and is centered around the OCRManager singleton class. The API can read a variety of common image and document formats, perform text extraction, and return results as plain text or structured OCR information.

The OCRManager class serves as the central entry point and supports document validation, page inspection, asynchronous OCR processing, multiple output formats, page-specific extraction, and cancellation support.

The OCR API is intended for workflows where document content must be analyzed programmatically, such as:

  • Processing scanned image archives or PDF archives.
  • Extracting text from deeds, survey records, and other land record documents.
  • Automating document indexing and search workflows.
  • Extracting structured text information for downstream geoprocessing or business logic.

Like many APIs in ArcGIS.Core, OCR operations must be initiated on the Main CIM Thread (MCT) using QueuedTask.Run. Most OCR methods perform asynchronous processing and return Task objects.

Namespace

The items of the OCR API are included in the ArcGIS.Core.OCR namespace. Add using ArcGIS.Core.OCR; to the top of your source files.

OCRManager class

OCRManager is the primary entry point for all OCR operations. It follows a singleton pattern and is accessed through the static Instance property.

var ocrManager = OCRManager.Instance;

The class provides functionality to:

  • Validate document support.
  • Obtain document page counts.
  • Extract plain text.
  • Extract structured OCR output.
  • Perform OCR on individual pages or entire documents.
  • Control OCR processing through options and cancellation tokens.

Threading requirements

Most OCR operations must be executed on the Main CIM Thread (MCT). Use QueuedTask.Run when calling OCR APIs:

await QueuedTask.Run(async () =>
{
    var text =
        await OCRManager.Instance.ExtractTextFromDocumentAsync(path);
});

Failure to execute on the MCT results in a CalledOnWrongThreadException.

Example: Extract all text from a PDF

await QueuedTask.Run(async () =>
{
  var fileName = @"C:\MyPDFFilesFolder\MyPDFDocument.pdf";
  if (!OCRManager.Instance.IsValidDocumentForOCR(fileName))
    return;
  string text = await OCRManager.Instance.ExtractTextFromDocumentAsync(fileName);
  System.Diagnostics.Debug.WriteLine(text);
});

The following code extracts the text from a tiff image file and writes the output to a text file in the default project folder.

Example: Extract text from a TIF and write to a file

protected async override void OnClick()
{
  await QueuedTask.Run(async () =>
  {
    var fileName = @"C:\MyScannedFilesFolder\MyScannedDocument.tif";
    // Return the root folder of the file 
    var currentProjectFolder = System.IO.Path.GetDirectoryName(Project.Current.URI);
    try
    {
      var ocrManager = OCRManager.Instance;
      var isValid = ocrManager.IsValidDocumentForOCR(fileName);
      if (!isValid)
        return;
      var output = await ocrManager.ExtractTextFromDocumentAsync(fileName);
      var outFilePath = Path.Combine(currentProjectFolder, "textExtract" + ".txt");
      await File.WriteAllTextAsync(outFilePath, output);
    }
    catch (Exception ex)
    {
      MessageBox.Show(ex.Message);
    }
  });
  MessageBox.Show("Exported text files.", "Text files from scans");
}

Supported document types

The OCR engine supports the following document types:

Extension Name Description
PDF Portable Document Format Open standard file type maintained by the International Organization for Standardization.
TIF or TIFF Tagged Image File Format Industry-standard computer file format used to store high-quality raster graphics and image data.
JPG or JPEG Joint Photographic Experts Group A raster image file format that uses lossy compression.
PNG Portable Network Graphics Extensible file format for lossless, portable, and compressed storage of raster images.
BMP Bitmap Device-independent bitmap format allows display of images across different screens and devices without needing a specific graphics adapter.

The supported file filter can be obtained directly from the manager:

string filter = OCRManager.Instance.SupportedFileFilter;

This value is suitable for use in file-open dialogs. The following code shows how to present a browse dialog filtered explicitly for OCR sources.

Example: Show a browse dialog for OCR sources

protected async override void OnClick()
{
  string fileName = "";
  var ocrManager = OCRManager.Instance;
  string filter = ocrManager.SupportedFileFilter;
  var dlg = new Microsoft.Win32.OpenFileDialog()
  {
    Title = "OpenDeed",
    Filter = filter,
    Multiselect = false
  };

  if (dlg.ShowDialog() == true)
    fileName = dlg.FileName;

  if (string.IsNullOrEmpty(fileName))
    return;

  var valid = await QueuedTask.Run(async () =>
  {
    bool isValid = ocrManager.IsValidDocumentForOCR(fileName);
    return isValid;
  });

  if (!valid)
    MessageBox.Show("Unsupported document.");
}

Validating a document file

Before executing OCR, verify that the file exists and is supported.

bool valid =
    OCRManager.Instance.IsValidDocumentForOCR(documentPath);

if (!valid)
{
    MessageBox.Show("Unsupported document.");
}

Validation checks:

  • File name is not null.
  • File exists.
  • File extension is supported.

Determining the number of pages

PDF and TIFF files can contain multiple pages.

Use GetDocumentPageCount to determine the number of pages in a document.

await QueuedTask.Run(() =>
{
    int pageCount =
        OCRManager.Instance.GetDocumentPageCount(documentPath);
});

Notes

  • Must be executed on the MCT.
  • Returns 0 when the document cannot be read.
  • Throws an exception when the document is invalid.

Extracting text from a document

The simplest OCR workflow extracts text from the entire document.

await QueuedTask.Run(async () =>
{
    string text =
        await OCRManager.Instance.ExtractTextFromDocumentAsync(documentPath);
});

The returned string:

  • Contains all recognized text.
  • May be empty if no text can be detected.
  • Is dependent on image quality and document content.

Extracting text from a specific page

OCR can be restricted to a single page. The following code extracts text from the first page. Page numbering is zero-based.

string pageText =
    await OCRManager.Instance.ExtractTextFromDocumentAsync(documentPath, 0);
Value Meaning
0 First page
1 Second page
n (n+1)th page
-1 All pages

If the requested page number exceeds the page count, the result is null.

Cancellation support

The process can be cancelled by the user at any time. This is implemented using a CancellationToken, allowing long-running OCR operations to be cancelled by the user by clicking the Cancel button on the progress dialog. If cancellation occurs, an OperationCanceledException is thrown.

var canceled = false;
var cts = new CancellationTokenSource();
try
{
  text = await OCRManager.Instance.ExtractTextFromDocumentAsync(docFileName, cts.Token);
}
catch (OperationCanceledException cex)
{
  canceled = true;
}

if (!canceled)
{
  // do something with text
}

Advanced OCR with OCROptions

For greater control over OCR processing, use the OCROptions class with the OCRManager ExtractFromDocumentAsync method. OCROptions controls:

  • Input document.
  • Page selection.
  • OCR output format.
  • Resolution.
  • OCR recognition model.

The default OCROptions constructor takes the input document file name. Alternatively, if you are looking to scan a single page of the document then you can use the constructor which also takes the page index. The other option parameters (output format, resolution, model) are specified using properties on the OCROptions class.

var options = new OCROptions(documentPath);

// or specify a particular page index
// in this example, scan the second page of the document
var options = new OCROptions(documentPath, 1);

OCR output types

There are two output types supported - Text and Tab Separated Value (TSV). They are specified with the OCROutputType enumeration. The default output type is Text.

The ExtractFromDocumentAsync method returns an object of type OCROutput depending upon the OutputType specified. An output type of OCROutputType.Text returns an OCRTextOutput object. An output type of OCROutputType.TSV returns an OCRTSVOutput object.

Text output

var options = new OCROptions(documentPath);
options.OutputType = OCROutputType.Text;
var result =
     await OCRManager.Instance.ExtractFromDocumentAsync(options);
if (result is OCRTextOutput textOutput)
{
  string text = textOutput.Text;
}

TSV output

var options = new OCROptions(documentPath);
options.OutputType = OCROutputType.TSV;
var result =
     await OCRManager.Instance.ExtractFromDocumentAsync(options);
if (result is OCRTSVOutput tsvOutput)
{
  // process the TSV output
}

TSV output provides structured OCR information and may include information such as:

  • Words.
  • Text blocks.
  • Positional information.
  • Layout analysis data.

TSV output is useful when applications require more than simple text extraction. For more information about the TSV output see the next section Understanding TSV output.

Understanding TSV output

TSV output provides structured OCR results rather than a single text string. In addition to recognized text, the OCR engine returns information about where text was detected within the document image and how recognized content is organized. TSV output is based on the structured output produced by the underlying OCR engine and is intended for applications that require more information than plain text extraction alone.

Why use TSV output?

TSV output can provide:

  • Recognized text.
  • Page-level organization.
  • Text block and line information.
  • Approximate text locations within the image.
  • Recognition confidence values.

This additional information can be useful when post-processing OCR results, filtering detected text, or performing document analysis.

OCR hierarchy

Recognized content is organized into a hierarchy similar to:

  • Page
    • Block
      • Paragraph
        • Line
          • Word

This structure provides additional context about how the OCR engine interpreted the document.

Positional information

For each recognized word, TSV output may include information such as:

  • Page number.
  • Block number.
  • Paragraph number.
  • Line number.
  • Word number.
  • Bounding rectangle coordinates.
  • Recognition confidence.
  • Recognized text.

This information allows applications to associate recognized text with approximate locations within the source image.

Text output versus TSV output

Feature Text Output TSV Output
Recognized text ✓ ✓
Page information Limited ✓
Text block information No ✓
Approximate text location No ✓
Confidence values No ✓
Document structure No ✓

Use OCROutputType.Text when only the extracted text is required. Use OCROutputType.TSV when applications require access to additional OCR metadata and document layout information.

The following code shows how to use the OCRTSVOutput structured information to display a reconstructed layout of the document in a FlowDocument.

Example: Reconstruct document layout from TSV output

protected async override void OnClick()
{
  var fileName = @"C:\MyPDFFilesFolder\MyPDFDocument.pdf";
  // Variable to safely pass the data from the background thread to the UI thread
  OCRTSVOutput tsvOutput = null;
  try
  {
    // Execute on the Main CIM Thread (MCT)
    await QueuedTask.Run(async () =>
    {
      var options = new OCROptions(fileName);
      options.OutputType = OCROutputType.TSV;
      tsvOutput = await OCRManager.Instance.ExtractFromDocumentAsync(options) as OCRTSVOutput;
    });
    //UI operations must happen outside QueuedTask.
    // Ensure we actually got data back before moving to the UI logic
    if (tsvOutput == null)
    {
      ArcGIS.Desktop.Framework.Dialogs.MessageBox.Show(
        "OCR extraction returned no data.", "Error");
      return;
    }
    // Return to the Main UI Thread to build WPF elements
    // FlowDocument and its child elements belong strictly to the UI thread
    FlowDocument flowDoc = CreateFlowDocument(tsvOutput);
    // Create and configure the hosted ProWindow on the UI Thread
    var proWindow = new ProWindow
    {
      Title = "PDF extracted Flow Document",
      Width = 1200,
      Height = 1000,
      WindowStartupLocation = WindowStartupLocation.CenterOwner,

      // Ties window lifecycle and visibility to ArcGIS Pro's primary window
      Owner = FrameworkApplication.Current.MainWindow
    };

    var viewer = new FlowDocumentScrollViewer
    {
      Document = flowDoc
    };

    proWindow.Content = viewer;

    // Show Dialog safely blocks only the UI loop, keeping ArcGIS Pro responsive
    proWindow.ShowDialog();
  }
  catch (Exception ex)
  {
    ArcGIS.Desktop.Framework.Dialogs.MessageBox.Show(
      $"An error occurred: {ex.Message}", "OCR Error");
  }
}
static internal FlowDocument CreateFlowDocument(OCRTSVOutput tsvOutput)
{
  var flowDoc = new FlowDocument();

  if (tsvOutput == null)
    return flowDoc;

  foreach (var page in tsvOutput.Pages)
  {
    List<Paragraph> pageParagraphs = new();

    foreach (var block in page.Blocks)
    {
      foreach (var paragraph in block.Paragraphs)
      {
        foreach (var line in paragraph.Lines)
        {
          string lineWords = string.Join(" ", line.Words.Select(w => w.Content));
          pageParagraphs.Add(new Paragraph(new Span(new Run(lineWords))));
        }
      }
    }
    flowDoc.Blocks.AddRange(pageParagraphs);
    flowDoc.Blocks.Add(new Paragraph(new Span(new Run(Environment.NewLine))));
  }
  return flowDoc;
}

Limitations

TSV output provides information about text detected by the OCR engine; however, the quality of the results depends on the quality and content of the source image. OCR generally performs best on high-quality document images containing text with a common reading orientation.

Documents containing text at many different rotations, curved text, dense graphics, engineering annotations, survey dimensions, map labels, or other complex layouts can be more challenging to recognize accurately. In these cases, applications should treat OCR output as an aid to processing rather than as an authoritative interpretation of the document.

When OCR accuracy is critical, applications should validate extracted results before relying on them for automated workflows.

Processing individual pages

A specific page can be requested through OCROptions. As previously mentioned, the page index is a 0-based index, meaning the first page is index 0; the second page is index 1 and so on.

var options = new OCROptions(documentPath, pageIndex);

Examples:

Process only the first page of the document

new OCROptions(documentPath, 0);

Process only the fourth page of the document.

new OCROptions(documentPath, 3);

Process all pages of the document

new OCROptions(documentPath, -1);

Exception handling

The OCR API can throw several exceptions.

Exception Description
ArgumentNullException Required argument is null
ArgumentException Invalid document or unsupported extension
OCRException OCR engine error
OperationCanceledException Operation was cancelled
CalledOnWrongThreadException Method called outside the MCT

Example:

try
{
  await QueuedTask.Run(async () =>
  {
    string text = await OCRManager.Instance.ExtractTextFromDocumentAsync(path);
  });
}
catch (OCRException ex)
{
  MessageBox.Show(ex.Message);
}
catch (ArgumentException ex)
{
  MessageBox.Show(ex.Message);
}

Performance considerations

Image quality

OCR accuracy depends heavily on:

  • Resolution.
  • Scan quality.
  • Image clarity.
  • Document orientation.
  • Text complexity. Poor-quality scans may produce incomplete or inaccurate results.

Large documents

When processing large PDF or TIFF documents:

  • Process individual pages when practical.
  • Use cancellation support.
  • Consider reporting progress to users.

Output selection

When only plain text is required, use:

OCROutputType.Text

Structured outputs generally require additional processing and memory. Processing each page individually is more robust, and is demonstrated in the following example.

Example: Process each page individually

await QueuedTask.Run(async () =>
{
  int pageCount = OCRManager.Instance.GetDocumentPageCount(documentPath);
  for (int page = 0; page < pageCount; page++)
  {
    string text = await OCRManager.Instance.ExtractTextFromDocumentAsync(
                    documentPath, page);
    System.Diagnostics.Debug.WriteLine($"Page {page + 1}");
    System.Diagnostics.Debug.WriteLine(text);
  }
});

Extracting traverse information from deeds

In addition to general OCR functionality, the OCR API includes specialized support for extracting traverse information from deed descriptions through the ExtractTraverseFromDeedAsync methods on OCRManager. The ExtractTraverseFromDeedAsync methods are available as extension methods within the ArcGIS.Desktop.Editing namespace.

This functionality builds upon OCR text recognition and attempts to identify coordinate geometry (COGO) information from legal descriptions, using keywords to convert recognized deed language into traverse-related information that can be used in downstream COGO workflows.

The deed traversal extraction capability is conceptually related to the COGO and Traverse APIs, and is intended for workflows that begin with a scanned or image-based deed document and ultimately result in the creation of traverse courses and COGO geometry.

Deed traversal extraction is documented in detail in the COGO ProConcepts topic. Developers interested in creating traverses from deed descriptions should refer to the COGO concepts documentation for information on the traverse object model, COGO line construction, traverse adjustment, and feature creation workflows. OCR recognition quality remains dependent on the quality, content, and layout of the source document.

A typical high-level workflow is:

  1. Use OCRManager to read and interpret a deed document.
  2. Extract traverse information using ExtractTraverseFromDeedAsync.
  3. Use the resulting traverse information with the COGO and Traverse APIs.
  4. Optionally create COGO features or perform traverse calculations and adjustments.

For more information, see the Traverse and COGO concepts documentation.

Summary

The OCR API provides a straightforward mechanism for extracting text and structured OCR information from image-based documents. OCRManager serves as the central entry point and supports document validation, page inspection, asynchronous OCR processing, multiple output formats, page-specific extraction, and cancellation support.

The API exposes OCR functionality directly through the ArcGIS Pro SDK and does not require developers to add or manage a separate OCR library dependency within their add-in projects.

For simple text extraction workflows, OCROutputType.Text provides a convenient way to obtain recognized content as plain text. For more advanced scenarios, OCROutputType.TSV provides access to structured OCR metadata, including document hierarchy, approximate text locations, and recognition confidence information.

OCR results are dependent on image quality, document layout, and text orientation. The OCR engine is generally most effective on document-style content that follows a common reading orientation. More complex content, such as engineering drawings, maps, survey plats, and documents containing text at many different angles, may produce less consistent results and should be validated before being used in automated workflows.

The OCR API is well suited for document processing, indexing, search, classification, and related automation tasks while following the standard ArcGIS Pro threading model through execution on the Main CIM Thread using QueuedTask.Run.