AdjustPropertiesByExample Method

Description

Profile weighting and thresholding properties are analyzed and adjusted to automatically detect the current set of edges.

Return Type

A Variant value.

[out, retval]

Syntax

object.AdjustPropertiesByExample ([AdjustFlags])

The AdjustPropertiesByExample Method syntax has these parts:

Part	Description
object	An expression evaluating to an object of type McProfileEdges.
AdjustFlags	Optional. A mcAdjustPropertiesByExampleFlags enumeration, as described in settings. Flags can be set to exclude adjustment of selected properties. In addtion, the mcapbefMakeRoughGuess flag removes the assumption that all good edges have been placed on the test profile. The mcapbefAnalyzeOnly flag will prevent any properties from being changed, but still proceeds with the analysis and returns the analyzed results; this flag is normally combined with the mcapbefKeepPattern flag.

Settings

The settings for AdjustFlags are:

Constant		Value	Description
	mcapbefNoAdjustFlags	0	No flags
	mcapbefMakeRoughGuess	1	Normally, AdjustPropertiesByExample assumes that you have placed edges along the test profile at all positions where they are desired and have removed any edges from positions where they are not desired. However when the mcapbefMakeRoughGuess flag is set, the Pattern and other edge detection properties are computed based only on egdes that are present without trying to make adjustments for sections of the test profile where edges are missing. That is, no assumption is made that all good edges along the test profile have been identified. This allows you to quickly set up edge detection by just going through the following sequence: 1) place one or two good edges, 2) call AdjustPropertiesByExample with the mcapbefMakeRoughGuess, 3) call FindEdges, 4) correct missplaced edges by removing extra ones and/or adding missed ones (see McEditEdgesTool), and 5) call AdjustPropertiesByExample without the mcapbefMakeRoughGuess flag to do a more complete property analysis.
	mcapbefResetHotspot	2	When clear, the MatchHotspot property is not changed. If this flag is set, then the MatchHotspot is always reset to 50 (at the midpoint of the Pattern). If the mcapbefKeepPattern flag is set, then this flag is forced off (that is, when the Pattern is not allowed to change, neither is the MatchHotspot). By default this flag is clear so that the detected Pattern will be relative to the current MatchHotspot.
	mcapbefKeepPattern	4	When set, the Pattern property is not changed. If this flag is set, then the mcapbefResetHotspot flag is forced off. By default this flag is clear, so that AdjustPropertiesByExample will automatically set the pattern. You will usually not want to set this flag, since one of the most useful adjustments that the McProfilesEdges.AdjustPropertiesByExample method performs is to automatically set the Pattern based on where edges have been placed. The exceptional situation where you would want to set this flag is where you know what sort of pattern you are looking for (e.g., a rising or falling edge). In this situation, by setting this flag you confine the AdjustPropertiesByExample to only adjust other parameters.
	mcapbefSetPointsForSameSize	8	When clear, the mcpewfPointsForSameSize bit of the WeightingFlags property is not changed. By default this flag is clear, so that whether size-missmatch weighting is done will not be changed. If the flag is set, then an analysis is made of whether fitting is substantially improved on the test profile by enabling size-missmatch weighting. If so then the mcpewfPointsForSameSize is set in the WeightingFlags property, otherwise it is cleared.
	mcapbefSetPointsForSameOffset	16	When clear, the mcpewfPointsForSameOffset bit of the WeightingFlags property is not changed. By default this flag is clear, so that whether weighting is done will not be changed. If the flag is set, then an analysis is made of whether fitting is substantially improved on the test profile by enabling offset weighting. If so then the mcpewfPointsForSameOffset is set in the WeightingFlags property, otherwise it is cleared.
	mcapbefKeepSizeWeighting	32	When set, the SizeWeighting property is not changed. By default this flag is clear, since you will almost always want to allow the AdjustPropertiesByExample method to be able to set the SizeWeighting property as part of its adjustments.
	mcapbefKeepThresholdForEdge	64	When set, the ThresholdForEdge property is not changed. By default this flag is clear, since you will almost always want to allow the AdjustPropertiesByExample method to be able to set the ThresholdForEdge property as part of its adjustments.
	mcapbefAnalyzeOnly	128	When set, no properties are changed, but the analysis results are returned as if they had been (except that the count of changed properties will be zero). You would usually combine this flag with the mcapbefKeepPattern flag, since without that the results relate to the automatically detected Pattern property, to which you will have no access (since the Pattern property will not be changed). You would often also want to set the mcapbefPreserveBadEdges flag, so that poor test edges are not automatically removed.
	mcapbefPreserveBadEdges	256	Normally, any test edge that is especially poorly correlated with the Pattern or that marks a section of the test profile that has exceptionally small variation will be removed from the test set and so removed from consideration when setting the edge detection properties. This is appropriate, because such edges were almost certainly missplaced by the user (test edges must mark a consistent pattern on the test profile for the property adjustment to be successful). But when the mcapbefPreserveBadEdges flag is set, bad edges are not removed and the operation proceeds in spite of them. You might wish to set this flag along with the mcapbefAnalyzeOnly (and possibly the mcapbefKeepPattern flag) to use the returned results array to analyze a set of edges.
	mcapbefDefault	0	By default all flags are clear. This allows the Pattern, SizeWeighting and ThresholdForEdge properties to be adjusted to allow FindEdges to best match the current set of edges while avoiding finding edges that are not present. The MatchHotspot and size and offset weighting are not changed. If there are any bad edges, they are removed.

Remarks

Edge finding is controlled by a number of properties that can interact in non-obvious ways. In many cases, this does not matter because edges are found only at obvious and unique points on clean profiles (e.g., at points of sharply rising luminance). In other cases, however things can be tricker (e.g., on noisy images) and his can make setting the edge weighting and detection properties a challenge. The AdjustPropertiesByExample will automatically set these parameters based on the edges currently on a profile.

AdjustPropertiesByExample always works with the current set of edges on the ProfileAncestor's first (zero'th) profile. There must be at least one edge on this profile and it must be placed at a location that shows some luminance variation in the profile. The MatchLength property must be set by the caller and is central to the analysis, since it determines the length of the Pattern matched and thus how closely edges may be detected.

The analysis proceeds by first changing the EdgeFindingMethod to mcpefmMatchPattern, if necessary (this method is the most general). Next, the sections of the test profile about the test edges are averaged to come up with the Pattern property (this step is skipped if the mcapbefKeepPattern bit of the AdjustFlags argument is set). The test edge profile sections are analyzed to see how closely they match the pattern. Next, all sections of the test profile that correlate with the Pattern are detected, and spots that do not correspond with the test edges are marked as “non-edges”. The “non-edge” profile sections are analyzed to see how closely they match the pattern. Finally, all of this information is analyzed to try to set the SizeWeighting, ThresholdForEdge and WeightingFlags properties, so as to maximize the chance of finding edges and not finding non-edges. The AdjustFlags argument allows you to specify that some or all of these properties are to be kept in their current state and not adjusted.

After calling AdjustPropertiesByExample there is no guarantee that FindEdges will find exactly the set of test edges marked on the test profile. For well placed test edges, FindEdges will detect the same set of edges but will usually move them a little. Or it may miss some test edges or find some “non-edges”. This is because FindEdges can only mark edges at spots on the profile that correlate well with the Pattern. All bets are off if the test edges mark random or conflicting profile patterns (e.g., some mark rising edges while others mark falling edges). To find edges that mark different profile patterns, you should create an McProfileEdges instance for each type of edge you were interested in (e.g., one for rising edges and one for falling edges).

The Threshold will be set as a relative or absolute threshold depending on the state of the mcpeofAbsoluteThresholding of the OptionFlags property.

Exceptions

The ProfilesAncestor must have at least one profile. A fatal error is generated if the ProfilesAncestor has no profiles.

For any useful edge analysis or property adjustment there must be at least one edge placed on the first (0th) profile. Edges that are placed on completely flat sections (of length MatchLength) will have zero edge pattern StdDev. This is illegal, since such an edge can never be detected by FindEdges. Thus all such zero-variance edges are automatically removed from the current set of edges.

If the original set of edges plus the zero-variance removal step results in zero remaining edges, then all elements of the returned results array are set to zero. In particular, the mcapberiEdgeCount element (4th element, index 3) will be zero in this case. AdjustPropertiesByExample does not treat this “zero test edge” condition as a fatal error, because it is assumed that edges will be placed by users who will occasionally make mistakes in their edge placement. However, the calling program should check for this condition and give feedback to the user.

If the mcapbefPreserveBadEdges AdjustFlags bit is set, then exceptionally bad test edges are not removed. Instead, the calling program should analyze the results array to see if there were particularly “bad” test edges. Bad test edges (that is ones that do not mark edges with a consistent pattern) will have low average correlation between the edge patterns and the Pattern property (mcapberiEdgeCorrAvg), high StdDev of this correlation (mcapberiEdgeCorrStdDev) and/or will have a low minimum correlation (mcapberiEdgeCorrMin). A negative minimum correlation (mcapberiEdgeCorrMin) in particular denotes an exceptionally bad test edge.