QR detector works in Python but fails in C++: fix the input image

Your prototype decodes the QR in a Python console, and the same file returns an empty string from the C++ build on the device — same OpenCV version, same code contents. The discrepancy is almost never the algorithm; it is the Mat that reaches detectAndDecode: a different load flag, a rescaled frame, a recompressed screenshot or a code that sits at 2 pixels per module, where the smallest perturbation decides success. This guide gives you the test that proves what each program is actually seeing, the pixel-per-module arithmetic behind the failure, the resize and threshold fix that restores detection, and the point at which a dedicated reader is the sturdier answer.

Why does the same QR decode in Python but fail in C++?

At the same OpenCV version the Python and C++ QRCodeDetector are one implementation behind two bindings, so the algorithm is not what changed; the Mat you hand it is, and in practice the file, its load flags or its scale differ.

Both calls run the same objdetect code. A bench case has a recognizable shape: both sides report the same version, the C++ code checks for an empty Mat before calling the detector, the check passes, and detectAndDecode still returns an empty string. That combination clears the file read and leaves three suspects, in the order they usually turn out to be guilty:

1. The two programs hold different pixels: a reduced-size load flag, a rescale before the call, or a different file under the same name.
2. The symbol sits at a marginal size, around 2 pixels per module, where the smallest perturbation flips the result.
3. Lossy recompression or a cropped quiet zone pushed a readable code just under the detection threshold.

The third item explains the puzzling part: editing the QR payload changes the outcome even though nothing in the parsing changed. That is the signature of an image at its size limit, not of a decoder bug. For the frame, focus and lighting checks that sit upstream of any detector, see QR code not detected by vision software: fix image setup; the topic page collects the other code-reading guides.

How do I check that both programs are looking at the same pixels?

Run one test: save the Mat from the failing program with imwrite, decode that exported file in Python, and print rows, cols and type on both sides; if the sizes differ, or Python fails on the exported file too, the input image is the whole problem.

imwrite writes exactly the pixels your C++ code passed to the detector, so Python becomes the referee. Three outcomes cover every case:

• Python decodes the export and the sizes differ: your C++ path is loading or rescaling differently, and the load-flag check below finds it.
• Python also fails on the export: the image is marginal everywhere, and the module-size arithmetic in the next section decides the fix.
• Sizes and types match and both sides fail identically: the input is consistent and simply too small or too damaged for this symbol, and the resize fix is what remains.

On Android the image often arrives as a byte buffer from an asset or a camera callback rather than as a path. Decode the buffer with imdecode and the same flag you use on the desktop, and be suspicious of any platform bitmap option that downsamples at load time: a half-size decode halves the pixels per module before your code runs. Log rows, cols and the Mat type once on both sides; that pair of numbers settles most arguments about which program changed the image.

How many pixels per module does the QR detector need?

Plan for about 3-4 pixels per module, treat 2 as the floor where detection starts to fail, and compute it as code width in pixels divided by modules per side, which is 17 plus 4 times the version number.

The floor comes from the finder patterns: each corner square must keep its 1:1:3:1:1 dark-light alternation resolvable, and below roughly 2 pixels per module that alternation aliases into noise. Detection begins at those squares, so the finder-pattern location step is exactly what starves first when pixels run short. The 3-4 pixel target is working practice rather than a standard constant; it leaves margin for blur, JPEG artifacts and threshold wobble.

Worked example, with inputs you swap for your own: the payload is a JSON string of about 100 characters, which at error-correction level M needs version 6, because byte mode holds 84 characters at version 5 and 108 at version 6. That gives 17 + 4 × 6 = 41 modules per side. The screenshot shows the code 100 px wide, so pixels per module = 100 ÷ 41 ≈ 2.4, inside the failure band — which is why the same file decodes sometimes and not always. The target is 41 × 4 = 164 px of code width, so the upscale factor is 164 ÷ 100 ≈ 1.6.

The same arithmetic runs in reverse when frames come back too coarse: downscaling before barcode decoding covers the large-module failure and when a smaller image actually helps.

Which imread flags change the image before detection?

The IMREAD_REDUCED_COLOR_2, _4 and _8 flags shrink the file to 1/2, 1/4 or 1/8 of its pixels at load time, so the same path that reads fine in Python at full size fails in C++ by design, not by bug.

cv2.imread and cv::imread share the same defaults, so plain loads behave identically, and IMREAD_GRAYSCALE is harmless here because the detector converts colour to gray internally. The flags that quietly change results are:

• IMREAD_REDUCED_COLOR_2 / _4 / _8 and their grayscale variants: preview conveniences, fatal for a marginal symbol.
• IMREAD_IGNORE_ORIENTATION: skips the EXIF rotation that imread otherwise applies to JPEGs, so a phone photo carrying orientation data lands differently on each side.
• The flag you pass to imdecode for buffers: keep it identical to the file flag, or the round-trip test lies to you.

When frames come from a camera rather than a file, the same orientation trap moves upstream to capture, and correcting camera frames before decoding works through it at that stage.

Can JPEG recompression and a broken quiet zone stop a working decoder?

Yes: lossy recompression adds noise concentrated on module edges, and quiet-zone violations cut the four-module margin the QR specification reserves, either of which pushes a marginal symbol under the detection threshold even though its pixels are all present.

A screenshot is already a lossy JPEG, and every save through an app pipeline adds artifacts exactly where binarization looks. Test compression in one move: re-save the failing image as PNG, which is lossless, and decode that. If the PNG decodes and the JPEG does not, compression is the margin killer, and handing images between programs as PNG or raw buffers ends the problem.

The quiet zone is the second half. The QR specification reserves a margin of four modules on all sides, and detectors use it to separate the finder squares from the background. A screenshot cropped tight to the symbol, or a label whose border graphic runs into the margin, starves detection at any resolution. Keep the four-module border inside every programmatic crop; the safe barcode cropping guide works out the geometry.

Why does changing the QR payload sometimes make it decode?

Because the payload chooses the mask pattern and the symbol version: eight mask patterns alternate modules differently, and a longer string can push the code up a version, so each edit moves the noise phase and the pixel budget rather than the parser.

At 2.4 pixels per module, one mask lands its dark-light transitions cleanly on pixel boundaries while its neighbour straddles them; the detector succeeds on one and fails on the other. The payload also sets the version: ten extra characters at level M can move the symbol from version 5 to version 6, growing it from 37 to 41 modules per side and cutting pixels per module by about 10 percent.

Error correction does not rescue this. The Reed-Solomon layer repairs damaged data cells after the symbol is found; it cannot help when the finder patterns never resolve. Treat a payload edit that fixes the decode as a diagnosis, not a repair: the image sits at the edge, and the honest fix is more pixels per module.

How do I resize and preprocess the image so the C++ call decodes?

Upscale so each module spans about 4 pixels before detection: compute the factor as 4 divided by the current pixels per module, resize with cubic interpolation for non-integer factors or nearest-neighbour at exact integers, then binarize with an Otsu threshold and decode again.

In order:

1. Load at full size with IMREAD_COLOR; no reduced flags anywhere in the path.
2. Measure the code width in pixels and compute pixels per module; below about 3, upscale by 4 ÷ pixels-per-module.
3. Convert to gray and threshold with Otsu, which re-sharpens module edges smeared by interpolation and JPEG noise.
4. Decode; if the symbol wraps a cylinder and still fails, try the curved variant once, because flat labels never need it.

// Illustrative example: upscale until each module spans about 4 px, then decode.
cv::Mat img = cv::imread(path, cv::IMREAD_COLOR);  // full size, no reduced flags
int modules = 41;                                  // 17 + 4 x version 6
double codePx = 100.0;                             // measured code width in px
double ppm = codePx / modules;                     // 2.44 px per module
double f = 4.0 / ppm;                              // 1.64 upscale factor
cv::Mat big, gray, bw;
cv::resize(img, big, cv::Size(), f, f, cv::INTER_CUBIC);
cv::cvtColor(big, gray, cv::COLOR_BGR2GRAY);
cv::threshold(gray, bw, 0, 255, cv::THRESH_BINARY | cv::THRESH_OTSU);
cv::QRCodeDetector qr;
std::string data = qr.detectAndDecode(bw);         // non-empty means decoded

On the worked example this lifts the symbol from 2.4 to about 4 pixels per module, where the finder squares resolve reliably, and the file that failed on the device decodes on it.

Prevention comes down to four habits: log rows, cols and Mat type plus the OpenCV version string in both builds; hand images between programs as PNG or raw buffers, never as re-compressed JPEG; keep the four-module quiet zone in every crop; decode at full resolution and scale down only after the decode, for display.

When should production reads move to a dedicated code reader?

Move to a dedicated reader when the code must decode reliably every cycle under line conditions: an industrial fixed code reader adds a controlled strobed light, a hardware trigger and a confidence value with each decode, which a generic detector call does not give you.

A bench script answers whether one image decodes; a line tool answers whether every part decoded and which parts did not. Industrial fixed code readers wrap the decoder with that trigger, light and per-read confidence, so a marginal code shows up as falling confidence instead of a silent empty string — the judgment the barcode read confidence guide applies to software results. Glare and impact at the station are what code reader accessories such as protective covers and light boards are for.

Three readers that take this job off your own decoder:

The MV-ID3013PM-12M-WBN carries a 12 mm lens at 1.3 MP, the MV-ID813M-05S-WBN-SR carries 4.9 mm at the same resolution, and the choice between them is working distance once the code size is fixed. The LS-CRD-0028 reads up to 60 codes per second from its 2560 × 2048 sensor when the line runs fast.

Where the station needs more than the code — presence, orientation, a character check beside it — a smart camera runs that application on the device and hands results to the PLC. The MV-SC3050XC-16M-ATN-H pairs a 5 MP color sensor with a global shutter and an M12 mount, and all of these filter down from the camera and reader finder.

One more number if you are specifying hardware around the code: at 3 pixels per module a version-6 symbol needs 41 × 3 = 123 px, so a 24 mm code inside a 40 mm field of view asks for about 205 px of sensor width — far below any industrial camera, which is why sensor resolution almost never explains a QR failure and the pixel pipeline does. The camera resolution calculator runs that field-of-view-and-feature computation for your own numbers:

If the read stays in software, the checks above fix it; if it moves to the line, size the station as a system, starting at the camera step: