Golden template symbol comparison: fix invalid template descriptor

You saved the master image of your symbol, pointed the golden template compare at it, and the software replied with an invalid template descriptor error. The message is blunt but narrow: the match step never received usable learned data. In integration work this comes down to four causes, and three of them are fixed within an hour without touching the optics. This guide walks the causes in order of likelihood, gives a one-minute test for each, and shows the rebuild end to end: capture a representative runtime frame, crop the search region, learn with the strategy the line will use, save the descriptor file, and load that file, not the bitmap, at compare time. A worked example sizes a symbol template and search ROI from real numbers, and the closing sections cover the verification test and the hardware habits that keep a master valid.

What a template descriptor actually is

Golden template matching runs in two phases. The learn phase reads the master image and compresses it into a template descriptor: the edges, gradients and scoring data the engine searches with. The match phase takes that descriptor plus a runtime frame and returns position and a score. The master bitmap is the ingredient; the descriptor is the product of training.

An "invalid template descriptor" report therefore means one of two things. Either the object handed to the match call is not a descriptor at all — you loaded the bitmap, or an empty handle — or the descriptor is genuine but does not cover what the search requests, such as rotation-invariant matching against a descriptor learned without rotation data. Keep two artefacts after training: the master image, for audit and relearning, and the descriptor, for the compare loop. The compare loop loads only the descriptor.

The four causes, in order of likelihood

1. The compare loop loads the bitmap

Most common by far. The save step writes an image of the symbol, and at runtime the code loads that file and passes it to the match call. The match reads the descriptor header, finds image pixels instead, and refuses. Test: log the file the compare actually opens; an image extension is the giveaway. Fix: run the learn function on the master image, save the descriptor it returns, and load that file in the compare loop.

2. Learn and search strategies disagree

The two phases must agree on strategy. A descriptor learned for translation-only matching holds no rotation information, and a match call that then asks for rotation-invariant search rejects it instead of guessing. Test: put the learn settings and the search settings side by side — rotation range, angle tolerance, minimum score, match mode. Fix: relearn with the settings the runtime search uses, and keep those settings in one configuration that both phases read.

3. The template size is out of range

Two bounds bite. Below roughly a 32 × 32 pixel side count the learn step either fails outright or produces a descriptor too feature-starved to match, and the narrowest stroke you must detect should stay at least 3 pixels wide. At the other end, the template must be strictly smaller than the search region on both axes, or the search has nowhere to move. Test: print template width and height beside the search ROI width and height. When the ROI itself is the constraint, start from pattern match error: template image too small. Fix: crop the template tighter, widen the ROI, or put more pixels on the symbol optically.

4. Pixel format or scale mismatch

The master must come from the runtime camera, at the same resolution and in the same pixel format as the live frames. A descriptor learned from a three-plane color image will not match a single-plane grayscale frame, and a master resampled to a new size carries different edge data at a different pixel scale. Test: print width, height, bit depth and plane count for the master and for one runtime frame. Fix: recapture the master with the production camera and convert both sides to the same format at the same point in the pipeline; when frames are deeper than 8 bits, follow the practice in saving 12-bit camera images without losing intensity data.

Rebuild the master template, step by step

1. Capture 20 to 50 frames with the production camera under production lighting. Lock exposure and gain, switch auto-exposure off, and if the line must change exposure while running, do it as runtime camera exposure control without reloading the driver describes.
2. Pick the representative frame: median brightness, symbol centered, no glare.
3. Crop the search ROI — the symbol plus the part's wander on each axis.
4. Run learn inside that ROI with the production strategy settings.
5. Save two files as a versioned pair: the master image and the descriptor.
6. Load the descriptor in the compare loop and run the verification below.

Worked example: an 8 mm symbol at 0.05 mm per pixel

Example values for one molded-logo line (application numbers for this case, not a product spec): a 2 MP camera delivering 1600 × 1200 pixels in 8-bit grayscale, an 80 mm × 60 mm field of view, an 8 mm × 8 mm symbol with 1.0 mm strokes, and ±5 mm of part wander in x and y.

Work the numbers:

• scale = 80 mm / 1600 px = 0.05 mm per pixel
• symbol = 8 mm / 0.05 = 160 px, so the template is 160 × 160 px
• stroke = 1.0 mm / 0.05 = 20 px, comfortably above the 3 px a match engine needs to hold a feature
• wander = 5 mm / 0.05 = 100 px per side
• ROI = 160 + (2 × 100) = 360 px in x and y, inside a 1600 × 1200 frame with room to spare

Decision: template 160 × 160 px, search ROI 360 × 360 px. At 160 px the template clears the 32 px floor by a factor of five, so template size is not your error — check what the compare loop loads and whether the learn and search strategies match. Scale moves it fast: double the field of view to 160 mm and the symbol drops to 80 px with 10 px strokes, still workable; at a 320 mm field of view strokes reach 5 px and rejections begin.

For a different field of view or symbol size, put your own numbers through the camera resolution calculator.

Verify the fix

Reload the descriptor from disk and match it against the master image itself. A healthy descriptor returns the top of the score scale — 1.00 where 1.00 is a perfect match, or 1000 on a 0 to 1000 scale. Then run 20 runtime frames and record the minimum score; release the master when that minimum clears your acceptance threshold with margin, and tune position reporting as covered in pattern search sensitivity versus accuracy.

A score below about 0.95 against the learn image itself means the descriptor does not describe its own source: rebuild it. A pass on the learn image that collapses on live frames means the master no longer represents the line — lighting drifted, focus moved, presentation changed. That is a relearn, not a code bug. For the result side of the call, configuring golden template match results walks the score and overlay settings.

When a golden template is the wrong tool

Intensity comparison inherits known weaknesses: scores degrade with noise, lighting change and occlusion, and the method is not scale tolerant, so the part must hold one distance from the lens. Shiny or curved surfaces glare or stretch the symbol, and good parts fail. When lighting moves through the day, move to edge based pattern matching for stable results when lighting changes. When hue is what separates the marks, plan on color pattern matching for reliable part localization with both sides in the same color format. When the part outgrows one frame, template matching a part larger than the field of view shows the multi-shot route. And when you need defect calls rather than presence and position, through-hole solder inspection beyond golden-image matching shows where the method stops paying.

Hardware that keeps a master valid

A descriptor stays valid only while the images stay identical, so the camera, the light and the compare host all hold the line.

Lock the optics down: a fixed focal length lens, focus secured, auto exposure and auto gain off before the master is captured. The MV-CU020-90GC is a 2.5 MP GigE camera with a 1/1.7" sensor, global shutter and C-mount; convert its color frames to grayscale once, in the same pipeline stage, for learn and match alike. Browse area scan cameras or the camera finder for the sensor size your field of view needs.

A smart camera closes the whole loop inside one device, which removes the PC-side format conversions behind many descriptor errors. The LS-SMC-0063 is a 1.6 MP smart camera with a 16 mm lens, built-in white light and 60 fps operation. The smart cameras range carries the on-device inspection options.

The compare loop wants a host that reboots into the same state every shift. A vision controller such as the MV-VC2140-128G40-1T, with 8 GB of memory and four built-in light channels, strobes the light and runs the match from one box; see vision controllers for the series list, or start a full bill of materials at the system configurator.

Checks before you save the next master

• Master captured by the runtime camera under locked exposure — not a drawing, a scan or a resized crop.
• Pixel format, bit depth and plane count identical for master and runtime frames.
• Template strictly smaller than the search ROI on both axes.
• Learn strategy identical to the production search strategy.
• Descriptor saved and versioned beside the master image.
• Match against the learn image returns the top score before release.

If the error survives all four causes, send the master image, the descriptor and one runtime frame through the contact page and we will trace it with you.