Back to Aurora Vision Library website

You are here: Start » Function Reference » Computer Vision » Template Matching » LocateSingleObject_Edges2

LocateSingleObject_Edges2


Header: AVL.h
Namespace: avl
Module: MatchingPro

Finds a single occurrence of a predefined template on an image by comparing object edges.

Applications: Detection of an object whose outlines are sharp and rigid. Often one of the first filters in a program.

Syntax

C++
C#
 
void avl::LocateSingleObject_Edges2
(
	const avl::Image& inImage,
	atl::Optional<const avl::ShapeRegion&> inSearchRegion,
	atl::Optional<const avl::CoordinateSystem2D&> inSearchRegionAlignment,
	const avl::EdgeModel2& inEdgeModel,
	int inMinPyramidLevel,
	atl::Optional<int> inMaxPyramidLevel,
	float inEdgeThreshold,
	avl::EdgePolarityMode::Type inEdgePolarityMode,
	avl::EdgeNoiseLevel::Type inEdgeNoiseLevel,
	bool inIgnoreBoundaryObjects,
	int inMaxDeformation,
	float inMinScore,
	atl::Conditional<avl::Object2D>& outObject,
	atl::Optional<atl::Conditional<atl::Array<avl::Path>>&> outObjectEdges = atl::NIL,
	atl::Optional<int&> outPyramidHeight = atl::NIL,
	atl::Optional<avl::ShapeRegion&> outAlignedSearchRegion = atl::NIL,
	atl::Array<avl::Image>& diagEdgePyramid,
	atl::Array<avl::Image>& diagMatchPyramid,
	atl::Conditional<atl::Array<float> >& diagScores
)

Parameters

Name Type Range Default Description
Input value
inImage const Image& Image on which object occurrence will be searched
Input value
inSearchRegion Optional<const ShapeRegion&> NIL Region of possible object centers
Input value
inSearchRegionAlignment Optional<const CoordinateSystem2D&> NIL Adjusts the region of interest to the position of the inspected object
Input value
inEdgeModel const EdgeModel2& Model of objects to be searched
Input value
inMinPyramidLevel int 0 - 12 0 Defines the lowest pyramid level at which object position is still refined
Input value
inMaxPyramidLevel Optional<int> 0 - 12 3 Defines the total number of reduced resolution levels that can be used to speed up computations
Input value
inEdgeThreshold float 0.01 - 10.0f Minimum strength of edges used for matching with the model
Input value
inEdgePolarityMode EdgePolarityMode::Type MatchStrictly Defines how edges with reversed polarity will contribute to the object score
Input value
inEdgeNoiseLevel EdgeNoiseLevel::Type High Defines how much noise the object edges have
Input value
inIgnoreBoundaryObjects bool False Flag indicating whether objects crossing image boundary should be ignored or not
Input value
inMaxDeformation int 0 - 0 Maximal distance in pixels between model edge and an edge visible in the input image
Input value
inMinScore float 0.0 - 1.0 0.7f Minimum score of object candidates accepted at each pyramid level
Output value
outObject Conditional<Object2D>& Found object
Output value
outObjectEdges Optional<Conditional<Array<Path>>&> NIL Model edges of the found object
Output value
outPyramidHeight Optional<int&> NIL Highest pyramid level used to speed up computations
Output value
outAlignedSearchRegion Optional<ShapeRegion&> NIL Transformed input shape region
Diagnostic input
diagEdgePyramid Array<Image>& Image edges used for matching at each pyramid level
Diagnostic input
diagMatchPyramid Array<Image>& Candidate object locations found at each pyramid level
Diagnostic input
diagScores Conditional<Array<float> >& Scores of the found object at each pyramid level

Optional Outputs

The computation of following outputs can be switched off by passing value atl::NIL to these parameters: outObjectEdges, outPyramidHeight, outAlignedSearchRegion.

Read more about Optional Outputs.

Description

The operation matches the object model, inEdgeModel, against the input image, inImage. The inSearchRegion region restricts the search area so that only in this region the centers of the objects can be presented. The inMinScore parameter determines the minimum score of the valid object occurrence.

In the inImage every pixel with gradient's magnitude at least inEdgeThreshold is considered an edge pixel. Only those are later used during the matching process. To establish the value of this threshold properly the diagEdgePyramid output which shows all the edges with sufficient gradient's magnitude may be used. If the inEdgePolarityMode parameter is set to Ignore, the object occurrences in the inImage image do not have necessarily to have the same contrast as the object in the model image.

The computation time of the filter depends on the size of the model, the sizes of inImage and inSearchRegion, but also on the value of inMinScore. This parameter is a score threshold. Based on its value some partial computation can be sufficient to reject some locations as valid object instances. Moreover, the pyramid of the images is used. Thus, only the highest pyramid level is searched exhaustively, and potential candidates are later validated at lower levels. The inMinPyramidLevel parameter determines the lowest pyramid level used to validate such candidates. Setting this parameter to a value greater than 0 may speed up the computation significantly, especially for higher resolution images. However, the accuracy of the found object occurrences can be reduced. Larger inMinScore generates less potential candidates on the highest level to verify on lower levels. It should be noted that some valid occurrences with score above this score threshold can be missed. On higher levels score can be slightly lower than on lower levels. Thus, some valid object occurrences which on the lowest level would be deemed to be valid object instances can be incorrectly missed on some higher level. The diagMatchPyramid output represents all potential candidates recognized on each pyramid level and can be helpful during the difficult process of the proper parameter setting.

The outObject.Point contains the model reference point of the matched object occurrence. The outObject.Angle contains the rotation angle of the object. The outObject.Match provides information about both the position and the angle of the found match combined into value of Rectangle2D type. The outObject.Alignment contains information about the transform required for geometrical objects defined in the context of template image to be transformed into object in the context of outObject.Match position. This value can be later used e.g. by 1D Edge Detection or Shape Fitting categories filters.

Hints

  • You can use EnhanceSingleObjectMatch filter to fine-tune the results. A great example of usage is presented in the CreateGoldenTemplate2 filter.
  • If an object is not detected, first try decreasing inMaxPyramidLevel, then try decreasing inMinScore.
  • If all the expected objects are correctly detected, try achieving higher performance by increasing inMaxPyramidLevel and inMinScore.
  • Please note, that due to the pyramid strategy used for speeding-up computations, some objects whose score would finally be above inMinScore may be not found. This may be surprising, but this is by design. The reason is that the minimum value is used at different pyramid levels and many objects exhibit lower score at higher pyramid levels. They get discarded before they can be evaluated at the lowest pyramid level. Decrease inMinScore experimentally until all objects are found.
  • If precision of matching is not very important, you can also gain some performance by increasing inMinPyramidLevel.
  • If the performance is still not satisfactory, go back to model definition and try reducing the range of rotations and scaling as well as the precision-related parameters: inAnglePrecision, inScalePrecision and inEdgeCompleteness.
  • To obtain high accuracy of matching make sure that the edges visible on the diagEdgePyramid output are not too thick. Increase inEdgeThreshold to make them thinner.
  • Also consider increasing inEdgeThreshold if there is much noise on the diagEdgePyramid output.
  • Verify accuracy of the matching by checking the outObjectEdges output. If the accuracy is lower than expected, make sure that inMinPyramidLevel = 0, try increasing inEdgeThreshold and also consider higher values for inAnglePrecision during model creation.
  • To further improve matching accuracy use the EnhanceSingleObjectMatch filter.
  • If the object being detected can be darker or brighter than the background on different images, use the inEdgePolarityMode parameter set to Ignore.
  • If the object being detected is only partially visible or its shape and the model shape are not identical, use the inEdgePolarityMode parameter set to MatchWeakly.
  • If there is only low noise in the object edges, use the inEdgeNoiseLevel parameter set to Low.
  • Define inSearchRegion to limit possible object locations and speed-up computations. Please note, that this is the region where the outObject.Point results belong to (and NOT the region within which the entire object has to be contained).

Examples

Locating a single object with the edge-based method (inMaxPyramidLevel = 3). Background clutter and glares are efficiently ignored.

Remarks

Read more about Local Coordinate Systems in Machine Vision Guide: Local Coordinate Systems.

Additional information about Template Matching can be found in Machine Vision Guide: Template Matching

Hardware Acceleration

This operation supports automatic parallelization for multicore and multiprocessor systems.

See Also