# Setup a Parameter Search

To find the best combination of tool parameters for your specific VisionPro Deep Learning tool, you starts with launching Parameter Search Utility and setting up the search.

### Launch Parameter Search

Launch Parameter Search independently from VisionPro Deep Learning.

- Windows Startup Menu

- C:\Program Files\Cognex\VisionPro Deep Learning\2.1.1\Parameter Search\

Note: To launch Parameter Search, you need to quit VisionPro Deep Learning first. Save the workspaces to preserve what you've been working in Cognex Deep Learning Studio, terminate it, and launch Parameter Search.

### Setup Workspace, Stream, Tool

Before launching Parameter Search, you need to make sure that your VisionPro Deep Learning workspace is ready for the search. All the images in your workspace must be labeled, the workspace must have a training set with enough images, and the mode and the architecture of the tools in the workspace must be chosen, before you import this workspace into Parameter Search.

Once you launched the Parameter Search utility, you enter the Home screen shown below. On this screen, you can import the workspace, stream, and the tool to be tested against many training/processing parameter sets.

Steps

1. On the right side of Path bar, click button and set the path to the directory that contains your workspaces, you will use for searching.

2. Once the path to the workspaces is set, all the workspaces exist under that path will be loaded on Workspace pane. Choose the specific workspace you will use on the pane. A loaded workspace contains all of the configured streams and tools in it.

   - If you want to add a workspace from another path to the current path, you can directly import a workspace from another directory with button. The imported workspace must be of VisionPro Deep Learning Workspace Archive file (.vwsa) format, which is created when you export a workspace from VisionPro Deep Learning. On Upload Workspace dialog, you can select this VisionPro Deep Learning Workspace Archive file to import this workspace into the current path. The imported workspace will be on Workspace pane and also copied and placed under the physical directory of the current path.

3. Choose the stream you will use on the Stream pane.

4. Choose the tool you will use on the Tool Chain pane. Once you select the tool its details will be shown on the Tool Information pane.

5. After confirming the tool information, click OK to move on to setting up which parameters would be tested for this tool.

### Setup Parameters

Once the workspace, stream, and tool is loaded, you will enter the Parameter Search main screen shown below. To start a search, you need to bring a set of parameters whose values are to be tested. Go to the navigation tab at the top of the main screen and click Search.

CAUTION: If you change the current stream/tool with Stream/Tool drop-down menu, the parameter configurations (the values of the set of parameters to be searched) and the search results for a search for the currently loaded stream and tool will be removed. Click Save before switching over to another tool or stream.
CAUTION: Before you click Home to go back to Home screen, click Save to save the current parameter configurations. Going back to Home screen will reset all the configurations.

Steps

1. On the Search page of this main page, click Add to add a new parameter. You can add 1 or more training or processing parameters to be tested.

   - If you have a previously saved Parameter Search Data XML file which contains a set of parameters and their values to be searched, click Load to load it on the Search page.

2. In the Parameter column, click the downwards arrow and it will initiate a drop-down menu where you can scroll through the full list of tool parameters. Select the parameters you want, or type in their names in the cells directly. For the details of available parameters for each tool, see VisionPro Deep Learning Tool Parameters

   Note: The values of the tool parameters that are not selected in a search are set to the values which were already set in the loaded workspace during the search.
   Note: If you only choose processing parameters for the Parameter column, the currently loaded tool must be an already trained one since every processing parameter can only be tested on a trained tool.

3. In the Values column, type in the range of values for these parameters. Click each cell in Values column to modify the values for a parameter. Mainly there are 3 ways of providing values (or value ranges) of each parameter.

   1. Type the specific values in the cell (Int, Double)
      - To add multiple values for a specific parameter, use a blank(Space key) as the separator between each value.
   2. Enable checkboxes in the cell (Enum, Boolean)
      - For the values of some parameters (eg: Network Model), enable checkboxes to select the values to be tested in the search.
   3. Fill in the cell by the input form (Size, Interval, String, Dictionary)

4. Click the check button if you finished editing a cell and want to fix the value range(s) for a parameter.

- After entering a value if the cell is outlined in red, there is an error in the syntax.
- If you want to modify inserted values for a parameter, click the cell again you want to modify.
- The list of parameters and the range and the supported type of them are described in the table at the bottom of this section.
- Only the parameters whose heading checkboxes are enabled are used in the search. If all of the selected parameters are processing parameters, training is skipped during the search.

5. Set the search options if necessary.

   Option | Description
   Trial | Set the number of trials for this search. Note that multiple iterations will provide more statistical analysis, such as the mean, median and standard deviation which will be displayed in the result table on Graphs page, but will also require more time to execute.
   Filter | Filter results (the result tables, Database Overview, the graphs) displayed on Results and Graphs page using the filter syntax. Type in a filtering phrase and press Enter. The filter syntax will be applied on result table and the graph. See Display Filters and Filter Grammar for the details of the filter syntax. Once a filter syntax is applied, the search results of the views which were screened out by applying the filter will not be shown as those views are not processed. You cannot change the filter syntax once the training is finished.
   Optimized GPU Memory | Enable optimized GPU memory by feeding the amount of memory to be used. You can enable the optimized GPU memory for efficiency if your tool is a Focused mode tool. When your tool is a High Detail or High Detail Quick tool, optimized GPU memory will be automatically disabled for faster performance.
   Save Tools | Save the currently loaded tool with the search results once the search is done. If you want to export the parameter configurations and the trained tools (the trained networks) trained with these configurations once the search is done, you should enable this option. The trained tools will be exported under the directory containing the Parameter Search Data XML file. If you click Start with the Save Tools enabled, you will select the target directory to export a Parameter Search Data XML file. The saved tools will be placed under your target directory ("./saved_tools/PARAMETER_SEARCH_DATA_XML_FILE_NAME/"). The exported tools can be imported from VisionPro Deep Learning. The file name of each saved tool is in "uuid" format (example: 6ffa1800-376a-4bf7-a5a4-64bc4e8c854e) The file extensions for each tool are: .vgta: Green Classify .vrta: Red Analyze .vbta: Blue Locate/Read

6. Click Save to save the Parameter Search Data XML file. Once it is saved, the Parameter Search Data XML file will contain the parameter configurations, and it will also contain the search results shown in Result and Graphs pages once the search is done.

   One important thing here is that the saved Parameter Search Data XML file will not contain the trained networks (the trained tools) which are the results of a search. Thus, you cannot use Apply To Workspace with the loaded Parameter Search Data XML file in the Result page. To apply the saved search results to your workspace, you must save the trained networks by enabling Save Tools checkbox to save tool files containing the trained networks before beginning a search. You can load these tool files into your workspace in VisionPro Deep Learning.

   Note: If you did not save the file when you press the Start, you will automatically be prompted to save the Parameter Search Data XML file.

7. Click Start to begin the search. The progress status of the search will be displayed at the bottom of the page.

8. Once the search begins, the utility will indicate the search progress for each parameter combination at the lower pane of the screen.

9. If you click Pause to temporarily halt the search and click Start again, the search will be resumed from the paused test.
10. Once the search is completed, you can review the results to determine the best combination of parameters on the Results tab and the Graphs tab.

##### Parameter List

Parameter | Tool | Data Type | Example
--- | --- | --- | ---
Aspect Ratio | Green Classify - Focused, Red Analyze - Focused (Supervised, Unsupervised), Blue Locate, Blue Read | Double | The syntax is a number, 0 to 100 (where 0 = off), which will be displayed as a percentage. If you want to test 0%, 2% and 5%, you would enter: 0 2 5
Angle Range | Blue Locate, Blue Read | Interval | An interval by 2 angle values. Each angle (the minimum and the maximum) value is double-formatted.
Aspect-Ratio Range | Blue Locate | Interval | An interval by 2 aspect-ratio values. Each apsect-ratio (the minimum and the maximum) value is double-formatted.
Border Type | Green Classify - Focused, Red Analyze - Focused (Supervised, Unsupervised), Blue Locate, Blue Read | Enum: Black White Reflect Wrap Replicate | The syntax is the name of the parameter setting.
Capacity | Red Focused - Unsupervised | Enum: Huge Large Medium Small Tiny | The syntax is the name of the parameter setting.
Centered | Red Analyze - Focused (Supervised, Unsupervised) | Boolean | The syntax is the Boolean state, True or False.
Color | Green Classify - Focused, Red Analyze - Focused (Supervised, Unsupervised), Blue Locate | Int32 | The syntax is a 32-bit integer, 1 through 4. If you want to test greyscale, BGR and BGR(A), enter: 1 3 4
Contrast | Green Classify - Focused, Red Analyze - Focused (Supervised, Unsupervised), Blue Locate, Blue Read | Double | The syntax is a number, 0 to 100 (where 0 = off), which will be displayed as a percentage.
Epoch Count | All | Int32 | The syntax is a 32-bit integer, 1 through 100000.
Exclusive | Green Classify - Focused | Boolean | The syntax is the Boolean state, True or False.
Feature Filter | Blue Locate Blue Read | String | The syntax is a string representing the filter to be used. If you want to filter features whose center is within the ROI, enter: x in [0,width] and y in [0,height]
Feature Size | Green Classify - Focused, Red Analyze - Focused (Supervised, Unsupervised), Blue Locate, Blue Read | Size | The width and height value of the feature size.
Size Range | Blue Locate, Blue Read | Interval | An interval by 2 size values. Each size (the minimum and the maximum) value is double-formatted
Flip | Green Classify - Focused, Red Analyze - Focused (Supervised, Unsupervised), Blue Locate | Enum | The syntax is the name of the parameter setting. None, Horizontal, Vertical , or Both.
Polarity | Blue Read | String | The syntax is the name of the parameter setting. It also supports Enum type input in GUI. Actual or Invert.
Invert Contrast | Green Classify - Focused, Red Analyze - Focused (Supervised, Unsupervised), Blue Locate, Blue Read | Boolean | The syntax is the Boolean state, True or False.
Low Precision | Green Classify - Focused, Red Analyze - Focused (Supervised, Unsupervised) | Boolean | The syntax is the Boolean state, True or False.
Luminance | Green Classify - Focused, Red Analyze - Focused (Supervised, Unsupervised), Blue Locate, Blue Read | Double | The syntax is a number, 0 to 100 (where 0 = off), which will be displayed as a percentage.
Masking Mode | Green Classify - Focused, Red Analyze - Focused (Supervised, Unsupervised), Blue Locate, Blue Read | Enum: Transparent Mask Overlay | The syntax is the name of the parameter setting.
Precision | Blue Locate | Double | The syntax is a number, 0 to 100 (where 0 = off), which will be displayed as a percentage.
Region Filter | Red Analyze High Detail, Red Analyze - Focused (Supervised, Unsupervised), Red Analyze High Detail Quick | String | The syntax is a string representing the filter to be used. Example: area > 500
Rotation | Green Classify - Focused, Red Analyze - Focused (Supervised, Unsupervised), Blue Locate | List of intervals | The syntax is [low,high], where "low" and "high" are numbers.
Sampling Density | Green Classify - Focused, Red Analyze - Focused (Supervised, Unsupervised), Blue Locate, Blue Read | Double | The syntax is a number, 0 to 10 (where 0 = off), which will be displayed as a percentage.
Iterations | Red Analyze - Focused Unsupervised | Int32 | The syntax is a 32-bit integer, 1 through 10.
Scale | Green Classify - Focused, Red Analyze - Focused (Supervised, Unsupervised), Blue Locate | Double | The syntax is a number, 0 to 100 (where 0 = off), which will be displayed as a percentage.
Shear | Green Classify - Focused, Red Analyze - Focused (Supervised, Unsupervised), Blue Locate, Blue Read | Double | The syntax is a number, 0 to 100 (where 0 = off), which will be displayed as a percentage.
Simple Regions | Red Analyze Focused (Supervised and Unsupervised) | Boolean | The syntax is the Boolean state, True or False.
Threshold | Blue Read, Blue Locate, Green Classify Focused, | Double | The syntax is a number, 0 to 100 (where 0 = off), which will be displayed as a percentage.
Threshold | Red Analyze - Focused (Supervised, Unsupervised), Red Analyze High Detail, Red Analyze High Detail Quick | Interval | An interval by 2 threshold values. Each threshold (the minimum and the maximum) value is double-formatted, between 0 and 1. Example: [0.7036, 0.9051]
Training Passes | Red Focused - Unsupervised | Int32 | The syntax is a 32-bit integer, 1 through 3.
Use Baseline | Red Focused - Unsupervised | Boolean | The syntax is the Boolean state, True or False.
Network Model | All except Green Classify High Detail Quick and Red Analyze High Detail Quick | String | The syntax is the name of the parameter setting. It also supports Enum type input in GUI following the tool architectures. Focused: Small, Medium, Large High Detail: Small, Normal, Large, Extra Large
Detail | Blue Locate | int32 | The syntax is a 32-bit integer, 1 to 4. It also supports Enum type input in GUI: 1, 2, 3, 4
Minimum Epochs | Green Classify and Red Analyze in High Detail modes | Int32 | The syntax is a 32-bit integer, 0 through current epoch.
Stride | Red Analyze in High Detail mode | Int32 | The syntax is a 32-bit integer, 10 through 100.
Patch Size | Red Analyze in High Detail mode | String | It also supports Enum type input in GUI. 128x128, 256x256
Patience Epochs | Green Classify High Detail, Red Analyze High Detail | Int32 | The syntax is a 32-bit integer, 0 through 100000.
Downsampling Size | Red Analyze in High Detail mode | Int32 | The syntax is a 32-bit integer, 1 through 100000. The corresponding variable name in GUI is DownsamplingSize.
Class Weight | Green Classify in High Detail mode | Dictionary | Example of 3 parameter values: { "tag1": 1, "tag2": 1, "tag3": 1 } { "tag1": 1, "tag2": 1, "tag3": 2 } { "tag1": 2, "tag2": 1, "tag3": 1 } The ratio of Class 1 to Class 2 as 2:1 means that the number of training images for Class 1 is as twice as Class 2.
Validation Set Ratio | Green Classify, Red Analyze in High Detail mode | Int32 | The syntax is a 32-bit integer, 1 through 50.
Horizontal Flip | Green Classify, Red Analyze in High Detail mode | Boolean | The syntax is the Boolean state, True or False.
Vertical Flip | Green Classify, Red Analyze in High Detail mode | Boolean | The syntax is the Boolean state, True or False.
Rotation 90º | Green Classify, Red Analyze in High Detail mode | Boolean | The syntax is the Boolean state, True or False.
Rotation | Green Classify, Red Analyze in High Detail mode | Boolean | The syntax is the Boolean state, True or False.
Zoom In | Green Classify, Red Analyze in High Detail mode | Boolean | The syntax is the Boolean state, True or False.
Colorwise | Green Classify, Red Analyze in High Detail mode | Boolean | The syntax is the Boolean state, True or False.
Gradation | Green Classify, Red Analyze in High Detail mode | Boolean | The syntax is the Boolean state, True or False.
Distortion | Green Classify, Red Analyze in High Detail mode | Boolean | The syntax is the Boolean state, True or False.
Contrast | Green Classify, Red Analyze in High Detail mode | Boolean | The syntax is the Boolean state, True or False.
Luminance | Green Classify, Red Analyze in High Detail mode | Boolean | The syntax is the Boolean state, True or False.
Sharpen | Green Classify, Red Analyze in High Detail mode | Boolean | The syntax is the Boolean state, True or False.
Blur | Green Classify, Red Analyze in High Detail mode | Boolean | The syntax is the Boolean state, True or False.
Noise | Green Classify, Red Analyze in High Detail mode | Boolean | The syntax is the Boolean state, True or False.
Resize Size | Green Classify in High Detail mode | Size | You would enter the size you want to resize: 90x90 100x100 110x110.
Threshold | Green Classify in High Detail mode and Green Classify High Detail Quick | Single | The syntax is a number, 0 through 100.