Finding a Template

Searches a live camera image for a stored template and reports every occurrence found.

Address, relative to the module:

find-template/

Inputs

The two required values are the image to search and the template to look for. Everything else has a working default; the parameters that control the search itself are described in Tuning the Search.

Node Type Default Description

input/input-image-address

string

(empty)

Data Layer address of the image to search. Required

input/template-name

string

(empty)

Template to search for, as listed on system/templates. .png is added if you give no extension. Required

The directory it is read from is system/template-dir, which the whole application shares - see Template Storage.

Outputs

Node Type Description

output/result

flatbuffer

The matches found, sorted by confidence

output/status-code

int16

Execution status

output/status-text

string

The same outcome in words

The result

output/result is a hdv.template_match.Result flatbuffer:

Field Type Description

matches

array

One entry per occurrence found, sorted by confidence, highest first

best_index

ulong

Index of the best match. Always 0, because the list is sorted

best_score

float

Confidence of the best match, or 0.0 if nothing was found

template_name

string

The template used for this run

match_mode

string

The matching algorithm used

match_thresh

float

The threshold applied

image_width, image_height

uint

Size of the searched image, so coordinates can be normalised

timestamp

ulong

Microseconds since the epoch, taken when the search finished

Each entry in matches contains:

Field Type Description

oriented_bounding_box

struct

center_x, center_y, width, height in pixels, and angle in degrees

confidence

float

Match score between 0 and 1

scale

float

The template scaling factor this match was found at

rotation

float

The template rotation this match was found at, in degrees

An empty matches list together with status code 1 means the search ran correctly and found nothing. That is a normal result - the part is simply not there, or not similar enough to pass the threshold. It is not an error.

Procedure

  1. Set input/input-image-address and input/template-name.

  2. Adjust the search parameters if the defaults do not fit - see Tuning the Search.

  3. Write to find-template/execute.

  4. Read output/status-code. 1 means the search ran.

  5. Read output/result for the matches, or output/status-text if the status code was negative.

Once the inputs are set they keep their values, so a repeated search is a single write to execute.

Common failures

Failures are described step by step in Troubleshooting:

Searching only part of the image

input/crop/ limits the search to a rectangle - faster, and it avoids matching a part that happens to appear elsewhere in the frame. All four values are uint16.

A zero width or height means "as far as the image goes" on that axis:

Setting Region searched

all four zero (the default)

the whole image

startX=100, startY=50, sizes zero

from (100, 50) to the bottom-right corner

width=0, height=200

a 200 pixel band reaching the right edge

A region reaching past an edge is refused, not trimmed - searching a smaller area than asked for would show up much later as matches that are simply missing. The reason names the input and the limit it broke, for example crop/startX + crop/width (100 + 541 = 641) exceeds the image width 640. A region smaller than the template is refused too, with status -5.

Which image the positions refer to

input/result-coordinate decides what the positions in output/result are measured against:

Value Meaning

IMAGE (default)

The full image at input-image-address, so a position can be used directly for a robot pick whatever the crop region is

CROP

The searched region, whose top left corner is (0,0)

It changes only how the result is reported, never what is found. image_width and image_height in the result follow the same choice.

What a failed search leaves behind

The matches are cleared before the search starts, so a run that fails for any reason leaves output/result empty rather than holding the hits from an earlier image. Reading the result without checking output/status-code therefore shows nothing, not a stale match.

Status -1 (busy) is the exception: that call never ran, so it leaves the result of the search that is in progress alone.

Searching every frame of a camera

find-template searches one image per call. To have a module search every frame a camera streams, with the same inputs, see Finding Templates on an Image Stream (Experimental).