Click here to show toolbars of the Web Online Help System: show toolbars
 

Filters
Filter values by
  • Context settings
    • General context settings
    • String related settings
    • Font related settings
  • Result buffer settings
| Customize Help
| Save Settings

MstrControl


Function Map
Syntax
Description
Parameters
- ContextOrResultId
- Index
Table: For a String Reader context, specific font, specific string model, or result buffer
- ControlType
- ControlValue
Parameter Associations
Table: For the context or a specific string
Table: For the context
Table: For a specific string
Table: For a specific font
Table: For a font-based or a fontless context
Table: For the result buffer
Type specific versions of the function when using a C compiler under 64-bit
Compilation information
Synopsis
Control a String Reader context, result buffer, a specific string model, or a specific font.
Syntax
void MstrControl(
MIL_ID ContextOrResultId, //in
MIL_INT Index, //in
MIL_INT64 ControlType, //in
MIL_DOUBLE ControlValue //in
)
Description

This function sets the specified control for a String Reader context, for one (or all) of the specified string models or fonts contained therein, or a result buffer. These settings control the execution of MstrRead() operations. All the control type settings can be inquired using MstrInquire().

Changing certain control type settings might require preprocessing the String Reader context again, using MstrPreprocess(). To know if the String Reader context needs to be preprocessed, call MstrInquire() with M_PREPROCESSED.

Unless otherwise specified, the control type settings are applicable to both font-based and fontless contexts.

Note that when using a C compiler (not a C++ or other compiler) in 64-bit mode, MstrControl() internally calls the MIL_DOUBLE version of this function (MstrControlDouble()). If you need to pass integer values, call the MIL_INT64 version of this function (MstrControlInt64()).
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
ContextOrResultId

Specifies the String Reader context or result buffer whose settings to modify. The String Reader context must have been previously allocated on the system using MstrAlloc(). The String Reader result buffer must have been previously allocated on the system using MstrAllocResult().

Index

Specifies that the String Reader context, a specific font, a specific string model, or a result buffer is controlled. Set this parameter to one of the following values.

function map For a String Reader context, specific font, specific string model, or result buffer
Click to summarizeValue Description
Click to summarize M_DEFAULT

Specifies the default.

If a String Reader context is specified, same as M_CONTEXT.

If a String Reader result buffer is specified, same as M_GENERAL.

(summarize)
Click to summarize

Specifies to apply the control settings to a font.

Note that this value is only available for a font-based context.

(summarize)
Parameters

This parameter specifies the index of the font. You can set this parameter to one of the following:
M_ALL

Specifies to apply the control settings to all fonts.
Value >= 0

Specifies the index of the individual font to which to apply the control settings.

User labels cannot be used as indices; to retrieve the index of a font from its user label, use MstrInquire() with M_FONT_INDEX_FROM_LABEL.
Click to summarize

Specifies to apply the control settings to a string.

(summarize)
Parameters

This parameter specifies the index of the string. You can set this parameter to one of the following:
M_ALL

Specifies to apply the control settings to all strings.

Note that to apply control settings to all strings, the ControlType and ControlValue parameters must be supported by all the string models.
Value >= 0

Specifies the index of the individual string to which to apply the control settings.

User labels cannot be used as indices; to retrieve the index of a string from its user label, use MstrInquire() with M_STRING_INDEX_FROM_LABEL.
Click to summarize M_CONTEXT

Specifies that a general setting of a String Reader context will be controlled.
Click to summarize M_GENERAL

Specifies that a general setting of a String Reader result buffer will be controlled, if one is specified.
ControlType

Specifies the setting to change.

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

ControlValue

Specifies the setting's new value.

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

Parameter associations

The tables below list possible values for the ControlType and ControlValue parameters.

The following ControlType and corresponding ControlValue parameter settings can be specified for either the String Reader context (M_CONTEXT) or each specific string in the String Reader context (M_STRING_INDEX()).

function map For the context or a specific string
Click to summarize
ControlType		 Description
ControlValue
Click to summarize M_STRING_NUMBER

Sets either the maximum (total) number of all strings that can be read with a String Reader context (M_CONTEXT), or the maximum number of a specific string (M_STRING_INDEX()) that can be read with a String Reader context. INQ

(summarize)
Click to summarize M_DEFAULT

Specifies the default value; the default value is 1.
Click to summarize M_ALL

Specifies that all strings will be read.

Note that this setting can increase the read time; always set M_STRING_NUMBER to a specific number whenever possible.

(summarize)
Click to summarize Value

Specifies the maximum number of strings that can be read.

For M_CONTEXT, this value specifies the maximum (total) number of strings that can be read. Any value greater than or equal to 1 can be set.

For M_STRING_INDEX(), this value specifies the maximum number of a specific string model that can be read. Any value greater than or equal to 0 can be set.

(summarize)

The possible ControlType and corresponding ControlValue parameter settings for the String Reader context (M_CONTEXT) are:

function map For the context
Click to summarize
ControlType		 Description
ControlValue
Click to summarize M_DISABLE_CHAR

Disables the specified character in the fontless context. Only uppercase characters and numbers can be disabled.

The String Reader module will not try to match found characters with disabled characters.

Note that this control type is only available for a fontless context. INQ

(summarize)
Click to summarize M_ALL

Specifies that no characters will be read.
Click to summarize ASCII value

Specifies the ASCII value of the character to disable.
Click to summarize M_ENABLE_CHAR

Enables the specified character in the fontless context. Only uppercase characters and numbers can be enabled.

The String Reader module will only try to identify enabled characters.

Note that this control type is only available for a fontless context. INQ

(summarize)
Click to summarize M_ALL

Specifies that all characters will be read.

This is the default value.

(summarize)
Click to summarize ASCII value

Specifies the ASCII value of the character.
Click to summarize M_ENCODING

Sets the type of character encoding used by the String Reader context.

All functions that accept or return a string of characters as a parameter use character encoding to determine the type of the pointer. The type of character encoding is also used as the default result type (MstrGetResult()) for a string of characters.

The character encoding cannot be changed when there are characters in the context whose ASCII character values lie outside the range [0, 127]. This applies to characters which are in fonts and constraints. INQ

(summarize)
Click to summarize M_DEFAULT

Same as M_ASCII.
Click to summarize M_ASCII

Specifies an 8-bit ASCII standard. This corresponds to the char data type.

(summarize)
Click to summarize M_UNICODE

Specifies a 16-bit Unicode standard. This corresponds to the short data type.

(summarize)
Click to summarize M_FONT_ADD

Adds an empty font to the String Reader context. The maximum number of fonts in a String Reader context is 255.

Note that this control type is only available for a font-based context. INQ

(summarize)
Click to summarize M_DEFAULT

Same as M_USER_DEFINED.
Click to summarize M_USER_DEFINED

Specifies a user-defined type of font. Initially, the font is empty. To add characters to the font, or to edit it, use MstrEditFont().

(summarize)
Click to summarize M_FONT_DELETE

Deletes a font from the String Reader context.

Note that this control type is only available for a font-based context.

(summarize)
Click to summarize M_DEFAULT

Same as M_ALL.
Click to summarize M_ALL

Specifies that all fonts will be deleted.
Click to summarize Value >= 0

Specifies the index of the font to delete.
Click to summarize M_MAX_CHAR_SIZE_X

Sets the width (X-size) of the widest enabled character in the fontless context. Specify the width that the character has when it has a height of M_REF_CHAR_SIZE_Y.

If the read algorithm encounters a character with a height other than M_REF_CHAR_SIZE_Y, the maximum width will be interpolated.

Note that this control type is only available for a fontless context. INQ

(summarize)
Click to summarize M_DEFAULT

Specifies the default value; the default value is 65 pixels.
Click to summarize 0 <= Value <= 65536

Specifies the maximum character width, in pixels.
Click to summarize M_MIN_CHAR_SIZE_X

Sets the width (X-size) of the narrowest enabled character in the fontless context. Specify the width that the character has when it has a height of M_REF_CHAR_SIZE_Y.

If the read algorithm encounters a character with a height other than M_REF_CHAR_SIZE_Y, the maximum width will be interpolated.

Note that this control type is only available for a fontless context. INQ

(summarize)
Click to summarize M_DEFAULT

Specifies the default value; the default value is 6 pixels.
Click to summarize 0 <= Value <= 65536

Specifies the minimum character width, in pixels.
Click to summarize M_MINIMUM_CONTRAST

Sets the minimum contrast between a character in the target image and its background, in order for the character to be read by MstrRead().

Increasing the minimum contrast will typically speed up the read operation, particularly in presence of noise; however, if the minimum contrast is higher than the contrast of an actual character, that character will be lost. INQ

(summarize)
Click to summarize M_DEFAULT

Specifies the default value; the default value is 15.
Click to summarize 1 <= Value <= 255

Specifies the minimum contrast.
Click to summarize M_REF_CHAR_SIZE_Y

Sets the height which will be the reference for M_MIN_CHAR_SIZE_X, M_MAX_CHAR_SIZE_X, and M_REF_CHAR_THICKNESS.

The reference height is the height at which you specify the width of the narrowest and widest characters, as well as their thickness, with M_MIN_CHAR_SIZE_X, M_MAX_CHAR_SIZE_X, and M_REF_CHAR_THICKNESS, respectively.

Note that this control type is only available for a fontless context. INQ

(summarize)
Click to summarize M_DEFAULT

Specifies the default value; the default value is 46 pixels.
Click to summarize 0 <= Value <= 65536

Specifies the height, in pixels.
Click to summarize M_REF_CHAR_THICKNESS

Sets the thickness (stroke width) of enabled characters in the fontless context. Specify the thickness of characters when they have a height of M_REF_CHAR_SIZE_Y.

If the read algorithm encounters a character with a height other than M_REF_CHAR_SIZE_Y, the maximum width will be interpolated.

Note that this control type is only available for a fontless context. INQ

(summarize)
Click to summarize M_DEFAULT

Specifies the default value; the default value is 6 pixels.
Click to summarize 0 <= Value <= 65536

Specifies the thickness, in pixels.
Click to summarize M_SEARCH_CHAR_ANGLE

Sets whether to perform calculations specific to angular-range search strategies, for characters.

The read algorithm is naturally robust to variations in a character's angle. Therefore, a character might still be read correctly, even if M_SEARCH_CHAR_ANGLE is disabled. INQ

(summarize)
Click to summarize M_DEFAULT

Same as M_DISABLE.
Click to summarize M_DISABLE

Specifies not to perform calculations specific to angular-range search strategies.
Click to summarize M_ENABLE

Specifies to perform calculations specific to angular-range search strategies.
Click to summarize M_SEARCH_SKEW_ANGLE

Sets whether to perform calculations specific to angular-range skew search strategies, for characters.

The read algorithm is naturally robust to variations in a character's skew. Therefore, a character might still be read correctly, even if M_SEARCH_SKEW_ANGLE is disabled. INQ

(summarize)
Click to summarize M_DEFAULT

Same as M_DISABLE.
Click to summarize M_DISABLE

Specifies not to perform calculations specific to angular-range skew search strategies.
Click to summarize M_ENABLE

Specifies to perform calculations specific to angular-range skew search strategies.
Click to summarize M_SEARCH_STRING_ANGLE

Sets whether to search for the string angle. INQ

(summarize)
Click to summarize M_DEFAULT

Same as M_ENABLE.
Click to summarize M_DISABLE

Specifies not to search for the string angle.
Click to summarize M_ENABLE

Specifies to search for the string angle.
Click to summarize M_SPACE_CHARACTER

Sets the character value to use as a space character within the formatted string or text that will be read.

M_SPACE_CHARACTER applies only when getting the formatted string (MstrGetResult() with M_FORMATTED_STRING) or the formatted text (MstrGetResult() with M_TEXT). A space character is inserted in the string each time the distance between two adjacent characters exceeds the space width, at the scale of the string.

The space character must be set before the string is read. INQ

(summarize)
Click to summarize M_DEFAULT

Specifies the default value; the default value is numerical ASCII code 32.
Click to summarize M_NONE

Specifies no space character.
Click to summarize Value

Specifies the space character, as its numerical code (ASCII or Unicode). For example, ASCII 10 results in a new line character, ASCII 32 results in a space character. Note that the character value must be cast to a MIL_DOUBLE.

(summarize)
Click to summarize M_SPEED

Sets the search and read speed of the MstrRead() operation. Note that increasing the speed can decrease the robustness of MstrRead(). INQ

(summarize)
Click to summarize M_DEFAULT

Same as M_MEDIUM.
Click to summarize M_HIGH

Specifies a high speed.
Click to summarize M_MEDIUM

Specifies a medium speed.
Click to summarize M_STOP_EXPERT

Stops the current string expert operation.

Note that you can only perform this operation from another thread of higher priority.

(summarize)
Click to summarize M_DEFAULT

Implements the default behavior.
Click to summarize M_STOP_READ

Stops the current string read operation.

Note that you can only perform this operation from another thread of higher priority.

(summarize)
Click to summarize M_DEFAULT

Implements the default behavior.
Click to summarize M_STRING_ADD

Adds a string model to the String Reader context. The maximum number of string models in a String Reader context is 255. INQ

(summarize)
Click to summarize M_DEFAULT

Same as M_USER_DEFINED.
Click to summarize M_USER_DEFINED

Specifies a user-defined type of string model. Initially, a user-defined string model does not have any constraints, does not use any checksum error detection, and all its parameters are set to their default value.

(summarize)
Click to summarize M_STRING_DELETE

Deletes a string from the String Reader context.

(summarize)
Click to summarize M_DEFAULT

Same as M_ALL.
Click to summarize M_ALL

Specifies that all strings will be deleted.
Click to summarize Value >= 0

Specifies the index of the string to delete.
Click to summarize M_STRING_SEPARATOR

Sets the character value to use as a string separator within the formatted text that will be read.

M_STRING_SEPARATOR applies only when getting the formatted text (MstrGetResult() with M_TEXT). A string separator is inserted between each string in the text; that is, each time the distance between two adjacent characters is greater than the space size. The space size depends on the space width (at the scale of the string) and the maximum number of consecutive spaces.

The string separator character must be set before the string is read. INQ

(summarize)
Click to summarize M_DEFAULT

Specifies the default value; the default value is numerical ASCII code 10.
Click to summarize M_NONE

Specifies no separator character.
Click to summarize Value

Specifies the separator character, as its numerical code (ASCII or Unicode). For example, ASCII 10 results in a new line character, ASCII 32 results in a space character. Note that the character value must be cast to a MIL_DOUBLE.

(summarize)
Click to summarize 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. INQ

(summarize)
Click to summarize M_DEFAULT

Specifies the default value; the default value is 0.
Click to summarize 0 <= Value <= 100

Specifies the number of character thickening iterations.
Click to summarize M_THRESHOLD_MODE

Sets the threshold method of the character blob extraction. INQ

(summarize)
Click to summarize M_DEFAULT

Same as M_LOCAL_WITH_RESEGMENTATION.
Click to summarize M_LOCAL

Specifies local thresholding that uses only one threshold step that is automatically computed by the module. This threshold method can be used in various contrast situations and can improve the read operation's speed, compared to M_LOCAL_WITH_RESEGMENTATION.

(summarize)
Click to summarize M_LOCAL_WITH_RESEGMENTATION

Specifies local thresholding that uses multiple threshold steps and split and merge techniques. This threshold method allows the module to extract character blobs in low contrast and in complex situations such as merged or broken characters.

(summarize)
Click to summarize M_USER_DEFINED

Specifies global thresholding that uses the threshold value set with M_THRESHOLD_VALUE. This threshold method improves the read operation's speed, compared to M_LOCAL_WITH_RESEGMENTATION and M_LOCAL.

(summarize)
Click to summarize M_THRESHOLD_VALUE

Sets the global threshold value when M_THRESHOLD_MODE is set to M_USER_DEFINED (otherwise it is ignored). INQ

(summarize)
Click to summarize M_DEFAULT

Same as M_AUTO_COMPUTE.
Click to summarize M_AUTO_COMPUTE

Specifies to automatically compute the global threshold value.
Click to summarize 0 <= Value <= 255

Specifies the threshold value.
Click to summarize M_TIMEOUT

Sets the maximum read time for MstrRead(), in msec. If the read operation times out, the strings read up to that point will be returned as a result.

Note that the actual maximum read time might vary slightly from the time that you set. INQ

(summarize)
Click to summarize M_DEFAULT

Specifies the default value; the default value is 2000.0 msec.
Click to summarize M_DISABLE

Specifies an infinite amount of read time.
Click to summarize Value >= 0

Specifies the maximum read time, in msec.

The possible ControlType and corresponding ControlValue parameter settings for a specific string (M_STRING_INDEX()) are:

function map For a specific string
Click to summarize
ControlType		 Description
ControlValue
Click to summarize M_CHAR_ACCEPTANCE

Sets the acceptance level for the character score.

The character's score quantifies the similarity between the character in the target and the character in the font; it also quantifies the similarity between the character in the target and the other characters of the string in the target.

To be accepted as a string result, the character's score must be greater than or equal to M_CHAR_ACCEPTANCE.

Scores can be retrieved with MstrGetResult(). INQ

(summarize)
Click to summarize M_DEFAULT

Specifies the default value; the default value is 50.0%.
Click to summarize 0.0 <= Value <= 100.0

Specifies an acceptable score, as a percentage.
Click to summarize M_CHAR_ASPECT_RATIO_MAX_FACTOR

Sets the factor used to determine the maximum acceptable aspect ratio for the characters in the string. This value is relative to the found string aspect ratio. That is, UpperLimit = FoundStringAspectRatio x M_CHAR_ASPECT_RATIO_MAX_FACTOR.

This value sets the maximum possible aspect ratio variation for the characters in the string. Characters with an aspect ratio outside the aspect ratio range will not be returned as results.

Note that this control type is only available for a font-based context. INQ

(summarize)
Click to summarize M_DEFAULT

Specifies the default value; the default value is 1.1.
Click to summarize 1.0 <= Value <= 2.0

Specifies the factor that determines the maximum aspect ratio of the characters in the string.
Click to summarize M_CHAR_ASPECT_RATIO_MIN_FACTOR

Sets the factor used to determine the minimum acceptable aspect ratio for the characters in the string. This value is relative to the found string aspect ratio. That is, LowerLimit = FoundStringAspectRatio x M_CHAR_ASPECT_RATIO_MIN_FACTOR.

This value sets the minimum possible aspect ratio variation for the characters in the string. Characters with an aspect ratio outside the aspect ratio range will not be returned as results.

Note that this control type is only available for a font-based context. INQ

(summarize)
Click to summarize M_DEFAULT

Specifies the default value; the default value is 0.9.
Click to summarize 0.5 <= Value <= 1.0

Specifies the factor that determines the minimum aspect ratio of the characters in the string.
Click to summarize M_CHAR_HOMOGENEITY_ACCEPTANCE

Sets the acceptance level for the character's homogeneity score.

The character's homogeneity score quantifies the similarity between the character in the target and the other characters of the string in the target.

To be accepted as a string result, the character's homogeneity score must be greater than or equal to M_CHAR_HOMOGENEITY_ACCEPTANCE.

Scores can be retrieved with MstrGetResult(). INQ

(summarize)
Click to summarize M_DEFAULT

Specifies the default value; the default value is 50.0%.
Click to summarize 0.0 <= Value <= 100.0

Specifies an acceptable score, as a percentage.
Click to summarize M_CHAR_MAX_BASELINE_DEVIATION

Sets the maximum baseline deviation that all characters defined in the font can have in the target image.

A character's maximum baseline deviation is the maximum tolerable baseline deviation that a character in a string can have before it is rejected from the string. For more information on character baseline deviations, see the Character's maximum baseline deviation subsection of the Degrees of freedom section of Chapter 12: String Reader.

Note that for non-punctuation characters, String Reader calculates the baseline deviation, as a percentage of each individual character's height (Y-size). For example, a baseline deviation of 10 means that a character's baseline deviates from the string's baseline by 10% of the character's height (Y-size). For punctuation characters (M_PUNCTUATION), String Reader calculates the baseline deviation as a percentage of the height of the character with the greatest Y-size in the font. For example, a baseline deviation of 10 means that the punctuation character's baseline deviates from the string's baseline by 10% of the height of the tallest character in the font. This is done because the Y-size of punctuation characters is typically too small to calculate the baseline deviation as a percentage of the character's height. INQ

(summarize)
Click to summarize M_DEFAULT

Specifies the default value; the default value is 10.
Click to summarize 0 <= Value <= 100

Specifies the character's maximum baseline deviation within the string model.
Click to summarize M_CHAR_SCALE_MAX_FACTOR

Sets the factor used to determine the upper limit (maximum permitted scale) of the scale range for the characters in the string. This value is relative to the found string scale. That is, UpperLimit = FoundStringScale x M_CHAR_SCALE_MAX_FACTOR.

This value sets the possible increasing scale variation for the characters in the string. Characters with a scale outside the scale range will not be returned as results. INQ

(summarize)
Click to summarize M_DEFAULT

Specifies the default value; the default value is 1.1.
Click to summarize 1.0 <= Value <= 2.0

Specifies the factor that determines the maximum scale of the characters in the string.
Click to summarize M_CHAR_SCALE_MIN_FACTOR

Sets the factor used to determine the lower limit (minimum permitted scale) of the scale range for the characters in the string. This value is relative to the found string scale. That is, LowerLimit = FoundStringScale x M_CHAR_SCALE_MIN_FACTOR.

This value sets the possible decreasing scale variation for the characters in the string. Characters with a scale outside the scale range will not be returned as results. INQ

(summarize)
Click to summarize M_DEFAULT

Specifies the default value; the default value is 0.9.
Click to summarize 0.5 <= Value <= 1.0

Specifies the factor that determines the minimum scale of the characters in the string.
Click to summarize M_CHAR_SIMILARITY_ACCEPTANCE

Sets the acceptance level for the character's similarity score.

The character's similarity score quantifies the similarity between the character in the target and the character in the font.

To be accepted as a string result, the character's similarity score must be greater than or equal to M_CHAR_SIMILARITY_ACCEPTANCE.

Scores can be retrieved with MstrGetResult(). INQ

(summarize)
Click to summarize M_DEFAULT

Specifies the default value; the default value is 50.0%.
Click to summarize 0.0 <= Value <= 100.0

Specifies an acceptable score, as a percentage.
Click to summarize M_FOREGROUND_VALUE

Sets the foreground color of the string. INQ

(summarize)
Click to summarize M_DEFAULT

Same as M_FOREGROUND_BLACK.
Click to summarize M_FOREGROUND_BLACK

Specifies that black is the foreground color of the string.
Click to summarize M_FOREGROUND_BLACK_OR_WHITE

Specifies that the foreground color of the string can be either black or white.
Click to summarize M_FOREGROUND_WHITE

Specifies that white is the foreground color of the string.
Click to summarize M_SPACE_MAX_CONSECUTIVE

Sets the maximum number of consecutive space characters allowed in the string.

Together with the space width (MstrControl() with M_SPACE_WIDTH), M_SPACE_MAX_CONSECUTIVE determines the maximum distance between 2 adjacent characters of the same string. If the distance between two characters is greater than the maximum distance, then they are considered to be part of 2 different strings. INQ

(summarize)
Click to summarize M_DEFAULT

Specifies the default value; the default value is 3.
Click to summarize Value >= 0

Specifies the maximum number of consecutive space characters.
Click to summarize M_STRING_ACCEPTANCE

Sets the acceptance level for the string score.

To be accepted as a string result, both the string's score and the string target score must be greater than or equal to their respective acceptance levels.

The string score is the average score of the characters in the string.

Scores can be retrieved with MstrGetResult(). INQ

(summarize)
Click to summarize M_DEFAULT

Specifies the default value; the default value is 50.0%.
Click to summarize 0.0 <= Value <= 100.0

Specifies an acceptable score, as a percentage.
Click to summarize M_STRING_ANGLE

Sets the nominal angle of the string. INQ

(summarize)
Click to summarize M_DEFAULT

Same as M_ACCORDING_TO_REGION.
Click to summarize M_ACCORDING_TO_REGION

Specifies to set the nominal angle to the angle of the rectangular ROI (set using MbufSetRegion()) in the image.

If no region of interest has been defined, the default value is 0.0°. This implies that to read a string at an angle, the target image must have a rectangular ROI defined around the string to be read, and that ROI should be at an angle.

(summarize)
Click to summarize M_STRING_ANGLE_DELTA_NEG

Sets the lower limit of the string's angular range, relative to the nominal angle (MstrControl() with M_STRING_ANGLE). That is, LowerLimit = M_STRING_ANGLE - M_STRING_ANGLE_DELTA_NEG.

This value sets the possible clockwise angular variation of the string. Strings with angles outside the angular range will not be returned as results. INQ

(summarize)
Click to summarize M_DEFAULT

Specifies the default value; the default value is 10.0°.
Click to summarize 0.0 <= Value <= 10.0

Specifies the lower limit of the angular range, in degrees.
Click to summarize M_STRING_ANGLE_DELTA_POS

Sets the upper limit of the angular range, relative to the nominal angle (MstrControl() with M_STRING_ANGLE). That is, UpperLimit = M_STRING_ANGLE + M_STRING_ANGLE_DELTA_POS.

This value sets the possible counter-clockwise angular variation of the string. Strings with angles outside the angular range will not be returned as results. INQ

(summarize)
Click to summarize M_DEFAULT

Specifies the default value; the default value is 10.0°.
Click to summarize 0.0 <= Value <= 10.0

Specifies the upper limit of the angular range, in degrees.
Click to summarize M_STRING_ASPECT_RATIO

Sets the nominal aspect ratio of the string.

The aspect ratio of the string is the median aspect ratio of all the characters in the string, while the aspect ratio of a character is the ratio of its scale in X by its scale in Y. This indicates how the width and the height of the characters in the string vary relative to the characters in the font.

Note that this control type is only available for a font-based context. INQ

(summarize)
Click to summarize M_DEFAULT

Specifies the default value; the default value is 1.0.
Click to summarize 0.5 <= Value <= 2.0

Specifies the ratio of pixel width to pixel height of the target.
Click to summarize M_STRING_ASPECT_RATIO_MAX_FACTOR

Sets the factor used to determine the upper limit of the string's aspect ratio. This value is relative to the nominal aspect ratio (MstrControl() with M_STRING_ASPECT_RATIO). That is, UpperLimit = M_STRING_ASPECT_RATIO x M_STRING_ASPECT_RATIO_MAX_FACTOR.

This value sets the possible increasing aspect ratio variation for the string. Strings with an aspect ratio outside the aspect ratio range will not be returned as results.

Note that this control type is only available for a font-based context. INQ

(summarize)
Click to summarize M_DEFAULT

Specifies the default value; the default value is 1.25.
Click to summarize 1.0 <= Value <= 2.0

Specifies the factor that determines the maximum aspect ratio of the string.
Click to summarize M_STRING_ASPECT_RATIO_MIN_FACTOR

Sets the factor used to determine the lower limit of the string's aspect ratio. This value is relative to the nominal aspect ratio (MstrControl() with M_STRING_ASPECT_RATIO). That is, LowerLimit = M_STRING_ASPECT_RATIO x M_STRING_ASPECT_RATIO_MIN_FACTOR.

This value sets the possible decreasing aspect ratio variation for the string. Strings with an aspect ratio outside the aspect ratio range will not be returned as results.

Note that this control type is only available for a font-based context. INQ

(summarize)
Click to summarize M_DEFAULT

Specifies the default value; the default value is 0.8.
Click to summarize 0.5 <= Value <= 1.0

Specifies the factor that determines the minimum aspect ratio of the string.
Click to summarize M_STRING_CERTAINTY

Sets the certainty level for the string score.

If both the string score and the string target score of a string candidate are above their respective certainty levels, the candidate is immediately considered a string result, without reading the rest of the target image for a string with higher scores (provided the specified number of strings to read has been read).

Scores can be retrieved with MstrGetResult(). INQ

(summarize)
Click to summarize M_DEFAULT

Specifies the default value; the default value is 70.0%.
Click to summarize 0.0 <= Value <= 100.0

Specifies the certainty level for the string score, as a percentage.
Click to summarize M_STRING_SCALE

Sets the nominal scale of the string.

The scale of the string is the median scale in the X-direction of all the characters in the string. INQ

(summarize)
Click to summarize M_DEFAULT

Specifies the default value; the default value is 1.0.
Click to summarize 0.25 <= Value <= 4.0

Specifies the value of the scale.
Click to summarize M_STRING_SCALE_MAX_FACTOR

Sets the factor used to determine the upper limit (maximum permitted scale) of the string's scale range. This value is relative to the nominal scale (MstrControl() with M_STRING_SCALE). That is, UpperLimit = M_STRING_SCALE x M_STRING_SCALE_MAX_FACTOR.

This value sets the possible increasing scale variation for the string. Strings with a scale outside the scale range will not be returned as results. INQ

(summarize)
Click to summarize M_DEFAULT

Specifies the default value; the default value is 2.0.
Click to summarize 1.0 <= Value <= 2.0

Specifies the factor that determines the minimum scale of the string.
Click to summarize M_STRING_SCALE_MIN_FACTOR

Sets the factor used to determine the lower limit (minimum permitted scale) of the string's scale range. This value is relative to the nominal scale (MstrControl() with M_STRING_SCALE). That is, LowerLimit = M_STRING_SCALE x M_STRING_SCALE_MIN_FACTOR.

This value sets the possible decreasing scale variation for the string. Strings with a scale outside the scale range will not be returned as results. INQ

(summarize)
Click to summarize M_DEFAULT

Specifies the default value; the default value is 0.5.
Click to summarize 0.5 <= Value <= 1.0

Specifies the factor that determines the minimum scale of the string.
Click to summarize M_STRING_SIZE_MAX

Sets the maximum string size (number of characters) of the string model.

The space characters are not counted in the string size. The maximum string size must be greater than or equal to the minimum string size (MstrControl() with M_STRING_SIZE_MIN). INQ

(summarize)
Click to summarize M_DEFAULT

Same as M_INFINITE.
Click to summarize M_INFINITE

Specifies no maximum string size.
Click to summarize Value >= 1

Specifies the maximum string size.
Click to summarize M_STRING_SIZE_MIN

Sets the minimum string size (number of characters) of the string model.

The space characters are not counted in the string size. The minimum string size must be lower than or equal to the maximum string size (MstrControl() with M_STRING_SIZE_MAX). INQ

(summarize)
Click to summarize M_DEFAULT

Specifies the default value; the default value is 1.
Click to summarize Value >= 1

Specifies the minimum string size.
Click to summarize M_STRING_TARGET_ACCEPTANCE

Sets the acceptance level for the string target score.

To be accepted as a string result, both the string's score and the string target score must be greater than or equal to their respective acceptance levels.

The string target score is computed from the unread characters that are in the region of the string in the target image. These otherwise readable characters remain unread due to user-specified constraints, such as scale and grammar restrictions. The more unread characters there are, the lower the target score will be.

Scores can be retrieved with MstrGetResult(). INQ

(summarize)
Click to summarize M_DEFAULT

Specifies the default value; the default value is 50.0%.
Click to summarize 0.0 <= Value <= 100.0

Specifies an acceptable string target score, as a percentage.
Click to summarize M_STRING_TARGET_CERTAINTY

Sets the certainty level for the string target score.

If both the string score and the string target score of a string candidate are above their respective certainty levels, the candidate is immediately considered a string result, without reading the rest of the target image for a string with higher scores (provided the specified number of strings to read has been read).

Scores can be retrieved with MstrGetResult(). INQ

(summarize)
Click to summarize M_DEFAULT

Specifies the default value; the default value is 70.0%.
Click to summarize 0.0 <= Value <= 100.0

Specifies the certainty level for the string target score, as a percentage.
Click to summarize M_STRING_USER_LABEL

Sets a unique user-defined label for the specified string model. This label can be used as a means of identifying your string model, independently from its index, in the String Reader context. INQ

(summarize)
Click to summarize M_DEFAULT

Same as M_NO_LABEL.
Click to summarize M_NO_LABEL

Specifies that no user label is associated with the string model.
Click to summarize Value

Specifies the user label of the string model. The value must be an integer that is not associated as a label with any other string model in the String Reader context. Since the same label cannot be associated with multiple string models, you cannot pass a user label if you use MstrControl() with M_STRING_INDEX() set to M_ALL.

(summarize)

The possible ControlType and corresponding ControlValue parameter settings for a specific font (M_FONT_INDEX()) are:

function map For a specific font
Click to summarize
ControlType		 Description
ControlValue
Click to summarize M_DRAW_BOX_MARGIN_X

Sets the margin in the X-direction, between the character box and the drawing box.

The character box is the bounding box of the character. The drawing box is the box used for drawing purposes. For more information, see MstrDraw(). INQ

(summarize)
Click to summarize M_DEFAULT

Specifies the default value; the default value is 3.
Click to summarize Value >= 0

Specifies the horizontal margin, in pixels.
Click to summarize M_DRAW_BOX_MARGIN_Y

Sets the margin in the Y-direction, between the character box and the drawing box.

The character box is the bounding box of the character. The drawing box is the box used for drawing purposes. For more information, see MstrDraw(). INQ

(summarize)
Click to summarize M_DEFAULT

Specifies the default value; the default value is 3.
Click to summarize Value >= 0

Specifies the vertical margin, in pixels.
Click to summarize M_FONT_USER_LABEL

Sets a unique user-defined label for the specified font. This label can be used as a means of identifying your font, independently from its index, in the String Reader context. INQ

(summarize)
Click to summarize M_DEFAULT

Same as M_NO_LABEL.
Click to summarize M_NO_LABEL

Specifies that no user label is associated with the font.
Click to summarize Value

Specifies the user label of the font. The value must be an integer that is not associated as a label with any other font in the String Reader context. Since the same label cannot be associated with multiple fonts, you cannot pass a user label if you use MstrControl() with M_FONT_INDEX() set to M_ALL.

(summarize)

The following ControlType and corresponding ControlValue parameter settings can be specified for either a font-based context or for a fontless context.

Note that the Index parameter must be set to M_FONT_INDEX() for a font-based context or to M_CONTEXT for a fontless context.

function map For a font-based or a fontless context
Click to summarize
ControlType		 Description
ControlValue
Click to summarize M_SPACE_WIDTH

Sets the width of the space character of the font.

Note that the space character is not like other characters in the font. For example, you cannot set it as a constraint (MstrSetConstraint()), and it is not counted in the string size (MstrControl() with M_STRING_SIZE_MIN and M_STRING_SIZE_MAX). For more information, see MstrGetResult() with M_STRING_SIZE, M_STRING, and M_FORMATTED_STRING.

Together with the maximum number of consecutive space characters allowed in the string (MstrControl() with M_SPACE_MAX_CONSECUTIVE), M_SPACE_WIDTH determines the maximum distance between 2 adjacent characters of the same string. If the distance between two characters is greater than the maximum distance, then they are considered to be part of 2 different strings. M_SPACE_WIDTH also determines how to convert the distance into space characters, when getting formatted string results (MstrGetResult() with M_FORMATTED_STRING). INQ

(summarize)
Click to summarize M_DEFAULT

Same as M_MEAN_CHAR_WIDTH.
Click to summarize M_INFINITE

Specifies that the width of the space character is infinite.

In this case, all characters on the same line are always part of the same string. Also, there will never be a space character in the read string since the distance can never be large enough to constitute a space character.

(summarize)
Click to summarize M_MAX_CHAR_WIDTH

Specifies that the width of the space character is equal to the maximum character X-size of the font.
Click to summarize M_MEAN_CHAR_WIDTH

Specifies that the width of the space character is equal to the average character X-size of the font.
Click to summarize M_MIN_CHAR_WIDTH

Specifies that the width of the space character is equal to the minimum character X-size of the font.
Click to summarize M_QUARTER_MAX_CHAR_WIDTH

Specifies that the width of the space character is equal to a quarter of the maximum character width of the font.

M_QUARTER_MAX_CHAR_WIDTH is the closest to the typical space width of a standard font.

(summarize)
Click to summarize Value >= 1

Specifies the width of the space character, in pixels.

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

Note that the Index parameter must be set to M_GENERAL.

function map For the result buffer
Click to summarize
ControlType		 Description
ControlValue
Click to summarize 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)
Click to summarize M_DEFAULT

Same as M_ACCORDING_TO_CALIBRATION.
Click to summarize M_ACCORDING_TO_CALIBRATION

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

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

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

(summarize)
Type specific versions of the function when using a C compiler under 64-bit
void MstrControlInt64 (MIL_ID ContextOrResultId, MIL_INT Index, MIL_INT64 ControlType, MIL_INT64 ControlValue)
Details
Parameters

ContextOrResultId

See ContextOrResultId of the main function for a description.

Index

See Index 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.
void MstrControlDouble (MIL_ID ContextOrResultId, MIL_INT Index, MIL_INT64 ControlType, MIL_DOUBLE ControlValue)
Details
Parameters

ContextOrResultId

See ContextOrResultId of the main function for a description.

Index

See Index 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; milstr.lib.
DLL Requires mil.dll; milstr.dll.
DEFAULT ALL ALL CONTEXT GENERAL STRING NUMBER DEFAULT ALL DISABLE CHAR ALL ENABLE CHAR ALL ENCODING DEFAULT ASCII UNICODE FONT ADD DEFAULT USER DEFINED FONT DELETE DEFAULT ALL MAX CHAR SIZE X DEFAULT MIN CHAR SIZE X DEFAULT MINIMUM CONTRAST DEFAULT REF CHAR SIZE Y DEFAULT REF CHAR THICKNESS DEFAULT SEARCH CHAR ANGLE DEFAULT DISABLE ENABLE SEARCH SKEW ANGLE DEFAULT DISABLE ENABLE SEARCH STRING ANGLE DEFAULT DISABLE ENABLE SPACE CHARACTER DEFAULT NONE SPEED DEFAULT HIGH MEDIUM STOP EXPERT DEFAULT STOP READ DEFAULT STRING ADD DEFAULT USER DEFINED STRING DELETE DEFAULT ALL STRING SEPARATOR DEFAULT NONE THICKEN CHAR DEFAULT THRESHOLD MODE DEFAULT LOCAL LOCAL WITH RESEGMENTATION USER DEFINED THRESHOLD VALUE DEFAULT AUTO COMPUTE TIMEOUT DEFAULT DISABLE CHAR ACCEPTANCE DEFAULT CHAR ASPECT RATIO MAX FACTOR DEFAULT CHAR ASPECT RATIO MIN FACTOR DEFAULT CHAR HOMOGENEITY ACCEPTANCE DEFAULT CHAR MAX BASELINE DEVIATION DEFAULT CHAR SCALE MAX FACTOR DEFAULT CHAR SCALE MIN FACTOR DEFAULT CHAR SIMILARITY ACCEPTANCE DEFAULT FOREGROUND VALUE DEFAULT FOREGROUND BLACK FOREGROUND BLACK OR WHITE FOREGROUND WHITE SPACE MAX CONSECUTIVE DEFAULT STRING ACCEPTANCE DEFAULT STRING ANGLE DEFAULT ACCORDING TO REGION STRING ANGLE DELTA NEG DEFAULT STRING ANGLE DELTA POS DEFAULT STRING ASPECT RATIO DEFAULT STRING ASPECT RATIO MAX FACTOR DEFAULT STRING ASPECT RATIO MIN FACTOR DEFAULT STRING CERTAINTY DEFAULT STRING SCALE DEFAULT STRING SCALE MAX FACTOR DEFAULT STRING SCALE MIN FACTOR DEFAULT STRING SIZE MAX DEFAULT INFINITE STRING SIZE MIN DEFAULT STRING TARGET ACCEPTANCE DEFAULT STRING TARGET CERTAINTY DEFAULT STRING USER LABEL DEFAULT NO LABEL DRAW BOX MARGIN X DEFAULT DRAW BOX MARGIN Y DEFAULT FONT USER LABEL DEFAULT NO LABEL SPACE WIDTH DEFAULT INFINITE MAX CHAR WIDTH MEAN CHAR WIDTH MIN CHAR WIDTH QUARTER MAX CHAR WIDTH RESULT OUTPUT UNITS DEFAULT ACCORDING TO CALIBRATION PIXEL WORLD DEFAULT GENERAL DEFAULT CONTEXT GENERAL