MmodFind

This function searches for the model(s) that are in the specified Model Finder context, in the specified target image, Edge Finder result buffer, or M_SHAPE_SEGMENT Model Finder result buffer; the latter case is only available when searching for the synthetic rectangular model of a M_SHAPE_RECTANGLE type of context. Results are stored in the specified Model Finder result buffer. The resulting values can be read using the MmodGetResult() function.

To search regions at an angle for M_SHAPE_... models, you can set the region using MmodControl() with M_ANGLE_REGION. You can also use MmodControl() with M_SEARCH_POSITION_FROM_GRAPHIC_LIST or you can use a target image buffer associated with a rectangular M_VECTOR region of interest that has been set with MbufSetRegion().

When searching in an Edge Finder result buffer, MmodFind() will search for the models only in the included edges of the Edge Finder result buffer. The search is performed using both the global search settings of the Model Finder context and each model's current search settings (see MmodControl()).

If an occurrence has both a score and target score greater than or equal to its model's respective certainty levels (specified using MmodControl() with M_CERTAINTY and M_CERTAINTY_TARGET), it is automatically considered an occurrence (default 80%); the remaining occurrences will be the best of those greater than or equal to the model's acceptance levels (specified using MmodControl() with M_ACCEPTANCE and M_ACCEPTANCE_TARGET).

The maximum number of occurrences found depends on the maximum number specified for the context (specified using MmodControl() with Index set to M_CONTEXT and ControlType set to M_NUMBER). If it is set to M_ALL, MmodFind() tries to find the maximum number of occurrences specified for each model (specified using MmodControl() with Index set to an index value and ControlType set to M_NUMBER), greater than or equal to the acceptance levels.

Note, the Model Finder context must be preprocessed (MmodPreprocess()) before calling this function.

For each model defined in your Model Finder context, you can limit the operation to a different region of the image buffer, using MmodControl() with M_SEARCH_POSITION_RANGE set to M_ENABLE, and setting the M_POSITION_..., and M_POSITION_DELTA... control types to define the region in which you expect the occurrence to be found.

If you are using an M_SHAPE_... type of Model Finder context, the model is considered to have the same units as the target. If the target is calibrated, the model will be interpreted in world units. Conversely, if the target does not have a camera calibration context associated with it, the model will be interpreted in pixel units. The model will be defined in the same coordinate system as the target. You cannot associate a calibration context with the model.

For other types of Model Finder contexts, their models can be calibrated. If their models are calibrated, you must specify a calibrated target image or Edge Finder results. Conversely, if the models are uncalibrated, the target must be uncalibrated as well. Note, however, that if you calibrate the models using McalUniform() to apply a uniform camera calibration of pixel size equal to 1, the target image or Edge Finder results need not be calibrated. Conversely, if the models are uncalibrated, they can be used with a calibrated target only if it has been calibrated using McalUniform() to apply a uniform camera calibration of pixel size equal to 1.

If the target image or Edge Finder results are calibrated, results are calculated in the world coordinate system; otherwise, they are calculated in the pixel coordinate system.

If the target image or Edge Finder results are calibrated, you can retrieve results in real-world or in pixel units. However, in the presence of distortion, some results are meaningless when converted from real-world to pixel units (for example, angle, scale, and transformation coefficient results). For example, if a model appears warped in the target image, but the camera calibration context of the target image compensates for this during the model search, the resulting angle is meaningful in the real-world coordinate system, and meaningless in the pixel coordinate system.

For an M_GEOMETRIC or M_GEOMETRIC_CONTROLLED type of Model Finder context, if the target image or Edge Finder results are not calibrated and the nominal search aspect ratio is not set to 1 (MmodControl() with M_ASPECT_RATIO), the nominal search aspect ratio is taken into account horizontally when performing the search, adjusting the target pixel width to equal the pixel height (the model's aspect ratio is not adjusted). As such, results will be returned for this corrected target coordinate system.

If you are searching for model(s) in an Edge Finder result buffer, you can speed up the search by setting M_EXTRACTION_SCALE in MedgeControl() prior to calling MedgeCalculate(). For more information on speeding up your search, see the Interfacing with Geometric Model Finder section of Chapter 9: Edge Finder.