IOcrSettingManager Interface

Summary

Manages the underlying engine-specific settings of this IOcrEngine.

Syntax

public interface IOcrSettingManager 

@interface LTOcrSettingManager : NSObject 

public class OcrSettingManager 

public: 
   interface class IOcrSettingManager abstract 

class IOcrSettingManager: 

Remarks

Access the instance of the IOcrSettingManager used by an IOcrEngine through the IOcrEngine.SettingManager property.

IOcrSettingManager allows you to do the following:

• Get and set the underlying engine-specific settings. IOcrEngine is a wrapper for the OCR engine. The OCR engine contains additional specific features and functionalities that can be queried and updated using the IOcrSettingManager interface.
• Load and save the engine settings. Once you set up the OCR engine, re-use these settings by saving the engine state into memory or to an XML file on disk. You can later reload these settings and use them in the same or a different instance of IOcrEngine.

Use the different methods of the IOcrSettingManager interface to get and set the engine-specific settings. Each setting has a unique name (a string value). Get all of the settings available to the current OCR engine through the GetSettingNames method. The GetSettingDescriptor method returns a description of the setting (its type, friendly name and value range). You can then use the various get and set methods to query and change the values of specific settings. For example, if the setting type is OcrSettingValueType.Integer, you can use the GetIntegerValue to get the current value of the setting and the SetIntegerValue to change its value. Refer to the example below for a complete demo.

This interface also contains methods to load and save the engine state to a .NET stream or an XML file on disk. The following table lists all the states saved:

You must call the IOcrEngine.Startup method before you can use the IOcrEngine.SettingManager property.

Note

The IOcrEngine.LanguageManager and IOcrEngine.SpellCheckManager state is also saved when the engine settings are saved. For more information, refer to IOcrSettingManager.Save.

For a list of supported engine-specific settings and their meanings, refer to OCR engine-specific Settings.

Members

Recognition.Adaption

Adapted data file path. Not used in this version of LEADTOOLS.

StringMaximumLength: -1

StringNullAllowed: True

Recognition.AutoRecognizeManager

Default orientation for the generated document if a page is blank or graphics only.

EnumIsFlags: False.

Optimize the recognition speed based on the final document format.

true to optimize the recognition speed based on the format of the final document; otherwise, false. The default value is true. As an example, the OCR engine does not recognize font attributes such as italic or bold if the final document format is Text.

Perform an automatic second pass clean up on the internal black and white image when the first pass does not provide satisfactory results. The default value is true.

Recognition.CharacterFilter

Discard noise like characters. true to ignore recognized characters that have features similar to noise; otherwise, false. The default value is false.

Discard noisy zones. true to discard all the results in the zone if the engine determines that all the characters recognized are noise; otherwise, false. The default value is false.

The minimum height of a recognized character, in pixels. The default value is 6.

Units: pixels

IntegerMinimumValue: 0

IntegerMaximumValue: 2147483647 (Int32.MaxValue)

Characters to exclude from the minimum pixel width and height rule. The default value is ".". Can be null.

StringMaximumLength: -1

StringNullAllowed: True

The minimum width of a recognized character, in pixels. The default value is 6.

Units: pixels

IntegerMinimumValue: 0

IntegerMaximumValue: 2147483647 (Int32.MaxValue)

Automatically post-process MICR results. true to post-process any MICR zones by discarding all of the characters, numbers and symbols that do not belong to the MICR character set as well as performing basic validity data checking; otherwise, false. The default value is true.

Automatically detect foreground and background colors of each character. If this value is true, then the engine tries to automatically detect the colors of the zones when IOcrPage.AutoZone is called and sets the values in OcrZone.ForeColor and OcrZone.BackColor.

Detect the exact bounding rectangle for each recognized character. true to detect the exact bounding rectangle for each recognized character; otherwise, false. The default value is false.

Recognition.Fonts

Enable the detection of font style properties. These flags affect the final generated document if the format supports fonts (such as the PDF or DOCX formats). Values can be OR-ed together. The default value is Bold | Italic | Underline | SansSerif | Serif | Proportional | Superscript | Subscript | Strikeout.

EnumIsFlags: True

Enable Caps/Caps font recognition enhancements. true to enable Caps/Caps (CamelCase) font recognition enhancements; otherwise, false. The default value is false.

Disable to detect multiple font spacing (monospace versus proportional) when the image contains lines with a mixture of font spacings which is atypical.
Default value is True.

Recognize font attributes. true to enable font attributes recognition; otherwise, false. The default value is true.

Enable the detection of image type.

EnumIsFlags: False

Maximum memory size in KB of a page before switching to disk or tiled.

The appropriate setting depends on the system hardware configuration and the number of cores and application types being used. Change this setting if out-of-memory errors occur when running your application.

The IOcrEngine supports loading RasterImage objects directly from disk files, streams or URLs, (as for example, the various methods in the IOcrPageCollection and IOcrAutoRecognizeManager classes do). The loaded RasterImage holds the original image and is useful only when saving graphics zones or image-over-text overlays. If the image is large, and one created using conventional memory, then a large amount of physical memory is used to hold this image in memory and is not available for other purposes such as auto-zoning or recognition. This is more noticeable in multi-threaded applications where loading several large images in conventional memory can cause out-of-memory errors, even when performing operations that normally would succeed.

Use MaximumPageConventionalMemorySize to set the maximum size of the image in memory allowed before the IOcrEngine automatically switches to use the disk memory feature of RasterImage and (RasterMemoryFlags). The MaximumPageConventionalMemorySize is in KBytes and its default value depends on the processors being used. For x86 processors, the value is 42187 (42MBytes). For x64 processors, the value is calculated dynamically (1.7GBytes for each 8 cores, not exceeding the physical memory size). These values allow a typical OCR image (8.5 by 11 inches at 300 DPI and 32-bits per pixel) to be loaded in conventional memory. Anything significantly larger than that gets switched to use disk memory mode.

Different factors affect the performance of a particular setting and must be weighed and they include the following factors:

• The speed of the machine's hard drive - increases the penalty for using disk memory rather than conventional memory.
• Load time - using disk memory consumes more time loading than using conventional memory.
• Autozoning and Recognition - using disk memory improves the performance of autozoning, recognition and other operations because conventional memory is freed for image processing.

Units: KB

IntegerMinimumValue: 0

IntegerMaximumValue: 2147483647 (Int32.MaxValue)

Modify processing image. true to modify the processing image after recognition; otherwise, False. It is best to set the value of this setting to true if IOcrPage.Recognize is called only once per page. IOcrAutoRecognizeManager temporarily sets the value of this setting to true while performing a recognition job.

Recognition.Preprocess

Black and white image conversion method. This setting influences how a non-black and white image, stored in the Engine, is converted to black and white. The default value is Default.

EnumIsFlags: False

Black and white image conversion threshold. The threshold to use when converting colored images to bitonal (black and white) in preparation for recognizing the text on the image. Conversion separates the text intensities from the background intensities. The default value is 185.

This is the equivalent of calling IntensityDetectCommand on the image with InColor equal to the detected foreground (text) color, OutColor equal to the detected background color, Channel set to Master, HighThreshold equal to 255, and LowThreshold equal to the value of this setting.

IntegerMinimumValue: 0

IntegerMaximumValue: 255

Black and white Sauvola K factor.

Units: DoubleMinimumValue: 0

DoubleMaximumValue: 1

Black and white Sauvola R factor.

IntegerMinimumValue: 1

IntegerMaximumValue: 4096

Black and white Sauvola window size.

IntegerMinimumValue: 2

IntegerMaximumValue: 4096

Down sample large image. true to down-sample large images prior to recognition; otherwise, false. The default value is false.

Set the value to true to prevent the OCR engine from creating processing images (the image used for recognition) larger than 4000 by 4000 pixels (in order to preserve memory and resources). This value is ignored if the value of the MobileImagePreprocess setting is true.

Minimum confidence percentage for auto-rotate. Used by the IOcrPage.AutoPreprocess method to determine the minimum confidence percentage threshold to use when orienting pages. The default value is 26.

IntegerMinimumValue: 0

IntegerMaximumValue: 100

Mobile image preprocess. true to enable mobile image processing mode; otherwise, false. The default value is false.

Modify original image during preprocessing options. Specifies how the original image is modified when calling the IOcrPage.AutoPreprocess method. Values can be OR-ed together. The default value is Deskew | Rotate | Invert.

EnumIsFlags: True

Recognize inverted text regions. true to automatically detect and recognize inverted regions, otherwise; false. The default value is false.

Set this value to true to support OCRing an image that contains both black/white and white/black areas.

Use the zoning engine to exclude graphics areas from preprocessing calculations. true to use the zoning engine to exclude graphics areas from preprocessing calculations such as deskew and auto-rotate; otherwise, false. The default value is true.

Recognition module tradeoff between speed and accuracy. The default value is Balanced.

EnumIsFlags: False

Specifies the recognition module to use to process machine-printed, handwritten text, or a combination of both.

EnumIsFlags: False

Share original image. true to share the image reference used to create the OCR page; otherwise, false. The default value is false.

Setting this value to true affects the IOcrPageCollection.AddPage(RasterImage, OcrProgressCallback) and IOcrPageCollection.InsertPage(int, RasterImage, OcrProgressCallback) methods. When the value is false, these methods make a copy of the image and use the copy to create the page. Calling IOcrPage.GetRasterImage(OcrPageType.Original) on such a page returns a null reference. Otherwise, if the value is true, these methods use the same image reference to create the page.

To return the original image reference, call IOcrPage.GetRasterImage(OcrPageType.Original) on the copy page.

IOcrAutoRecognizeManager temporarily changes the value of this setting to true while performing a recognition job.

Recognition.Threading

Maximum number of threads to use in recognition. Gets or sets the maximum number of threads to use in recognition. The LEADTOOLS OCR Module - LEAD Engine provides support for recognizing document zones in separate threads. This can improve the performance of the IOcrPage.Recognize method. The default value is 0, which instructs LEADTOOLS to use the system thread pool. The number of threads is calculated automatically. Setting the value to a number > 1 also turns multi-threading on, but the number of threads specified is ignored and calculated automatically instead.

To turn multi-threading off inside the IOcrPage.Recognize method and use a single thread, set the value to 1.

IntegerMinimumValue: 0

IntegerMaximumValue: 2147483647

Recognition.Words

Discard words with low confidence. true to discard words with a low rating; otherwise, false. The default value is true.

Discard zones with low confidence. true to discard zones with low ratings; otherwise, false. The default value is false.

This setting controls the output. If true, the engine checks all of the words/characters in a zone. If it determines that the overall confidence and type of characters constitute noise, then the recognition results for the entire zone is discarded.

Low word confidence. Discard any word with a confidence value less than this value. The default value is 50. This setting only takes effect when DiscardLowConfidenceWords is set to true.

IntegerMinimumValue: 0

IntegerMaximumValue: 100

Recognition.Zoning

Check box detection sensitivity.

EnumIsFlags: False

Crop image to zone size. true to crop each zone from the original image and recognize it by itself; otherwise, false. The default value is true.

Setting this value to true can improve the performance of the IOcrPage.Recognize method.

Vertical zone detection mode. This works with Latin and Asian languages.

EnumIsFlags: False

Detect zone rotation angle. true to try to detect a separate rotation angle for each zone; otherwise, false. The default value is false.

Setting this value to false can increase the speed of the recognition engine.

Disable multi-threading while zoning. true to disable multi-threading when performing auto-zoning; otherwise, multi-threading is enabled. The default value is false.

Multi-threading enhances the performance of the auto-zoning algorithm. However, it can be undesirable if the OCR engine is hosted on a server.

Enable double zoning. true to perform a second, internal auto-zoning procedure on each text zone in order to generate more homogeneous zones for recognition; otherwise, false. The default value is true.

Setting this value can improve the performance of the IOcrPage.Recognize method.

Auto zoning options. These flags affect the way the IOcrPage.AutoZone method works. Values can be OR-ed together. The default value is Detect Text | Detect Graphics | Detect Table | Detect Accurate Zones | Table Cells As Zones | Use Advanced Table Detection | Use Text Extractor | Favor Graphics.

EnumIsFlags: True

SpellChecker

Enable caching of incorrectly spelled words. true to enable caching of frequent words, otherwise; false. The default value is true.

Maximum number of spell checkers dictionaries to use. Gets or sets the maximum number of spell checkers to use at the same time. The default value is the number of available dictionaries found in the system.

IntegerMinimumValue: 0

IntegerMaximumValue: 255

Example

This example will start the LEADTOOLS OCR Module - LEAD Engine. Shows the values of all the settings and change a few of them.

using Leadtools; 
using Leadtools.Codecs; 
using Leadtools.Ocr; 
using Leadtools.Document.Writer; 
 
public void OcrSettingManagerExample() 
{ 
   // Create an instance of the engine 
   using (IOcrEngine ocrEngine = OcrEngineManager.CreateEngine(OcrEngineType.LEAD)) 
   { 
      // Start the engine using default parameters 
      ocrEngine.Startup(null, null, null, LEAD_VARS.OcrLEADRuntimeDir); 
 
      IOcrSettingManager settingManager = ocrEngine.SettingManager; 
 
      // Dump all the settings supported by this engine to a text file on disk 
      DumpAllSettings(settingManager); 
 
      // Image file to OCR 
      string tifFileName = Path.Combine(LEAD_VARS.ImagesDir, "Ocr1.tif"); 
 
      // File formats to save 
      DocumentFormat[] formats = { DocumentFormat.Text, DocumentFormat.Pdf }; 
 
      foreach (DocumentFormat format in formats) 
      { 
         // Generate the output file name 
         string outFileName = Path.ChangeExtension(tifFileName, DocumentWriter.GetFormatFileExtension(format)); 
 
         Console.WriteLine("Format: {0}\nOutput file: {1}", format, outFileName); 
 
         int detectFontStyles = 0; 
         bool recognizeFontAttributes = false; 
 
         if (format == DocumentFormat.Text) 
         { 
            // This is 'text' format, we dont need to recognize fonts attributes such as bold and italic 
            // This will make the recognition process faster 
 
            Console.WriteLine("Turning off font attributes"); 
 
            // Save the old settings 
            detectFontStyles = settingManager.GetEnumValue("Recognition.Fonts.DetectFontStyles"); 
            recognizeFontAttributes = settingManager.GetBooleanValue("Recognition.Fonts.RecognizeFontAttributes"); 
 
            // Turn them off now 
            settingManager.SetEnumValue("Recognition.Fonts.DetectFontStyles", "None"); 
            settingManager.SetBooleanValue("Recognition.Fonts.RecognizeFontAttributes", false); 
         } 
 
         // Show the settings we are using 
         Console.WriteLine("Recognizing using these font attributes settings:"); 
         Console.WriteLine("Recognition.Fonts.DetectFontStyles: {0}", settingManager.GetEnumValueAsString("Recognition.Fonts.DetectFontStyles")); 
         Console.WriteLine("Recognition.Fonts.RecognizeFontAttributes: {0}", settingManager.GetBooleanValue("Recognition.Fonts.RecognizeFontAttributes")); 
 
 
         // Recognize and save the file to the output format 
         using (IOcrDocument ocrDocument = ocrEngine.DocumentManager.CreateDocument()) 
         { 
            // Add a page to the document 
            IOcrPage ocrPage = ocrDocument.Pages.AddPage(tifFileName, null); 
 
            // Recognize the page 
            // Note, Recognize can be called without calling AutoZone or manually adding zones. The engine will 
            // check and automatically auto-zones the page 
            ocrPage.Recognize(null); 
 
            // Save the document we have as PDF 
            ocrDocument.Save(outFileName, format, null); 
         } 
 
         // Re-set the original settings 
         if (format == DocumentFormat.Text) 
         { 
            Console.WriteLine("Resetting original settings"); 
            settingManager.SetEnumValue("Recognition.Fonts.DetectFontStyles", detectFontStyles); 
            settingManager.SetBooleanValue("Recognition.Fonts.RecognizeFontAttributes", recognizeFontAttributes); 
         } 
      } 
 
      // Shutdown the engine 
      // Note: calling Dispose will also automatically shutdown the engine if it has been started 
      ocrEngine.Shutdown(); 
   } 
} 
 
private static void DumpAllSettings(IOcrSettingManager settingManager) 
{ 
   // Write all the settings into a disk file 
   string settingsFileName = Path.Combine(LEAD_VARS.ImagesDir, "Settings.txt"); 
   using (StreamWriter writer = File.CreateText(settingsFileName)) 
   { 
      writer.WriteLine("Settings"); 
      string[] settingNames = settingManager.GetSettingNames(); 
 
      foreach (string settingName in settingNames) 
      { 
         IOcrSettingDescriptor sd = settingManager.GetSettingDescriptor(settingName); 
 
         writer.WriteLine("  Name:           {0}", sd.Name); 
         writer.WriteLine("  ValueType:      {0}", sd.ValueType); 
         writer.WriteLine("  FriendlyName:   {0}", sd.FriendlyName); 
 
         switch (sd.ValueType) 
         { 
            case OcrSettingValueType.BeginCategory: 
               writer.WriteLine("-------------------------------------"); 
               break; 
 
            case OcrSettingValueType.Integer: 
               writer.WriteLine("    Units: {0}", sd.Units); 
               writer.WriteLine("    IntegerMinimumValue: {0}", sd.IntegerMinimumValue); 
               writer.WriteLine("    IntegerMaximumValue: {0}", sd.IntegerMaximumValue); 
               break; 
 
            case OcrSettingValueType.Enum: 
               writer.WriteLine("    EnumIsFlags: {0}", sd.EnumIsFlags); 
               writer.WriteLine("    EnumMemberFriendlyNames"); 
               { 
                  int[] values = sd.GetEnumMemberValues(); 
                  string[] names = sd.GetEnumMemberFriendlyNames(); 
                  for (int i = 0; i < values.Length; i++) 
                  { 
                     writer.WriteLine("      {0} : {1}", names[i], values[i]); 
                  } 
               } 
               break; 
 
            case OcrSettingValueType.Double: 
               writer.WriteLine("    Units: {0}", sd.Units); 
               writer.WriteLine("    DoubleMinimumValue: {0}", sd.DoubleMinimumValue); 
               writer.WriteLine("    DoubleMaximumValue: {0}", sd.DoubleMaximumValue); 
               break; 
 
            case OcrSettingValueType.Boolean: 
               break; 
 
            case OcrSettingValueType.Character: 
               break; 
 
            case OcrSettingValueType.String: 
               writer.WriteLine("    StringMaximumLength:   {0}", sd.StringMaximumLength); 
               writer.WriteLine("    StringNullAllowed:     {0}", sd.StringNullAllowed); 
               break; 
 
            case OcrSettingValueType.Rectangle: 
               break; 
 
            case OcrSettingValueType.EndCategory: 
               break; 
 
            default: 
               break; 
         } 
      } 
   } 
} 
 
static class LEAD_VARS 
{ 
   public const string ImagesDir = @"C:\LEADTOOLS23\Resources\Images"; 
   public const string OcrLEADRuntimeDir = @"C:\LEADTOOLS23\Bin\Common\OcrLEADRuntime"; 
}