You are here: Start » AVL.NET » AVL.LocateMultipleObjects_Edges


Finds all occurrences of a predefined template on an image by comparing object edges.



public static void LocateMultipleObjects_Edges
	AvlNet.Image inImage,
	NullableRef<AvlNet.Region> inSearchRegion,
	AvlNet.EdgeModel inEdgeModel,
	int inMinPyramidLevel,
	int? inMaxPyramidLevel,
	float inEdgeThreshold,
	AvlNet.EdgePolarityMode inEdgePolarityMode,
	AvlNet.EdgeNoiseLevel inEdgeNoiseLevel,
	bool inIgnoreBoundaryObjects,
	float inMinScore,
	float inMinDistance,
	IList<AvlNet.Object2D> outObjects,
	NullableRef<SafeList<SafeList<AvlNet.Path>>> outObjectEdges,
	NullableValue<int> outPyramidHeight,
	IList<AvlNet.Image> diagEdgePyramid,
	IList<AvlNet.Image> diagMatchPyramid,
	IList<List<float>> diagScores


Name Type Range Default Description
inImageAvlNet.ImageImage on which object occurrences will be searched.
inSearchRegionAvlNet.NullableRef<AvlNet.Region>Region of possible object centers. Default value: atl::NIL.
inEdgeModelAvlNet.EdgeModelModel of objects to be searched.
inMinPyramidLevelint<0, 12>0Defines the lowest pyramid level at which object position is still refined. Default value: 0.
inMaxPyramidLevelint?<0, 12>3Defines the total number of reduced resolution levels that can be used to speed up computations. Default value: 3.
inEdgeThresholdfloat<0.01f, INF>10.0fMinimum strength of edges used for matching with the model. Default value: 10.0f.
inEdgePolarityModeAvlNet.EdgePolarityModeMatchStrictlyDefines how edges with reversed polarity will contribute to the object score. Default value: MatchStrictly.
inEdgeNoiseLevelAvlNet.EdgeNoiseLevelHighDefines how much noise the objects edges have. Default value: High.
inIgnoreBoundaryObjectsboolFalseFlag indicating whether objects crossing image boundary should be ignored or not. Default value: False.
inMinScorefloat<0.0f, 1.0f>0.7fMinimum score of object candidates accepted at each pyramid level. Default value: 0.7f.
inMinDistancefloat<0.0f, INF>10.0fMinimum distance between two found objects. Default value: 10.0f.
outObjectsSystem.Collections.Generic.IList<AvlNet.Object2D>Found objects.
outObjectEdgesAvlNet.NullableRef<AvlNet.SafeList<AvlNet.SafeList<AvlNet.Path>>>Model edges of the found objects. Can be null to skip this parameter calculation.
outPyramidHeightAvlNet.NullableValue<int>Highest pyramid level used to speed up computations. Can be null to skip this parameter calculation.
diagEdgePyramidSystem.Collections.Generic.IList<AvlNet.Image>Image edges used for matching at each pyramid level.
diagMatchPyramidSystem.Collections.Generic.IList<AvlNet.Image>Candidate object locations found at each pyramid level.
diagScoresSystem.Collections.Generic.IList<System.Collections.Generic.List<float>>Scores of the found objects at each pyramid level.


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. The inMinDistance parameter determines minimum distance between any two valid occurrences (if two occurrences lie closer than inMinDistance from each other, the one with greater score is considered to be valid).

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 outObjects.Point array contains the model reference points of the matched object occurrences. The corresponding outObjects.Angle array contains the rotation angles of the objects. The corresponding outObjects.Match array provides information about both the position and the angle of each match combined into value of Rectangle2D type. Each element of the outObjects.Alignment array contains informations about the transform required for geometrical objects defined in the context of template image to be transformed into object in the context of corresponding outObjects.Match position. This array can be later used e.g. by 1D Edge Detection or Shape Fitting categories filters.


Following example locates an EdgeModel object for loaded mounts.jpg image. It is a part of the bigger Basic Template Matching Example.

List<Object2D> matches = new List<Object2D>();

AVL.LoadImage("mounts.jpg", false, inspectingImage);

if (model.HasValue)
        0, 10.0f,
        false, 0.8f, 20.0f,

Locating multiple objects with the edge-based method.


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.

Hardware acceleration settings may be manipulated with Settings class.

Function Overrides

See also