Pattern match error template image too small: fix ROI size

You wire up capture, learn and search, the captured frame looks perfect on screen, and the learn step still stops with error -1074395234: the template image is too small. The camera is innocent. That error means the learn function received fewer pixels than its minimum template size, and the cause sits in one of three places: the ROI you passed, the resolution of the frame you learned on, or the pixels your optics put on the feature. This guide gives you the size floor, the arithmetic that decides whether your field of view can even reach it, a fix order that works in minutes, and the set-up habits that keep the error off the line.

Why does the learn step reject my template as too small?

The learn step is a hard size gate, not a quality judgment: it rejects any learned region under roughly 32 × 32 pixels, and the check runs inside the vision software before a single feature is extracted.

The function never analysed your part, so there is nothing in the image content to fix. Three things deliver too few pixels. An ROI that was never drawn, or one that a reconnect or mode change reset, hands over an empty or near-empty rectangle. A capture below full sensor resolution — a cropped camera ROI, binning, decimation or a preview-sized buffer — shrinks every feature before your drawn ROI comes into play. And a genuinely small feature in a wide field of view lands under the floor even with everything else correct.

The first two causes account for nearly every occurrence on a real line, because a set-up that puts fewer than 32 pixels on an inspectable part is rare. So check the software side first and let the arithmetic in the optics section tell you when to suspect the lens.

How many pixels does the template actually need?

Treat roughly 32 × 32 pixels as the reject floor and size the template to cover the whole distinctive feature with a small margin; in a correctly scaled set-up the learned rectangle lands between about 100 and 500 pixels across.

The matcher learns the gradient structure inside the rectangle — corners, notches, printed marks, machined steps. The matcher family's documented tolerance is about ±5% size variation and any rotation from 0° to 360°, but only when the template carries enough structure to lock onto. A uniform surface fails at any size, so place the rectangle over the feature's edges rather than its featureless middle.

Two boundaries apply at the same time: the template must be smaller than the region you search in, and the part's expected movement belongs in the search region's margin, never inside the template itself. The opposite problem, a part too large for its field of view, has its own fix in template matching a part larger than the field of view.

How do I check what the learn step really received?

Read the numbers back from your own code at the wire that feeds the learn function — the image's width and height, and the ROI rectangle's x, y, width and height — and the error explains itself the moment those four values are on screen.

Run these checks on the exact buffers and descriptors that reach the learn call:

• Image size. Print the width and height of the frame wired to learn. It must equal the sensor's full count; a display copy or preview buffer loses a factor of 30 or more in pixel count on a 12 MP frame.
• ROI validity. Width and height above zero, x and y inside the image, no clipping. An ROI drawn at one resolution and reused after the resolution changed usually lands partly outside and gets intersected down to almost nothing.
• Same buffer. Wire the captured buffer you inspected, not a copy the interface rescaled for the screen.
• Camera-side ROI. A reduced sensor ROI behaves exactly like a smaller sensor, and its settings persist across reconnects more often than people expect.

If the learn step keeps reading a different image than the one you drew on, that is an input binding problem, not a size problem: ROI image source binding covers it. To redraw the rectangle on the live frame, the overlay mechanics sit in drawing the pattern matching overlay on the image.

Is the optics or the ROI making the feature too small?

Work the arithmetic before touching anything: a feature falls under the 32-pixel floor only when the field of view exceeds feature size × image width ÷ 32, which for a 12 mm feature on a 4000-pixel image means 1.5 m — under a metre of FOV, the ROI is the guilty party.

Run your own numbers through the second line before blaming the lens. At a 4000-pixel image width, a 12 mm feature needs a field of view wider than 1500 mm to fall under the floor; even a 40 mm feature would need 5000 mm. Production fields of view sit between roughly 20 mm and 600 mm, which is why genuine optics-induced cases are scarce.

A feature that really is tiny changes the answer: a 1 mm mark inside a 300 mm field of view spans 1 × 4000 ÷ 300 = 13 pixels, under the floor with a perfectly healthy ROI. There the fix is optical — a longer focal length, a shorter working distance or a higher-resolution sensor — chosen so the span clears about 100 pixels.

What does a correct capture-to-learn set-up look like in numbers?

A 25 mm lens on a 1/1.7" sensor at a 300 mm working distance covers a 92 mm field of view, puts about 43 pixels on every millimetre, and turns a 12 × 9 mm connector feature into a 560 × 430 pixel learned ROI.

Each step follows from the one before:

1. Sensor width. A 1/1.7" sensor measures about 7.7 mm across.
2. Field of view. 7.7 mm × 300 mm ÷ 25 mm = 92.4 mm, call it 92 mm.
3. Pixel pitch on the part. 4000 px ÷ 92.4 mm = 43.3 px/mm.
4. Feature span. 12 mm × 43.3 = 520 px wide; 9 mm × 43.3 = 390 px tall.
5. Learned ROI. Add a 40 pixel margin per side: 560 × 430 px — 17 and 13 times the 32-pixel floor.
6. Search ROI. The learned rectangle plus the part's expected travel on every side.

The capture side needs an image 4000 pixels wide at 30 fps, which is exactly what the 12 MP USB3 area scan camera delivers over USB3.

Check your own sensor, distance and target field of view with the calculator below; its button opens the lens finder filtered to the focal length it computes.

Which camera settings shrink the template before you draw the ROI?

The capture chain can shrink the template before your ROI has any say: a reduced sensor ROI, binning or decimation, a preview-resolution acquisition mode, or a fixed focal length at the wrong working distance all cut the feature's pixel span at the source.

Read the camera's ROI, binning and decimation back after configuration rather than trusting the set call; those settings persist across reconnects and power cycles, and a reverted ROI behaves exactly like a smaller sensor. The camera ROI size, offsets and persistence guide shows where the values hide and how they survive session restarts.

Fixed-lens hardware removes the focal-length escape route. A smart camera such as the MV-SC5060XM-08M-WBN integrates a 6 MP sensor with an 8 mm M12 lens, so its field of view is set by mounting distance alone — run the pixel-span arithmetic at the chosen mounting distance during commissioning and the error never appears from this hardware.

Compact vision sensors show how small the pixel budget can get. Take a typical 0.3 MP sensor with a 3 mm lens focused at 240 mm: a 1/6"-class sensor measures about 3.6 mm across, so the field of view is 3.6 mm × 240 mm ÷ 3 mm = 288 mm, and a 640-pixel-wide image puts 640 ÷ 288 = 2.2 px/mm on the part. A 12 mm feature then spans 12 × 2.2 = 27 pixels — under the floor with no ROI mistake anywhere. That sensor class is built for presence and guidance at coarse detail; a match template on a 12 mm feature at that distance needs a shorter working distance or a higher-resolution sensor.

When neither distance nor lens can move, resolution is the remaining lever: more pixels across the same field of view lift every feature's span in proportion to the image width. A 20 MP 1" C-mount sensor such as the MV-CS200-10GC is the usual next step, and the camera finder filters by resolution, shutter and interface so you can compare the candidates side by side.

How do I fix the error step by step?

Work the list in order and stop at the step that clears the error; in the field the ROI and the capture resolution end it nine times out of ten, and optics only enters when the pixel-span arithmetic says it must.

1. Capture a fresh frame and print its width and height. Expect the sensor's full count — 4000 × 3000 on the 12 MP example above.
2. Print the ROI rectangle you pass to the learn function: x, y, width, height. A width or height below 32 pixels is the whole error.
3. Draw the ROI again on the freshly captured frame, at full resolution. Never reuse a rectangle created at another resolution or in an earlier session.
4. Re-run the learn step on the exact buffer you inspected, not on a display copy.
5. If image and ROI are both correct, compute the pixel span: feature size × image width ÷ FOV. Below 32 pixels, shorten the working distance, lengthen the focal length or raise the sensor resolution until the span clears about 100 pixels.
6. Save the learned template and its settings to file so the production program loads instead of re-learning.

How do I stop it coming back on the line?

Learn once at set-up and load thereafter: the template file stores the learned ROI, the minimum score and the other match settings alongside the image data, so the production cycle never calls the learn step and cannot trip its size gate again.

Keep three habits around that saved file. Record the trained feature's pixel span — feature size × image width ÷ FOV — on the set-up sheet, so any lens or mounting change is checked against the same number before the line runs. Re-learn deliberately: a part revision, a lens swap or a resolution change invalidates the old file, and the pixel-span check repeats before the new template is accepted. And match the matcher to the conditions: when lighting drifts across the line, edge-based pattern matching holds scores where grayscale correlation drops, and when a fixture change presents parts rotated, the 180-degree flip fix sorts the tolerance side.

Learn-once also simplifies the runtime: the production cycle only ever executes the match, which a vision controller or any standard PC handles, while the camera side starts from the area scan cameras page, or from smart cameras when the inspection fits on-device. For a new build, the camera configurator walks sensor, interface and mount in order.

If the same program later grows into surface-defect detection, golden template comparison follows the same learned-template discipline, and its results wiring is its own configuration step: configuring golden template match results. More fixes in this error family sit under the systems topic page.