| MIL 10 Reference
| Customize Help
| Save Settings

MocrControl



See also
Availability
Not available in MIL-Lite
Available in MIL

Available on Windows
Available on Linux

Available on Non-Matrox computer
Available on Matrox 4Sight-X
Available on Matrox 4Sight GP
Available on Matrox Supersight
function map Function map
Examples
Synopsis
Control an OCR font context or an OCR result buffer setting.
Syntax
void MocrControl(
MIL_ID FontContextOrResultOcrId, //in
MIL_INT64 ControlType, //in
MIL_DOUBLE ControlValue //in
)
Description

This function allows you to control an OCR read/verify operation setting. This function also allows you to control various settings that affect how results are retrieved by MocrGetResult(). To inquire the current value of a particular control type, use MocrInquire().

After changing the OCR controls or constraints, use MocrPreprocess() to speed up any following read or verify operation.

Note that this function reference has not been updated for a MIL system added during a MIL update. Refer to the MIL system's release note to see if there is complementary information.
Parameters
This function is not supported on the selected boards.
Parameters
FontContextOrResultOcrId

Specifies the identifier of the OCR font context or the OCR result buffer to control.

ControlType

Specifies the type of control to set.

See the Parameter associations section for possible values that can be specified.

ControlValue

Specifies the required value for the control.

See the Parameter associations section for possible values that can be specified.

The following ControlType and corresponding ControlValue parameter settings are used to specify the characteristics of the font.

function map For the characteristics of the font
CollapseControlType Description
ControlValue
Collapse M_CHAR_ERASE

Erases a character from the font of the OCR font context.

(summarize)
Collapse Value

Specifies the ASCII character associated with the character. Note that the character must be present in the OCR font context.

(summarize)

The following ControlType and corresponding ControlValue parameter settings are used to specify operational controls for read and verify operations.

function map For operation controls for read and verify operations
CollapseControlType Description
ControlValue
Collapse M_BLANK_CHARACTERS

Sets whether the space between characters in the target image is read or not.

Note that this is available only when using an M_GENERAL OCR font context. In addtion, blank characters cannot be verified (using MocrVerifyString()) and will cause a MIL error. INQ

(summarize)
Collapse M_DISABLE

Specifies that blank spaces will not be read from the target image into the result string.

Note that spaces could still be erroneously read if your OCR font context is not manually calibrated properly or the string length for your target image is wrong.

This is the default value.

(summarize)
Collapse M_ENABLE

Specifies that blank spaces will be read from the target image into the result string.

Collapse M_BROKEN_CHAR

Sets the capability to read/verify a broken character. INQ

(summarize)
Collapse M_DISABLE

Specifies that, during the read/verify, OCR should not try to compensate for broken characters. Note that this enables a faster algorithm for reading/verifying a string within the target image.

Note that broken characters could still be erroneously read if your target image is noisy, scratched, has low contrast characters, or if the illumination is not uniform.

This is the default value.

(summarize)
Collapse M_ENABLE

Specifies that broken characters should be identifies as possible characters.

Collapse M_CHAR_ACCEPTANCE

Sets the acceptance level used to determine a successful match between the font and the characters found within the target image. During a read/verify operation, the character found with the highest match score, either equal to or greater than the acceptance level, will be returned.

If the match score is less than the acceptance level, the result with the highest match score closest to the acceptance level will be returned. If the match score is 0% the invalid character (M_CHAR_INVALID) is returned.

A perfect match is 100%, no correlation is 0%. The match score depends on the image quality. You should experiment to decide what is a typical match score for your application. INQ

(summarize)
Collapse 0.0 <= Value <= 100.0

Specifies the acceptance level for a target character.

The default value is 1.0.

(summarize)
Collapse M_CHAR_INVALID

Sets the ASCII character for all characters within the selected string or strings during the next read or verify operation whose match scores fall below the character acceptance level. INQ

(summarize)
Collapse M_NULL

Specifies that no special character will replace unrecognized characters.

This is the default value.

(summarize)
Collapse 1 <= Value <= 255

Specifies the character that will replace unrecognized characters.

Collapse M_CONTEXT_CONVERT

Changes the type of OCR font context. Note that not all controls are available with both types of OCR font contexts. The restrictions are indicated within each control. When you change the type of OCR font context, invalid controls are replaced by their default value. INQ

(summarize)
Collapse M_CONSTRAINED

Specifies an OCR font context that works well with degraded target images. It requires more information about the target string, but provides a more robust search.

(summarize)
Collapse M_GENERAL

Specifies an OCR font context that works well with clean target images. It requires less information about the target string, but provides a less robust search.

(summarize)
Collapse M_EXTRA_CHARACTERS

Sets whether to still read and identify the string when the image contains more characters than otherwise expected. INQ

(summarize)
Collapse M_DEFAULT

Same as M_DISABLE.

Collapse M_DISABLE

Specifies that the read/verify operation should not try to compensate for extra characters.

Collapse M_ENABLE

Specifies that the read/verify operation should try to compensate for extra characters.

Collapse M_MORPHOLOGIC_FILTERING

Sets the number of iterations of morphological filtering.

Morphological filtering can add robustness to the OCR operation by internally enhancing the contrast of the image, but it requires processing time. The optimal number of iterations depends on the complexity of the target image. INQ

(summarize)
Collapse 0 <= Value <= 100

Specifies the number of iterations. 0 disables the morphologic filtering. Only integer values are accepted.

The default value is 2.

(summarize)
Collapse M_SKIP_STRING_LOCATION

Sets whether to first locate the strings in the target image before trying to identify characters against the OCR font context or to skip this step and save processing time. INQ

(summarize)
Collapse M_DISABLE

Specifies that the step will not be skipped.

This is the default value.

(summarize)
Collapse M_ENABLE

Specifies that the step will be skipped.

Collapse M_SPEED

Sets the algorithm's search speed. Note that increasing the search speed can decrease the robustness and subpixel accuracy of a read/verify operation. This is most effective on large-sized characters. INQ

(summarize)
Collapse M_HIGH

Specifies a high speed.

Collapse M_LOW

Specifies a low speed.

Collapse M_MEDIUM

Specifies a medium speed.

This is the default value.

(summarize)
Collapse M_VERY_HIGH

Specifies a very high speed.

Collapse M_VERY_LOW

Specifies a very low speed.

Collapse M_STRING_ACCEPTANCE

Sets the acceptance level used to determine a successful match between the font and a read/verified string. During a read/verify operation, the string found with the highest match score, either equal to or greater than the acceptance level, will be returned.

If the match score is less than the acceptance level, the result with the highest match score closest to the acceptance level will be returned. If the match score is 0%, a blank string is returned. Note that, in this case, MocrGetResult() with M_STRING_VALID_FLAG would be false.

A perfect match is 100%, no correlation is 0%. The match score depends on the image quality. You should experiment to decide what is a typical match score for your application. INQ

(summarize)
Collapse 0.0 <= Value <= 100.0

Specifies the acceptance level for a string.

The default value is 1.0.

(summarize)
Collapse M_STRING_ANGLE_INTERPOLATION_MODE

Sets the interpolation mode to use when reading/verifying a string at an angle. INQ

(summarize)
Collapse M_BICUBIC

Specifies that bicubic interpolation should be used.

Collapse M_BILINEAR

Specifies that bilinear interpolation should be used.

This is the default value.

(summarize)
Collapse M_NEAREST_NEIGHBOR

Specifies that nearest neighbor interpolation should be used.

Collapse M_TOUCHING_CHAR

Sets the capability to read/verify characters that touch each other in the target image. INQ

(summarize)
Collapse M_DISABLE

Specifies to disable the identification of touching characters. Enables a faster algorithm for read or verify operations.

This is the default value.

(summarize)
Collapse M_ENABLE

Specifies to enable the identification of touching characters.

The following ControlType and corresponding ControlValue parameter settings are used to set the characteristics of the target characters.

function map For the characteristics of the target characters
CollapseControlType Description
ControlValue
Collapse M_CHAR_POSITION_VARIATION_X

Sets the amount by which the position of the characters in the target string can vary along the X-axis. This tolerance is relative to the position of each character, as determined by M_TARGET_CHAR_SPACING. This tolerance increases the region being searched for characters within the target image. INQ

(summarize)
Collapse 0.0 <= Value <= 100.0

Specifies the position tolerance, in pixels of the character, not of the target image.

The default value is 0.0.

(summarize)
Collapse M_CHAR_POSITION_VARIATION_Y

Sets the amount by which the position of the characters in the target string can vary along the Y-axis. This tolerance is relative to the position of each character, as determined by M_TARGET_CHAR_SPACING. This tolerance increases the region being searched for characters within the target image. INQ

(summarize)
Collapse 0.0 <= Value <= 100.0

Specifies the position tolerance, in pixels of the character, not of the target image.

The default value is 0.0.

(summarize)
Collapse M_STRING_ANGLE

Sets the expected angle at which the string can be found. INQ

(summarize)
Collapse M_ACCORDING_TO_REGION

Specifies to use the angle of the rectangular ROI (set using MbufSetRegion()) associated with the target image buffer. If the target image is not associated with an ROI, an angle of 0.0 is used.

This is the default value.

(summarize)
Collapse 0 <= Value <= 360

Specifies the angle, in degrees.

Collapse M_STRING_ANGLE_DELTA_NEG

Sets the possible angle variation in a clockwise rotation, relative to M_STRING_ANGLE. When searching for a string over a range of angles (setting M_STRING_ANGLE_DELTA_POS and/or M_STRING_ANGLE_DELTA_NEG to a value greater than 1°), the font context's character size must be greater than 16x16 to avoid a MIL error when calling MocrReadString(), MocrVerifyString() or MocrCalibrateFont(). INQ

(summarize)
Collapse 0 <= Value <= 180

Specifies the possible clockwise angle variation, in degrees. A value less than or equal to 1° will not search over a range of angles.

The default value is 0.0.

(summarize)
Collapse M_STRING_ANGLE_DELTA_POS

Sets the possible angle variation in a counter-clockwise rotation, relative to M_STRING_ANGLE. When searching for a string over a range of angles (setting M_STRING_ANGLE_DELTA_POS and/or M_STRING_ANGLE_DELTA_NEG to a value greater than 1°), the font context's character size must be greater than 16x16 to avoid a MIL error when calling MocrReadString(), MocrVerifyString() or MocrCalibrateFont(). INQ

(summarize)
Collapse 0 <= Value <= 180

Specifies the possible counter-clockwise angle variation, in degrees. A value less than or equal to 1° will not search over a range of angles.

The default value is 0.0.

(summarize)
Collapse M_STRING_NUMBER

Sets the number of strings to be read/verified from the target image. Multiple strings can only be found if each string resides on a different line within the target image and each line of text does not overlap the previous.

Note that, for best results, all strings read in an image with multiple strings should be of similar length, have a consistent inter-line spacing and should start at a similar location along the X-axis. INQ

(summarize)
Collapse M_ALL

Specifies that the number of strings in the target image should be determined automatically.

Collapse Value

Specifies the number of lines of text in the target image. Note that specifying this value can improve the speed of a following read/verify operation.

The default value is 1.

(summarize)
Collapse M_STRING_SIZE

Sets the length of the string to be read/verified from the target image. INQ

(summarize)
Collapse M_ANY

Specifies that the length of the string is unknown.

Note that this is available only when using an M_GENERAL OCR font context.

(summarize)
Collapse Value

Specifies the string length to read/verify, which must be less than or equal to the maximum string length of the OCR font context.

Note that when using an M_GENERAL OCR font context and M_BLANK_CHARACTERS are enabled, blank characters must be counted in the string length.

The default value is set to the maximum string length of the OCR font context. When OCR font context constraints are set, specifying a string length can improve the speed of a following read/verify operation.

Note that if M_SEMI_M12_92 is used, the string length must be 12. If M_SEMI_M13_88 is used, the string length must be 18.

(summarize)
Collapse M_TARGET_CHAR_SIZE_X

Sets the width of the target characters. Note that this can also be automatically set using MocrCalibrateFont(). INQ

(summarize)
Collapse M_SAME

Specifies that the character width is found automatically. Use this value when the font uses a fixed width for all its characters.

Note that this is available only when using an M_GENERAL OCR font context.

(summarize)
Collapse Value > 1

Specifies the character width in pixels (with subpixel accuracy).

The default value is set to the character size X of the font.

(summarize)
Collapse M_TARGET_CHAR_SIZE_Y

Sets the height of the target characters. Note that this can also be automatically set using MocrCalibrateFont(). INQ

(summarize)
Collapse M_SAME

Specifies that the character height is found automatically. Use this value when the font uses a fixed height for all its characters.

Note that this is available only when using an M_GENERAL OCR font context.

(summarize)
Collapse Value > 1

Specifies the character height in pixels (with subpixel accuracy).

The default value is set to the character size Y of the font.

(summarize)
Collapse M_TARGET_CHAR_SPACING

Sets the amount of space between characters in the string. Note that this can also be automatically set using MocrCalibrateFont(). INQ

(summarize)
Collapse M_ANY

Specifies that the inter-character spacing is unknown and not the same between the characters. This enables automatic spacing detection.

Note that this is available only when using an M_GENERAL OCR font context.

(summarize)
Collapse M_SAME

Specifies that the inter-character spacing is the same throughout the target string. This enables automatic spacing detection.

Note that this is available only when using an M_GENERAL OCR font context.

(summarize)
Collapse Value >= 2

Specifies the inter-character spacing, in pixels, with subpixel accuracy.

The default value is set to the character cell size of the font.

(summarize)
Collapse M_TEXT_STRING_SEPARATOR

Sets the ASCII character to be used as a string separator within the text read/verified. This separator will be inserted between each string. Note that this must be set before the text is read/verified. INQ

(summarize)
Collapse Value

Specifies the ASCII code of the character.

The default value is '\n'.

(summarize)
Collapse M_THICKEN_CHAR

Sets the number of character thickening iterations.

Each iteration enlarges the thickness of the target character. This is useful for some types of fonts (for example, dotted characters). You should choose a value large enough for the intra character dots to connect but not too large to connect separate characters together.

Note that the characters included in the font should not be dotted. Instead a thickened version should be included.

(summarize)
Collapse M_DEFAULT

Specifies the default value; the default value is 0.

Collapse 0 <= Value <= 100

Specifies the number of times a character should be thickened. Only integer values are accepted.

(summarize)
Collapse M_THRESHOLD

Sets the threshold value used to internally binarize the target image for segmentation of characters.

Note that this control type is available only when using an M_GENERAL OCR font context. INQ

(summarize)
Collapse M_AUTO

Specifies to use an automatically computed threshold value.

Collapse Value

Specifies the threshold value.

The default value is 1.

(summarize)

The following ControlType and corresponding ControlValue parameter settings are used to control settings of the result buffer.

function map For the result buffer
CollapseControlType Description
ControlValue
Collapse M_RESULT_OUTPUT_UNITS

Sets whether to return results in pixels or world units. This essentially sets the output coordinate system to use. The setting of this control type will only affect functions within this module which return positional results. This control type can be changed at any time to return results in the required output units. INQ

(summarize)
Collapse M_DEFAULT

Same as M_ACCORDING_TO_CALIBRATION.

Collapse M_ACCORDING_TO_CALIBRATION

Specifies that results are returned in world units if the result was calculated on an image associated with a calibration context; otherwise, specifies that results are returned in pixel units.

Collapse M_PIXEL

Specifies that results are returned in pixel units, with respect to the pixel coordinate system.

Collapse M_WORLD

Specifies that results are returned in world units, with respect to the relative coordinate system. If world units are specifed, calling MocrGetResult() generates an error if the result was not calculated on a calibrated image.

(summarize)
Collapse M_SELECT_STRING

Selects the line of text to return from the result buffer, when multiple lines of text are read/verified. INQ

(summarize)
Collapse M_ALL

Specifies that all strings are selected.

This is the default value.

(summarize)
Collapse Value

Specifies a specific string. Strings are identified by numbers from 0 to (M_STRING_NUMBER-1).

(summarize)
Type-specific versions of the function
void MocrControlInt64 (MIL_ID FontContextOrResultOcrId, MIL_INT64 ControlType, MIL_INT64 ControlValue)
Parameters

FontContextOrResultOcrId

See FontContextOrResultOcrId of the main function for a description.

ControlType

See ControlType of the main function for a description.

ControlValue

See ControlValue of the main function for a description.

Compilation information
Header Include mil.h.
Library Use mil.lib; milocr.lib.
DLL Requires mil.dll; milocr.dll.
CHAR ERASE BLANK CHARACTERS DISABLE ENABLE BROKEN CHAR DISABLE ENABLE CHAR ACCEPTANCE CHAR INVALID NULL CONTEXT CONVERT CONSTRAINED GENERAL EXTRA CHARACTERS DEFAULT DISABLE ENABLE MORPHOLOGIC FILTERING SKIP STRING LOCATION DISABLE ENABLE SPEED HIGH LOW MEDIUM VERY HIGH VERY LOW STRING ACCEPTANCE STRING ANGLE INTERPOLATION MODE BICUBIC BILINEAR NEAREST NEIGHBOR TOUCHING CHAR DISABLE ENABLE CHAR POSITION VARIATION X CHAR POSITION VARIATION Y STRING ANGLE ACCORDING TO REGION STRING ANGLE DELTA NEG STRING ANGLE DELTA POS STRING NUMBER ALL STRING SIZE ANY TARGET CHAR SIZE X SAME TARGET CHAR SIZE Y SAME TARGET CHAR SPACING ANY SAME TEXT STRING SEPARATOR THICKEN CHAR DEFAULT THRESHOLD AUTO RESULT OUTPUT UNITS DEFAULT ACCORDING TO CALIBRATION PIXEL WORLD SELECT STRING ALL GENERAL