Tuning the Search

input/confidence-threshold is the smallest score a match must reach, from 0 to 1. It defaults to 0.6.

Scores here are comparable between runs, so the practical method is to measure rather than guess:

A threshold at or above 0.9 will usually reject everything, including good matches.

input/nms-min-dist is the minimum distance in pixels between two reported matches. Where several matches fall within that distance, only the highest scoring one is kept.

Without it a single part is commonly reported several times, as a cluster of matches a few pixels apart. Set it to roughly half the size of the part in pixels. The default of 0 keeps every match, which is only useful when parts genuinely sit closer together than their own size.

input/preprocess/blur-sigma-x applies a Gaussian blur to both the image and the object’s picture before matching. It is off by default.

Turn it on - start at 1.0 - when scores hover near the threshold or the images are noisy. Measured on real fixtures, blurring lifts weak matches noticeably (roughly 0.53 to 0.60) while leaving already strong matches about where they were. That is exactly why it is off by default: it helps the borderline cases and does nothing for the healthy ones.

blur-sigma-y defaults to the same value as X. The kernel sizes are computed from the sigma unless you set them, in which case they must be odd. All of them are ignored while blur-sigma-x is 0 or less.

The blur is applied before binning, so a sigma stays a count of pixels in your original image and does not change meaning when you change bin-size.

input/preprocess/bin-size downsamples both the image and the object’s picture by an integer factor before matching. It defaults to 1, which disables it. This is the setting that makes a search faster.

The cost of a match scales with the pixel count, so binning pays off steeply. Measured on a 1920x1080 image with a 128x128 object, mean of five runs:

What you give up is precision - reported positions quantise to bin-size pixels - and detail. Bin far enough and the object’s picture no longer has the edges the detector keys on: at bin-size 8 a 128x128 object is reduced to 16x16 and the detector refuses it. That is reported as a failed run naming the refused object, never as an empty result, so it cannot be mistaken for an absent part.

Positions in output/result are always in the pixels of the image you configured - the application scales them back - so raising bin-size changes nothing about how you read the result.

Small objects reach that limit sooner than large ones. Raise bin-size one step at a time and watch the scores: when they start dropping towards the threshold, you have gone one step too far.

bin-size costs you nothing at the edges of the region: it is searched exactly as configured whatever the bin - see The region is searched exactly as given.

input/pyramid lists the image pyramid levels the search runs at, defaulting to [1,2]. Larger values make the detection more tolerant but coarser.

Which levels are valid depends on the image size, and there is no general rule. An invalid combination is reported as a failed run with a negative status code rather than being guessed at, so change it in small steps and check the status.

input/crop/{startX, startY, width, height} restricts the search to part of the image. A zero width or height reaches the corresponding edge, so the default all-zero region searches everything and startX=100 with zero sizes searches from there to the bottom right corner.

Two reasons to use it: speed, since a smaller region is searched faster, and reliability, since excluding areas where the part cannot be avoids false matches on similar-looking background.

This is the first thing to reach for when a search is too slow, because unlike bin-size it costs no precision at all.

The region is searched exactly as you set it - see The region is searched exactly as given.

If an object is missed at particular orientations while being found reliably at others, no setting here will fix it. The detector does not rotate templates - teach another view at the orientation being missed. See Creating an Object.

Likewise, if the object is missed when it sits closer to or further from the camera, teach a view at that distance.

The order of things to try:

Raising input/pyramid is not on this list: measured, it is slightly slower rather than faster.

Keep the settings stable between runs. The detector is compiled from the object’s picture on the first run and reused while nothing changes; changing any input rebuilds it, and rebuilding costs far more than a detection.