MmodControl

Sets the number of occurrences for which to search.

For M_CONTEXT, this control type sets the maximum number of all model occurrences for which to search in the target.

For a model, this control type sets the maximum number of occurrences of the specified model, for which to search in the target.

Once the number of occurrences for the context, with scores and target scores greater than or equal to their certainty levels, has been reached, the search will stop, regardless of whether the actual number set for any individual model has been found.

To further illustrate the relationship between the M_NUMBER setting for the context and that of the individual models, see the Expected number of occurrences subsection of the Customizing search settings section of Chapter 8: Geometric Model Finder. INQ

Sets the accuracy with which to find occurrences. The precision achieved is dependent on the quality of the model and the target. In addition, positional accuracy is slightly affected by the setting of the M_SPEED.

Note that lower accuracy can speed up the MmodFind() operation.

This control type is not supported for an M_SHAPE_... type of Model Finder context. INQ

Sets the degree to which MIL processes edgels in the target (MmodFind()) The target edgels that MIL processes are considered active. By limiting the active edgels in the target, you can speed up the search. To draw the active edgels in the target, use MmodDraw() with M_DRAW_ACTIVE_EDGELS.

This control type is only supported for a geometric Model Finder context (MmodAlloc() with M_GEOMETRIC). INQ

Sets the aspect ratio to apply to the target before starting the search. When the target is not calibrated, this control type allows you to quickly compensate for aspect ratio distortion in the target, typically a side effect of the sampling rate used by the frame grabber. When the target is calibrated, this control type is ignored.

This control type is mainly useful when dealing with synthetic models since it does not compensate for aspect ratio distortion in the model.

When performing the search, the nominal search aspect ratio is taken into account horizontally, adjusting the target pixel width to equal the pixel height. As such, results will be returned for this corrected target coordinate system. However, the results are converted to the original target coordinate system if you draw them using MmodDraw().

This control type is not supported for an M_SHAPE_... type of Model Finder context. INQ

Sets the level of details to extract from model images and target images during edge extraction. The detail level determines what is considered an edge/background.

A higher detail level will include more edges than a lower detail level.

This setting is only used when dealing with image-type models and image-type targets. INQ

Sets the resolution level for the initial stage (lowest resolution) of the search.

Level 0 is the original target and each higher level is half the size (and resolution) of the previous one. If the specified level is not supported by the search algorithm, the highest possible level will be used.

A higher first level speeds up the initial search but might make it less reliable because the model might not retain enough distinctive features at a lower resolution.

M_FIRST_LEVEL is for advanced users of the Model Finder module. The default setting usually provides the best results for the search operation.

Note that if you set a lower value for M_FIRST_LEVEL than the one assigned to M_LAST_LEVEL, MmodControl() will override your settings and automatically assign M_FIRST_LEVEL the same value as M_LAST_LEVEL. This implies that only one resolution level will be used for the search.

This control type is not supported for an M_SHAPE_... type of Model Finder context. INQ

Sets the resolution level for the final stage (the highest resolution) of the search.

Level 0 is the original target and each higher level is half the size (and resolution) of the previous one. If the specified level is not supported by the search algorithm, the highest possible level will be used.

A higher last level speeds up the initial search but might make it less reliable and less accurate because the model might not retain enough distinctive features at a low resolution.

M_LAST_LEVEL is for advanced users of the Model Finder module. The default setting usually provides the best results for the search operation.

Note that if you set a higher value for M_LAST_LEVEL than the one assigned to M_FIRST_LEVEL, MmodControl() will override your settings and automatically assign M_LAST_LEVEL the same value as M_FIRST_LEVEL. This implies that only one resolution level will be used for the search.

This control type is not supported for an M_SHAPE_... type of Model Finder context. INQ

Sets whether to save the target edges in the result buffer. By enabling this control type, you can retrieve target chain information using MmodGetResult() and you can draw target edges using MmodDraw().

For an M_SHAPE_SEGMENT type of context, this control type must be enabled if you want to use the search results as a target for a subsequent search of a model defined in a M_SHAPE_RECTANGLE type of context. INQ

Sets whether to perform calculations specific to angular-range search strategies.

Typically, to search for models within their specified angular range (M_ANGLE- M_ANGLE_DELTA_NEG to M_ANGLE + M_ANGLE_DELTA_POS) in the target, calculations specific to angular-range search strategies should be enabled for the context. These calculations are not required to search for models at their nominal angle (M_ANGLE). In addition, if you expect that the occurrences sought are close to their model's nominal angle, you can try disabling these calculations to see if Model Finder can still find the required occurrences. Disabling these calculations might speed up the search depending on the model and the target.

Note that M_SEARCH_ANGLE_RANGE must be enabled to search for rotation-invariant non-synthetic models (for example, an image-type model of a circle).

Also note that candidates can only be returned as occurrences if found within the angular range specified for their model. Therefore, whether you enable or disable the calculation, you can restrict which candidates are returned as occurrences by narrowing the angular range.

This control type is not supported for an M_SHAPE_... type of Model Finder context. INQ

Sets whether to perform calculations specific to position-range search strategies.

Typically, to search for models within their specified position range (M_POSITION_X, M_POSITION_Y, M_POSITION_DELTA_NEG_X, M_POSITION_DELTA_POS_X, M_POSITION_DELTA_NEG_Y, M_POSITION_DELTA_POS_Y) in the target, calculations specific to position-range search strategies should be enabled for the context. These calculations are not required to search for models at their nominal position (M_POSITION_X and M_POSITION_Y). In addition, if you expect that the occurrences sought are close to their model's nominal position, you can try disabling these calculations to see if Model Finder can still find the required occurrences. Disabling these calculations might speed up the search depending on the model and the target.

Note that candidates can only be returned as occurrences if found within the position range specified for their model. Therefore, whether you enable or disable the calculations, you can restrict which candidates are returned as occurrences by narrowing the position range.

Finally, if these calculations are disabled and no nominal position is specified (M_POSITION_X and M_POSITION_Y set to M_ALL), no occurrences will be found and no errors will be returned.

This control type is not supported for an M_SHAPE_... type of Model Finder context. INQ

Sets whether to perform calculations specific to scale-range search strategies.

Typically, to search for models within their specified scale range (M_SCALE x M_SCALE_MIN_FACTOR) to (M_SCALE x M_SCALE_MAX_FACTOR) in the target, calculations specific to scale-range search strategies should be enabled for the context. These calculations are not required to search for models at their nominal scale (M_SCALE). In addition, if you expect that the occurrences sought are close to their model's nominal scale, you can try disabling these calculations to see if Model Finder can still find the required occurrences. Disabling these calculations might speed up the search depending on the model and the target.

Note that candidates can only be returned as occurrences if found within the scale range specified for their model. Therefore, whether you enable or disable the calculation, you can restrict which candidates are returned as occurrences by narrowing the scale range.

This control type cannot be set to M_ENABLE if the Model Finder context is set to M_GEOMETRIC_CONTROLLED.

This control type is not supported for an M_SHAPE_... type of Model Finder context. INQ

Sets whether to enable sharing of edges between occurrences.

This control type is not supported for a model defined in an M_SHAPE_CIRCLE, an M_SHAPE_ELLIPSE, or an M_SHAPE_SEGMENT type of Model Finder context. INQ

Sets the degree of smoothness (noise reduction) applied to the model images and target images during the edge extraction.

This setting is only used when dealing with image-type models or using image-type targets. INQ

Sets the algorithm's search speed. Note that increasing the search speed can decrease the robustness and subpixel accuracy of the MmodFind() operation.

This control type is not supported for an M_SHAPE_... type of Model Finder context. INQ

Stops the current MmodFind() operation. You must call MmodControl() with M_STOP_FIND from another thread (typically of higher priority). The number of occurrences found at that point will be returned.

Sets whether target caching is enabled. When target caching is enabled, the geometric representation of the target, generated by MmodFind(), is kept in the result.

Subsequent calls to MmodFind() can reuse the representation, if they use the same result buffer and target. This increases the speed of the searches.

Note that the geometric representation generated with a given Model Finder context might not be compatible with another context. In such a case, the cache will not be used.

Also note that this constant cannot be set to M_ENABLE if the Model Finder context is set to M_GEOMETRIC_CONTROLLED.

This control type is not supported for an M_SHAPE_... type of Model Finder context. INQ

Sets the maximum search time for MmodFind(), in msec. If a search times out, the number of occurrences found at that point will be returned. INQ

Sets the acceptance level for the score. An occurrence will be returned only if the match score between the target and the model is greater than or equal to this level.

The score is a measure, as a percentage, of the presence and fit of the model's active edges in the occurrence. Using M_FIT_ERROR_WEIGHTING_FACTOR, you can specify how much the fit influences the score. INQ

Sets the acceptance level for the target score. An occurrence will be returned only if the target score between the target and the model is greater than or equal to this level.

The target score is a measure, as a percentage, of edges found in the occurrence that are not found in the original model, weighted by the deviation in position of the common edges. Using M_FIT_ERROR_WEIGHTING_FACTOR, you can specify how much the fit influences the target score.

This control type is not supported for a model defined in an M_SHAPE_... type of Model Finder context. INQ

Sets the nominal search angle; this is the angle at which you expect to find the model's reference axis (specified using M_REFERENCE_ANGLE) in the target.

For a model defined in an M_SHAPE_ELLIPSE or M_SHAPE_RECTANGLE type of Model Finder context, the model's reference axis is, by default, aligned with its principle axis (its width).

This control type is not supported for a model defined in an M_SHAPE_CIRCLE type of Model Finder context. INQ

Sets the lower limit of the angular range, relative to the nominal search angle (M_ANGLE). Occurrences with angles outside the angular-range cannot be returned as results.

Note that typically, to search for model occurrences within the angular range, calculations specific to angular-range search strategies should be enabled (M_SEARCH_ANGLE_RANGE) for the context. When enabled, the angular range should be used to cover an expected variance in angle. Note that the actual angle of the occurrence does not affect search speed. If you need to search for a model at discrete angles only (for example, at intervals of 90 degrees), it is typically more efficient to define several models with different expected angles, than to search through the full angular range.

This control type is not supported for a model defined in an M_SHAPE_CIRCLE type of Model Finder context. INQ

Sets the upper limit of the angular range, relative to the nominal search angle (M_ANGLE). Occurrences with angles outside the angular-range cannot be returned as results.

Note that typically, to search for model occurrences within the angular range, calculations specific to angular-range search strategies should be enabled (M_SEARCH_ANGLE_RANGE) for the context. When enabled, the angular range should be used to cover an expected variance in angle. Note that the actual angle of the occurrence does not affect search speed. If you need to search for a model at discrete angles only (for example, at intervals of 90 degrees), it is typically more efficient to define several models with different expected angles, than to search through the full angular range.

This control type is not supported for a model defined in an M_SHAPE_CIRCLE type of Model Finder context. INQ

Associates the specified camera calibration context with the specified model. Note that if you do not save, with the Model Finder context, the camera calibration contexts associated with the models (MmodSave() or MmodStream() with M_WITH_CALIBRATION), you must re-associate each model with its camera calibration context after restoring the context (MmodRestore(), or MmodStream()).

In addition, for a synthetic model, you should use M_ASSOCIATED_CALIBRATION to associate the camera calibration context of a calibrated target with the model. Note that the camera calibration contexts associated with synthetic models are not saved or restored by MmodSave(), MmodRestore() or MmodStream().

This control type is not supported for a model defined in an M_SHAPE_... type of Model Finder context. INQ

Defines a unique model from a source image, automatically. This control type is only supported for models of type M_AUTO_DEFINE.

Sets a margin at the bottom of the bounding box of the model's active edges.

The bounding box of the model's active edges plus the specified margins define the size of the model box.

The model box is used to compute the target score and to set the different masks of the model. If you change this value, all of this model's previous masks are discarded, since their size is no longer valid.

M_BOX_MARGIN_BOTTOM is only available for synthetic models.

This control type is only valid for synthetic models. If in an M_SHAPE_... type of Model Finder context, this margin is only used for drawing; it does not affect the match. INQ

Sets a margin at the left side of the bounding box of the model's active edges.

The bounding box of the model's active edges plus the specified margins define the size of the model box.

The model box is used to compute the target score and to set the different masks of the model. If you change this value, all of this model's previous masks are discarded, since their size is no longer valid.

M_BOX_MARGIN_LEFT is only available for synthetic models.

This control type is only valid for synthetic models. If in an M_SHAPE_... type of Model Finder context, this margin is only used for drawing; it does not affect the match. INQ

Sets a margin at the right side of the bounding box of the model's active edges.

The bounding box of the model's active edges plus the specified margins define the size of the model box.

The model box is used to compute the target score and to set the different masks of the model. If you change this value, all of this model's previous masks are discarded, since their size is no longer valid.

M_BOX_MARGIN_RIGHT is only available for synthetic models.

This control type is only valid for synthetic models. If in an M_SHAPE_... type of Model Finder context, this margin is only used for drawing; it does not affect the match. INQ

Sets a margin at the top of the bounding box of the model's active edges.

The bounding box of the model's active edges plus the specified margins define the size of the model box.

The model box is used to compute the target score and to set the different masks of the model. If you change this value, all of this model's previous masks are discarded, since their size is no longer valid.

M_BOX_MARGIN_TOP is only available for synthetic models.

This control type is only valid for synthetic models. If in an M_SHAPE_... type of Model Finder context, this margin is only used for drawing; it does not affect the match. INQ

Sets the direction of the Y-axis for a model of type M_DXF_FILE.

When the model is added to the Model Finder context from a CAD DXF file, the model will retain its coordinate system (the origin and the axis). Most CAD DXF files are oriented so that the Y-axis is positive going up, whereas the coordinate system MIL uses is oriented with the Y-axis positive going down. So if you take the edge coordinates of an object from a CAD DXF file and put them in an image, the imaged object will look flipped when compared to the original object. This is also the case for a model defined from a CAD DXF file. This means that, unless the object is symmetrical, the match will not be made.

This control type is not supported for a model defined in an M_SHAPE_... type of Model Finder context. INQ

Sets the certainty level for the score, as a percentage. If both the score and target scores are greater than or equal to their respective certainty levels, the occurrence is considered a match, without searching the rest of the target for better matches (provided the specified number of occurrences has been found). INQ

Sets the certainty level for the target score. If both the score and target scores are greater than or equal to their respective certainty levels, the occurrence is considered a match, without searching the rest of the target for better matches (provided the specified number of occurrences has been found).

This control type is not supported for a model defined in an M_SHAPE_... type of Model Finder context. INQ

Sets the radius used to round all the corners of predefined-shaped models that have corners.

This control type is only valid for models of type M_RECTANGLE, M_SQUARE, M_DIAMOND, M_TRIANGLE, and M_CROSS. Attempting to use this value for any other model type will generate an error.

This control type is not supported for a model defined in a M_SHAPE_... type of Model Finder result buffer. INQ

Sets the fit error weighting factor. This factor determines the contribution of the fit error in the score and target score calculation. INQ

Sets the minimum angular separation required for two occurrences to be considered two distinct matches (two separate occurrences). Note, only one of the separation criteria needs to be met for occurrences to be considered distinct.

DISTINCT OCCURRENCE = (Separation in X) OR (Separation in Y) OR (Separation in Angle) OR (Separation in Scale) OR (Separation in Aspect Ratio).

This control type is not supported for a model defined in an M_SHAPE_CIRCLE type of Model Finder context. INQ

Sets the minimum separation required in scale for two occurrences to be considered distinct matches (two separate occurrences). This value is specified as a scale factor. Note, only one of the separation criteria needs to be met for occurrences to be considered distinct.

DISTINCT OCCURRENCE = (Separation in X) OR (Separation in Y) OR (Separation in Angle) OR (Separation in Scale) OR (Separation in Aspect Ratio). INQ

Sets the minimum separation required along the X-axis for two occurrences to be considered distinct matches (two separate occurrences). Note, only one of the separation criteria needs to be met for occurrences to be considered distinct.

DISTINCT OCCURRENCE = (Separation in X) OR (Separation in Y) OR (Separation in Angle) OR (Separation in Scale) OR (Separation in Aspect Ratio). INQ

Sets the minimum separation required along the Y-axis for two occurrences to be considered distinct matches (two separate occurrences). Note, only one of the separation criteria needs to be met for occurrences to be considered distinct.

DISTINCT OCCURRENCE = (Separation in X) OR (Separation in Y) OR (Separation in Angle) OR (Separation in Scale) OR (Separation in Aspect Ratio). INQ

Sets the pixel scale of the model, if it is a synthetic model. This value is the scale to apply to the model to go from model units to pixel units. M_PIXEL_SCALE is used for the match if the target is not calibrated.

If the target is calibrated, this value is not used for the match nor for the returned results. However, this value will be used for draw operations.

This control type is not supported for a model defined with an M_SHAPE_... type of Model Finder context. For these types of contexts, model units are interpreted to be in the units of the target. If the target is calibrated, the units are interpreted to be in calibrated units. If the target is not, the units are interpreted to be in pixel units. INQ

Sets the expected polarity of occurrences, compared to that of the model.

This control type is not supported for a model defined in an M_SHAPE_SEGMENT type of Model Finder context. INQ

Sets the valid position range in the negative X-direction, relative to the nominal position (M_POSITION_X and M_POSITION_Y).

The position range limits the region in which the position of a model occurrence can be found; position coordinates which fall outside this region cannot be returned as results (MmodGetResult() with M_POSITION_X and M_POSITION_Y). Note that the position returned for an occurrence is determined by the model's reference axis position. The region defined by the position range can lie partially, or totally, outside the target.

Note that typically, to search for model occurrences within the position range, calculations specific to position-range search strategies should be enabled (M_SEARCH_POSITION_RANGE) for the context. When enabled, using a small position range generally decreases the search time, depending on the number of details present in the target. Always set the position range to the minimum required when speed is a consideration.

When M_POSITION_X is set to M_ALL, M_POSITION_DELTA_NEG_X will be treated as if set to M_INFINITE regardless of its actual setting. INQ

Sets the valid position range in the negative Y-direction, relative to the nominal position (M_POSITION_X and M_POSITION_Y).

The position range limits the region in which the position of a model occurrence can be found; position coordinates which fall outside this region cannot be returned as results (MmodGetResult() with M_POSITION_X and M_POSITION_Y). Note that the position returned for an occurrence is determined by the model's reference axis position. The region defined by the position range can lie partially, or totally, outside the target.

Note that typically, to search for model occurrences within the position range, calculations specific to position-range search strategies should be enabled (M_SEARCH_POSITION_RANGE) for the context. When enabled, using a small position range generally decreases the search time, depending on the number of details present in the target. Always set the position range to the minimum required when speed is a consideration.

When M_POSITION_Y is set to M_ALL, M_POSITION_DELTA_NEG_Y will be treated as if set to M_INFINITE regardless of its actual setting. INQ

Sets the valid position range in the positive X-direction, relative to the nominal position (M_POSITION_X and M_POSITION_Y).

The position range limits the region in which the position of a model occurrence can be found; position coordinates which fall outside this region cannot be returned as results (MmodGetResult() with M_POSITION_X and M_POSITION_Y). Note that the position returned for an occurrence is determined by the model's reference axis position. The region defined by the position range can lie partially, or totally, outside the target.

Note that typically, to search for model occurrences within the position range, calculations specific to position-range search strategies should be enabled (M_SEARCH_POSITION_RANGE) for the context. When enabled, using a small position range generally decreases the search time, depending on the number of details present in the target. Always set the position range to the minimum required when speed is a consideration.

When M_POSITION_X is set to M_ALL, M_POSITION_DELTA_POS_X will be treated as if set to M_INFINITE regardless of its actual setting. INQ

Sets the valid position range in the positive Y-direction, relative to the nominal position (M_POSITION_X and M_POSITION_Y).

The position range limits the region in which the position of a model occurrence can be found; position coordinates which fall outside this region cannot be returned as results (MmodGetResult() with M_POSITION_X and M_POSITION_Y). Note that the position returned for an occurrence is determined by the model's reference axis position. The region defined by the position range can lie partially, or totally, outside the target.

Note that typically, to search for model occurrences within the position range, calculations specific to position-range search strategies should be enabled (M_SEARCH_POSITION_RANGE) for the context. When enabled, using a small position range generally decreases the search time, depending on the number of details present in the target. Always set the position range to the minimum required when speed is a consideration.

When M_POSITION_Y is set to M_ALL, M_POSITION_DELTA_POS_Y will be treated as if set to M_INFINITE regardless of its actual setting. INQ

Sets the nominal search position for the X-coordinate. INQ

Sets the nominal search position for the Y-coordinate. INQ

Sets the angle of the reference axis for the model. Angle results are returned relative to this axis, rather than the model source image axis.

By default, for an ellipse model defined in an M_SHAPE_ELLIPSE type of Model Finder context, the reference axis is aligned with the principal axis of the model (the width). INQ

Sets the X-offset of the origin of the model's reference axis, relative to the model origin. Position results return the X-coordinate of the model's reference axis origin transformed at the model occurrence. Position results are relative to the target origin.

Note that the reference axis origin need not be in the model. INQ

Sets the Y-offset of the origin of the model's reference axis, relative to the model origin. Position results return the Y-coordinate of the model's reference axis origin transformed at the model occurrence. Position results are relative to the target origin.

Note that the reference axis origin need not be in the model. INQ

Sets the nominal search scale.

For a model defined in an M_SHAPE_ELLIPSE or M_SHAPE_RECTANGLE type of Model Finder context, scale calculations are taken with respect to the model's width. The model's height is not taken into account. Use M_MODEL_ASPECT_RATIO to account for height differences. For example, if the model has a width of 4 and a height of 2 and the occurrence is expected to have a height of 2 and a width of 8, set M_SCALE to 2 and M_MODEL_ASPECT_RATIO to 2. Recall that the width of a model in an M_SHAPE_ELLIPSE or M_SHAPE_RECTANGLE type of Model Finder context, or the width of an occurrence of this type of model, is always measured along its principal axis.

For a model defined in an M_SHAPE_SEGMENT type of Model Finder context, scale calculations are taken with respect to the model's length. INQ

Sets the factor used to determine the upper limit (maximum permitted scale) of the scale range. M_SCALE is multiplied by this factor. Occurrences with scales outside the scale-range cannot be returned as results.

Note that typically, to search for model occurrences within the scale range, calculations specific to scale-range search strategies should be enabled (M_SEARCH_SCALE_RANGE) for the context. When enabled, the scale range should only cover the expected variance in scale to avoid slowing down the search and avoid finding unwanted occurrences. A search through a range of scales is performed in parallel, meaning that the actual scale of an occurrence has no bearing on which occurrence will be found first. INQ

Sets the factor used to determine the lower limit (minimum permitted scale) of the scale range. M_SCALE is multiplied by this factor. Occurrences with scales outside the scale-range cannot be returned as results.

Note that typically, to search for model occurrences within the scale range, calculations specific to scale-range search strategies should be enabled (M_SEARCH_SCALE_RANGE) for the context. When enabled, the scale range should only cover the expected variance in scale to avoid slowing down the search and avoid finding unwanted occurrences. A search through a range of scales is performed in parallel, meaning that the actual scale of an occurrence has no bearing on which occurrence will be found first. INQ

Specifies to use a search region defined from a 2D graphics list.

The 2D graphics list must contain a maximum of one graphic of type rectangle (MgraRect(), MgraRectAngle(), MgraInteractive() with M_GRAPHIC_TYPE_RECT, or MgraRectFill()) and have its input units set to pixels (MgraControlList() with M_INPUT_UNITS set to M_PIXEL).

M_GEOMETRIC or M_GEOMETRIC_CONTROLLED type models must be defined at an angular offset of 0 degrees.

Using this value is effectively equivalent to making multiple calls to MmodControl() with M_POSITION_X, M_POSITION_Y, M_POSITION_DELTA_NEG_X, M_POSITION_DELTA_NEG_Y, M_POSITION_DELTA_POS_X, and M_POSITION_DELTA_POS_Y. INQ

Sets a unique user-defined label for the specified model. This label can be used as a means of identifying your model, independently from its index, in the Model Finder context. INQ