# Blue Locate Parameters

The parameters adjust how the tool is trained, and also how the tool processes statistical results. You can open and close the parameters side pane by selecting the tool and then clicking the % icon. You can access additional parameters that provide advanced features by selecting Expert Mode in the Help menu.

## Network Model and Features Parameters

Parameter | Expert Mode | Description
Network Model | No | Specifies the size of the neural network model Each VisionPro Deep Learning tool is a neural network. A neural network mimics the way biological neurans work in the human brain. The neural network consists of interconnected layers of artifical neurons, called nodes, and they have multiple layers. Neural networks excel at tasks like image classification and pattern recognition., which affects the time required for training Training is the process that your tool, which is a neural network, is learning about the features (pixels) based on the labels you made. For example, a tool will learn the defect/normal pixels in each image based on the defect/normal labels you drew. The goal of the tool Training is learning enough to give the correct inspection results of whether an unseen image is defective or not. The key to training is to ensure that you include all possible variations within your training set, and that your images are accurately labeled. Training times vary by the application, tool setup and the GPU in the PC being used to train the network. and processing. The Network Model parameter allows you to reduce the size of the trained tool network, which reduces the amount of time required for processing. The default value, Large, retains the standard tool behavior and performance. The two other values, Small and Medium, provide progressively faster runtime execution. Selecting a value other than Large can result in different tool results. These differences are typically minor, however, when using this option, you need to validate tool performance using your own labeled data.
Oriented | No | Enables tolerance for unlimited rotation change during training. A runtime property controls the specific range of rotation that can be accommodated by the tool. When enabled, the list of parameters changes as follows: The Rotation perturbation Perturbation is the process of improving the trained tool tolerance of part and image variation by simulating the effect of specific types of variation. parameter is removed. The Angle Range processing parameter is added. With this parameter, you can modify the orientation range during runtime. When enabled, you must consistently label each feature A feature is a visually distinguishable area in an image. Features typically represent something of interest for the application (a defect, an object, a particular component of an object). with its orientation, in addition to the position and the identity of the feature. During runtime, the orientation of each feature is determined and reported, and you can adjust the Angle Range and Size Range Processing parameters, if necessary, to account for variations. Note: If you only need the tool to tolerate feature rotation, do not enable this setting. Instead, use the Rotation perturbation parameter.
Scaled | No | Enables tolerance for unlimited scale change during training. A runtime property controls the specific range of scale that can be accommodated by the tool. The available values are Uniform and Non-uniform. When set to Uniform, the list of parameters changes as follows: The Scale perturbation parameter is removed. The Size Range processing parameter is added. With this parameter, you can modify scale during runtime. When set to Non-uniform, the list of parameters changes as follows: The Scale and Aspect Ratio perturbation parameters are removed. The Size Range and Aspect-Ratio Range processing parameters are added. With these, you can modify scale and aspect ratio during runtime. Features with sizes in the search range are matched, and those outside the range are not matched. If you set the Scaled parameter to Non-uniform, the size of the feature is defined as the geometric mean of the X- and Y- dimension of the feature. When considering the runtime scale range for non-uniform scale, the scale of a particular found feature is equal to the geometric mean of the X- and Y-sizes of the found feature, divided by the geometric mean of the X- and Y-sizes of the Feature Size. When enabled, you must consistently label each feature size The subjective size of the image features that you feel are most important for analyzing image content. The feature size determines the size of the image region used for sampling. Only used with Blue Locate, Blue Read, and Legacy type tools., in addition to the position and the identity of the feature. During runtime, the scale of each feature is determined and reported, and you can adjust the Angle Range and Size Range Processing parameters, if necessary, to account for variations. Note: If you only need the tool to tolerate feature scale, do not enable this setting. Instead, use the Scale perturbation parameter.
Legacy Mode | No | Enables the legacy behavior of the Oriented and Scaledparameters. In this state, the scale and rotation tolerances are fixed during training, based on the training samples and the perturbation parameters. When enabled, the extracted feature orientation and scale are of limited precision. Scale is clamped to 1/4–4 times the feature size interval.

## Sampling Parameters

The Sampling parameters control the way that images are sampled you train and process Legacy mode tools. For more information, see Feature Sampling.

Note: If you change the Sampling parameters of an already trained tool, you must retrain the tool because the underlying image statistics might be changed.

Parameter | Expert Mode | Description
Feature Size | No | Specifies the typical feature diameter in pixels. The Feature Size is displayed in the lower left of the image, and you can resize it within the image to set a more accurate size. The feature size should be about the size of the object that you are identifying. If you are labeling Labeling is the process of annotating an image with "ground truth". Depending on the tool that you are using, labeling can take different forms. You label an image set for two reasons: to provide the information needed to train the tool and to allow you to measure and validate the performance of the trained tool against the ground truth. features of different sizes, pick a compromise feature size. Feature size strongly influences processing time (n2). In other words,, a Feature Size of 100 is 100 times faster than a size of 10, while a Feature Size less than 15 usually does not yield good results. When setting the Feature Size, consider the following in regards to processing time (Ptime): Note: The tool sees an area five times larger than the Feature Size setting. However, the level of detail is much higher in the center of the feature than in the periphery. For more information, see Feature Size. Note: The Precision parameter provides additional user controls over sampling at runtime. The tool performs additional interpolated sampling at locations where it detects features. It uses these additional samples to refine the feature pose. You can control the number of additional sampling passes using the Precision parameter, which specifies the degree of pose improvement at which resampling is stopped.
Detail | Yes | Specifies how much focus the tool places on the area within the feature graphic versus the area surrounding feature graphic. The value range is 1–4, with higher values focusing the attention of the tool on the area inside the feature graphic.
Color | No | Specifies the number of color channels to use when sampling the image. When set to 1, color images are converted to greyscale. The following values are available: Treats the image as greyscale Two channels images (spectral images, gray+alpha) BGR image. BGR(A) image Note: The VisionPro Deep Learning tools use the BGR channel order. RGB(A) images are converted to greyscale. For computational efficiency (memory allocation, transfer, file save, color conversion,… ), always prefer the correct number of channels. If your application relies on color images, only use the minimum number of required color channels, and only send images that already have the correct number of channels to avoid conversion. This is because:
Number of Image Channels | Number of Training Channels | Description
--- | --- | ---
1 (greyscale) | 1 | The correct setting for a greyscale image.
1 | 2, 3, 4 | Most likely, this results in a training error.
2 | 1 | The tool uses only the first channel.
2 | 2 | The tool uses the full pixel information.
2 | 3, 4 | This results in a training error.
3 (BGR) | 1 | This results in a BGR to greyscale conversion.
3 | 2 | The tool only uses the first two channels (in other words, B and G).
3 | 3 | The tool uses the full pixel information.
3 | 4 | Most likely, this results in a training error.
4 (BGRA) | 1 | This results in a BGR(A) to greyscale conversion.
4 | 2 | The tool only uses the first two channels (in other words, B and G).
4 | 3 | The tool only uses the first three channels (in other words, B, G and R).
4 | 4 | The tool uses the full pixel information.
Border Type | Yes | Specifies how pixels on the outside of the image are sampled. Adding an additional mask at the boundaries of the image highly reduces the false detection rate. Black: Fills the outside of the image with a solid color, black. Replicate: Fills the outside of the image with the last pixel.
Masking Mode | Yes | Specifies how a mask is applied to the sampled image. A mask is used to limit areas of the image processed by the tool. Masks can be set after training, however, setting them before training helps the learning phase. Transparent: Collects samples within the unmasked parts of the image, but also collects data from the Context Region from the areas that are masked. This ensures that features or defects that are at the boundary of the mask or ROI The Region of Interest (ROI) defines the area of operation for the tool. The ROI preserves the positions, angles, stretch and skew of the original image. generate the same response as features or defects that are in the center. Mask: Ignores the pixels in the masked parts of the image during training and runtime. This setting also alters the response of the tool to defects or features near the mask boundary. This setting also works to focus the tool toward the center of the ROI. Overlay: Adds the mask to the sampled image as an additional color channel.

## Training Parameters

The Training tool parameters control the training process.

Note: If you change the training parameters of an already trained tool, you must retrain the tool.

Parameter | Expert Mode | Description
Training Set | No | Specifies the training data set used to create a neural network model A specific spatial arrangement of a set of features (Blue Locate and Blue Read tools only.) During a post-processing step, the Blue Locate and Blue Read tools can fit all of the features detected in an image to the models defined for the tool. The overall pose and identity of the model is then returned.. The system only extracts the features of the images that are included in the training set. Click Edit to open a dialog where you can specify the sample sets and the percentage of the labeled images used as training samples. The system selects the training images randomly each time you start training.
Epoch Count | No | Specifies the number of optimization iterations done during training. Use a lower value when your application has limited complexity, or when creating a lower quality model for testing different parameter settings. The tools typically need to see the training image set A collection of images of your specific application. A training image set represents images of a specific part or process acquired in a consistent way using the lighting, optical, and mechanical characteristics of your runtime system. The training image set includes images that represent the range of image appearances that you expect to see in normal operation. data about 50 times, which is the default setting, and is typically sufficient for most standard applications. If you use fewer epochs, the neural network might get stuck in learning, or become unable to accurately solve the problem. However, if you use too many epochs, you risk overfitting Overfitting means that the tool is memorizing the data from the training images, which leads to lower performance when using unseen images.. Note: If your training image set contains a large number of images, or the size of the images in your training image set are large compared to the Feature Size, you might need to increase the Epoch Count setting. There is a risk of overfitting if you have a very small training image set. If you have a large training image set, and your network is addressing all of the samples in the set, the network is much more general than if you have a smaller training image set and the network is keyed into that small sample set.

## Perturbation Parameters

With the Perturbation parameters, you can allow the tools to generate images that simulate the variations expected during runtime.

Read more...

For example, if your part rotates by +/-45 degrees, you can set the Rotation parameter, and the software rotates the images during training by that amount. However, image perturbation is not a substitute for collecting and training actual images. The image perturbations can only approximate the variations of real parts or scenes.

Note: For the best results, Cognex recommends using actual sample images of the part variations. When a part spins, there might be different shadows, which are not captured by the tool when the rotation is based on artificially spinning the image.

The Perturbation parameters are common across all of the tools, and you can use these parameters in combination. This way, you can generate more complex images by using the parameters separately, as well as in conjunction.

Note: All training image samples can be applied to perturbation. Every train image has 50% chance to be augmented to every checked options independently. By the law of large numbers, all perturbation options can be applied equally and trained by increasing the number of epochs.

Parameter | Expert Mode | Description
Rotation | No | Specifies the possible orientations, defining a piece-wise uniform distribution from which a perturbing rotation angle is drawn (if set to [0°, 0°], no rotational perturbation is used). For example, with the following settings, [-10°, 10°] or [170°, 190°], the part can be detected between -10 and 10 degrees, or between 170 and 190 degrees. These types of settings are particularly useful if your part can be orientated with a regular orientation, or upside down with a small variation in its angle, but never in between.
Scale | No | Specifies the normal distribution around 1 from which a perturbing scaling factor is drawn (if set to 0%, it is not applied). For example, a Scale setting of 100%, provides images half the original size to double the original (0.5x to 2.0x the original).
Original = | Possible Perturbations = |  |  |
Aspect-Ratio | No | Specifies the normal distribution around 1 from which a perturbing aspect-ratio factor is drawn (if set to 0%, it is not applied).
Shear | No | Specifies the normal distribution around 1 from which a perturbing shearing factor is drawn (if set to 0%, it is not applied).
Flip | No | Specifies whether to randomly flip the image during sampling in the horizontal, vertical or both directions. This is useful if the object or surface exhibits the corresponding symmetries. This setting can help to highly increase the quantity of training data.
Horizontal |
Vertical |
Both |
Luminance | No | Specifies the normal distribution around 1 from which a perturbing luminance factor is drawn (if set to 0%, it is not applied).
Contrast | No | Specifies the normal distribution around 1 from which a perturbing contrast factor is drawn (if set to 0%, it is not applied).
Invert Contrast | Yes | Randomly inverts the contrast in order to simulate contrast reversal in the training samples.

## Processing Parameters

The Processing parameters control the way the tool processes images. Processing with the same models always gives the same results. You do not need to retrain the tool after changing the Processing parameters. You can see the effect after reprocessing the database.

For a tool with a defined model, the features found during processing are searched for the feature collections that provide the best fit for the defined models.

Parameter | Expert Mode | Description
Sampling Density | No | Specifies the density of sampling points with respect to the Feature Size setting. The sampling density The amount by which the sampling point is moved in the image between samples, expressed in terms of the feature size. If the feature size is 100 and the sampling density is 1, the sampling location is advanced by 100 pixels between samples. A sampling density of 4 advances the sampling location by 25 pixels between samples. determines the degree of overlap between adjacent samples. A sampling rate of 1 means that the sampling location is incremented by the feature size between samples. The default sampling rate for most tools is 3, which means that the sampling location is incremented by one third of the feature size. The Sampling Density parameter affects the processing time and the accuracy of the tool. Higher Sampling Density settings are more accurate but significantly increase processing time. The processing time depends approximately quadratically to the Sampling Density (Sd) value. For example, a Sampling Density setting of 1 is approximately nine times faster than a setting of 3 (n2).
Threshold | No | Specifies how close the found feature must be to the desired feature to be detected. The found feature must exceed the setting.
Precision | No | Controls when the tool stops refining the feature position. The tool repeats the refinement of feature position until the difference between the current position and the new, refined position is less than the specified precision, multiplied by the value of the Feature Size parameter. For example, if you have a Feature Size of 40, and a Precision setting of 5%, the tool stops searching for the position of the feature when the next jump would be less than 2 pixels (0.05 * 40 = 2 pixels).
| If Precision is equal to 400%, the tool stops at D0. 200% = D1 100% = Matches with precision
Stop criteria: |
Angle Range | No | Specifies the range (the minimum and the maximum values) of rotation that the tool can accommodate. This parameter is available only when you enable the Oriented parameter and set it to Uniform.
Size Range | No | Specifies the range (the minimum and the maximum values) of scale that the tool can accommodate. This parameter is available only when you enable the Scaled parameter and set it to Uniform.
Aspect-Ratio Range | No | Specifies the range (the minimum and the maximum values) of aspect-ratio that the tool can accommodate. This parameter is available only when you enable the Scaled parameter and set it to Non-Uniform.
Feature Filter | Yes | Specifies a filter based on feature id, x, y, size and orientation, which is used as criteria for found features. By specifying a filter for features, features that do not match the filter are hidden from the results. If the parameter is left blank, all features are returned. Since this filtering is done after the tool has processed the images, the features are not removed, simply hidden from the results. Features that are not present due to the filter reappear, without reprocessing the image, by removing the filter criteria. Note: The syntax for filters is the same as the syntax used for Display Filters. For more information about constructing the syntax for a filter, see Custom Display Filters. For example, if you set the Feature Filter parameter as follows:
Feature Filter | Description
--- | ---
x in [0,view A view of an image is a region of pixels in an image. Tool processing is limited to the pixels within the view. You can manually specify a view, or you can use the results of an upstream tool to generate a view..width] and y in [0,view.height] | With this filter, only features whose center is within the ROI are returned.
(id = '0' and x < 200) or (x='1' and x > 200) | With this filter, assuming a view that is 400 pixels wide, features that have an ID of 0 and are on the left, and features that have an ID of 1 and are on the right, are returned.
If you enabled the Scaled parameter , the tool can return matches at scale values where you do not intend to find features. In this event, it can be helpful to use the Feature Filter to remove the mismatched features. For example, if you have a tool trained to find large capacitors and small capacitors, and the Size Range parameter is set to a range large enough to accommodate both the large and small capacitors, intermediate-sized matches are possible. In this event, if you use the Feature Filter, you can define a mechanism to suppress these types of matches (for example "size > X or size < Y").