| Customize Help

Global context settings


The global settings of a String Reader context can determine the strategy used to read all of the context's string models, which in turn, could affect the speed and robustness of the read operation (MstrRead()). To adjust the global context settings to fit your individual application's needs, use MstrControl() with M_CONTEXT.

The default value for each global context setting is typically good. However, if you want to find the optimum balance between speed and robustness for a particular application, it is recommended that you experiment with different global context setting values.

The global context settings include:

  • Minimum contrast.

  • Speed.

  • Timeout.

  • Maximum number of strings to read.

  • Encoding.

  • Space character.

  • String separator.

  • Scale.

  • Skew.

Unlike other global context settings of String Reader, you can set the maximum number of strings to read for both the String Reader context and each string model within the context. For more information, see the Number of strings to read section earlier in this chapter.

Scale and skew have been previously discussed. For more information, see the String scale and character scale subsection of the Degrees of freedom section earlier in this chapter and the Skew angle subsection of the Degrees of freedom section earlier in this chapter. Space characters and string separators are discussed in the Formatted and non-formatted results subsection of the Retrieving results and annotation section later in this chapter.

If the results of your operation are poor due to defects in the image (causing characters not to be distinguishable from some or all of the background) the image might need further processing, such as using MimMorphic() with M_TOP_HAT or M_BOTTOM_HAT. For more information, refer to the Top and bottom hat subsection of the Custom morphological operations section of Chapter 4: Advanced image processing.

Minimum contrast

String Reader is contrast invariant. Therefore, if a valid character exists in the target image, it will be read, regardless of whether the contrast between that character and its background is high or low. However, you might be able to speed up the read time by specifying the minimum contrast value, using MstrControl() with M_MINIMUM_CONTRAST. Valid values are between 1 and 255. The default value is 15. Any character in the target image that does not have a contrast greater than the specified minimum value will be ignored, thereby possibly increasing the speed of the read operation.

Increasing the minimum contrast might make a readable character unreadable. For example, if the contrast between a valid character and its background is 25, and you set the minimum contrast to 50, that character will not be read. It is therefore important to make sure that the minimum contrast value is not causing the read operation to ignore acceptable characters.

Speed

You can specify the algorithm's read speed, using MstrControl() with M_SPEED. The speed can be set to M_MEDIUM or M_HIGH. The default is M_MEDIUM.

Higher read speeds cause the read operation to take a greater number of shortcuts, which typically results in shorter read times, though it can also skip important information.

Timeout

In time critical applications, you can set a time limit, in msec, for String Reader to read using the specified string models. To do so, use MstrControl() with M_TIMEOUT. The default value is 2000 msecs. Due to certain application-dependent calculations, the actual maximum read time might vary slightly from the timeout specified. You can disable the timeout setting using M_DISABLE.

After the time limit has been reached, the read operation will terminate, even if the required number of strings has not been read. Results are returned for all strings read up to the timeout. It is not possible to predict which strings will be read beforehand.

To check whether the timeout limit has been reached, use MstrGetResult() with M_TIMEOUT_END.

Encoding

You can set the type of character encoding used by the String Reader context. To do so, use MstrControl() with M_ENCODING.

The selected encoding scheme will affect the expected data type of the information that you pass to or retrieve from String Reader. For example, when adding characters to the font, using MstrEditFont() with M_CHAR_ADD, the expected data type is based on the M_ENCODING setting.

The encoding schemes supported are M_ASCII and M_UNICODE. M_ASCII specifies an 8-bit ASCII standard character type, and corresponds to the char data type. This is the default value. M_UNICODE specifies a 16-bit Unicode standard character type, and corresponds to the short data type.