Find Image
Waits for a saved template image to appear on screen, then branches on whether it was found.
Find Image is the workhorse of visual automation. Most flows are a chain of "look for this, then act on it".
Purpose
Looks for one or more captured template images on the live screen and reports where the best match is.
Use it to wait for a button or icon to appear, confirm a screen loaded, or feed a match's coordinates into a Click. It keeps re-checking fresh screenshots until it matches or the timeout runs out — so it doubles as a smart wait.
When to use it
- Waiting for a button, icon, or screen to appear.
- Confirming an action worked, by detecting the screen it should have produced.
- Locating something whose position moves, so a Click can tap it.
- Distinguishing between several possible screens, using branch-by-template.
When not to use it
- To read a value — a number, a timer, coordinates. Use Read Text.
- To detect state with no distinct icon — a bar emptying, a screen fading. Use Check Region.
- As a fixed delay. If you just need to pause, Wait is clearer.
Requirements
At least one captured template asset. Templates are captured from Live Preview and stored with the flow.
How it runs
At least one capture and match always runs, even for a very small timeout.
On timeout with no match, the node routes Failure but its status is success. The detection worked; the image simply was not there.
This means a not-found never trips a retry policy and never counts toward the consecutive-failure guardrail. See status versus route.
Settings
| Setting | Type | Range | Default | What it does |
|---|---|---|---|---|
| Template(s) | asset ref | 1–16 | — | The captured image(s) to look for |
| Template name | string | ≤ 120 chars | — | Friendly label for the capture |
| Threshold | number | 0.5–0.99 | flow default (0.88) | Minimum match confidence; higher is stricter |
| Search region | rectangle | percentage of screen | whole screen | Restrict the search — faster and avoids false hits |
| Timeout | integer | 1–120000 ms | flow default | How long to keep looking |
| Poll interval | integer | 50–120000 ms | flow default (250) | How often to re-capture |
| Multi-template | boolean | — | false | Match a set of templates; highest confidence wins |
| Branch by template | boolean | — | false | One output port per template instead of one Success |
| Colour mode | choice | color, grayscale | color | Match in colour or greyscale |
| Scale mode | object | none or multiScale | none | Match at a range of sizes |
| Ambiguity mode | choice | requireUnique, best, all | best | What to do when several places match |
| Min best/second-best delta | number | ≥ 0 | — | How much clearer the winner must be, for requireUnique |
| Max matches | integer | 1–100 | — | Cap for all mode |
| Save results to variables | list | ≤ 16 | — | Bind output fields to variable names |
Threshold
The single most impactful setting.
- 0.88 is a good starting point and the product default.
- 0.95+ frequently misses valid matches — a one-pixel shift or a slight anti-aliasing difference drops the score.
- Below 0.75 starts matching noise.
Tune by testing, not by guessing: use Test Node to see the actual confidence your template achieves.
Search region
Setting a search region is the cheapest available speed-up: the matcher works on a crop instead of the whole frame. It also prevents false positives elsewhere on screen.
If you know roughly where something appears, restrict it.
Multi-template and branch-by-template
Two separate switches that stack:
| Configuration | Behaviour | Ports |
|---|---|---|
| Single template | Match one image | success / failure |
| Multi-template on | Match a set, keep the highest confidence | success / failure |
| Multi-template + Branch by template | Match a set, route by which one matched | one port per template + notFound |
Branch-by-template is how you handle "this screen could be in one of four states" in a single node. The template's id is the port key, so renaming a template keeps its branch; deleting one removes its port.
Save results to variables
Bind the node's output fields to variable names a later node can use:
centerX, centerY, confidence, matched, matchedTemplate, match x / y / width / height, scale
The variables are auto-declared on a successful match.
To tap what you found, you do not need variables at all — set the Click node's coordinate source to this Find Image node. Use variables when you need the numbers for arithmetic or logging.
Ambiguity policy
| Mode | Meaning |
|---|---|
best | Take the highest-scoring match (default) |
requireUnique | Fail if the runner-up is too close — use when a wrong pick is costly |
all | Report every match above threshold, up to maxMatches |
Ports
| Port | Taken when | Required |
|---|---|---|
| Success | The template was found | Yes (single/multi mode) |
| Failure | Not found before the timeout (status still success), or a recoverable detection error — ambiguous match, engine failure, low-quality template | No |
| Cancelled | The run was stopped mid-search | No — never followed |
| Fatal | Capture failed, device disconnected, or a parameter is invalid | No — never followed |
| per-template | Branch mode: the matched template's own id | No |
| notFound | Branch mode: no template matched | No |
Basic example
Wait for a button and tap it:
- Template: the Start button, tightly cropped
- Threshold:
0.88 - Timeout:
5000ms
Wire Success → Click (coordinate source = this node), Failure → Stop: failure.
Realistic example — optional popup
A daily-reward popup appears some days but not others. Both cases are normal:
The short timeout matters: you are asking "is it here now", not waiting for it to arrive. A 30-second timeout here would waste 30 seconds on every run where there is no popup.
Advanced example — branch by template
One node decides which of four screens you are on:
This replaces four sequential Find Image nodes with one, and one screenshot instead of four.
Best practices
- Capture a tight crop of just the target, without background. Background is what makes a template stop matching later.
- Start at threshold 0.88 and tune with Test Node.
- Always wire Failure. An unwired Failure port turns "not found" into an ended run.
- Set a search region whenever you know roughly where the target is.
- Match the timeout to the question. "Is it here now?" = short. "Wait for it to load" = long.
- Use the node as a Click's coordinate source rather than plumbing coordinates through variables.
- Prefer branch-by-template over a chain of Find Images when you are identifying which of several screens is showing.
Performance notes
- Cost per poll ≈ (region area) × (number of templates) × (number of scales). All three multiply.
- Search region is the biggest lever. Cropping to a quarter of the screen roughly quarters the matching work.
- Multi-scale matching is expensive — each scale step is another full pass. Enable it only when the target genuinely changes size.
- Greyscale is cheaper than colour and often just as reliable for UI chrome.
- A short poll interval means more captures per second. Below ~150 ms you are usually spending more on capture than you gain in responsiveness.
- A long timeout costs nothing when the image is present — the node returns immediately on match. Long timeouts only cost time in the not-found case.
Memory notes
- Templates are loaded and cached for matching. Many large templates mean a larger working set; tight crops are smaller in every sense.
- Every poll captures a fresh frame. Frames are transient, but a very short poll interval increases capture churn.
allambiguity mode with a highmaxMatchesretains a list of matches; keep the cap sensible.
Common mistakes
| Mistake | What happens | Fix |
|---|---|---|
| Wiring only Success | "Not found" ends the run | Wire Failure |
| Cluttered template | Confidence drops as the background changes | Tight crop of the distinctive part |
| Threshold at 0.95+ | Misses valid matches | Start at 0.88 |
| Timeout too short for a loading screen | Gives up during the animation | Match the timeout to what you are waiting for |
| Long timeout on an optional element | Wastes that time on every run | Short timeout for "is it here now" |
| Retry policy added to "search harder" | Never fires — not-found is status success | Raise the timeout instead |
| Multi-scale left on everywhere | Detection several times slower | Enable only where sizes vary |
Troubleshooting
It never finds an image that is clearly on screen. Lower the threshold and check with Test Node what confidence you actually get. If it is far below 0.88, the template probably includes background that has changed.
It matches the wrong place.
Set a search region, or switch ambiguity to requireUnique with a delta so a close call fails rather than guessing.
It worked, then stopped after a resolution or zoom change. Template matching is pixel-based. Re-capture the template, or enable multi-scale detection in the flow's feature gates.
The node is slow. Check the region size, template count and scale range — those three multiply. Start by adding a search region.
A branch-by-template port disappeared. Its template was removed from the selection. The editor prunes the orphaned edge.
FAQ
Does a not-found count as a failure for retry or health limits?
No. Its status is success.
Can I search only part of the screen? Yes — set a search region. It is faster and more reliable.
How many templates can one node hold? Up to 16.
What confidence should I aim for? Comfortably above your threshold. If your best real-world match is 0.89 against a threshold of 0.88, the margin is too thin — improve the template.
Is the poll interval the same as the timeout? No. Poll interval is how often it re-checks; timeout is how long it keeps trying.
Related nodes
- Click — tap what was found
- Swipe — centre what was found
- Read Text — read a value instead of finding a picture
- Check Region — detect state with no icon
- If — branch on this node's outcome later in the flow
Related pages
- Execution Model — status versus route
- Flow Anatomy — template quality