MdmrControl

Filters
See also

User Guide:

Fonts Results and annotations Steps to read dot-matrix strings from an image String models

Reference:

MdmrAlloc MdmrAllocResult MdmrControlFont MdmrControlStringModel MdmrFree MdmrGetResult MdmrImportFont MdmrInquire MdmrInquireFont MdmrInquireStringModel MdmrRead MstrGetResult

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/GPm

Available on Matrox Supersight

Function map

Examples

dmreditfontfile.cpp
dmrgenfontfile.cpp
dmrshowfontfile.cpp
mdmr.cpp
mdmr.cs
mdmr.vb
variousdotmatrixreadings.cpp

Function Map

- 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 setting, add or delete a font or string model to or from a context, or remove results from a 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 setting of a SureDotOCR context or a SureDotOCR result buffer. This function also allows you to add or delete a font or string model from a context, or to remove 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 if there is complementary information.

Parameters

This function is not supported on the selected boards.

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 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.

For controlling a SureDotOCR context setting
For adding fonts or string models to, or deleting fonts or string models from, a SureDotOCR context
For controlling a SureDotOCR result buffer

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).

For controlling a SureDotOCR context setting
ControlType		Description
	ControlValue	Description
M_DOT_DIAMETER		Sets the diameter of the dots that make up the characters in the strings. INQ (summarize) Sets the diameter of the dots that make up the characters in the strings. INQ (more details...)
	Value > 0.0	Specifies the diameter, in pixels.
M_FOREGROUND_VALUE		Sets the foreground of the characters in the strings. INQ (summarize) Sets the foreground of the characters in the strings. INQ (more details...)
	M_DEFAULT	Same as M_FOREGROUND_BLACK.
	M_FOREGROUND_BLACK	Specifies that the string can be read if the foreground of its characters is darker than the background. For example, black characters on a white surface. (summarize) Specifies that the string can be read if the foreground of its characters is darker than the background. (more details...)
	M_FOREGROUND_WHITE	Specifies that the string can be read if the foreground of its characters is lighter than the background. For example, white characters on a black surface. (summarize) Specifies that the string can be read if the foreground of its characters is lighter than the background. (more details...)
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) Sets the maximum pixel intensity of a character's dots. INQ (more details...)
	M_DEFAULT	Specifies the default value; the default value is 255.0.
	0.0 <= Value <= 255.0	Specifies the maximum pixel intensity.
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) Sets how to establish the maximum pixel intensity of a character's dots. INQ (more details...)
	M_DEFAULT	Same as M_AUTO.
	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) Specifies to automatically establish the maximum pixel intensity of a character's dots. (more details...)
	M_USER_DEFINED	Specifies to use the maximum pixel intensity value set with M_MAX_INTENSITY.
M_MIN_CONTRAST		Sets the minimum contrast of a character. M_MIN_CONTRAST only has an effect if M_MIN_CONTRAST_MODE is set to M_USER_DEFINED. INQ (summarize) Sets the minimum contrast of a character. INQ (more details...)
	M_DEFAULT	Specifies the default value; the default value is 15.0.
	0.0 <= Value <= 255.0	Specifies the minimum contrast.
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) Sets how to establish the minimum contrast (difference in pixel intensity) between a character (foreground) and its background. INQ (more details...)
	M_DEFAULT	Same as M_AUTO.
	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) Specifies to automatically establish the minimum contrast of characters. (more details...)
	M_USER_DEFINED	Specifies to use the minimum contrast value set with M_MIN_CONTRAST.
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) Sets the minimum pixel intensity of a character's dots. INQ (more details...)
	M_DEFAULT	Specifies the default value; the default value is 0.0.
	0.0 <= Value <= 255.0	Specifies the minimum pixel intensity.
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) Sets how to establish the minimum pixel intensity of a character's dots. INQ (more details...)
	M_DEFAULT	Same as M_AUTO.
	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) Specifies to automatically establish the minimum pixel intensity of character dots. (more details...)
	M_USER_DEFINED	Specifies to use the minimum pixel intensity value set with M_MIN_INTENSITY.
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) Sets the value with which to determine the maximum distance between two characters in a string. INQ (more details...)
	M_DEFAULT	Specifies the default value; the default value is 3.0.
	Value > 0.0	Specifies the maximum distance value.
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) Sets how to determine the maximum distance between two characters in a string. INQ (more details...)
	M_DEFAULT	Same as M_CHAR_WIDTH_FACTOR.
	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) 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. (more details...)
	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) Specifies no maximum space size. (more details...)
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) Sets the value with which to determine the minimum distance between two characters in a string. INQ (more details...)
	M_DEFAULT	Specifies the default value; the default value is 1.0.
	Value > 0.0	Specifies the minimum distance value.
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) Sets how to determine the minimum distance between two characters in a string. INQ (more details...)
	M_DEFAULT	Same as M_CHAR_WIDTH_FACTOR.
	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) 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. (more details...)
	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) Specifies no minimum space size. (more details...)
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) Sets the height of the rectangular region that encloses the strings to read. INQ (more details...)
	Value > 0.0	Specifies the height, in pixels.
M_STRING_BOX_SIZE_MODE		Sets how to establish the size of the rectangular region that encloses the strings to read. INQ (summarize) Sets how to establish the size of the rectangular region that encloses the strings to read. INQ (more details...)
	M_DEFAULT	Same as M_USER_DEFINED.
	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.
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) Sets the width of the rectangular region that encloses the strings to read. INQ (more details...)
	Value > 0.0	Specifies the width, in pixels.
M_TIMEOUT		Sets the maximum read time for MdmrRead(), in msec. No results are returned if the read operation times out. INQ (summarize) Sets the maximum read time for MdmrRead(), in msec. INQ (more details...)
	M_DEFAULT	Specifies the default value; the default value is 2000.0 msec.
	M_DISABLE	Specifies an infinite amount of read time.
	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.

For adding fonts or string models to, or deleting fonts or string models from, a SureDotOCR context

ControlType

Description

ControlValue

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)

Adds an empty font to the context.

(more details...)

M_DEFAULT

Same as M_NEW_LABEL.

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)

Specifies to add a font with an automatically assigned label.

(more details...)

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)

Specifies to add a font with the indicated label, as an integer.

(more details...)

M_FONT_DELETE

Deletes one or all fonts from the context.

(summarize)

Deletes one or all fonts from the context.

(more details...)

M_DEFAULT

Same as M_ALL.

M_FONT_INDEX(

MIL_INT IndexValue

)

Specifies to delete the font by indicating its index.

(summarize)

Specifies to delete the font by indicating its index.

(more details...)

Parameters

IndexValue

Set this parameter to the following:

Value >= 0

Specifies the index of the font to delete.

M_FONT_LABEL(

MIL_INT LabelValue

)

Specifies to delete the font by indicating its label.

(summarize)

Specifies to delete the font by indicating its label.

(more details...)

Parameters

LabelValue

Set this parameter to the following:

Value > 0

Specifies the label of the font to delete.

M_ALL

Specifies to delete all fonts.

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)

Adds an empty string model to a context.

(more details...)

M_DEFAULT

Same as M_NEW_LABEL.

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)

Specifies to add a string model with an automatically assigned label.

(more details...)

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)

Specifies to add a string model with the indicated label, as an integer.

(more details...)

M_STRING_DELETE

Deletes one or all string models from a context.

(summarize)

Deletes one or all string models from a context.

(more details...)

M_DEFAULT

Same as M_ALL.

M_STRING_INDEX(

MIL_INT IndexValue

)

Specifies to delete the string model by indicating its index.

(summarize)

Specifies to delete the string model by indicating its index.

(more details...)

Parameters

IndexValue

Set this parameter to the following:

Value >= 0

Specifies the index of the string model to delete.

M_STRING_LABEL(

MIL_INT LabelValue

)

Specifies to delete the string model by indicating its label.

(summarize)

Specifies to delete the string model by indicating its label.

(more details...)

Parameters

LabelValue

Set this parameter to the following:

Value > 0

Specifies the label of the string model to delete.

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.

For controlling a SureDotOCR result buffer
ControlType		Description
	ControlValue	Description
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) Removes all results from the SureDotOCR result buffer. (more details...)
	M_DEFAULT	Specifies the default behavior.
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) Sets whether to return results in pixels or world units. INQ (more details...)
	M_DEFAULT	Same as M_ACCORDING_TO_CALIBRATION.
	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.
	M_PIXEL	Specifies that results are returned in pixel units, with respect to the pixel coordinate system.
	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) Specifies that results are returned in world units, with respect to the relative coordinate system. (more details...)
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) Stops the current read operation. (more details...)
	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.