MmodFind

This function searches for the model(s) defined in the specified Model Finder context, in a target image or an Edge Finder result buffer, and writes the results in the provided result buffer. When an Edge Finder result buffer is specified, MmodFind() will search for the models only in the included edges in 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()). The resulting values can be read with the MmodGetResult() function.

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.

If you are using a Model Finder context whose models are calibrated, the target image or Edge Finder results must also be calibrated. Conversely, if the models are uncalibrated, the target must be uncalibrated as well. If you are using an M_SHAPE_CIRCLE type of Model Finder context, the model does not need to be calibrated and will inherit the calibration of the target image or of the target Edge Finder result buffer.

Note, however, that if you calibrate the models using McalUniform() to apply a uniform 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 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 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.

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 8: Edge Finder.