MpatAllocAutoModel()函数

Synopsis

Automatically allocate a unique pattern matching model from a source image.

Format

MIL_ID MpatAllocAutoModel(SystemId, SrcImageBufId, SizeX, SizeY, PosUncertaintyX, PosUncertaintyY, ModelType, Mode, ModelIdPtr)

MIL_ID SystemId;	System identifier
MIL_ID SrcImageBufId;	Source image identifier from which to extract model
long SizeX;	Model width
long SizeY;	Model height
long PosUncertaintyX;	Maximum X-axis displacement
long PosUncertaintyY;	MaximumY-axis displacement
long ModelType;	Model type
long Mode;	Mode of operation
MIL_ID *ModelIdPtr;	Storage location for model identifier

Description

This function searches for the most-suitable unique area, of the specified dimensions, in the model source image. If found, it automatically allocates a model, using this area’s data. If not found, no model is allocated and an error is reported. It can take several seconds to find the best model (more for large images). If specified, it can find multiple unique models.

Allocate a model with MpatAllocAutoModel when you want to perform whole image alignment, for which allocation of a unique model is essential.

This function returns a model identifier for future use of the model with the pattern recognition functions. When the model buffer is no longer required, you should release its memory, using MpatFree.

The SystemId parameter specifies the system on which the model buffer will be allocated. This parameter must be set to a valid system identifier, M_DEFAULT_HOST or M_DEFAULT. To use the default Host system of the current MIL application, specify M_DEFAULT_HOST. If you specify M_DEFAULT, MIL will select the most appropriate system on which to allocate the buffer (the Host system or any already allocated system).

The SrcImageBufId parameter specifies the identifier of the image buffer from which to extract the model. This image should be representative of the images that will be searched with the resulting model.

The SizeX and SizeY parameters define the width and height of the desired model.

The PosUncertaintyX and PosUncertaintyY parameters specify the maximum translation (shift) accepted between the source and target images. These values represent the number of pixels by which the target location can be offset from the model location, in either direction on the vertical and horizontal axes. The valid search region of the model is automatically set by using these values to extend the range of the source model location.

The ModelType parameter specifies the type and capabilities of the model. If set to M_NORMALIZED (normalized grayscale correlation), it finds the position and match score of the model in a target image, using MpatFindModel. If set to M_ORIENTATION (containing rotational information), it finds the global orientation (not position) of the model in a target image, using MpatFindOrientation. Note, a model of M_ORIENTATION type must contain all the significant features of the target image (for example, a unique object on a plain background). Combining the types allows the model to be used for both purposes (M_NORMALIZED+M_ORIENTATION).

Models are directly associated with a set of search parameters. Upon allocation of an M_NORMALIZED model type, these model-search parameters are set to the following defaults:

X and Y offset	Determined by the corner offset of the model to the source image. (use MpatInquire to access values)
Positional accuracy	M_MEDIUM (+/-) 0.25 pixels
Search number:	1
Search speed:	M_MEDIUM
Acceptance level:	70%
Certainty level:	80%
Search angle:	0°

You can change a model’s search parameters at any time, using the appropriate MpatSet…() command (MpatSetAcceptance, MpatSetAccuracy, MpatSetCenter, MpatSetCertainty, MpatSetDontCare, MpatSetNumber, MpatSetPosition, MpatSetSpeed).

The Mode parameter controls the speed of the allocation process. This can be either M_FAST (M_DEFAULT), for speedy allocation, or M_BEST, for high-precision allocation, of the most unique model. If you want to allocate several models from the same image, you can add M_MULTIPLE+n to the Mode parameter (where n represents the number of models to allocate). For example, set Mode to M_BEST+M_MULTIPLE+4 to find and allocate the four most unique models available in your image. Models can overlap within the image.

The ModelIdPtr parameter specifies the address of the variable or array in which the model identifier(s) are to be written. The identifier is required to use a model with other pattern recognition functions. Since MpatAllocAutoModel also returns the model identifier, you can set this parameter to M_NULL when allocating a single model. If allocation fails, M_NULL is written as the identifier.

Returned value

The returned value is the model identifier. If allocation fails, M_NULL is returned.

Status

Current limitations:

• This function currently only supports unsigned grayscale two-dimensional images up to 8 bits deep.
• The model width must be between 24 and 256 (inclusive), and the height must be between 24 and 240 (inclusive).

See also

MpatFree, MpatInquire, MpatSetAcceptance, MpatSetAccuracy, MpatSetCenter, MpatSetCertainty, MpatSetDontCare, MpatSetNumber, MpatSetPosition, MpatSetSpeed