ILMatch Interface Reference

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 (int level)
void	GetPatImage (ILImage *img)
void	GetPatMask (ILImage *mask)
void	GetPatPruneMask (ILImage *mask)
LArray< ILPolygon * >	GetPatShape (int level)
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, LArray< int > shapeIdx0, LArray< int > shapeIdx1)
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. 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 \) .
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.

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

C++

ILMatchPtr matchTool = LMatch::Create();
matchTool->Learn(m_template_img, nullptr);
LPVErrorCode err = matchTool->Learn(img, roi);
if (err != LPVErrorCode::LPVNoError) return;

C#

LMatch matchTool = new LMatch();
matchTool.Learn(m_template_img, null);
LPVErrorCode err = matchTool.Learn(img, (LRegion)roi);
if (err != LPVErrorCode.LPVNoError) return;

COM

ILMatchPtr matchTool = LMatch::Create();
// or, ILMatchPtr matchTool(__uuidof(LMatch)), for absence of built-in Create functions (before 2.2.0)
matchTool->Learn(m_template_img, NULL);
LPVErrorCode err = matchTool->Learn(img, roi);
if (err != LPVErrorCode::LPVNoError) return;

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

(

int

level

)

Get the feature points of trained pattern.

Parameters

level

Specify the level of required features, possible values are -1 indicating all levels, 0 (default) for level 0 of original size, 1 for level 1 in scaled size.

Return values

featurePoints

Return the feature points.

Since

2.5.0

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

GetPatShape()

LArray< ILPolygon *> GetPatShape

(

int

level

)

Get the shape of trained pattern as polylines.

Parameters

level

Specify the level of required features, possible values are -1 indicating all levels, 0 (default) for level 0 of original size, 1 for level 1 in scaled size.

Return values

shapePolys

Return the shape polylines.

Remarks

In order to keep the indexes of shape polylines consistent, for the pruned shape polylines via Prune(), we'll return empty LPolygon objects in the shape polylines.

See also

Prune().

Since

2.5.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,
		LArray< int >	shapeIdx0,
		LArray< int >	shapeIdx1
	)

Prune the trained template features, eliminate the features which are located outside of the given region or belong to the shape polylines of the given indexes.
Pass in null region and empty shape indexes to restore the features to original.

Parameters

[in]	img	The input image
[in]	region	The input region.
[in]	shapeIdx0	The indexes of shape polylines in level 0 to be removed
[in]	shapeIdx1	The indexes of shape polylines in level 1 to be removed

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

See also

Learn()