| Customize Help

Retrieving and analyzing results

After having successfully located your model occurrences in your target using MmodFind(), you can extract the required results from your result buffer using MmodGetResult().

Possible results

You can retrieve several types of results with the Model Finder module. These results provide considerable information on the nature of the occurrence found. In addition to the score, target score, model coverage, target coverage, fit error, and forward/reverse transformation coefficients discussed previously in this chapter, results can be returned for:

  • Number of occurrences.

  • Index or user label of occurrences.

  • Position X and position Y.

  • Scale.

  • Polarity.

  • Angle.

  • Whether the timeout limit has been reached.

You can specify whether to retrieve results for all edges of the target in the region of the occurrence, or only the edges in the occurrence that correspond to the model's active edges, using M_TARGET and M_MODEL, respectively.

Results are returned in descending order of match score, such that the result with the highest score is returned first. Generally, you should first retrieve the total number of occurrences found for all the models in the Model Finder context, to ascertain the size of the result array needed. Note that results can be returned for the entire context; the model index (M_INDEX result type) is used to differentiate results between models. For a complete description of all possible results, refer to the description of MmodGetResult() in the MIL Reference.

Note that certain results types are only supported with certain types of models, or result buffers. For instance, M_RADIUS is only supported for M_CIRCLE type models, while the M_ASPECT_RATIO result type is not supported for an M_SHAPE_CIRCLE type of Model Finder result buffer.

Occurrences are indexed with positive integers starting from 0.

Drawing results

The MmodDraw() function provides several operations for drawing results in any specified image buffer or 2D graphics list. You can also choose to draw in the display's overlay buffer. By drawing into the display's overlay buffer, you can annotate an image non-destructively (see the Annotating the displayed image non-destructively section of Chapter 23: Displaying an image). You can also draw zoomed results. You can draw a model box, or a bounding box around the occurrence, the active edges of the model, the edges of the result occurrence, or draw a cross-like symbol at the model's reference axis origin or occurrence position.

Typically, all drawing operations in MmodDraw() can be combined; you can therefore draw multiple results simultaneously. For example, to draw the edges of the result occurrence and its position, you would specify M_DRAW_EDGES + M_DRAW_POSITION.

The following code snippet shows how to combine drawing operations using MIL constant combination:

MmodDraw(M_DEFAULT, MilResult, MilOverlayImage, M_DRAW_EDGES+M_DRAW_POSITION,
                              M_DEFAULT, M_DEFAULT);

When drawing results, you can draw the active edges of the model transformed at the occurrence position, or the edges of the target in the region of the occurrence.

You can also draw a zoomed version of results that were obtained from a specified region in the target. To do so, specify the appropriate values for the MgraControl() M_DRAW_OFFSET_X, M_DRAW_OFFSET_Y, M_DRAW_ZOOM_X, and M_DRAW_ZOOM_Y control types. The relative origin values must be specified in pixels, and are relative to the coordinates of the top-left corner of the region in the model source, while the scale values specify the X- and Y-scaling factors used to fill the destination buffer. For more information on zooming, see the Defining and adding models to your Model Finder context section earlier in this chapter.

You can use a previously allocated 2D graphics context (see Chapter 24: Generating graphics) to control the drawing color, or use the default 2D graphics context (M_DEFAULT).