MmodDefine

This function allows you to add a model to, or delete a model from, a Model Finder context. For an M_GEOMETRIC or M_GEOMETRIC_CONTROLLED type of Model Finder context, you can define a model from an image, from a result buffer, from two other models, or you can define a synthetic model. Image-type, result-type, merge-type, and synthetic models can be mixed in the same Model Finder context. For an M_SHAPE_CIRCLE type of Model Finder context, you can only define a single synthetic M_CIRCLE model.

There are two types of image-type models: models for which you manually define their location in the model source image (M_IMAGE), and models that MIL automatically defines from the model source image (M_AUTO_DEFINE). M_AUTO_DEFINE defines a unique model by searching the model source image for unique geometric features. MmodDefine() can define an automatic model based on default settings. To have specified settings taken into account during model definition, you must allocate an empty image-type model using M_AUTO_DEFINE, set the appropriate control types using MmodControl(), and then call MmodControl() with M_AUTO_DEFINE. It can take several seconds to find the best model (or more for large or small images). To be useful, the model source image should be a typical target image; otherwise, the selected area for the model might never be present in the target image. For more information on defining a model automatically, see the Image-type models subsection of the Defining and adding models to your Model Finder context section of Chapter 7: Geometric Model Finder.

There are two types of result-type models: models defined from an Edge Finder result buffer (Edge Finder-type models), and models defined from a Model Finder result buffer (Model Finder-type model).

Merge-type models are composed of the edges of two different models. When you define a merge-type model, the two models from which it is merged are not affected.

There are two types of synthetic models: models of a predefined shape (predefined-shape models) and models defined from a CAD DXF file (CAD-file models). Use MmodDefineFromFile() to define a CAD-file model.

By default, synthetic models are defined to have a 10% margin around the bounding box of their active edges. When finding an occurrence, any extra edges found in this area will reduce the target score. When using an M_GEOMETRIC or M_GEOMETRIC_CONTROLLED type of Model Finder context, you can change the size of the margins with the MmodControl() M_BOX_MARGIN_... control types.

How you specify the dimensions of synthetic models depends on the type of context. For an M_GEOMETRIC or M_GEOMETRIC_CONTROLLED type of Model Finder context, specify the dimensions of synthetic models in user-defined units. Then, specify the ratio between model units and pixel units using MmodControl() with M_PIXEL_SCALE. If the target is not calibrated, then M_PIXEL_SCALE is used for the match. If the target is calibrated, the model units should be the same as the calibrated units. If the target is calibrated, M_PIXEL_SCALE will be used for draw operations, but not for the match nor the returned results. If you are searching for a synthetic model in a calibrated target, you must also associate the calibration context of the target with the model, using M_ASSOCIATED_CALIBRATION. MIL needs the calibration context for internal purposes at preprocessing time. MIL will not use the calibration context to compensate for incongruencies between the model and the target, nor will MIL map the model's coordinate system to that of the target. For an M_SHAPE_CIRCLE type of Model Finder context, specify the dimensions of the synthetic models in the units of the target; M_PIXEL_SCALE and M_ASSOCIATED_CALIBRATION are not used.

After you have specified your pixel scale and scale settings, you can verify if your synthetic models are valid, using MmodInquire() with M_VALID. Synthetic models can be invalid if their global size in X or Y (size of the model box * M_PIXEL_SCALE * M_SCALE) is greater than 1024.

If the image or the result buffer used to define the model is calibrated, then that calibration context is automatically associated with the model. Models can use different calibration contexts within the same Model Finder context, provided all calibrations map to the same world. All image-type or result-type models must be either calibrated or not.

When a call to MmodFind() is made, all models that are part of the specified context are searched for simultaneously in the target.

Note, when a model is added or deleted, the Model Finder context must be preprocessed again, using MmodPreprocess().

The search is performed according to the general search settings specified in the Model Finder context (M_CONTEXT), as well as the individual model search settings. Both the context and individual model search settings can be specified using MmodControl().

The model index starts at 0, and each subsequent model added to the Model Finder context is given a sequential index number, in the order that the model was added. If a model is deleted, all entries with higher indices are shifted down one.

For more information on defining models, see the Guidelines for choosing models section of Chapter 7: Geometric Model Finder.