If the ReturnAllResults run-time parameter is false, every returned result will have its Accepted property set to true, and a result will be returned only if all of the following conditions are met:

• The result's Score is greater than or equal to AcceptThreshold.
• The result's ContrastFraction is greater than or equal to ContrastFractionThreshold.

• The result's angle (as reported by the Rotation property of the CogTransform2DLinear returned by GetPose in the API) was either:

  • obtained by not enabling the angle DOF but choosing nominal search (using the Zone's Angle arrow)

    OR

  • obtained by enabling the angle DOF (using the Zone's Angle arrow) and has a value between the Low and High angles that you specified.

• The result's scale (as reported by the Scaling property of the CogTransform2DLinear returned by GetPose in the API) was either:

  • obtained by not enabling the scale DOF but choosing nominal search (using the Zone's Scale arrow)

    OR

  • obtained by enabling the scale DOF (using the Zone's Scale arrow) and has a value between the Low and High scales that you specified.
• The result's Score makes it one of the top-scoring results. Only the NumberToFind top-scoring results (that meet all of the other conditions) will be returned.

The following example demonstrates this case:

If the ReturnAllResults run-time parameter is true, additional pattern instances may be reported as results. You can use the value of Accepted to determine why the additional result was excluded initially.

• If Accepted is true, the additional result was excluded solely because the NumberToFind was set too low. This could happen, for example, if your input image contains five instances of the pattern but you set NumberToFind to only find three. In this case, you might get two additional results that meet all of the acceptance conditions listed above, but were excluded from the results solely because they were not among the three highest-scoring instances.

• If Accepted is false, the additional result was excluded because it has one or more of the following:

  • A Score less than AcceptThreshold.
  • A ContrastFraction less than ContrastFractionThreshold.
  • An angle that is outside of the angle range you specified using Low and High angles if you enabled the angle DOF.
  • A scale that is outside of the scale range you specified using Low and High scales if you enabled the scale DOF.

The following example demonstrates this case:

The default training parameters will work well with most vision applications.

The following PatMax RedLine training parameters have the same definitions as those for the PatMax tool:

• GrainLimitCoarse - In general, the larger the coarse granularity limit, the faster alignments will run. Use caution in manually changing the coarse granularity limit because changing this value can drastically affect the PatMax RedLine tool’s ability to locate patterns at all.

• GrainLimitFine

  Using the PatMax RedLine tool, you can choose to auto-compute the coarse and fine granularity values independently (unlike in the PatMax tool).

• TrainRegion - Select a training region that contains a good representation of what you are trying to find at run time.
• Train Origin - A six degree of freedom origin for the pattern. This linear transform maps points from "Pattern Space" (that is, the coordinate space defined by this pattern Origin) to the selected space of the train image. For example, mapping the point (0, 0) through the transform returns the position of the pattern origin in the selected space of the train image.

For the definition and detailed usage of these common training parameters, see the PatMax Software topic.

The following training parameters are specific to the PatMax RedLine tool:

• FeatureThreshold - used to determine what image features are strong enough to be trained. It is a dimensionless number between zero and one. Raising this threshold trains fewer features. Lowering it trains more features.

  Only adjust this parameter after you have looked at your trained pattern and confirmed that you need more (or fewer) image features. Large values (0.7 or higher) may produce too few features for accurate pattern finding. Large values may also eliminate so many features that it is impossible to even train a pattern.

• TrainTimeout - timeout for training.

The only properties that do not untrain the pattern when changed are:

• Origin
• TrainTimeout
• TrainTimeoutEnabled

The following PatMax RedLine run-time parameters have the same definitions as those for the PatMax tool:

• AcceptThreshold - the acceptance threshold for the score of a result. Only instances of the pattern that receive scores greater than or equal to this threshold are accepted. Valid range is from zero to one. You should supply an acceptance threshold that is lower than the lowest score you ever expect to receive from a true instance of your pattern. For detailed information on pattern acceptance, see the Pattern Acceptance and Reporting section.
• XYOverlap - the area overlap threshold. Two result candidates are said to overlap in area if the fraction of their area that overlaps is greater than the given XYOverlap threshold. The valid range of the threshold is from zero to one. The PatMax RedLine tool discards the weaker pattern instance when two pattern instances overlap for all degrees of freedom (DOF) as well as area. See the Overlap property of the angle DOF zone, and the Overlap property of the scale DOF zone for more information.

For the definition and detailed usage of these common training parameters, see the PatMax Software topic.

The following run-time parameters are specific to the PatMax RedLine tool or their definitions slightly differ from those in the PatMax tool:

• NumberToFind - the number of results to search for. If the ReturnAllResults run-time parameter is false, the number of results returned by the PatMax RedLine tool is always less than or equal to the value you specify (unlike the PatMax tool, which may return more results than specified by its ApproximateNumberToFind run-time parameter). If ReturnAllResults is true, you may get additional results.
• ContrastFractionThreshold - the threshold for the contrast fraction of a result. Only instances of the pattern that have a contrast fraction greater than or equal to this threshold are accepted. The contrast fraction is a number between zero and one. It is computed by dividing the average contrast of the matching image features by the average contrast of the trained pattern features. If this ratio exceeds one it is reported as exactly one. (Unlike the PatMax tool, where the absolute contrast of the run-time image is measured and not the contrast relative to the trained pattern features.) ContrastFractionThreshold does not need to be set at all unless there will be run-time matches that are of lower-than-trained contrast that need to be rejected in your application. Otherwise, contrast variation is dealt with automatically and this parameter should remain at 0.
• AccuracyMode - the desired level of accuracy for result poses. The PatMax RedLine tool may run faster if your application can tolerate lower accuracy. The accuracy of a result pose (including its position, rotation, and scale) is highly dependent upon the quality of the trained pattern and the contents of the run-time image. For most applications, the Standard accuracy mode gives a good trade-off between accuracy and speed. If you desire more accuracy and are willing to sacrifice some speed, you can use the Accurate mode. If you desire more speed and are willing to sacrifice some accuracy, you can use the Fast mode. Fast mode is especially useful if you are searching for multiple pattern instances and only want to know how many were found.
• CoarseAcceptThresholdFraction - the fraction of the accept threshold that should be used to evaluate candidate scores during the coarse phase of PatMax RedLine run time. The PatMax RedLine tool first finds candidate patterns at coarse granularity. High-scoring coarse results are then refined at fine granularity. A coarse result is considered high-scoring if its score exceeds an internally-computed coarse accept threshold. By default, the PatMax RedLine tool determines the coarse accept threshold automatically. In exceptional cases you may need to override the automatic computation. You can override the automatic computation by enabling and setting setting the CoarseAcceptThresholdFraction run-time parameter. The coarse accept threshold will then be computed by multiplying together the coarse accept threshold fraction, specified by this value, and the AcceptThreshold.
• ReturnAllResults - whether the PatMax RedLine tool should return only the results that you asked for or it should also return results that are similar to the ones you asked for. If the PatMax RedLine tool fails to return all of the results that you expect, it may be useful to set this property to true. This allows the PatMax RedLine tool to return additional results that are similar to the ones you asked for. Additional results will not always be present, but if they are present you can inspect them to see if the PatMax RedLine tool is finding your desired result and then excluding it from the final set of results because it fails to meet one of the acceptance conditions. You can then adjust the relevant acceptance condition so that the desired result is returned.
• IgnorePolarity - whether to ignore the polarity of edge features when searching for patterns. If true, the polarity of the pattern features is ignored. If false, only patterns whose polarity matches the trained pattern will be found. The polarity of a feature indicates whether the edge describes a light-to-dark transition in the image or a dark-to-light transition. You should ignore polarity if instances of your pattern may have edge features whose polarity is the opposite of the trained ones. In this case your pattern should receive approximately the same score regardless of whether some, all, or none of the features have opposite polarity. For the PatMax tool, this is a train-time parameter. Unlike the PatMax tool, the PatMax RedLine tool may give slightly different answers for the same image if the value of IgnorePolarity changes.
• ScoreUsingClutter - whether the PatMax RedLine tool should reduce the score of results that contain extraneous features at the found image location. Extraneous features are known as clutter. They appear in the run-time image at locations which should be empty. A pattern's score is reduced as the amount of clutter increases, but the score will never go negative. A clutter measurement is computed, and reported in each result, only if ScoreUsingClutter is set to true. Otherwise, each result reports a clutter value of -1. The clutter value is a ratio. It is computed by dividing the number of clutter features at the found location by the number of features in the trained pattern. This ratio can be larger than one. Clutter features are extra features that appear in the run-time image at locations which should be empty. The corresponding area of the train image is called "empty" when: it lies within the train region, it contains no features, and it is not masked as "Don't Care".
• Timeout - the maximum execution time (in milliseconds) allowed for a PatMax RedLine tool to run. This value only applies if TimeoutEnabled is set to true. If a timeout occurs, an exception will be thrown, which will appear in the run status of the tool.

• Angle DOF zone parameters:

  • Nominal - the nominal angle for the angle degree of freedom zone. The nominal angle is only used if the configuration is set to Nominal. In this case, the PatMax RedLine tool will only look for pattern instances at exactly the Nominal angle that you specify. You can specify any value for the nominal angle.
  • Low - the low limit for the angle degree of freedom zone. The Low limit is only used if you enabled the angle DOF (using the Zone's Angle arrow). In this case, the PatMax RedLine tool will find pattern instances whose result angle lies between the Low and High limit values only. You can specify any value for the Low angle limit. Setting the Low limit to a value larger than the High limit also sets the High limit to the new value.
  • High - the high limit for the angle degree of freedom zone. The High limit is only used if you enabled the angle DOF (using the Zone's Angle arrow). In this case, the PatMax RedLine tool will find pattern instances whose result angle lies between the Low and High limit values only. You can specify any value for the High angle limit. Setting the High limit to a value smaller than the Low limit also sets the Low limit to the new value.
  • Overlap - the overlap threshold for the angle degree of freedom zone. Two result candidates are said to overlap in the angle degree of freedom if the absolute difference between their angles is less than or equal to the given Overlap threshold. The PatMax RedLine tool discards the weaker pattern instance when two pattern instances overlap for all degrees of freedom as well as area.

  The PatMax RedLine tool will iteratively refine its angle estimate until it finds the angle value that best matches the run-time image features.

  Using the nominal angle value is very different from specifying a tight range of angle values. In the Nominal case, the pattern is tried at exactly one angle, and scored at that angle. In the case where angle DOF is enabled, more than one angle is tried and the algorithm iterates to find the best angle. The initial range of angles is given by you (using Low and High), but the PatMax RedLine tool might discover that the best angle is outside of your initial range, leading to a result that is not accepted. For example, if you ask the PatMax RedLine tool to find a pattern instance at a nominal angle of 0.1 radians, it might find a run-time instance whose true angle is 0.101 radians. This happens when the pattern at the nominal angle is close enough to the run-time features to receive a high score. The reported angle will be exactly 0.1 radians. If, however, you ask the PatMax RedLine tool to find a pattern instance within a range of angles between 0.0999 radians and 0.1001 radians, that same run-time instance would not be reported with an angle of 0.101. By default, it will not be reported at all. The PatMax RedLine tool will iterate to the true angle (of 0.101) and then determine that it falls outside of your desired angle range. The run-time instance will be eliminated unless ReturnAllResults is set to true.

  The result angle is measured from the selected space of the input image to the coordinate space of the pattern (as defined by the pattern origin). The tool always returns angle results in the range -180 degrees to +180 degrees.

• Scale DOF zone parameters:

  • Nominal - the nominal scale for the scale degree of freedom zone. The nominal scale is only used if the configuration is set to Nominal. In this case, will only look for pattern instances at exactly the Nominal scale that you specify.
  • Low - the low limit for the scale degree of freedom zone. The Low limit is only used if you enabled the scale DOF (using the Zone's Scale arrow). In this case, the PatMax RedLine tool will find pattern instances whose result scale lies between the Low and High limit values only. Setting the Low limit to a value larger than the High limit also sets the High limit to the new value.
  • High - the high limit for the scale degree of freedom zone. The High limit is only used if you enabled the scale DOF (using the Zone's Scale arrow). In this case, the PatMax RedLine tool will find pattern instances whose result scale lies between the Low and High limit values only. Setting the High limit to a value smaller than the Low limit also sets the Low limit to the new value.
  • Overlap - the overlap threshold for the scale degree of freedom zone. Two result candidates are said to overlap in the scale degree of freedom if the ratio of their scales is less than or equal to the given Overlap threshold. To compute the ratio, the PatMax RedLine tool always divides the larger scale by the smaller one, yielding a value that is greater than or equal to one. For example, given a result with scale of 1.25 and a result with a scale of 2.5, the ratio would be 2.0. These two results would only overlap in the scale degree of freedom if the Overlap value was set to 2.0 or higher. The PatMax RedLine tool discards the weaker pattern instance when two pattern instances overlap for all degrees of freedom as well as area.

  The PatMax RedLine tool will iteratively refine its scale estimate until it finds the scale value that best matches the runtime image features.

  Using the nominal scale value is very different from specifying a tight range of scale values. In the Nominal case, the pattern is tried at exactly one scale, and scored at that scale. In the case where scale DOF is enabled, more than one scale is tried and the algorithm iterates to find the best scale. The initial range of scales is given by you (using Low and High), but the PatMax RedLine tool might discover that the best scale is outside of your initial range, leading to a result that is not accepted. For example, if you ask the PatMax RedLine tool to find a pattern instance at a nominal scale of 1.0, it might find a run-time instance whose true scale is 1.01. This happens when the pattern at the nominal scale is close enough to the run-time features to receive a high score. The reported scale will be exactly 1.0. If, however, you ask the PatMax RedLine tool to find a pattern instance within a range of scales between 0.999 and 1.001, that same run-time instance would not be reported with a scale of 1.0. By default, it will not be reported at all. The PatMax RedLine tool will iterate to the true scale (of 1.01) and then determine that it falls outside of your desired scale range. The run-time instance will be eliminated unless ReturnAllResults is set to true.