QR code not detected by vision software: fix image setup

You can see the QR code plainly in the live image, yet the decoder returns nothing: no code, no read, an empty result. That split — visible to your eye, invisible to the software — points at the image setup far more often than at the decoding itself. This guide walks the four checks that restore detection, in the order they fail most often: the pixel format that reaches the decoder, the grey-level separation between dark and light modules, the four-module quiet zone, and the pixel count per module. Each check comes with a quick test and a concrete fix, and a worked example runs the arithmetic for a small direct-part mark. Most frames start detecting again before anyone touches the optics.

First: detection or decode?

A QR read runs in two stages. Detection locates the symbol: on QR that means finding the three nested finder squares, each with the 1:1:3:1:1 dark-to-light ratio, one near each corner — the QR finder pattern detection guide shows how that search works. Decoding then unwraps the grid and repairs errors.

A not-detected or no-code-found result dies in the first stage, before a single data module is read. The fix is therefore never the error-correction level or the payload: it is the image the detector received. If the detector does return a location but the payload comes back empty or wrong, you have the other failure — damaged or low-contrast modules — and the fixes in the decode-rate guide for damaged, low-contrast codes are the right ones.

Some integrated readers collapse both stages into one status line. When yours reports not-detected as a state rather than an empty decode, the model's own knowledgebase is the first stop: a not-detected troubleshooting walkthrough for an industrial code reader runs the same image checks step by step on one widely used reader line.

Feed the decoder 8-bit greyscale

Industrial decoders expect a single-channel, 8-bit greyscale image: values from 0 to 255, one number per pixel. Frames that arrive as four-channel colour with an alpha plane, as 16-bit, or as floating point are either refused outright or binarized on the wrong data, and the detector then sees noise where you see a code. Overlay and transparency effects are a common source: an alpha plane is not brightness information, and many vision tools never fold it into the pixels at all. Webcam and driver pipelines often hand over colour frames, which the decode path must convert.

The test takes seconds. Print the bits-per-pixel and channel count of the exact frame object you pass to the decode call — not of the file you exported earlier. If it is not 8 bits and one channel, convert to 8-bit greyscale before the decode step. When you save frames for replay, keep a lossless format such as PNG or BMP: chroma-compressed files smear module edges and can flip a marginal frame into a miss.

Give the modules grey-level contrast

Detection binarizes: it must split every pixel into a dark class and a light class from the histogram. The split needs only a couple of grey levels of separation, but that is a zero-margin condition; hold about 50 grey levels between the two peaks and detection survives part-to-part reflectivity drift and exposure wobble. To test, histogram the frame or read a line of pixels across one row of modules, and note the mean value of the dark modules and of the light modules. One merged peak means the lighting floods the surface or glare washes the marks out.

The fix follows the surface. A printed label on a flat panel reads under diffuse bright field from a ring or bar light. A laser-etched mark on machined metal reads better in dark field: low-angle rays strike the etched ridges and leave the flat background dark. Shiny caps, foil and laminated film throw a specular flash that erases whole finder squares — polarizing the light and the lens removes it at the source. For code on curved or reflective stock, the reflective-surface QR guide works the geometry case by case.

Where glare is the recurring enemy, buy the polarization in the reader. The MV-IDB005EXI-05NRP carries polarized illumination, focused at 70 mm with a 4.63 mm lens and 1.3 MP resolution.

Keep the four-module quiet zone clear

ISO/IEC 18004 reserves a quiet zone of four empty modules on all four sides of the symbol. Detection needs it: the finder-square search assumes nothing printed beside the corner marks. In pixels the check is border pixels divided by pixels per module, and the result must be at least 4 — at the worked example's 3.0 pixels per module that is a 12 px clear border on every side.

The usual thieves are logos merged into the code, date stamps under the bottom edge, die-cut labels with the graphic running to the paper edge, shrink-wrap creases and neighbouring codes. Regenerate the artwork with the border intact or shrink the mark; do not ask the detector to cope.

Size the modules at three pixels or more

Modules are resolved by sampling, and sampling has a floor. One dark module plus one light module is one full spatial cycle; sampling theory needs at least two pixels per cycle — one pixel per module — and that holds only with no noise and no blur. Real optics soften every edge and real print gains around it, so size fixed-camera detection at three pixels per module, and at four to five for laser-etched direct marks. Very large modules fail too, in the opposite direction: if your modules span tens of pixels, see the downscaling guide before barcode decoding.

Blur kills detection before it kills decode, because the finder squares smear into the background first. Keep motion blur under one pixel: exposure in seconds stays below pixel size in millimetres divided by part speed in millimetres per second.

When the field of view cannot shrink because other features must stay in frame, buy pixels instead. The MV-ID5120RM-08M-RBN steps up to a 12 MP sensor over GigE; its rolling shutter suits parts that stop for the shot.

Worked example: a 4 mm, 57-module QR mark at a 60 mm field of view

The mark: a QR version 10 symbol, which carries 57 modules per side (versions step up by four modules from 21 at version 1), laser-etched 4 mm across on a small aluminium part, with the standard four-module quiet zone. The camera: a 5 MP fixed reader of the LS-CRD-0028 class — a 2560 x 2048 sensor behind an 8 mm lens. The framing: a 60 mm wide field of view, chosen to keep the milled pocket around the mark in picture.

The rule in words: pixels per module equals the sampling density in pixels per millimetre times the module width in millimetres.

The arithmetic: module width = 4 mm / 57 = 0.070 mm. Sampling = 2560 px / 60 mm = 42.7 px/mm. Pixels per module = 42.7 px/mm × 0.070 mm = 3.0.

That lands exactly on the three-pixel floor with no margin, so detection will flicker frame to frame as etch depth and lighting wander. Two fixes. Tighten the framing to 45 mm: sampling becomes 2560 px / 45 mm = 56.9 px/mm, and 56.9 px/mm × 0.070 mm = 4.0 pixels per module — a pass. If the pocket fixes the 60 mm view, step up to a 12 MP sensor, about 4096 px wide in this class: 4096 px / 60 mm = 68.3 px/mm, and 68.3 px/mm × 0.070 mm = 4.8 pixels per module. The quiet-zone corollary moves with it: the border must be at least 4 × 3.0 = 12 px today and 16 px after the reframe.

The ten-minute bench order

Work the checks in this order; each rules out a whole class of causes before you touch the next.

1. Export the failing frame losslessly and read its format: 8 bits, one channel. Convert and retry if not.
2. Histogram the frame: two peaks, about 50 grey levels apart. If the peaks sit closer, fix lighting or add polarization before anything else.
3. Pixels per module: symbol width in pixels divided by modules per side, at least 3 — aim at 5 on etched marks.
4. Quiet zone: border pixels divided by pixels per module, at least 4.
5. Blur: zoom to 400 percent on a module edge; if the edge spans more than about one pixel, cut exposure or strobe the light.
6. Change one variable, re-shoot, and re-run steps 2 to 5. Two changes at once hide which one worked.

Freeze the acquisition so it stays fixed

Detection that passes on the bench and fails on the line is usually acquisition drift. Fix exposure and gain manually: auto modes re-balance every frame and quietly walk the histogram. Fire the strobe from the same trigger that grabs the frame, and decode the same pixel format at runtime that you tuned with on the bench. Keep a golden marked part at the station and re-check the two histogram peaks and the pixels-per-module count at commissioning and after any lighting change.

A reader that shows a live image in setup and a grey frame at runtime has a trigger or hand-off problem: the grey image at runtime guide walks that path, and the code-reading topic collects the decode-side fixes for when detection is solid but reads stay marginal.

When every check passes and detection still fails

If the frame is 8-bit grey, the peaks sit 50 levels apart, the border is clear and the modules sample at four-plus pixels, the remaining suspect is optical reach: the lens cannot resolve a 70 µm module at that working distance, or the lighting geometry cannot illuminate the surface at that angle. Change hardware rather than tune software. For labelled cartons and flat panels a matched fixed-lens reader covers it; for the small etched marks of the worked example, buy pixels or shorten the working distance. Browse the fixed code readers and smart cameras categories, or run mark size and distance through the code reader finder.

The LS-CRD-0028 covers the label-and-panel case: a 2560 x 2048 sensor at 30 fps and up to 60 codes/s with its 8 mm lens.

To size a reader against your own mark, start at the configurator's camera step with the symbol width and working distance in hand. Worked the checks and still stuck? Send the symbol size, working distance and line speed through the contact page and we will size the read with you.