MpatAllocModel()函数

Synopsis

Allocate a pattern matching model from a source image.

Format

MIL_ID MpatAllocModel(SystemId, SrcImageBufId, OffX, OffY, SizeX, SizeY, ModelType, ModelIdPtr)

MIL_ID SystemId;	System identifier
MIL_ID SrcImageBufId;	Source image buffer
long OffX;	X-coordinate of model origin within an image
long OffY;	Y-coordinate of model origin within an image
long SizeX;	Model width
long SizeY;	Model height
long ModelType;	Model type
MIL_ID *ModelIdPtr;	Storage location for model identifier

Description

This function allocates a model, using data from the specified area of the model source image.

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.

The OffX and OffY parameters specify the origin coordinates of the model in the specified model image (SrcImageBufId).

The SizeX and SizeY parameters specify the width and height of the model. This data is extracted from the model image starting from the specified origin.

The given model width (SizeX), height (SizeY), and position (OffX, OffY) must be valid in the model image.

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).

Normalized 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:

Positional accuracy:	M_MEDIUM (+/-) 0.25 pixels
Expected position:	M_ALL (full image)
Positional uncertainty:	M_ALL (full image)
Search number:	1
Search speed:	M_MEDIUM
Acceptance level:	70%
Certainty level:	80%
Search angle:	0°
Center of model	An integer value equal to ((SizeX – 1) / 2, (SizeY – 1) / 2) (relative to the model origin).

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 ModelIdPtr parameter specifies the address of the variable in which the model identifier is to be written. This identifier is required to use the model with other pattern recognition functions. Since MpatAllocModel also returns the model identifier, you can set this parameter to M_NULL.

Returned value

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

Status

• ?This function currently supports only unsigned 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, MpatSetAcceptance, MpatSetAccuracy, MpatSetCenter, MpatSetCertainty, MpatSetDontCare, MpatSetNumber, MpatSetPosition, MpatSetSpeed, MpatAllocAutoModel