This interface provide functionalities of pattern matching. More...

Inheritance diagram for ILMatch:

Public Member Functions
void	GetPatCenter (double patX, double patY, double *patAngle)

LPVPatCenterMode	GetPatCenterMode ()

ILPoints *	GetPatFeature ()

void	GetPatImage (ILImage *img)

void	GetPatMask (ILImage *mask)

void	GetPatPruneMask (ILImage *mask)

BOOL	IsLearnt ()

LPVErrorCode	Learn (ILImage img, ILRegion region)

LPVErrorCode	LearnWithShape (ILImage img, ILRegion region, ILRegion *shapeRegion)

LPVErrorCode	LearnWithShapeImage (ILImage img, ILRegion region, ILImage *shapeImg)

LPVErrorCode	Match (ILImage img, ILRegion region, ILMatchResults **results)

LPVErrorCode	Prune (ILImage img, ILRegion region)

void	SetPatCenter (LPVPatCenterMode centerMode, double patX, double patY, double patAngle)

Public Member Functions inherited from ILObject
ILObject *	Copy ()

LPVErrorCode	Load (LString filename)

void	Reset ()

LPVErrorCode	Save (LString filename)

BOOL	Valid ()

Properties
int	AcceptScore `[get, set]`
	The minimum acceptable score, in range from 1 to 100. Higher score indicates more strict evaluation standard. The searching wouldn't go through all candidates. It firstly sort the candidates by its approximate similarity to template, then optimize their position/angle/scale to sub-pixel level one-by-one. It stops if there are enough results met the specified acceptable score.

int	AccuracyLevel `[get, set]`
	Accuracy level for the matching, higher level usually means more accurate and stable result but slower. It should be either 0(Low), 1(Middle, default) or 2(High).

int	AngleBias `[get, set]`
	The angle bias in range from -180 to 180. By default, it's 0.

int	AngleTolerance `[get, set]`
	The angle tolerance in range from 0 to 180. By default, it's 5. The matching angle range is based on the bias and tolerance as \( AngleBias \pm AngleTolerance \) .

double	DetailLevel `[get, set]`
	Level of detail of the pattern template, in range of 0 ~ 1. By default, it's set to 0.5. Higher level indicates more details contained in the trained template, while it may introduce more noise and slow down the detection. You should set the proper detail level firstly, then train the template via Learn(), since the template features should be re-extracted again in the training process. If at the same time DetailLevel and ShortThreshold / WeakThreshold is specified, we'll filter according to ShortThreshold / WeakThreshold firstly, then adjust to the required detail level. . More...

BOOL	ExcludeBoundary `[get, set]`
	Whether to exclude the matching result on the boundary of the input image or region.

int	GrayValueWeight `[get, set]`
	The combination weight of the evaluation score based on the similarity of the matching result and the template image, using normalized cross correlation (NCC). By default, it's 0, means the gray score does not take any effect. The final score of the result is calculated as: \( Score = Score_{shape} \times (1 - w) + Score_{gray} \times w \) .

BOOL	IgnoreMissing `[get, set]`
	Whether the missing parts contribute negatively to the matching result. By default is true, the missing features are ignored when scoring and missing percentage check is skipped.

BOOL	IgnorePolarity `[get, set]`
	Whether to ignore polarity in matching. By default, it's off.

BOOL	IsotropicScale `[get, set]`
	Whether to keep aspect ratio when scaling, default to true.

int	MaxCount `[get, set]`
	The expected maximum count of the matching results.

int	MissingTolerance `[get, set]`
	The maximum acceptable missing rate of the matching features in percentage. The value range is 0 ~ 100. By default, it's 50, means 50% missing is acceptable. Note missing part check is only enabled when IgnoreMissing is false.

int	Overlap `[get, set]`
	The maximum acceptable overlap between the nearby matching results in percentage. The value range is 1 ~ 80. By default, it's 50, means 50% overlap. The recommended setting is around 30 ~ 70.

int	ScaleBias `[get, set]`
	The scale bias in range from 50 to 150%. By default, it's 100.

int	ScaleTolerance `[get, set]`
	The scale tolerance in range from 0 to 50%. By default, it's 0. The matching scale range is based on the bias and tolerance as \( ScaleBias \pm ScaleTolerance \) .

int	ShortThreshold `[get, set]`
	The short threshold is used to filter trained feature points extracted from short edge segments. It's a 0 ~ 100 percentage value related to the longer side of the training image or region, aka. the actual threshold is calculated as \( Max(Width, Height) \times ShortThreshold / 100 \) By default, it's set to 0 to skip the filtering. You should set the proper short threshold firstly, then train the template via Learn(), since the template features should be re-extracted again in the training process. More...

BOOL	StrictScore `[get, set]`
	Whether to enable strict scoring in matching. By default, it's off. If it's on, scoring is done on the original image with most detail information. If it's off, scoring is done on the scaled and smoothed image which is much faster but with less detail.

BOOL	UseCache `[get, set]`
	Whether to make use of cache in matching, it will slightly speed up the matching while consume more memory. By default, it's on.

int	WeakThreshold `[get, set]`
	The weak threshold is used to filter trained feature points of low contrast, in range of 0 ~ 100. By default, it's set to 0 to skip the filtering. You should set the proper weak threshold firstly, then train the template via Learn(), since the template features should be re-extracted again in the training process. More...

Detailed Description

This interface provide functionalities of pattern matching.

Pattern detector is designed to single or multiple instances of the trained pattern in the given image and region.
The algorithm is real-time and of sub-pixel accuracy. Detection is based mainly on shape information extracted from pattern template, with combination of the gray-scale features. It's robust to translation, scale and rotation of the pattern objects, as well as the lightening or material changes in production line which results in intensity, contrast or blurring in input images.

To use this interface, you should create a LMatch object.

Example Code

Member Function Documentation

◆ GetPatCenter()

void GetPatCenter	(	double *	patX,
		double *	patY,
		double *	patAngle
	)

Get the center of the pattern template.

Parameters

[out]	patX	The x-coordinate of the template center.
[out]	patY	The y-coordinate of the template center.
[out]	patAngle	The angle of the template center.

See also: SetPatCenter().

◆ GetPatCenterMode()

LPVPatCenterMode GetPatCenterMode ( )

Get the center mode of the pattern template.

Return values

centerMode The mode of the pattern center, see LPVPatCenterMode.

See also: SetPatCenter().

◆ GetPatFeature()

ILPoints* GetPatFeature ( )

Get the feature points of trained pattern.

Return values

featurePoints Return the feature points.

◆ GetPatImage()

void GetPatImage ( ILImage * img )

Get the pattern template image.

Parameters

[out] img Return the image.

◆ GetPatMask()

void GetPatMask ( ILImage * mask )

Get the pattern template mask.

Parameters

[out] mask Return the mask. It will be an empty image, if the template has no mask.

◆ GetPatPruneMask()

void GetPatPruneMask ( ILImage * mask )

Get the prune mask.

Parameters

[out] mask Return the mask. It will be an empty image, if the template has been pruned.

See also: Prune().

Since: 2.1.0

◆ IsLearnt()

BOOL IsLearnt ( )

Check whether the LMatch object is well-trained.

Return values

val	Return True if it's trained, otherwise, return False.

◆ Learn()

LPVErrorCode Learn	(	ILImage *	img,
		ILRegion *	region
	)

Learn the pattern template features from the provided image. The template center can be modified later.

Parameters

[in]	img	The input image
[in]	region	The input region, to limit the region of pattern template on the input image and also exclude some not-care pixels.

Return values

error Return error code if anything is wrong. It may fail if we found no proper feature on the input image.

See also: IsLearnt(), SetPatCenter(), Load(), Match(), LearnWithShape(), LearnWithShapeImage().

◆ LearnWithShape()

LPVErrorCode LearnWithShape	(	ILImage *	img,
		ILRegion *	region,
		ILRegion *	shapeRegion
	)

Learn the pattern template features from the provided image. The template center can be modified later.
The shape and polarity of the template features is described with the given shape region, adding a region produce a white-on-black shape while subtracting a region produce a black-on-white shape.
The feature points are extracted from the given shape region, thus not affected by DetailLevel.

Parameters

[in]	img	The input image. It is optional, but GrayValueWeight does not take any effect when the source image is absent.
[in]	region	The optional input region, to limit the region of pattern template on the input image. and also exclude some unwanted pixels and shape.
[in]	shapeRegion	The input shape region used to generate the template shape. It should be related to the coordinates of the input image, as same as the region parameter.

Return values

error Return error code if anything is wrong. It may fail if we found no proper feature on the input image.

Example: LearnWithShape.cpp/cs

See also: Learn(), LearnWithShapeImage().

◆ LearnWithShapeImage()

LPVErrorCode LearnWithShapeImage	(	ILImage *	img,
		ILRegion *	region,
		ILImage *	shapeImg
	)

Learn the pattern template features from the provided image. The template center can be modified later.
The shape and polarity of the template features are extracted from the shape image.
The feature points are extracted from the given shape image, thus not affected by DetailLevel.

Parameters

[in]	img	The input image. It is optional, but GrayValueWeight does not take any effect when the source image is absent.
[in]	region	The optional input region, to limit the region of pattern template on the input image. and also exclude some unwanted pixels and shape.
[in]	shapeImg	The shape image. It should have the same size as the image parameter.

◆ Match()

LPVErrorCode Match	(	ILImage *	img,
		ILRegion *	region,
		ILMatchResults **	results
	)

Match on the provided image. The returned positions are based on image coordinates.

Parameters

[in]	img	The input image
[in]	region	The input region, to limit the region of matching.
[out]	results	Return the matching results.

Return values

error Return error code if anything is wrong.

◆ Prune()

LPVErrorCode Prune	(	ILImage *	img,
		ILRegion *	region
	)

Prune the trained template features. The trained features outside of the given region are eliminated.

Parameters

[in]	img	The input image
[in]	region	The input region. Pass in null region to restore the features to original.

Return values

error Return error code if anything is wrong. It fails if all the features are removed.

Example: EditPattern.cpp/cs

See also: Learn(), LearnWithShape(), LearnWithShapeImage(), GetPatPruneMask().

Since: 2.1.0

◆ SetPatCenter()

void SetPatCenter	(	LPVPatCenterMode	centerMode,
		double	patX,
		double	patY,
		double	patAngle
	)

Customize the center of the pattern template. By default, we use the template image center as pattern center.
The template center indicates the report position of the matching result. For example, if the template center is moved to the left-top corner of the template image, we'll then always report the same left-top corner as the matching result.

Parameters

[in]	centerMode	The mode of the pattern center, see LPVPatCenterMode.
[in]	patX	The x-coordinate of the user-specified center, it's ignored if use other mode.
[in]	patY	The y-coordinate of the user-specified center, it's ignored if use other mode.
[in]	patAngle	The user-specified angle which will be used as 0 angle, it's ignored if use other mode.

See also: GetPatCenter().

Property Documentation

◆ DetailLevel

double DetailLevel

getset

Level of detail of the pattern template, in range of 0 ~ 1. By default, it's set to 0.5.
Higher level indicates more details contained in the trained template, while it may introduce more noise and slow down the detection.
You should set the proper detail level firstly, then train the template via Learn(), since the template features should be re-extracted again in the training process.
If at the same time DetailLevel and ShortThreshold / WeakThreshold is specified, we'll filter according to ShortThreshold / WeakThreshold firstly, then adjust to the required detail level.
.

See also: Learn(), WeakThreshold, ShortThreshold

◆ ShortThreshold

int ShortThreshold

getset

The short threshold is used to filter trained feature points extracted from short edge segments. It's a 0 ~ 100 percentage value related to the longer side of the training image or region, aka. the actual threshold is calculated as \( Max(Width, Height) \times ShortThreshold / 100 \) By default, it's set to 0 to skip the filtering.
You should set the proper short threshold firstly, then train the template via Learn(), since the template features should be re-extracted again in the training process.

See also: Learn(), DetailLevel, WeakThreshold

Since: 2.2.1

◆ WeakThreshold

int WeakThreshold

getset

The weak threshold is used to filter trained feature points of low contrast, in range of 0 ~ 100. By default, it's set to 0 to skip the filtering.
You should set the proper weak threshold firstly, then train the template via Learn(), since the template features should be re-extracted again in the training process.

See also: Learn(), DetailLevel, ShortThreshold

Since: 2.2.1

Public Member Functions

Properties

Detailed Description

Example Code

Member Function Documentation

◆ GetPatCenter()

◆ GetPatCenterMode()

◆ GetPatFeature()

◆ GetPatImage()

◆ GetPatMask()

◆ GetPatPruneMask()

◆ IsLearnt()

◆ Learn()

◆ LearnWithShape()

◆ LearnWithShapeImage()

◆ Match()

◆ Prune()

◆ SetPatCenter()

Property Documentation

◆ DetailLevel

◆ ShortThreshold

◆ WeakThreshold