| MIL 10 Reference
| Customize Help
| Save Settings

MbeadTemplate


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

Available on Windows
Available on Linux

Available on Non-Matrox computer
Available on Matrox 4Sight-X
Available on Matrox 4Sight GP
Available on Matrox Supersight
function map Function map
Examples
MbeadStream
MbeadTrain
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:

function map For specifying the bead type
CollapseValue Description
Collapse 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)
Collapse 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)
Collapse 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)
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:

function map For specifying a bead template
CollapseValue Description
Collapse

Specifies the index of the bead template.

(summarize)
Parameters

Specifies the index, which must be greater than or equal to 0.
Collapse

Specifies the label of the bead template.

(summarize)
Parameters

Specifies the label, which must be greater than 0.
Collapse 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.

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.

function map For adding a new bead template to a bead context
CollapseOperation Description
GraListIdOrSizeOfArray
FirstArrayPtr
SecondArrayPtr
ThirdArrayPtr
Collapse 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)
Collapse 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)
Collapse 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)
Collapse 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)
Collapse 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)
Collapse GraListIdOrSizeOfArray

Sets the identifier of a graphics list.

(summarize)

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

function map For performing an operation with a bead template in a bead context
CollapseOperation Description
GraListIdOrSizeOfArray
FirstArrayPtr
SecondArrayPtr
ThirdArrayPtr
Collapse 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)
Collapse GraListIdOrSizeOfArray

Sets whether to delete vertices or templates.

(summarize)
Collapse M_NULL

Specifies to delete the templates indicated by the LabelOrIndex parameter. To delete all templates, set the LabelOrIndex parameter to M_ALL.

(summarize)
Collapse M_ALL

Specifies to delete all vertices from the specified template. In this case, you cannot set the LabelOrIndex parameter to M_ALL.

(summarize)
Collapse 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)
Collapse ThirdArrayPtr

Sets the address of the array containing the indices of the vertices to delete, or specifies that this parameter is ignored.

(summarize)
Collapse 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)
Collapse 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)
Collapse M_INSERT

Inserts the specified vertices into the specified bead template. INQ

(summarize)
Collapse GraListIdOrSizeOfArray

Sets the size of the first and second source arrays (FirstArrayPtr and SecondArrayPtr).
Collapse FirstArrayPtr

Sets the address of the array containing the X-coordinates of the vertices to insert into the bead template. INQ

(summarize)
Collapse SecondArrayPtr

Sets the address of the array containing the Y-coordinates of the vertices to insert into the bead template. INQ

(summarize)
Collapse ThirdArrayPtr

Sets the address of the variable containing the place to insert the vertices. This variable must hold one of the following values:

(summarize)
Collapse M_BEGIN

Specifies that the vertices will be inserted before the bead template's first vertex.
Collapse M_END

Specifies that the vertices will be inserted after the bead template's last vertex.
Collapse -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)
Collapse M_REPLACE

Replaces the specified vertices of the specified bead template.

(summarize)
Collapse GraListIdOrSizeOfArray

Sets the size of the first, second, and third source arrays (FirstArrayPtr, SecondArrayPtr, and ThirdArrayPtr).
Collapse 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).
Collapse 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).
Collapse 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.
Collapse M_ROTATE_POINTS

Rotates the specified bead template around its origin (0,0).

This operation supports templates with any type of path.

(summarize)
Collapse 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)
Collapse M_SCALE_POINTS

Scales the specified bead template.

This operation supports templates with any type of path.

(summarize)
Collapse 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)
Collapse 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)
Collapse GraListIdOrSizeOfArray

Sets the size of the required source arrays (FirstArrayPtr and ThirdArrayPtr).
Collapse 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)
Collapse ThirdArrayPtr

Sets the address of the array containing the indices of the vertices for which to set the width.
Collapse M_TRANSLATE_POINTS

Moves the specified bead template.

This operation supports templates with any type of path.

(summarize)
Collapse FirstArrayPtr

Sets the address of the variable containing the amount by which to displace the bead template, in the X-direction.
Collapse 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.
DEFAULT BEAD EDGE BEAD STRIPE ALL ADD ADD FROM GRAPHIC LIST DELETE NULL ALL NULL INSERT BEGIN END REPLACE ROTATE POINTS SCALE POINTS SET WIDTH NOMINAL TRANSLATE POINTS ALL DEFAULT POLYLINE POLYLINE SEED ALL ADD