Save a webcam image as a golden template: fix black frames

You built a golden-template comparison from a working example: load a template file, compare a live image, and watch the differences get flagged. The moment you capture the template yourself from a USB webcam, the saved file comes out black, or the compare step runs clean on a part you know is scratched. Both symptoms have ordinary causes: exposure that has not settled, a display mode that overwrites what you think you saved, and an image type the compare step cannot use. This guide gives the capture-and-save workflow that produces a usable template — lock the exposure, discard the first frames, cast to U8, save a PNG, learn once — then the numbers that decide whether your resolution catches the defect, and when to retire the webcam.

Why the frame you save is black

Work through these four causes in order; in practice the first two cover most cases.

Auto-exposure has not settled. The camera's automatic exposure needs a few frames to converge after the stream starts, and the first frames are the dark ones. A loop that saves the first grabbed frame saves the ramp. Test it: grab 20 frames and save the last. If frame 20 is bright, discard the first ten frames in software and keep one from mid-stream.

The frame never reaches the image you save. The acquisition fills one image buffer while the save step writes a different, freshly created one, so the file holds nothing but zeros. Test it in code: read the minimum and maximum pixel value of the image just before writing it. Both at zero on every frame means the buffer is empty, not dark. The fix is to route the acquired frames into the single image buffer the rest of the program reads; webcam frames and the migrated image buffer walks through that wiring.

The scene really is dark. Iris closed, lens cap on, exposure time near zero, or the light controller switched off. When every frame, including frame 50, is black, work through camera black image: check exposure, lighting and lens cap before touching the software again.

The file is fine; the display lies. A display in continuous mode clears between loop iterations, so you are looking at a cleared screen, not at the saved image. Right-click the image display on the front panel and choose Snapshot so it holds the last frame it received. Test it: open the saved PNG in any operating-system viewer. If the part is there, the capture was correct and only the display mode was wrong.

One more symptom belongs here: the compare step returns a clean, black defect image with no error on a part you know is bad. That is not a capture failure. The comparison ran and found nothing, which points at image type or registration — the next two sections fix both.

The capture workflow, step by step

Run this once per part number. It produces one PNG and one learned template file that you reuse every shift.

1. Stabilize the scene. Fixture the part, switch the light on, give it ten minutes to settle, and block office and window light from reaching the part.
2. Lock exposure and gain. Turn auto-exposure and auto-gain off. Set a fixed exposure time — 5 ms is a good starting point — gain at its minimum, and adjust until the histogram of the bright background peaks between 200 and 220 of 255. Auto-exposure left running is the most common reason a template stops matching by the afternoon shift, and feedback loops make it worse: see auto-exposure ROI instability from detection feedback.
3. Prime the stream. Start the acquisition, throw away the first ten frames, and keep the next one.
4. Inspect the kept frame. Show it on a display in snapshot mode. Confirm the part fills the frame and the focus is sharp over the region you care about.
5. Cast to U8. Convert color to grayscale first if the source is color, then cast the image to unsigned 8-bit — the IMAQ Cast function in the IMAQ vision API. The compare step takes U8 on both inputs.
6. Crop to the inspection region. Apply the same rectangle to the template and to every live image so both have identical pixel dimensions. When that rectangle lands outside the rectified image, an invalid ROI after rectification in golden template inspection covers the repair.
7. Save as PNG. PNG is lossless; JPEG blocking on smooth surfaces reads as defects at fine thresholds. For loop code that acquires and writes each frame, see the hardware trigger grab loop in Python.
8. Learn once, compare many. Run IMAQ Learn Golden Template on the saved PNG and save the learned template it produces. At runtime, load that file and feed IMAQ Compare Golden Template the same U8 stream, cropped with the same rectangle. You create the template once; only a part change, an optics change or an exposure change justifies learning it again.

Why U8 and matching dimensions matter

The comparison takes an unsigned 8-bit grayscale image on both inputs, inspected image and template. Feed it 16-bit or color data and it either refuses to run or compares nothing — exactly how a scratched part passes with a clean defect image.

The algorithm registers the two images, subtracts them, and reports differences above your threshold as defects. The alignment setting defines the region of the inspected image that takes part in the comparison. Because the subtraction works pixel against pixel, template and live image must share the same dimensions and sit in the same place; crop both with the same rectangle.

If the learn step rejects the template file with an invalid descriptor, the file itself is malformed rather than the comparison being wrong — fixing an invalid template descriptor in golden template comparison covers that error. For the settings that decide what the match step returns and how defects get reported, see configuring golden template match returns in a Vision VI.

If you also need the sensor's extra depth for measurement, keep it out of the template path: recording 12-bit grayscale without dropping to 8 bits preserves it for analysis while the comparison still uses U8.

Size the image so defects actually show

A template comparison cannot find what spans fewer than about three pixels. Plan on three pixels across the smallest defect you must catch, and treat two as the floor. That number fixes your field of view once the camera is chosen.

Worked example: the camera is a 12 MP USB3 model with 4000 × 3000 pixels and a 1/1.7-inch sensor. A 1/1.7-inch sensor is roughly 7.5 mm wide, so one pixel is 7.5 mm / 4000 ≈ 1.9 µm. The smallest defect to catch is 0.1 mm, and the part fits inside 150 × 110 mm.

Three pixels across 0.1 mm means one pixel may cover at most 0.1 / 3 ≈ 0.033 mm, so the field of view may be at most 4000 × 0.033 mm ≈ 133 mm wide; the part fits with margin. Magnification is m = 7.5 / 133 = 0.056. At a working distance of 250 mm the focal length is f = 250 × 0.056 / 1.056 = 13.3 mm, so fit a 16 mm C-mount lens, the next standard size up. With that lens at 250 mm, m = 16 / (250 − 16) = 0.068 and the field of view is 7.5 / 0.068 = 110 mm wide by 82 mm high. One pixel then covers 110 / 4000 = 0.028 mm, and the 0.1 mm defect spans 3.6 pixels — it gets caught.

For exposure, the part stands still during capture: start at 5 ms at f/5.6 and trim to the same 200-220 background target, then lock exposure, gain and white balance. If a later version of this station presents parts moving at 50 mm/s, the blur rule bites: 50 mm/s × exposure must stay under one pixel of 0.028 mm, so exposure must be under 0.028 / 50 = 0.56 ms. Use a strobed light with a pulse shorter than that instead of a long exposure.

Run your own numbers through the lens focal length calculator and the camera resolution calculator before ordering the lens.

How to prove the template works

Four tests, in this order:

1. Open the saved PNG in an operating-system image viewer. A black file means a capture problem; a good file means the display was the problem.
2. Read the minimum and maximum pixel value of the saved image in code. A healthy scene spans roughly 30 to 230; minimum and maximum both at zero means an empty buffer.
3. Compare a known good part ten times without touching anything. Ten clean runs prove stability; random single-pixel hits that come and go mean ambient light or mains flicker is reaching the part — black bars in camera images: lighting flicker versus exposure separates the two.
4. Mark a known defect about three pixels wide — a fine scratch or an ink line — and confirm the compare step flags it at the threshold you will ship.

When a webcam is the wrong camera

The workflow above fixes the software; it cannot fix the hardware. A webcam regrades every frame through auto-exposure and auto-gain, distorts moving parts with a rolling shutter, and often delivers compressed frames whose artifacts look like defects at fine thresholds. Keep the webcam on the bench and put a machine-vision camera on the line:

The MV-CU020-90GC is a 2.5 MP GigE camera with a global shutter, so with exposure locked the template stays valid frame after frame.

When defect size drives the optics instead, step up in resolution. The LS-CMR-0166 is a 12 MP USB3 camera with 4000 × 3000 resolution at 30 fps — the numbers used in the worked example above.

If you would rather not keep a PC at the station, a vision sensor runs the comparison on the device and exports the pass/fail decision over its own I/O:

The MV-SC5060XM-08M-WBN is a 6 MP mono smart camera with an 8 mm lens and a GigE interface. Browse area scan cameras and smart cameras for the interface your controller speaks, or start from the camera finder.

Quick checklist

• Part fixtured; light warmed up ten minutes; ambient light blocked.
• Auto-exposure and auto-gain off; exposure fixed; background histogram peak 200-220 of 255.
• First ten frames discarded; kept frame checked in a snapshot-mode display.
• Image cast to U8 and cropped with the rectangle the live path uses.
• Template saved as PNG; learn step run once; learned template stored with its settings.
• Known good part: ten runs, zero defects.
• Three-pixel test defect flagged at the shipping threshold.

With the pipeline proven, the camera configurator walks the camera, lens and light choice in order — or contact us and we will size the station from your defect size and part speed.