This topic contains the following sections.
The CNLSearch edit control provides a graphical user interface (GUI) for the CogCNLSearchTool vision tool and its components. The CNLSearch tool lets you search for trained patterns of pixel values in images. You use the CNLSearch tool by first training part or all of a training image as a trained pattern, then searching for that trained pattern in one or more search images.
You train a pattern by grabbing a pattern training image, specifying the training region and pattern origin and other training parameters, then training the pattern. You search for the trained pattern by supplying a search image and specifying search parameters.
The CNLSearch edit control includes the following components:
- A row of control buttons at the top left.
- A tool display window that can display the CNLSearch tool image buffers: Current.TrainImage, Current.InputImage, and LastRun.InputImage. These buffers contain the trained pattern, the search image in which the CNLSearch tool searches for the pattern, and the same image with the results of the search. Right click the tool display to bring up menu options that include zooming in or out of the image or showing a pixel or subpixel grid.
- A set of tabs organized by function. These functions include parameter settings to run the tool, parameter settings for the search region of interest, display settings for the tool displays, and training results. Pressing the Control + Tab keys scrolls through the set of tabs.
- A status bar at the bottom left of the control. A green circle indicates that the tool ran successfully; red means the tool ran unsuccessfully. The status bar also displays the time to run the tool and any error codes or messages. The first time that the status bar displays is the raw tool execution time. The second includes the time needed to update the edit control. Controls only update when they are visible.
The following table describes the buttons at the top left of the edit control.
| Button | Description |
 | Runs the CNLSearch tool. You must have an image available in the Current.InputImage buffer (equivalent to the InputImage). This button invokes the Run method. Note that you must have already trained a pattern. |
 | Toggles electric mode. When selected, the CNLSearch tool runs automatically if certain parameters have changed. When the edit control is in electric mode, these parameters are indicated by electric bolt icons. |
 | Opens or closes the local tool display window. This window has a selection box that you use to specify the image buffer you want to view. |
 | Opens one or more floating tool display windows, providing an additional tool display window. As with the local tool display window, you can specify the image buffer to view. |
 | Loads a VisionPro persistence (.vpp) file, which contains a set of saved properties for this vision tool object type. Loading a persistence file for another object type throws an error and the load is unsuccessful. For more information about VisionPro persistence features, see the topic Persistence in VisionPro. |
 | Saves the current properties of the underlying tool to a VisionPro persistence file. You have the option to save either the entire tool or the tool without its images or results. |
 | Saves the current properties of the underlying tool to a new VisionPro persistence file. |
 | Resets the underlying tool to a default state. |
 | Opens the Image Mask Editor for creating a mask to add to the training image. |
 | Opens a new, separate results window, allowing you to view run results without turning to the Results tab. |
 | Enables or disables the display of tooltips for individual items in this edit control. |
 | Opens this help topic. |
The CNLSearch edit control has three image buffers. Two of the buffers use the underlying CNLSearch tool's InputImage and TrainImage; the third buffer displays the last input image that the CNLSearch tool ran on and the results of that search. All three buffers can be shown in both the local and floating tool display windows.
- The Current.InputImage provides the input images to the CNLSearch tool. This is the CNLSearch tool's InputImage buffer.
- The Current.TrainImage contains the trained pattern. This is the TrainImage buffer.
- The LastRun.InputImage buffer displays the last image on which the tool most recently ran. Use the Graphics tab to highlight the search area and the results of the search.
When you run the CNLSearch tool (by clicking the Run button), the tool searches the Current.InputImage for the pattern in the Current.TrainImage buffer. The results of this search are available on the Results tab, and the result graphics are displayed on the LastRun.InputImage buffer (select a result on the Results tab to highlight its graphic in the display, or click on a graphic in the display to highlight a result on the Results tab).
You can use the Current.InputImage as the trained pattern; to do this, go to the Train Params tab and click the Grab Train Image button. This button copies the Current.InputImage to the Current.TrainImage buffer, where you can use it to train the pattern that CNLSearch will search for.
Note that your application is responsible for copying an image into the edit control's Current.InputImage buffer. You can do this by using the Tool Group Edit Control to create a link from an AcqFifo tool's output image to the CNLSearch tool's input image, then running the AcqFifo tool or the tool group.
You use the Train Params tab to configure and train a CNLSearch pattern. The key operations you perform with this tab are
- Obtaining a training image
- Specifying the training-time parameters
- Training the pattern
The following table summarizes the operations and which controls you use to perform them.
| Feature | Description |
| Pattern | Displays the trained pattern image. This is specified by the TrainRegion, which is highlighted by a cyan border, within TrainImage. You can set the train region using the Train Region & Origin tab or by resizing its display in Current.TrainImage. The message text at the bottom of the tab indicates whether the CNLSearch tool is trained. |
| Load Pattern | Loads a trained pattern from a VisionPro persistence file. |
| Save Pattern | Saves the current trained pattern into a VisionPro persistence file, which has a VPP extension. |
| Algorithm | Selects which CNLSearch algorithms to train. You can only search for a pattern using an algorithm which has been trained for the pattern. This corresponds to the Algorithms property. |
| Ignore Polarity | If true, patterns which are negatively correlated with the trained pattern receive positive scores. If false, then patterns with negative correlation receive a score of zero. Corresponds to the IgnorePolarity property. |
| Advanced Training Enabled | If true, advanced training is enabled. Advanced training can be used to correct problems with repeating pattern images such as inaccurate search result locations. Advanced training applies only to the Linear Search algorithm. Corresponds to the AdvancedTrainingEnabled property. |
| Partial Match Limits | The training-time partial match limits let you specify how much of the trained pattern may fall outside of the search image at run time. These training time partial match limits are only used during training if advanced training is enabled. Corresponds to the PartialMatchLimitUp, PartialMatchLimitDown, PartialMatchLimitLeft, and PartialMatchLimitRight, properties. |
Train button | Trains the desired pattern as specified by the TrainRegion in TrainImage. Invokes Train function. If the tool already has a trained pattern then the tool will untrain and then retrain. When the pattern is successfully trained, the text at the bottom of the control says, "Trained." The Train button is available only when Current.TrainImage has an image. |
Grab Train Image button | Sets the TrainImage buffer to be a reference to the InputImage buffer. This button is not available unless there is an image in Current.InputImage. Your application must copy an image into the edit control's Current.InputImage buffer. You can do this by using the Tool Group Edit Control to create a link from an AcqFifo tool's output image to the CNLSearch tool's input image, then running the AcqFifo tool or the tool group. |
| Edge Thresholds | If you include the Nonlinear CNLPAS algorithm among those to train, you can specify the low and high threshold values for image edge pixels. Edge pixels with edge strength (the difference in grey levels across the edge) below the low threshold are excluded from the trained pattern; edges with edge strength above the high threshold are included in the pattern; and edges with strengths between the thresholds are included in the pattern if they are 8-connected to another edge above the high threshold. Equivalent to the EdgeThresholdLow and EdgeThresholdHigh properties. |
Use the Train Region and Origin tab to define the TrainRegion, which defines the area of the TrainImage buffer that becomes the trained pattern. You can also define the train region graphically in the Current.TrainImage buffer. It may be easier to first specify the training region graphically, then use this tab to fine tune the train region parameters. The CNLSearch edit control updates the train region values so that the values on this tab always match the shape of the train region in the Current.TrainImage buffer.
Some of the parameters on this tab, such as Rotation and Skew, can be specified in degrees (default) or radians. The underlying tool keeps the values in radians but the edit control converts them to degrees when appropriate.
| Feature | Description |
Defines how the tool interprets the training region you specify.
| |
Select the shape of the input region. Selecting "None=Use entire image" means that the tool uses the entire input image. A CNLSearch tool supports the following input region shapes: The set of region-defining parameters that appear depend on the region shape you use. For more information on using a polygon as an input region, see Using Polygon Input Regions. | |
| Selected Space Name | The coordinate space in which the training region is interpreted. Equivalent to the SelectedSpaceName property. For more information, see Coordinate Space Names. |
| Select Mode | Available when Region Shape is CogRectangle or CogRectangleAffine. Selects the set of parameters that define the rectangle. If cogRectangleAffine is chosen, note that the angles of rotation and skew can be specified in degrees or radians, although the underlying tool keeps the measurements in radians. |
| Fit In Image | Centers the train region within Current.TrainImage. Equivalent to the FitToImagemethod. |
| Feature | Description |
Origin X Origin Y | Values that define the location of the train region's origin. These values will change if you modify the origin graphically. Equivalent to the OriginX and OriginY properties. |
| Center Origin | Sets the train region's origin at the center of the train region. |
Use the Run Params tab to specify how to perform the pattern search. These parameters include the run algorithm to use and thresholds and limits.
| Feature | Description |
Algorithm | The algorithm that should be used to perform a CNLSearch inspection. You can specify Linear Search or Linear CNLPAS algorithms for search images with linear brightness changes from the trained image or the Nonlinear CNLPAS algorithm for search images with nonlinear brightness changes. Among the linear mode algorithms, Linear Search is a more aggressive algorithm which is faster but which may miss some pattern instances, while Linear CNLPAS is a conservative algorithm that may be slower but which is unlikely to miss any pattern instances. This setting is equivalent to the Algorithm property. Note that you must have trained the pattern for the algorithm you specify for the search. |
| Accuracy | Specifies the accuracy level for the search. Note that you must have trained the pattern for the accuracy level you specify for the search. |
| Maximum Results | Specifies the number of results to look for. Equivalent to the MaxResults property. |
| Accept threshold | Specifies the acceptance threshold for the result score. Specify a value such that no actual instance of a pattern will receive a score less than the threshold. Equivalent to the AcceptThreshold property. |
| Confusion threshold | Specifies the confusion threshold for the result score. Specify the highest score that something other than a valid pattern instance will receive. This value indicates to the tool how confusing you expect the search image to be; the higher a value you specify, the more careful the tool is. Equivalent to the ConfusionThreshold property. |
| XY Overlap | The maximum allowed percentage (0.0 through 1.0) of overlap between two pattern instances. If the overlapping area of the two pattern instances is greater than the specified percentage, then the pattern instance with the lower score is discarded. Equivalent to the XYOverlap property. |
| Reduce Partial Match Score | If checked, CNLSearch will reduce the score received by pattern instances that are partially outside of the search image. Scores will be weighted by the percentage of the pattern that is inside the image. Equivalent to the PartialMatchReduceScore property. |
| Search Point Enabled | Enables point search (which is only supported by the Linear Search algorithm), in which CNLSearch attempts to find only a single pattern instance at or near a point that you specify using the SearchPointX and SearchPointY controls. Equivalent to the SearchPointEnabled property. |
| Use Run Params Partial Match Limits | If checked, CNLSearch will use the partial match limits you specify in the Run Params tab to limit how much of the trained pattern is permitted to lie outside the search image. If this box is not checked, then the partial match limits specified in the Train Params tab are used. Checking this option button is equivalent to setting the PartialMatchLimitsUsePattern property to false. |
| Edge Thresholds Use Pattern | (Nonlinear CNLPAS algorithm only.) If checked, CNLSearch will use the edge threshold values you specify in the Train Params tab to create the run-time image edge map. If this box is not checked, then the EdgeThresholdLow and EdgeThresholdHigh thresholds you specify in this tab are used. Equivalent to EdgeThresholdsUsePattern property. |
Use the Search Region tab to define the SearchRegion, the area of the InputImage buffer to which the pattern search is constrained. The search region appears with a cyan border in the Current.InputImage, and you can graphically define the search region in this buffer. It may be easier to specify the search region graphically, then use this tab to fine tune the search region parameters. When you resize the search region in the InputImage, the values on this tab change; likewise, changing the parameter values causes the search region to alter its size and shape.
| Feature | Description |
Region Mode | Defines the bounding box for the region. Equivalent to the SearchRegionMode property.
|
| Region Shape | The shape of the search region; equivalent to SearchRegion. Selecting "None=Use entire image" means that the entire Current.InputImage becomes the search region. The set of region-defining parameters depends on the selected Region Shape. |
| Selected Space Name | The coordinate space in which the search region is interpreted. Equivalent to the SelectedSpaceName property. For more information, see Coordinate Space Names. |
| Select Mode | Available when Region Shape is CogRectangle or CogRectangleAffine. Selects the set of parameters that define the rectangle. If cogRectangleAffine is chosen, note that the angles of rotation and skew can be specified in degrees or radians, although the underlying tool keeps the measurements in radians. |
| Fit In Image | Centers the search region within Current.InputImage. Equivalent to the FitToImage method. |
Use the Graphics tab to choose the results graphics that are displayed in the LastRun.InputImage, Current.InputImage, and Current.TrainImage display buffers.
| Feature | Description |
Train Features | You can show these features in the Current.TrainImage buffer, which contains the trained pattern:
|
Results | You can show these features in the LastRun.InputImage buffer, which contains the image that the CNLSearch tool last searched, and the results of that search. Uses the CreateResultGraphics method to generate these results. |
Diagnostics display | Displays the following features.
|
The Results tab displays the results of the most recent pattern searches. This corresponds to the CogCNLSearchResult interface. Use the slider control below the results grid to display the complete set of results.
| Feature | Description |
Results Grid | Displays the following information for each result.
|