Interface ImageSearchDiagnostics

True when a match met the threshold.

Best final score anywhere on the searched area, whether or not it met the threshold. This is the number threshold is compared against.

Best SHAPE-only score anywhere, before colour and brightness verification. Like score it is a maximum over the whole searched area, taken independently, so the two need not describe the same position. A structure score well above score is a hint that colour verification rejected something, but only reason decides that: absent templates still reach 0.42 through 0.84 structurally, so a high value here is not on its own evidence the element was present.

Which kind of outcome this was. Each calls for a different fix; see advice. This is the field to branch on, and it is a closed set, so a switch on a misspelled value is a type error rather than a branch that silently never runs. templateTooLarge means the template does not fit inside the area searched, which is a whole screenshot used as a template, or a region smaller than the thing being looked for; widening the region or cropping smaller fixes it, and nothing about the template's appearance will.

One sentence naming the most useful next change, derived from the measurements in this object. Safe to show a user verbatim.

Template width in physical pixels, as decoded.

Template height in physical pixels, as decoded.

Fraction of the template that is not transparent. Below 0.6 the search cannot use its fastest levels: a 31%-opaque crop measured about 3.4x the cost of an opaque crop of the same dimensions, so a heavily erased template is both slower and easier to confuse.

Standard deviation of the template's visible brightness. Under about 5 the template is nearly one flat colour and will correlate with many places at once. A HIGH value does NOT mean the template is distinctive: this measures spread, not detail, so a crop of one straight boundary between two flat areas scores high while carrying almost no information. One measured at 50.1 matched an unrelated screen at 0.9987. Read a low value as a warning and a high value as no information either way; what makes a template safe is internal detail such as glyphs, icons or texture.

Standard deviation of the CAPTURED area's brightness. Near zero means Windows could not read the screen and handed back a blank image, which it does instead of failing for a fullscreen-exclusive game, a window that excludes itself from capture, or a locked session. Every score is zero in that case and none of them says why, so this is the field that separates cannot-see-the-screen from element-not-present; reason reports it as captureUnavailable.

True when the template carries so little structure that it is scored by absolute difference instead of correlation. Such a template matches any area of a similar colour.

Milliseconds this whole call took, capture included, for deciding whether a polling loop is affordable. Capturing costs a few milliseconds even for a small region, so a tight loop over a small region will not drop below that floor however much the area shrinks.

Width of the area actually searched, after region was applied.

Height of the area actually searched, after region was applied.

A region worth passing on later calls. Present only when this call matched AND no region was passed in, so it appears once, on the whole-screen call that found the element; a call that already had a region never suggests a smaller one. Sized so the element can move by its own width or height and still be inside, then trimmed to the desktop, so an element near a screen edge yields a smaller rectangle rather than one hanging off it. Always within the capture limit, so it can be passed straight back. Passing it is the single largest cost reduction available, because search cost tracks the searched area.