Match

Read-only Class

Read the result of a recognition search. Check found before clicking or using its location; a failed image search can still contain the best candidate's location.

Syntax

Match

This class cannot be constructed directly.

Returns

—

Example

m = Region(100, 200, 300, 400).find("btn", 3000)
if m.found:
    click(m)
    conf = m.confidence

# Recognition.result is only available in Python for the Recognition success branch.
if Recognition.result.found:
    click(Recognition.result, random=0)

Fields

Name	Description
`nameString?`	Matched target name. Template matches use the template name without extension, OCR uses the matched target text, and color matches use Color.
`foundBoolean`	Whether a match was found.
`confidenceNumber`	Confidence score from 0.0 to 1.0.
`confNumber`	Alias of confidence; returns the same score from 0.0 to 1.0.
`pointPoint? \| list[Point]`	Result location: a Point, a list of Points, or None. Color searches return a list, possibly empty. Check found and the value's shape before reading coordinates or indexing a list.
`boundsRegion?`	Rectangle around the result, or None when unavailable. A failed image search may still provide the best candidate's rectangle; check found first.
`regionRegion?`	Alias of bounds; returns the same matched Region or None.
`inference_infodict?`	Extra result details, or None. Model results can include class_id, class_name, timing fields ending in _ms (milliseconds), and input_width/input_height (pixels). Color results can include target_color, sampled_color, max_channel_delta, match_count, and matches. Keys vary by search; check that a key exists before reading it.

Field example

# Read optional details and color points safely.
m = Region(100, 200, 300, 400).find("btn", 3000)
target_name = m.name
is_found = m.found
score = m.confidence
short_score = m.conf
center = m.point
box = m.bounds
same_box = m.region
info = m.inference_info
if info is not None:
    info_class_id = info.get("class_id")
    info_class_name = info.get("class_name")

color_hit = Region(0, 0, 1080, 1920).find_color("#FFFFFF", tolerance=4)
color_name = color_hit.name
if color_hit.found and color_hit.point:
    first_color_point = color_hit.point[0]

# In the Recognition success branch:
current = Recognition.result
if current.found:
    text(current.name)
    current.highlight(color="yellow", auto_hide_ms=800)

Methods

2 methods

Match.highlight

Method

Mark a found result on screen. Draws bounds when available, otherwise a square around each point; does nothing when found=false. Drawing is scheduled, so the call can return before the frame appears. Only the latest update pending for the same instance is drawn at the next display frame.

Syntax

match.highlight(color="green", line_width=2, region_width=36, auto_hide_ms=0)

Parameters

Name	Description
`colorColor \| String \| Number`	Highlight color. Optional · Positional or named Default: `green`
`line_widthNumber`	Outline width in pixels, with a minimum of 1. Optional · Positional or named Default: `2`
`region_widthNumber`	Square width in pixels when only points are available, with a minimum of 1. Optional · Positional or named Default: `36`
`auto_hide_msNumber`	Time before hiding, in milliseconds. 0 or a negative value keeps the highlight visible until highlight_off(). Optional · Positional or named Default: `0`

Returns

Match — The same Match, so you can continue calling its methods.

Example

m = Region(100, 200, 300, 400).find("start", 3000)
m.highlight(color="yellow", line_width=3, auto_hide_ms=1200)

Match.highlight_off

Method

Turn off the active highlight generated from this match instance.

Syntax

match.highlight_off()

Returns

Match — Returns the same match after turning highlight off.

Example

m = Region(100, 200, 300, 400).find("start", 3000)
m.highlight()
m.highlight_off()