Drawing
By calling MbeadDraw(), you can perform drawing operations with a bead template and its points (when passing a bead context to the function), or with a measured bead and its points (when passing a bead result to the function). For example, when using a bead context, you can use M_DRAW_POSITION with M_TRAINED_PASS to draw a cross at the position of each trained point that has successfully passed the training phase. Similarly, when using a bead result, you can use M_DRAW_POSITION with M_PASS to draw a cross at the position of each trained point's corresponding measured point that has successfully passed the verification phase.
You can perform drawings in either an image buffer or graphics list, unless otherwise specified. To control the drawing color, you can use MbeadDraw() with a previously allocated graphics context or with the default graphics context. You can also choose to draw in the display's overlay buffer, which allows you to annotate an image non-destructively. For more information, see Chapter 22: Generating graphics and the Annotating the displayed image non-destructively section of Chapter 21: Displaying an image.
When calling MbeadDraw() with a bead context (and using a calibrated training image) or with a bead result (and using a calibrated target image), the destination drawing buffer need not be calibrated to the same world. MIL draws according to the calibration context associated to either the training or verification image.
Specifying the points
When calling MbeadDraw(), you must specify the points with which to draw, by setting the DrawOption parameter. The settings available depend on whether you are calling MbeadDraw() with a bead context or result.
When drawing with a bead context
When drawing with a bead context, you can specify that MIL performs the drawing operation (M_DRAW_...) using one of the following:
-
M_USER, which performs the drawing operation using the template's vertices.
If the template's path (MbeadControl() with M_TRAINING_PATH) follows a polyline, M_USER refers to the template's polyline points (MbeadTemplate()). If the template's path follows a circle or segment, M_USER refers to the minimum critical points that MIL internally calculates based on the settings of the path. For a path that follows a segment, MIL calculates three critical points, according to the specified start and end of the segment (MbeadControl() with M_TEMPLATE_SEGMENT_...). For a path that follows a circle, MIL calculates five critical points, according to the specified center and radius of the circle (M_TEMPLATE_CIRCLE_...).
-
M_TRAINED_FAIL, which performs the drawing operation using all the trained points that were expected but not established (found) during training (MbeadTrain()). In this case, the drawing operation uses the expected position of the trained point. Such drawings can be particularly useful when deciphering why a template isn't completely trained (MbeadInquire() with M_STATUS), especially if drawn on top of the training image (M_DRAW_TRAINING_IMAGE).
-
M_TRAINED_PASS, which performs the drawing operation using all the trained points that were established (found) during training.
-
M_TRAINED, which performs the drawing operation using all the trained points that were found (M_TRAINED_PASS) and all the trained points that were expected but not found (M_TRAINED_FAIL) during training.
When drawing with a bead result
When drawing with a bead result, you can specify that MIL performs the drawing operation (M_DRAW_...) using one of the following:
-
M_FAIL, which performs the drawing operation using all the measured points that were expected but did not pass verification. In this case, the drawing operation uses the expected position of the measured point (based on its associated trained point).
You can also draw using the measured points that failed for a more specific reason. For example, you can draw: the expected position of a measured point that was not found (M_FAIL_NOT_FOUND), the position of a measured point that was found but has failed because its position is not within the specified offset (M_FAIL_OFFSET), or the position of a measured point that was found but has failed because the width of the measured bead at that point is less than the specified minimum width (M_FAIL_WIDTH_MIN). Such drawings can be particularly useful when deciphering why MbeadGetResult() is returning a failed status (M_STATUS), especially when drawn on top of a target image.
-
M_PASS, which performs the drawing operation using all the measured points that have passed verification.
-
M_ALL, which performs the drawing operation using all the measured points (M_PASS and M_FAIL).
Specifying the drawing operation
Once you have selected the set of points, you should specify the type of drawing operation to perform on them. Using the selected set of points, MIL can draw:
-
The index value of each point (M_DRAW_POSITION_INDEX). If you specify M_USER as your set of points, you can only perform this drawing operation for templates with a path that follows a polyline, otherwise you will get an error.
You can also draw the index or label of the template that contains the selected set of points (M_DRAW_INDEX or M_DRAW_LABEL).
-
A cross at the position of each point (M_DRAW_POSITION) or a line that connects all the points (M_DRAW_POSITION_POLYLINE).
-
The area within which each point was established (M_DRAW_SEARCH_BOX) or an H-type line (|-|) indicating the width of the bead at that point (M_DRAW_WIDTH).
In the following example, MIL has drawn: the width of the bead (in white) at each measured point that has a passing status (M_DRAW_WIDTH and M_PASS), the search box (in white) of the measured points that were expected but not found (M_DRAW_SEARCH_BOX and M_FAIL_NOT_FOUND), and the search box (in gray) of the measured points that were expected but failed because the corresponding bead width was too small (M_DRAW_SEARCH_BOX and M_FAIL_WIDTH_MIN).
You can also call MbeadDraw() to draw a training image, using M_DRAW_TRAINING_IMAGE. Unlike other drawing operations, drawing a training image is not based on a specific set of points and it cannot be drawn in a graphics list. Also, when drawing a training image, you must use MbeadDraw() with a bead context and you must have internally saved the training image with MbeadTrain().
Adjusting the templates and trained points with which to draw
As previously discussed, MIL performs the drawing operation (DrawOperation) using the type of points selected (DrawOption), for either the bead context or result. Typically, you will want to perform the drawing operation on all points in all beads that meet the specified requirements. In this case, you must set the LabelOrIndex and Index parameters to M_ALL. You can however adjust these two parameter settings and specify that MIL should perform the drawing using a specific point in a specific template, or using one or all points in one or all templates. For example, you can draw search boxes for only one particular template in the context, or for only one particular point.
You can also specify that MIL should base the drawing on the specified templates as a whole, by setting the Index parameter to M_GENERAL and the LabelOrIndex parameter to one or all templates. In this case, MIL performs the drawing for the entire template if it contains one or more points that meet the requirements of the DrawOption parameter setting. For example, if you are using bead results and specify M_DRAW_POSITION with M_PASS, and you set the Index parameter to M_GENERAL and the LabelOrIndex parameter to a specific template, MIL will draw the position of all the points related to that template as long as at least one of its trained point's corresponding measured point has passed verification. Given this high level of flexibility, you should be especially mindful of each parameter setting when calling MbeadDraw().