IMAQ Match Pattern 4

Download PDF

Updated2023-02-21
13 minute(s) read

Owning Palette: Searching and Matching
Requires: NI Vision Development Module

Searches for a pattern, or template image, in an inspection image. Run the IMAQ Learn Pattern 5 VI before this VI to configure the template image for the matching phase.

For more information on Pattern Matching, refer to Advanced Pattern Matching Concepts.

Examples

Supported Image Types

8-bit unsigned grayscale 16-bit unsigned grayscale 16-bit signed grayscale

IMAQ Match Pattern 4

Algorithm specifies the pattern matching algorithm to use to search the Template Image in Image.

Refer to the NI Vision Concepts Help for in-depth information about each algorithm.

Low Discrepancy Sampling (0)	Uses a low discrepancy sampling algorithm. This algorithm extracts the most significant information to represent an image. Use one of the pyramidal matching algorithms instead if your template contains large regions of similar grayscale information, has a wide aspect ratio, or if it is very small.
Grayscale Value Pyramid (1)	Uses a grayscale value pyramid algorithm. This algorithm uses normalized gray values as features. It is useful when the template does not contain structured information but has intricate textures for dense edges.
Gradients Pyramid (2)	Uses a gradient pyramid algorithm. This algorithm uses filtered edge pixels as features. It is more resistant to occlusion and intensity changes as compared to the Grayscale Value Pyramid, and is often faster because of smaller amount of data. However, the strength and reliability of edges reduces at very low resolutions. This method requires the user to work at higher resolutions as compared to the Grayscale Value Pyramid method.

Image is a reference to the inspection image in which you want to search for the template image.

Template Image is a reference to the template for which you want to search during the matching phase. The template image is an output of the IMAQ Learn Pattern 5 VI.

ROI Descriptor specifies the region of the inspection image in which to perform pattern matching. This region must be a single rectangle or rotated rectangle contour. By default, the VI uses the entire inspection image for matching.

Global Rectangle contains the coordinates of the bounding rectangle.

Contours are each of the individual shapes that define an ROI.

	ID refers to whether the contour is the external or internal edge of an ROI.
	Type is the shape type of the contour.
	Coordinates indicates the relative position of the contour.

Parameters contains the parameters which are used to control the matching process.

Number of Matches Requested is the number of valid matches expected.

Minimum Match Score is the smallest score a match can have to be considered valid. The data range for a match is between 0 and 1000.

Angle Ranges is an array of angle ranges, where each range specifies how much you expect the template to rotate in the inspection image.

	Start Angle specifies the starting angle of the template.
	End Angle specifies the ending angle of the template.

error in (no error) describes the error status before this VI or function runs. The default is no error. If an error occurred before this VI or function runs, the VI or function passes the error in value to error out. This VI or function runs normally only if no error occurred before this VI or function runs. If an error occurs while this VI or function runs, it runs normally and sets its own error status in error out. Use the Simple Error Handler or General Error Handler VIs to display the description of the error code. Use error in and error out to check errors and to specify execution order by wiring error out from one node to error in of the next node.

	status is TRUE (X) if an error occurred before this VI or function ran or FALSE (checkmark) to indicate a warning or that no error occurred before this VI or function ran. The default is FALSE.
	code is the error or warning code. If status is TRUE, code is a nonzero error code. If status is FALSE, code is 0 or a warning code.
	source describes the origin of the error or warning and is, in most cases, the name of the VI or function that produced the error or warning. The default is an empty string.

Advanced Options sets a variety of algorithm-related options to use during the matching phase. If input is empty, Advanced Options stored in Template Image using IMAQ Set Preset Match Options or IMAQ Set Advanced Match Options will be used. If the input contains any Preset-Parameter, the provided advanced options will override any Advanced Options stored in Template Image.

Item determines the option you want to use during the matching phase. The following values are possible:

* Indicates the Advanced Option is a Preset-Parameter.

LD Sampling - Minimum Contrast* (0)	Specifies the minimum expected difference between the maximum pixel value and the minimum pixel value in the inspection image.
LD Sampling - Enable Supixel Accuracy* (1)	Determines whether to return the match results with subpixel accuracy. Set this option to 1 to enable subpixel accuracy. The default value is 0, which disables subpixel accuracy.
LD Sampling - Search Strategy* (2)	Specifies the aggressiveness of the search strategy available during the matching phase. Three types of search strategies are available. The default is 2. Conservative—Extracts template information for Conservative matching only. Balanced—Extracts template information for Balanced and Conservative matching. Aggressive—Extracts template information for Aggressive, Balanced, and Conservative matching.
LD Sampling - Subpixel Iterations* (3)	Specifies the maximum number of incremental improvements used to refine matches using subpixel information. The minimum value for this option is 20.
LD Sampling - Subpixel Tolerance* (4)	Specifies the maximum amount of change, in pixels, between consecutive incremental improvements in the match position before the VI stops refining the match position. The default value is 0, which specifies that the VI should always use a number of refinements equal to Subpixel Iterations. If you provide values for both Subpixel Iterations and Subpixel Tolerance, the VI refines the match for, at most, Subpixel Iterations but may stop early if Subpixel Tolerance is satisfied.
LD Sampling - Initial Match List Length* (5)	Specifies the maximum size of the match list. The match list contains the regions in the inspection image that have the highest probability of containing a match. The minimum value for this option is 5. The default value is 200.
LD Sampling - Match List Reduction Factor* (6)	Specifies the reduction of the match list as matches are refined. The default is 5.
LD Sampling - Initial Step Size* (7)	Specifies the number of template pixels that you want to include in a sample for the initial phase of matching. The default is 0, which allows the algorithm to compute the Initial Sample Size. For optimal speed, the VI coerces sizes that are less than 240 to an integer multiple of 12 and coerces sizes greater than 240 to an integer multiple of 60.
LD Sampling - Intermediate Angular Accuracy* (8)	Sets the angle accuracy, in degrees, to use during the final phase of the matching. The default is 1 degree. Use subpixel accuracy to achieve angle accuracy less than the default. This value must be no greater than the value for Initial Angular Accuracy. The VI coerces the angle to the largest integer smaller than it that evenly divides 360. This option is not used in conjunction with the Aggressive search strategy.
Pyramid - Max Pyramid Level* (100)	Specifies the pyramid level at which the coarse-to-fine matching begins. The higher this value the faster the matching will be. Thus, setting this to 0 will lead to a very large match time. All values higher than the maximum allowed pyramid level (automatically computed during learning the template) are coerced to the maximum allowed level. The default value is set to the optimal pyramid level (automatically computed during learning the template). Note that setting this value lower than the Max Pyramid Level To Store Data (used in learning the template) is not allowed, as the required data for coarse matching will be missing. The IMAQ Get Template Information VI can be used to obtain the various pyramid levels used while learning the template and this parameter can then be set accordingly.
Pyramid - Minimum Contrast* (102)	Specifies the minimum contrast to consider the image region for matching. Any image region lower than minimum contrast will be skipped for matching, which improves performance.
Pyramid - Enable Subpixel Accuracy* (103)	Determines whether to return the match results with subpixel accuracy. Set this option to 1 to enable subpixel accuracy. The default value is 0, which disables subpixel accuracy.
Pyramid - Subpixel Iterations* (104)	Specifies the maximum number of incremental improvements used to refine matches using subpixel information. The minimum value for this option is 20.
Pyramid - Subpixel Tolerance* (105)	Specifies the maximum amount of change, in pixels, between consecutive incremental improvements in the match position before the VI stops refining the match position. The default value is 0, which specifies that the VI should always use a number of refinements equal to Subpixel Iterations. If you provide values for both Subpixel Iterations and Subpixel Tolerance, the VI refines the match for, at most, Subpixel Iterations but may stop early if Subpixel Tolerance is satisfied.
Pyramid - Inital Match List Length* (106)	Specifies the maximum size of the match list. The match list contains the regions in the inspection image that have the highest probability of containing a match. The minimum value for this option is 5. The default value is 200 for shift matching, and 300 for rotation matching. The value of -1 indicates that the algorithm will calculate the optimum value of the size of the match list for the given case.
Pyramid - Match List Reduction Factor* (107)	Specifies the reduction of the match list as matches are refined. The default value is 1, which results in no reduction.
Pyramid - Intermediate Angular Accuracy* (108)	Specifies the angular accuracy used for initial coarse matching when rotation is present. The default value is 6 degrees. Setting this value too high creates the risk of losing out matches.
Pyramid - Process Border Matches* (109)	Specifies whether to search for partial (border matches) or not. Note that the border could either be the image border or the border of the supplied ROI region. Turning this parameter on increases the match time, especially for larger templates. The default value is TRUE.
Pyramid - Min Match Separation Distance* (111)	Specifies the minimum separation distance, in pixels, between the origins of two matches that have unique positions. The VI does not return matches that have the same position and angle. The default value is 20.
Pyramid - Min Match Separation Angle* (112)	Specifies the minimum angular difference, in degrees, between two matches that have unique angles. The VI does not return matches that have the same position, scale, and angle. The default value is 10.
Pyramid - Max Match Overlap* (113)	Specifies the maximum amount of overlap, expressed as a percentage, allowed between the bounding rectangles of two matches. The default value is 20.
Pyramid - Max Cache in MB* (114)	Specifies the maximum cache size to use while matching for rotation. The cache is used to control the size of the template data in memory while matching. Cases where successive search images are expected to have matches which are either at same angle or at angles belonging to a small set of recurring values will see maximum cache utilization and speed-ups. The default value is 25 Megabytes for Windows and NI Linux Real Time systems and 5 Megabytes for VxWorks based NI Real Time systems.
Pyramid - Clear Cache* (115)	Specifies whether or not to flush the cache after every match. Turning this ON will take away the caching benefits seen for successive match images having matches at the same angle or at recurring angles. The default value is OFF.
Pyramid - Enable Accurate Score Computation* (116)	Specifies whether to calculate an accurate score for the match based on subpixel location.
Pyramid - Interpolation Method for Accurate Score Computation* (117)	Specifies the interpolation algorithm to be used while calculating the score. The image is interpolated using either of the below algorithms. 0 - Zero Order - No Interpolation 1 - Bilinear - The intermediate pixels are linearly interpolated. This is the default value.
Pyramid - Enable Target to Template Score* (118)	Set this to 1 to enable recomputing Match Score based on higher match regions between the template and matched section of the image. For Example, if a matched object is occluded, Target to Template Score may remove occluded regions from score computation and consider the regions which are matching with the template.
Enable Defect Map (200)	Specifies whether or not to calculate the defect map between the template and match image. The default value is OFF.

Value is the value of the option you want to use during the matching phase.

Image (duplicate) is a reference to the inspection image in which you want to search for the trained pattern.

Matches (pixel) is an array of match clusters, in pixel coordinates.

	Position is a point-coordinate cluster corresponding to the center of the template.
	Angle is the rotation angle of the template in the source image at the current match location.
	Scale is the change in percentage size of the matched template from the original template. This parameter is not used for pattern matching, and is always set to 1.
	Score ranks the match results on a scale of 0 to 1,000, where 0 equals no match and 1,000 equals a perfect match.
	Bounding Box is an array of points that define the boundary of the template pattern in the image. You can connect this array directly to the IMAQ Overlay Multiple Lines 2 VI to overlay the location of a match on your image.

Matches (real-world) is an array of match clusters, in real-world coordinates.

	Position is a point-coordinate cluster corresponding to the center of the template.
	Angle is the rotation angle of the template in the source image at the current match location.
	Scale is the change in percentage size of the matched template from the original template. This parameter is not used for pattern matching, and is always set to 1.
	Score ranks the match results on a scale of 0 to 1,000, where 0 equals no match and 1,000 equals a perfect match.
	Bounding Box is an array of points that define the boundary of the template pattern in the image. You can connect this array directly to the IMAQ Overlay Multiple Lines 2 VI to overlay the location of a match on your image.

Number of Matches is the number of template matches found in the inspection image based on the input settings.

error out contains error information. If error in indicates that an error occurred before this VI or function ran, error out contains the same error information. Otherwise, it describes the error status that this VI or function produces. Right-click the error out indicator on the front panel and select Explain Error from the shortcut menu for more information about the error.

	status is TRUE (X) if an error occurred or FALSE (checkmark) to indicate a warning or that no error occurred.
	code is the error or warning code. If status is TRUE, code is a nonzero error code. If status is FALSE, code is 0 or a warning code.
	source describes the origin of the error or warning and is, in most cases, the name of the VI or function that produced the error or warning. The default is an empty string.

Examples

Refer to the following for an example that uses this VI.

LabVIEW\examples\Vision\Pattern Matching\Pattern Matching (All).vi
LabVIEW\examples\Vision\Pattern Matching\Pattern Matching.vi

NI Vision for LabVIEW

Table of Contents

IMAQ Match Pattern 4

Supported Image Types

Examples

Log in to get a better experience