Filters
Filter values by
  • Context controls
  • Result buffer controls
| Customize Help
| Save Settings

MdmrControl


Function Map
Syntax
Description
Parameters
- ContextOrResultDmrId
- ControlType
- ControlValue
Parameter Associations
Table: For controlling a SureDotOCR context setting
Table: For adding fonts or string models to, or deleting fonts or string models from, a SureDotOCR context
Table: For controlling a SureDotOCR result buffer
Type-specific versions of the function when using a C compiler under 64-bit
Compilation information
Synopsis
Control a SureDotOCR context or result buffer.
Syntax
void MdmrControl(
MIL_ID ContextOrResultDmrId, //in
MIL_INT64 ControlType, //in
MIL_DOUBLE ControlValue //in
)
Description

This function allows you to control a SureDotOCR context or a SureDotOCR result buffer. This includes adding or deleting a font or string model from a context, or removing all results from a result buffer. To inquire about a context, call MdmrInquire(). To get results from a result buffer, call MdmrGetResult().

To control the fonts and string models held by a SureDotOCR context, call MdmrControlFont() and MdmrControlStringModel(), respectively.

For a successful read operation, you must specify an explicit value for the control types that set the diameter of the dots in the string's characters (M_DOT_DIAMETER) and the dimensions of the rectangular region in which to read strings (M_STRING_BOX_HEIGHT and M_STRING_BOX_WIDTH).

You must preprocess the SureDotOCR context after you have finished adjusting context settings and before calling MdmrRead(). To know if a context needs to be preprocessed, call MdmrInquire() with M_PREPROCESSED.

Note that when using a C compiler (not a C++ or other compiler) in 64-bit mode, MdmrControl() internally calls the MIL_DOUBLE version of this function (MdmrControlDouble()). If you need to pass integer values, call the MIL_INT64 version of this function (MdmrControlInt64()).
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 which MIL system’s documentation you should use in its place and any possible differences.
Parameters
This function is not supported on the selected boards.
This function reference has not been updated for the selected MIL system. To show the content of this page, choose a second MIL system; refer to the MIL system's release note to see which MIL system’s documentation to choose and any possible differences.
Parameters
ContextOrResultDmrId

Specifies the identifier of the SureDotOCR context or result buffer to control. The context must have been previously allocated on the system using MdmrAlloc(). The result buffer must have been previously allocated on the system using MdmrAllocResult().

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.

Parameter associations

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

The following ControlType and corresponding ControlValue parameter settings are used to control a setting of the SureDotOCR context specified with the ContextOrResultDmrId parameter. SureDotOCR can only read strings that adhere to these settings (they apply to all strings in the context). If there are strings that require different settings, use a separate context.

function map For controlling a SureDotOCR context setting
Click to summarize
ControlType		 Description
ControlValue
Click to summarize M_DOT_DIAMETER

Sets the diameter of the dots that make up the characters in the strings. INQ

(summarize)
Click to summarize Value > 0.0

Specifies the diameter, in pixels.
Click to summarize M_FOREGROUND_VALUE

Sets the foreground value of the characters in the strings. INQ

(summarize)
Click to summarize M_DEFAULT

Same as M_FOREGROUND_BLACK.
Click to summarize M_FOREGROUND_BLACK

Specifies that strings with characters darker than the background will be read. For example, black characters on a white surface.

(summarize)
Click to summarize M_FOREGROUND_WHITE

Specifies that strings with characters lighter than the background will be read. For example, white characters on a black surface.

(summarize)
Click to summarize M_ITALIC_ANGLE

Sets the italic angle of all the characters in the strings. The angle must be provided counter clockwise and is relative a line perpendicular to the angle of the string. M_ITALIC_ANGLE only has an effect if M_ITALIC_ANGLE_MODE is set to M_ANGLE. INQ

(summarize)
Click to summarize M_DEFAULT

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

Specifies the italic angle, in degrees. A positive angle means that the characters are leaning counter-clockwise (left leaning); a negative angle means that the characters are leaning clockwise (right leaning).

(summarize)
Click to summarize M_ITALIC_ANGLE_MODE

Sets whether the italic angle is detected automatically or explicitly specified. M_ITALIC_ANGLE_MODE must be set to M_DEFAULT if M_STRING_ANGLE_MODE is set to M_DEFAULT; otherwise, MdmrPreprocess() will generate an error when called. INQ

(summarize)
Click to summarize M_DEFAULT

Specifies the default value; the default value is M_AUTO.
Click to summarize M_ANGLE

Specifies to use the italic angle specified with M_ITALIC_ANGLE. A string will only be read if its characters have the specified italic angle.

(summarize)
Click to summarize M_AUTO

Specifies that the italic angle is detected automatically. M_ITALIC_ANGLE is ignored.

(summarize)
Click to summarize M_ITALIC_PITCH

Sets the distance between successive dot centers in the italic angle direction. M_ITALIC_PITCH only has an effect if M_ITALIC_PITCH_MODE is set to M_USER_DEFINED. INQ

(summarize)
Click to summarize M_DEFAULT

Specifies the default value; the default value is 3.0 pixels.
Click to summarize Value > 0.0

Specifies the pitch, in pixels.
Click to summarize M_ITALIC_PITCH_MODE

Sets whether the distance between successive dot centers, in the italic angle direction, is detected automatically or explicitly specified. INQ

(summarize)
Click to summarize M_DEFAULT

Specifies the default value; the default value is M_AUTO.
Click to summarize M_AUTO

Specifies to automatically establish the distance between dot centers in the italic angle direction.
Click to summarize M_USER_DEFINED

Specifies to use the value set with M_ITALIC_PITCH. A string will only be read if its characters have the specified italic pitch.

(summarize)
Click to summarize M_MAX_INTENSITY

Sets the maximum pixel intensity of a character's dots. M_MAX_INTENSITY only has an effect if M_MAX_INTENSITY_MODE is set to M_USER_DEFINED. INQ

(summarize)
Click to summarize M_DEFAULT

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

Specifies the maximum pixel intensity.
Click to summarize M_MAX_INTENSITY_MODE

Sets how to establish the maximum pixel intensity of a character's dots. For a dot to be part of a character, its pixel intensity must be less than or equal to the maximum intensity. INQ

(summarize)
Click to summarize M_DEFAULT

Same as M_AUTO.
Click to summarize M_AUTO

Specifies to automatically establish the maximum pixel intensity of a character's dots. By default, SureDotOCR considers dots with any pixel intensity less than or equal to 255.0.

(summarize)
Click to summarize M_USER_DEFINED

Specifies to use the maximum pixel intensity value set with M_MAX_INTENSITY.
Click to summarize M_MIN_CONTRAST

Sets the minimum contrast between a character and its background. M_MIN_CONTRAST only has an effect if M_MIN_CONTRAST_MODE is set to M_USER_DEFINED. INQ

(summarize)
Click to summarize M_DEFAULT

Specifies the default value; the default value is 15.0.
Click to summarize 0.0 <= Value <= 255.0

Specifies the minimum contrast.
Click to summarize M_MIN_CONTRAST_MODE

Sets how to establish the minimum contrast (difference in pixel intensity) between a character (foreground) and its background. For a character to be read, its contrast must be greater than or equal to the minimum contrast. INQ

(summarize)
Click to summarize M_DEFAULT

Same as M_AUTO.
Click to summarize M_AUTO

Specifies to automatically establish the minimum contrast of characters. By default, SureDotOCR will not read characters with a contrast less than 15.0.

(summarize)
Click to summarize M_USER_DEFINED

Specifies to use the minimum contrast value set with M_MIN_CONTRAST.
Click to summarize M_MIN_INTENSITY

Sets the minimum pixel intensity of a character's dots. M_MIN_INTENSITY only has an effect if M_MIN_INTENSITY_MODE is set to M_USER_DEFINED. INQ

(summarize)
Click to summarize M_DEFAULT

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

Specifies the minimum pixel intensity.
Click to summarize M_MIN_INTENSITY_MODE

Sets how to establish the minimum pixel intensity of a character's dots. For a dot to be part of a character, its intensity must be greater than or equal to the minimum intensity. INQ

(summarize)
Click to summarize M_DEFAULT

Same as M_AUTO.
Click to summarize M_AUTO

Specifies to automatically establish the minimum pixel intensity of character dots. By default, SureDotOCR considers dots with any pixel intensity greater than or equal to 0.0.

(summarize)
Click to summarize M_USER_DEFINED

Specifies to use the minimum pixel intensity value set with M_MIN_INTENSITY.
Click to summarize M_SPACE_SIZE_MAX

Sets the value with which to determine the maximum distance between two characters in a string. This value is interpreted according to M_SPACE_SIZE_MAX_MODE. INQ

(summarize)
Click to summarize M_DEFAULT

Specifies the default value; the default value is 3.0.
Click to summarize Value > 0.0

Specifies the maximum distance value.
Click to summarize M_SPACE_SIZE_MAX_MODE

Sets how to determine the maximum distance between two characters in a string. If the actual distance between two characters is greater than the maximum distance, the read operation considers them part of separate strings. M_SPACE_SIZE_MAX_MODE indicates how to interpret M_SPACE_SIZE_MAX. INQ

(summarize)
Click to summarize M_DEFAULT

Same as M_CHAR_WIDTH_FACTOR.
Click to summarize M_CHAR_WIDTH_FACTOR

Specifies that the maximum distance between two characters in a string is determined by multiplying the M_SPACE_SIZE_MAX value by the string's maximum character width, in pixels. For example, if M_SPACE_SIZE_MAX is set to 3 (M_DEFAULT), the maximum distance between two characters in a string is equivalent to three times the string's maximum character width.

(summarize)
Click to summarize M_DISABLE

Specifies no maximum space size. This is equivalent to allowing an infinite amount of maximum space. In this case, no amount of space between aligned characters can cause them to be part of separate strings. This does not apply to characters on separate lines or severely misaligned characters.

(summarize)
Click to summarize M_SPACE_SIZE_MIN

Sets the value with which to determine the minimum distance between two characters in a string. This value is interpreted according to M_SPACE_SIZE_MIN_MODE. INQ

(summarize)
Click to summarize M_DEFAULT

Specifies the default value; the default value is 1.0.
Click to summarize Value > 0.0

Specifies the minimum distance value.
Click to summarize M_SPACE_SIZE_MIN_MODE

Sets how to determine the minimum distance between two characters in a string. If the actual distance between two characters is less than the specified value, SureDotOCR does not consider there to be a space. M_SPACE_SIZE_MIN_MODE indicates how to interpret M_SPACE_SIZE_MIN. INQ

(summarize)
Click to summarize M_DEFAULT

Same as M_CHAR_WIDTH_FACTOR.
Click to summarize M_CHAR_WIDTH_FACTOR

Specifies that the minimum distance between two characters in a string is determined by multiplying the M_SPACE_SIZE_MIN value by the string's maximum character width, in pixels. For example, if M_SPACE_SIZE_MIN is set to 1 (M_DEFAULT), the minimum distance between two characters in a string is equivalent to the string's maximum character width.

(summarize)
Click to summarize M_DISABLE

Specifies no minimum space size. This is equivalent to allowing an infinite amount of minimum space. In this case, no amount of space between characters in a string can cause SureDotOCR to recognize an actual space.

(summarize)
Click to summarize M_STRING_ANGLE

Sets at which angle to read a string, with respect to the coordinate system specified with M_STRING_ANGLE_INPUT_UNITS. INQ

(summarize)
Click to summarize M_DEFAULT

Specifies the default value; the default value is 0.
Click to summarize M_ACCORDING_TO_REGION

Specifies that the angle is set to the angle of the target image's ROI. If this value is chosen but no ROI has been defined, the angle is set to 0.0° in the coordinate system specified with M_STRING_ANGLE_INPUT_UNITS.

(summarize)
Click to summarize 0.0 <= Value <= 360.0

Specifies a fixed angle at which to read a string, in degrees. This is interpreted with respect to the X-axis of the coordinate system specified with M_STRING_ANGLE_INPUT_UNITS.

(summarize)
Click to summarize M_STRING_ANGLE_INPUT_UNITS

Sets the coordinate system to use for M_STRING_ANGLE. This control type is ignored when M_STRING_ANGLE is set to M_ACCORDING_TO_REGION. INQ

(summarize)
Click to summarize M_DEFAULT

Same as M_PIXEL.
Click to summarize M_PIXEL

Specifies to interpret the value in pixel units, with respect to the pixel coordinate system.
Click to summarize M_WORLD

Specifies to interpret the value in world units, with respect to the relative coordinate system.
Click to summarize M_STRING_ANGLE_MODE

Sets whether the string angle is detected automatically or explicitly specified. INQ

(summarize)
Click to summarize M_DEFAULT

Specifies the default value; the default value is M_AUTO.
Click to summarize M_ANGLE

Specifies to use the angle specified with M_STRING_ANGLE; the string will be read from left to right with the characters facing upward along the specified angle. A string will only be read if it has the specified angle.

(summarize)
Click to summarize M_AUTO

Specifies that the string angle is detected automatically; M_STRING_ANGLE is ignored.
Click to summarize M_ORIENTATION

Specifies that the string will be read from left to right with the characters facing upward, or from right to left with the character facing downward. This is useful in cases where the orientation of a string is rotated 180 degrees, and this rotation does not affect the acceptability of a product (for example, if the product is placed backwards at an inspection point but is still a good part).

(summarize)
Click to summarize M_STRING_BOX_HEIGHT

Sets the height of the rectangular region that encloses the strings to read. The height is oriented along the vertical axis that is perpendicular to the string's base. M_STRING_BOX_HEIGHT only has an effect if M_STRING_BOX_SIZE_MODE is set to M_USER_DEFINED. INQ

(summarize)
Click to summarize Value > 0.0

Specifies the height, in pixels.
Click to summarize M_STRING_BOX_SIZE_MODE

Sets how to establish the size of the rectangular region that encloses the strings to read. INQ

(summarize)
Click to summarize M_DEFAULT

Same as M_USER_DEFINED.
Click to summarize M_USER_DEFINED

Specifies that the size of the rectangular region in which to read strings is defined by the M_STRING_BOX_HEIGHT and M_STRING_BOX_WIDTH settings.
Click to summarize M_STRING_BOX_WIDTH

Sets the width of the rectangular region that encloses the strings to read. The width is oriented along the axis that represents the string's base. M_STRING_BOX_WIDTH only has an effect if M_STRING_BOX_SIZE_MODE is set to M_USER_DEFINED. INQ

(summarize)
Click to summarize Value > 0.0

Specifies the width, in pixels.
Click to summarize M_STRING_PITCH

Sets the distance between successive dot centers, in the string angle direction. M_STRING_PITCH only has an effect if M_STRING_PITCH_MODE is set to M_USER_DEFINED. INQ

(summarize)
Click to summarize M_DEFAULT

Specifies the default value; the default value is 3.0 pixels.
Click to summarize Value > 0.0

Specifies the pitch, in pixels.
Click to summarize M_STRING_PITCH_MODE

Sets whether the distance between successive dot centers, in the string angle direction, is detected automatically or explicitly specified. INQ

(summarize)
Click to summarize M_DEFAULT

Specifies the default value; the default value is M_AUTO.
Click to summarize M_AUTO

Specifies to automatically establish the distance between dot centers in the string angle direction.
Click to summarize M_USER_DEFINED

Specifies to use the value set with M_STRING_PITCH. A string will only be read if it has the specified string pitch.

(summarize)
Click to summarize M_TIMEOUT

Sets the maximum read time for MdmrRead(). No results are returned if the read operation times out. 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.0

Specifies the maximum read time, in msec.

The following ControlType and corresponding ControlValue parameter settings are used to add fonts or string models to, or delete fonts or string models from, the SureDotOCR context specified with the ContextOrResultDmrId parameter.

function map For adding fonts or string models to, or deleting fonts or string models from, a SureDotOCR context
Click to summarize
ControlType		 Description
ControlValue
Click to summarize M_FONT_ADD

Adds an empty font to the context. To add characters to a font, use MdmrImportFont(). You can also add characters to a font, or modify its settings, using MdmrControlFont(). The maximum number of fonts in a context is 255. To inquire the number of fonts in the context, call MdmrInquire() with M_NUMBER_OF_FONTS.

When you add an empty font, the dimensions of its dot-matrix template are initially set to 5 columns and 7 rows. If the font is empty, you can change these values by calling MdmrControlFont() with M_FONT_SIZE_COLUMNS and M_FONT_SIZE_ROWS.

(summarize)
Click to summarize M_DEFAULT

Same as M_NEW_LABEL.
Click to summarize M_NEW_LABEL

Specifies to add a font with an automatically assigned label. To inquire about the label, use MdmrInquireFont() with M_FONT_LABEL_VALUE. To change the label, use MdmrControlFont() with M_FONT_LABEL_VALUE.

(summarize)
Click to summarize Value > 0

Specifies to add a font with the indicated label, as an integer. The label must be unique among all font labels in the context.

(summarize)
Click to summarize M_FONT_DELETE

Deletes one or all fonts from the context.

(summarize)
Click to summarize M_DEFAULT

Same as M_ALL.
Click to summarize

Specifies to delete the font by indicating its index.

(summarize)
Parameters

Set this parameter to the following:
0 <= Value < M_NUMBER_OF_FONTS

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

Specifies to delete the font by indicating its label.

(summarize)
Parameters

Set this parameter to the following:
Value > 0

Specifies the label of the font to delete.
Click to summarize M_ALL

Specifies to delete all fonts.
Click to summarize M_STRING_ADD

Adds an empty string model to a context. To add character constraints to the string model, or to modify its settings, use MdmrControlStringModel(). The maximum number of string models in a context is 255. To inquire the number of string models in a context, call MdmrInquire() with M_NUMBER_OF_STRING_MODELS.

(summarize)
Click to summarize M_DEFAULT

Same as M_NEW_LABEL.
Click to summarize M_NEW_LABEL

Specifies to add a string model with an automatically assigned label. To inquire about the label, use MdmrInquireStringModel() with M_STRING_LABEL_VALUE. To change the label, use MdmrControlStringModel() with M_STRING_LABEL_VALUE.

(summarize)
Click to summarize Value > 0

Specifies to add a string model with the indicated label, as an integer. The label must be unique among all string model labels in the context.

(summarize)
Click to summarize M_STRING_DELETE

Deletes one or all string models from a context.

(summarize)
Click to summarize M_DEFAULT

Same as M_ALL.
Click to summarize

Specifies to delete the string model by indicating its index.

(summarize)
Parameters

Set this parameter to the following:
0 <= Value < M_NUMBER_OF_STRING_MODELS

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

Specifies to delete the string model by indicating its label.

(summarize)
Parameters

Set this parameter to the following:
Value > 0

Specifies the label of the string model to delete.
Click to summarize M_ALL

Specifies to delete all string models.

The following ControlType and corresponding ControlValue parameter settings are used to control the SureDotOCR result buffer specified with the ContextOrResultDmrId parameter.

function map For controlling a SureDotOCR result buffer
Click to summarize
ControlType		 Description
ControlValue
Click to summarize M_RESET

Removes all results from the SureDotOCR result buffer. This does not delete the result buffer identifier, as is the case with MdmrFree().

(summarize)
Click to summarize M_DEFAULT

Specifies the default behavior.
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)
Click to summarize M_STOP_READ

Stops the current read operation. You can only perform this operation from another thread of higher priority. No results are returned if you stop the read operation.

(summarize)
Click to summarize M_DEFAULT

Specifies the default behavior.
Type-specific versions of the function when using a C compiler under 64-bit
void MdmrControlInt64 (MIL_ID ContextOrResultDmrId, MIL_INT64 ControlType, MIL_INT64 ControlValue)
Details
Parameters

ContextOrResultDmrId

See ContextOrResultDmrId 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 MdmrControlDouble (MIL_ID ContextOrResultDmrId, MIL_INT64 ControlType, MIL_DOUBLE ControlValue)
Details
Parameters

ContextOrResultDmrId

See ContextOrResultDmrId 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; mildmr.lib.
DLL Requires mil.dll; mildmr.dll.
DOT DIAMETER FOREGROUND VALUE DEFAULT FOREGROUND BLACK FOREGROUND WHITE ITALIC ANGLE DEFAULT ITALIC ANGLE MODE DEFAULT ANGLE AUTO ITALIC PITCH DEFAULT ITALIC PITCH MODE DEFAULT AUTO USER DEFINED MAX INTENSITY DEFAULT MAX INTENSITY MODE DEFAULT AUTO USER DEFINED MIN CONTRAST DEFAULT MIN CONTRAST MODE DEFAULT AUTO USER DEFINED MIN INTENSITY DEFAULT MIN INTENSITY MODE DEFAULT AUTO USER DEFINED SPACE SIZE MAX DEFAULT SPACE SIZE MAX MODE DEFAULT CHAR WIDTH FACTOR DISABLE SPACE SIZE MIN DEFAULT SPACE SIZE MIN MODE DEFAULT CHAR WIDTH FACTOR DISABLE STRING ANGLE DEFAULT ACCORDING TO REGION STRING ANGLE INPUT UNITS DEFAULT PIXEL WORLD STRING ANGLE MODE DEFAULT ANGLE AUTO ORIENTATION STRING BOX HEIGHT STRING BOX SIZE MODE DEFAULT USER DEFINED STRING BOX WIDTH STRING PITCH DEFAULT STRING PITCH MODE DEFAULT AUTO USER DEFINED TIMEOUT DEFAULT DISABLE FONT ADD DEFAULT NEW LABEL FONT DELETE DEFAULT NUMBER OF FONTS ALL STRING ADD DEFAULT NEW LABEL STRING DELETE DEFAULT NUMBER OF STRING MODELS ALL RESET DEFAULT RESULT OUTPUT UNITS DEFAULT ACCORDING TO CALIBRATION PIXEL WORLD STOP READ DEFAULT