| Customize Help
| Save Settings

MbeadTemplate


Function Map
Syntax
Description
Parameters
- ContextBeadId
- Operation
- BeadType
Table: For specifying the bead type
- LabelOrIndex
Table: For specifying a bead template
- GraListIdOrSizeOfArray
- FirstArrayPtr
- SecondArrayPtr
- ThirdArrayPtr
- ControlFlag
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 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
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
Click to summarizeValue Description
Click to summarize 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)
Click to summarize 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)
Click to summarize 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
Click to summarizeValue Description
Click to summarize

Specifies the index of the bead template.

(summarize)
Parameters

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

Specifies the label of the bead template.

(summarize)
Parameters

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

When using a standard vector (std::vector) overload function in C++, you can pass M_DEFAULT to this parameter and MIL will automatically determine the size based on the number of items in the vector passed to the FirstArrayPtr, SecondArrayPtr, or ThirdArrayPtr parameter.

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

FirstArrayPtr
Accepts the address of one of the following (see the Parameter associations section for specifics on which is expected):
  • array of type MIL_DOUBLE [optionally, in C++: a reference to a constant std::vector<MIL_DOUBLE> ]

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
Accepts the address of one of the following (see the Parameter associations section for specifics on which is expected):
  • array of type MIL_DOUBLE [optionally, in C++: a reference to a constant std::vector<MIL_DOUBLE> ]

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
Accepts the address of one of the following (see the Parameter associations section for specifics on which is expected):
  • array of type MIL_DOUBLE [optionally, in C++: a reference to a constant std::vector<MIL_DOUBLE> ]

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
Click to summarize
Operation		 Description
GraListIdOrSizeOfArray
FirstArrayPtr
SecondArrayPtr
ThirdArrayPtr
Click to summarize 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)
Click to summarize 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)
Click to summarize 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)
Click to summarize 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)
Click to summarize M_ADD_FROM_GRAPHIC_LIST

Adds a new bead template, based on the vertices of a polyline (or polygon) from a 2D graphics list, to a bead context. The 2D 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)
Click to summarize GraListIdOrSizeOfArray

Sets the identifier of a 2D 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
Click to summarize
Operation		 Description
GraListIdOrSizeOfArray
FirstArrayPtr
SecondArrayPtr
ThirdArrayPtr
Click to summarize 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)
Click to summarize GraListIdOrSizeOfArray

Sets whether to delete vertices or templates.

(summarize)
Click to summarize M_NULL

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

(summarize)
Click to summarize M_ALL

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

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

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

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

Inserts the specified vertices into the specified bead template. INQ

(summarize)
Click to summarize GraListIdOrSizeOfArray

Sets the size of the first and second source arrays (FirstArrayPtr and SecondArrayPtr).
Click to summarize FirstArrayPtr

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

(summarize)
Click to summarize SecondArrayPtr

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

(summarize)
Click to summarize ThirdArrayPtr

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

(summarize)
Click to summarize M_BEGIN

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

Specifies that the vertices will be inserted after the bead template's last vertex.
Click to summarize -1 <= Value < TotalNumberOfVertices

Specifies an index value representing the position in the template after which to insert the specified vertices. Since the index of the template's first vertex is 0, you must set a value between negative one (inserts vertices before the bead template's first vertex) and the total number of vertices in the template minus one (inserts vertices after the bead template's last vertex).

(summarize)
Click to summarize M_REPLACE

Replaces the specified vertices of the specified bead template.

(summarize)
Click to summarize GraListIdOrSizeOfArray

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

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

This operation supports templates with any type of path.

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

Scales the specified bead template.

This operation supports templates with any type of path.

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

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

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

Moves the specified bead template.

This operation supports templates with any type of path.

(summarize)
Click to summarize FirstArrayPtr

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