How Key-Value Pairs Work

Our key-value pair (KVP) extraction engine is part of our OCR engine, and like other OCR technologies (MICR, MRZ, OMR, contextual OCR, and more), it benefits from a hybrid approach that includes heuristics, mathematics, and ML capabilities. We use an adaptive layout understanding and the same underlying techniques as NLP technologies.

Our engine automatically adapts to a document and searches for the correct approach, making the best use of resources available. This allows us to have excellent results when dealing with the usual weaknesses of traditional OCR and pure machine learning engines, particularly related to:

  • Text recognition in documents with lots of noise

  • Dotted line recognition

  • Touching and broken characters

  • Text on colored backgrounds

  • Underlined text

  • Skewed text

  • Text in graphics and tables

For more information on key-value pair extraction, check out our demo video below.

What Is a Key-Value Pair?

KVPs are two related data items: a key, and a value. The key defines the data and is fixed, and the value is variable and describes the key.

Depending on the type of document, the key-value pair fields are different. For instance, KVPs on an invoice will be different than the ones on a survey or a government form. Key-value pair fields for invoices can be the invoice number, date, total amounts, and taxes. Key-value pairs for government forms can be a social security number, the date of birth, and a personal address.

How to Use Our Engine

To use our engine to extract useful information from forms, follow these steps:

  1. Create a GdPictureOCR instance and a GdPictureImaging instance.

  2. Load an image of your form using the GdPictureImaging instance.

  3. Run OCR on your image using the GdpictureOCR object.

  4. Use the GetKeyValuePairCountto method to get the number of extracted key-value pairs.

// C#
string caption = "Example: KVP/OCR";
using (GdPictureOCR gdpictureOCR = new GdPictureOCR())
    // Set up your preferred parameters for OCR.
    gdpictureOCR.ResourceFolder = "\\GdPicture.Net 14\\redist\\OCR";
    gdpictureOCR.EnableSkewDetection = true;
    if (gdpictureOCR.AddLanguage(OCRLanguage.English) == GdPictureStatus.OK)
        // Set up the image you want to process.
        GdPictureImaging gdpictureImaging = new GdPictureImaging();
        // The standard open file dialog will allow you to select the file.
        int image = gdpictureImaging.CreateGdPictureImageFromFile("");


         string ocrResultID = gdpictureOCR.RunOCR();

         if (gdpictureOCR.GetStat() == GdPictureStatus.OK)
             string keyValuePairsData = "";

             for (int pairIdx = 0; pairIdx < gdpictureOCR.GetKeyValuePairCount(ocrResultID); pairIdx++)
                 if (pairIdx != 0)
                      keyValuePairsData += "\n";
                 keyValuePairsData += "Name: "     + gdpictureOCR.GetKeyValuePairKeyString(ocrResultID, pairIdx) + " | " +
                                      "Value: "    + gdpictureOCR.GetKeyValuePairValueString(ocrResultID, pairIdx) + " | " +
                                      "Type: "     + gdpictureOCR.GetKeyValuePairDataType(ocrResultID, pairIdx).ToString() + " | " +
                                      "Accuracy: " + Math.Round(gdpictureOCR.GetKeyValuePairConfidence(ocrResultID, pairIdx), 1).ToString() + "%";
             MessageBox.Show(keyValuePairsData, caption);
                MessageBox.Show("The OCR process has failed with the status: " + gdpictureOCR.GetStat().ToString(), caption);
            // Release the used image.
        MessageBox.Show("The AddLanguage() method has failed with the status: " + gdpictureOCR.GetStat().ToString(), caption);

Then you can iterate through the pairs to get the key, the value, the data type, and the confidence level.

Consider the form below. You might pass an image of this form.

Sample invoice

In this case, you’ll be able to extract key information from the form.


The GdPicture.NET Library KVP extraction engine also provides two fields in addition to key and value: type and accuracy.

The type data provides the nature of the content. In the example above, the engine recognizes that the value is an email, the value (+33) 6 59 49 60 76 is a phone number, and so on. When the nature of the value isn’t recognized, you’ll have Type:String.