MmodDefine

Board	Supported
Host System	Yes
V4L2	Yes
Clarity UHD	Yes
Concord PoE	No
GenTL	Yes
GevIQ	Yes
GigE Vision	Yes
Indio	No
Iris GTX	Yes
Radient eV-CL	Yes
Rapixo CL	Yes
Rapixo CoF	Yes
Rapixo CXP	Yes
USB3 Vision	Yes

Add a model to, or delete a model from, a Model Finder context.

Syntax

void MmodDefine(
    AIL_ID     ContextId,  //out
    AIL_INT64  ModelType,  //in
    AIL_DOUBLE Param1,     //in
    AIL_DOUBLE Param2,     //in
    AIL_DOUBLE Param3,     //in
    AIL_DOUBLE Param4,     //in
    AIL_DOUBLE Param5      //in
)

Description

This function allows you to add a model to, or delete a model from, a Model Finder context. To an M_GEOMETRIC or M_GEOMETRIC_CONTROLLED type of Model Finder context, you can add a model from an image, from a result buffer, from two other models, or you can add a synthetic model. Image-type, result-type, merge-type, and synthetic models can be mixed in the same Model Finder context. To an M_SHAPE_... type of Model Finder context, you can only add a single synthetic model of the same type (for example, to an M_SHAPE_CIRCLE type of context, you can only add 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 Aurora Imaging Library 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 Image-type models.

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. For a model in an M_SHAPE_... type of Model Finder context, this margin is used for drawing. For a model in anM_GEOMETRIC or M_GEOMETRIC_CONTROLLED context, any extra edges found in this area, when finding an occurrence, will reduce the target score. Regardless of the 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 camera calibration context of the target with the model, using M_ASSOCIATED_CALIBRATION. Aurora Imaging Library needs the camera calibration context for internal purposes at preprocessing time. Aurora Imaging Library will not use the camera calibration context to compensate for incongruencies between the model and the target, nor will Aurora Imaging Library map the model's coordinate system to that of the target.

Note: 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 less than 16 or greater than 1024.
For anM_SHAPE_... 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.

If the image or the result buffer used to define the model is calibrated, then that camera calibration context is automatically associated with the model. Models can use different camera calibration contexts within the same Model Finder context, provided all camera 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 Guidelines for choosing models.

Parameters

`ContextId` (out, AIL_ID)

Specifies the Model Finder context to which to add, or from which to delete, the model. The Model Finder context must have been previously allocated on the required system using MmodAlloc.

`ModelType` (in, AIL_INT64)

Specifies the type of model to define when adding models to the context, or specifies to delete a model from the Model Finder context.