MbeadTemplate

Filters
See also

User Guide:

Defining, training, and modifying bead templates Drawing Steps to validate beads Verifying beads and retrieving results

Reference:

MbeadAlloc MbeadControl MbeadInquire MbeadTrain MbeadVerify MgraInteractive MgraLines

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

mbead.cpp
mbead.cs
mbead.vb

Function Map

- BeadType

Table:

For specifying the bead type

- LabelOrIndex

Table:

For specifying a bead template

- GraListIdOrSizeOfArray

Parameter Associations

Table:	For adding a new bead template to a bead context
Table:	For performing an operation with a bead template in a bead context

Compilation information

Synopsis

Add, delete, or modify a bead template.

Syntax

void MbeadTemplate(

MIL_ID ContextBeadId,	//in
MIL_INT64 Operation,	//in
MIL_INT64 BeadType,	//in
MIL_INT LabelOrIndex,	//in
MIL_INT GraListIdOrSizeOfArray,	//in
const MIL_DOUBLE *FirstArrayPtr,	//in
const MIL_DOUBLE *SecondArrayPtr,	//in
const MIL_INT *ThirdArrayPtr,	//in
MIL_INT64 ControlFlag	//in

)

Description

This function adds a new bead template to a bead context. This function also performs operations on templates already in a context, such as deleting them, modifying them, or adding, deleting, or modifying their vertices.

By default, MIL interprets certain input settings for a template in pixel units (such as position and dimension). To specify that MIL should interpret these settings in world units, use MbeadControl() with M_TEMPLATE_INPUT_UNITS set to M_WORLD.

Whenever you add, delete, or modify a bead template, you must train it using MbeadTrain(). Once you train the template, you can use it to verify beads with MbeadVerify().

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

ContextBeadId

Specifies the identifier of a bead context. The bead context must have been previously allocated on the required system using MbeadAlloc().

Operation

Specifies to add a new bead template to a bead context, or specifies another operation to perform with a template that is already in a context.

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

BeadType INQ

Specifies the type of the new bead template to add to a bead context, or specifies that the type information is not required.

This parameter should be set to one of the following values:

For specifying the bead type
Value	Description
M_DEFAULT	Specifies the default type. When adding a new bead template to a bead context, M_DEFAULT is the same as M_BEAD_STRIPE. When performing an operation with a template that is already in a context, M_DEFAULT indicates that the type information is not required. This is the only possible setting for these operations. (summarize) Specifies the default type. (more details...)
M_BEAD_EDGE	Specifies to add a new bead template consisting of an edge. In this case, the template represents an outline of a bead delineated by a boundary established from intensity transitions in an image, such as the skeletal border of an object. By default, MIL assumes the foreground of the edge-bead is white and is on the counter-clockwise side of the path direction, while the background is assumed to be black and on the clockwise side of the edge-bead. To modify how MIL establishes the foreground, use MbeadControl() with M_FOREGROUND_VALUE. You can only specify M_BEAD_EDGE when adding a new bead template to a bead context. (summarize) Specifies to add a new bead template consisting of an edge. (more details...)
M_BEAD_STRIPE	Specifies to add a new bead template consisting of a stripe. In this case, the template represents a bead that has two edges and a width, such as a strip of some malleable material (for example, glue or lead). By default, MIL assumes the stripe-bead is white and is on a black background. By default, MIL also assumes that the bead's nominal width is consistent and is automatically learned from the training phase. To modify how MIL establishes the foreground and width, use MbeadControl() with M_FOREGROUND_VALUE and M_WIDTH_NOMINAL_MODE. You can only specify M_BEAD_STRIPE when adding a new bead template to a bead context. (summarize) Specifies to add a new bead template consisting of a stripe. (more details...)

LabelOrIndex

Specifies a unique label for a new bead template to add to a bead context, or specifies the index or label of a template in a context (or all templates in a context) with which to perform the operation. This parameter should be set to one of the following values:

For specifying a bead template
Value	Description
M_TEMPLATE_INDEX( MIL_INT Index )	Specifies the index of the bead template. (summarize) Specifies the index of the bead template. (more details...)
		Parameters
		Index Specifies the index, which must be greater than or equal to 0.
M_TEMPLATE_LABEL( MIL_INT Label )	Specifies the label of the bead template. (summarize) Specifies the label of the bead template. (more details...)
		Parameters
		Label Specifies the label, which must be greater than 0.
M_ALL	Specifies all bead templates.

GraListIdOrSizeOfArray

Specifies information required for the operation. If this information is not needed, set this parameter to M_NULL.

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

FirstArrayPtr

Specifies an attribute of the operation. Its definition is dependent on the Operation parameter setting. If the operation does not require this information, set this parameter to M_NULL.

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

SecondArrayPtr

Specifies an attribute of the operation. Its definition is dependent on the Operation parameter setting. If the operation does not require this information, set this parameter to M_NULL.

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

ThirdArrayPtr

Specifies an attribute of the operation. Its definition is dependent on the Operation parameter setting. If the operation does not require this information, set this parameter to M_NULL.

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

ControlFlag

Reserved for future expansion and must be set to M_DEFAULT.

Parameter associations

The tables below list possible values for the Operation, GraListIdOrSizeOfArray, FirstArrayPtr, SecondArrayPtr, and ThirdArrayPtr parameters.

For adding a new bead template to a bead context
For performing an operation with a bead template in a bead context

Set unused parameters to M_NULL.

The value in the table below is for adding a new bead template to a bead context. In this case, you must set the LabelOrIndex parameter to M_TEMPLATE_LABEL() and specify a unique label value for the new template.

For adding a new bead template to a bead context
Operation		Description
	GraListIdOrSizeOfArray
	FirstArrayPtr
	SecondArrayPtr
	ThirdArrayPtr
M_ADD		Adds a new bead template, based on the specified vertices or a fixed circle or segment, to a bead context. A template must have a path and a width. To establish the path of the template, use MbeadControl() with M_TRAINING_PATH. The template's default path (M_POLYLINE_SEED) follows a polyline that MIL establishes using the specified vertices (FirstArrayPtr and SecondArrayPtr) and then refining them according to a training image (MbeadTrain()). To specify a polyline path with a trained position that exactly follows the specified vertices, use M_POLYLINE. In either case, the order in which you specify the vertices establishes the path's shape and direction. You can also specify that the template's path follows a fixed segment or circle, which you must define using MbeadControl() with M_TEMPLATE_CIRCLE_... or M_TEMPLATE_SEGMENT_.... In this case you should not set any vertices. To establish the width of the template, use MbeadControl() with M_WIDTH_NOMINAL_MODE. By default (M_AUTO_UNIFORM), MIL uses a training image to establish an average bead width. To use a training image to establish a unique width at the position of each trained point, use M_AUTO_CONTINUOUS. You can also explicitly specify the template's width using M_USER_DEFINED. You can modify a template's vertices or width after you have set them (for example, using M_INSERT or M_SET_WIDTH_NOMINAL); keep this in mind since MIL bases the template's path and width using the most current settings when you call MbeadTrain(). (summarize) Adds a new bead template, based on the specified vertices or a fixed circle or segment, to a bead context. (more details...)
	GraListIdOrSizeOfArray	Sets the size of the first and second source arrays (FirstArrayPtr and SecondArrayPtr). If the template's path follows a segment or circle, set this parameter to M_NULL. INQ (summarize) Sets the size of the first and second source arrays (FirstArrayPtr and SecondArrayPtr). INQ (more details...)
	FirstArrayPtr	Sets the address of the array containing the X-coordinates of the template's vertices. You must specify at least 2 vertices. If the template's path follows a segment or circle, set this parameter to M_NULL. INQ (summarize) Sets the address of the array containing the X-coordinates of the template's vertices. INQ (more details...)
	SecondArrayPtr	Sets the address of the array containing the Y-coordinates of the bead template's vertices. You must specify at least 2 vertices. If the template's path follows a segment or circle, set this parameter to M_NULL. INQ (summarize) Sets the address of the array containing the Y-coordinates of the bead template's vertices. INQ (more details...)
M_ADD_FROM_GRAPHIC_LIST		Adds a new bead template, based on the vertices of a polyline (or polygon) from a graphics list, to a bead context. The graphics list must contain one polyline (or polygon) graphic, added with MgraLines() or MgraInteractive(). MIL considers the specified vertices (MgraLines() or MgraInteractive()) as the template's vertices. Note that a polygon is simply a polyline that MIL automatically closes by connecting the final vertex to the first with a straight line. Any operation or setting that applies to polylines also applies to polygons. A template must have a path and a width. To establish the path of the template, use MbeadControl() with M_TRAINING_PATH. The template's default path (M_POLYLINE_SEED) follows a polyline that MIL establishes using the specified vertices (MgraLines() or MgraInteractive()) and then refining them according to a training image (MbeadTrain()). To specify a polyline path with a trained position that exactly follows the specified vertices, use M_POLYLINE. In either case, the order in which you specify the vertices (MgraLines()) establishes the path's shape and direction. To establish the width of the template, use MbeadControl() with M_WIDTH_NOMINAL_MODE. By default (M_AUTO_UNIFORM), MIL uses a training image to establish an average bead width. To use a training image to establish a unique width at the position of each trained point, use M_AUTO_CONTINUOUS. You can also explicitly specify the template's width using M_USER_DEFINED. You can modify a template's vertices or width after you have set them (for example, using M_INSERT or M_SET_WIDTH_NOMINAL); keep this in mind since MIL bases the template's path and width using the most current settings when you call MbeadTrain(). (summarize) Adds a new bead template, based on the vertices of a polyline (or polygon) from a graphics list, to a bead context. (more details...)
	GraListIdOrSizeOfArray	Sets the identifier of a graphics list. (summarize) Sets the identifier of a graphics list. (more details...)

The values in the table below are for performing an operation with a bead template in a bead context. Unless otherwise specified, you can only perform these operations if the template's path follows a polyline, and you must set the LabelOrIndex parameter to a specific template, using either M_TEMPLATE_INDEX() or M_TEMPLATE_LABEL().

For performing an operation with a bead template in a bead context
Operation			Description
	GraListIdOrSizeOfArray
	FirstArrayPtr
	SecondArrayPtr
	ThirdArrayPtr
M_DELETE			Deletes the specified vertices from the specified template, or deletes the specified template. You can delete templates whose path follows a polyline, circle, or segment; however you can only delete vertices from a template if its path follows a polyline. (summarize) Deletes the specified vertices from the specified template, or deletes the specified template. (more details...)
	GraListIdOrSizeOfArray		Sets whether to delete vertices or templates. (summarize) Sets whether to delete vertices or templates. (more details...)
		M_NULL	Specifies to delete the templates indicated by the LabelOrIndex parameter. To delete all templates, set the LabelOrIndex parameter to M_ALL. (summarize) Specifies to delete the templates indicated by the LabelOrIndex parameter. (more details...)
		M_ALL	Specifies to delete all vertices from the specified template. In this case, you cannot set the LabelOrIndex parameter to M_ALL. (summarize) Specifies to delete all vertices from the specified template. (more details...)
		Value	Specifies the size of the array (ThirdArrayPtr) containing the vertices to delete from the specified bead template. In this case, you cannot set the LabelOrIndex parameter to M_ALL. (summarize) Specifies the size of the array (ThirdArrayPtr) containing the vertices to delete from the specified bead template. (more details...)
	ThirdArrayPtr		Sets the address of the array containing the indices of the vertices to delete, or specifies that this parameter is ignored. (summarize) Sets the address of the array containing the indices of the vertices to delete, or specifies that this parameter is ignored. (more details...)
		M_NULL	Specifies to ignore this parameter. You must set this parameter to M_NULL when you are deleting templates (GraListIdOrSizeOfArray is set to M_NULL) or when deleting all vertices from a template (GraListIdOrSizeOfArray is set to M_ALL). (summarize) Specifies to ignore this parameter. (more details...)
		ArrayAddress	Specifies the address of the array that indicates the vertices to delete. The array must have the same size as specified using GraListIdOrSizeOfArray. (summarize) Specifies the address of the array that indicates the vertices to delete. (more details...)
M_INSERT			Inserts the specified vertices into the specified bead template. INQ (summarize) Inserts the specified vertices into the specified bead template. INQ (more details...)
	GraListIdOrSizeOfArray		Sets the size of the first and second source arrays (FirstArrayPtr and SecondArrayPtr).
	FirstArrayPtr		Sets the address of the array containing the X-coordinates of the vertices to insert into the bead template. INQ (summarize) Sets the address of the array containing the X-coordinates of the vertices to insert into the bead template. INQ (more details...)
	SecondArrayPtr		Sets the address of the array containing the Y-coordinates of the vertices to insert into the bead template. INQ (summarize) Sets the address of the array containing the Y-coordinates of the vertices to insert into the bead template. INQ (more details...)
	ThirdArrayPtr		Sets the address of the variable containing the place to insert the vertices. This variable must hold one of the following values: (summarize) Sets the address of the variable containing the place to insert the vertices. (more details...)
		M_BEGIN	Specifies that the vertices will be inserted before the bead template's first vertex.
		M_END	Specifies that the vertices will be inserted after the bead template's last vertex.
		-1 <= Value <= (TotalNumberOfVertices - 1)	Specifies an index value representing the position in the template after which to insert the specified vertices. Since the index of the first vertex in the template is 0, you must set a value between negative one (same as M_BEGIN) and the total number of vertices in the template minus one (same as M_END). (summarize) Specifies an index value representing the position in the template after which to insert the specified vertices. (more details...)
M_REPLACE			Replaces the specified vertices of the specified bead template. (summarize) Replaces the specified vertices of the specified bead template. (more details...)
	GraListIdOrSizeOfArray		Sets the size of the first, second, and third source arrays (FirstArrayPtr, SecondArrayPtr, and ThirdArrayPtr).
	FirstArrayPtr		Sets the address of the array containing the X-coordinates of the vertices that will replace the specified vertices of the bead template (ThirdArrayPtr).
	SecondArrayPtr		Sets the address of the array containing the Y-coordinates of the vertices that will replace the specified vertices of the bead template (ThirdArrayPtr).
	ThirdArrayPtr		Sets the address of the array containing the indices of the vertices in the bead template that will be replaced by the new vertices.
M_ROTATE_POINTS			Rotates the specified bead template around its origin (0,0). This operation supports templates with any type of path. (summarize) Rotates the specified bead template around its origin (0,0). (more details...)
	FirstArrayPtr		Sets the address of the variable containing the angle by which to rotate the bead template. Positive angles indicate a counter-clockwise rotation. (summarize) Sets the address of the variable containing the angle by which to rotate the bead template. (more details...)
M_SCALE_POINTS			Scales the specified bead template. This operation supports templates with any type of path. (summarize) Scales the specified bead template. (more details...)
	FirstArrayPtr		Sets the address of the variable containing the factor by which to scale the bead template. The scale factor must be greater than zero. (summarize) Sets the address of the variable containing the factor by which to scale the bead template. (more details...)
M_SET_WIDTH_NOMINAL			Specifies the expected width of the specified bead template. When using M_SET_WIDTH_NOMINAL, MIL adjusts the template's nominal width (MbeadControl() with M_WIDTH_NOMINAL) according to the specified width value (FirstArrayPtr) at each specified vertex of the template (ThirdArrayPtr). You should only set the width when it differs from the nominal width of the bead. MIL linearly interpolates the width between consecutive vertices. For M_SET_WIDTH_NOMINAL to have an effect, you must specify that the bead's nominal width is user-defined, using MbeadControl() with M_WIDTH_NOMINAL_MODE set to M_USER_DEFINED. (summarize) Specifies the expected width of the specified bead template. (more details...)
	GraListIdOrSizeOfArray		Sets the size of the required source arrays (FirstArrayPtr and ThirdArrayPtr).
	FirstArrayPtr		Sets the address of the array containing the width of the corresponding vertices specified with ThirdArrayPtr. To reset a vertex's width back to the nominal width (M_WIDTH_NOMINAL), set its width in this array to M_RESET_WIDTH. INQ (summarize) Sets the address of the array containing the width of the corresponding vertices specified with ThirdArrayPtr. INQ (more details...)
	ThirdArrayPtr		Sets the address of the array containing the indices of the vertices for which to set the width.
M_TRANSLATE_POINTS			Moves the specified bead template. This operation supports templates with any type of path. (summarize) Moves the specified bead template. (more details...)
	FirstArrayPtr		Sets the address of the variable containing the amount by which to displace the bead template, in the X-direction.
	SecondArrayPtr		Sets the address of the variable containing the amount by which to displace the bead template, in the Y-direction.

Compilation information

Header	Include mil.h.
Library	Use mil.lib; milbead.lib.
DLL	Requires mil.dll; milbead.dll.