CV QR Detect

Decodes QR codes with OpenCV's own detector - no ONNX files, no downloads, no WeChat model. Drop an image in, get text and geometry out.

The two detectors

This is worth understanding before you tune anything, because they fail differently.

The classic detector (cv2.QRCodeDetector) scans lines looking for the 1:1:3:1:1 finder-pattern ratio and is what the eps_x/eps_y tolerances belong to. It's fast and it's a bit fussy: raise eps_x (0.2 by default) for blurry or low-contrast codes, lower it to reject false positives. use_alignment_markers refines corner positions using the code's alignment markers - turn it off for a damaged code whose markers are unreliable.

The ArUco-based detector (cv2.QRCodeDetectorAruco) reuses the ArUco marker machinery and is, in practice, usually the one that works on small, rotated, or perspective-distorted codes - a phone photo of a poster, a code at the edge of a wide-angle frame. It ignores the classic knobs entirely, so don't tune eps values while it's selected and wonder why nothing changes.

mode then chooses multi - every code in the image, the normal case - or curved, which runs detectAndDecodeCurved for a single code wrapped around a cylinder. Curved is a specialist: it rectifies before decoding and fails on some flat codes, so don't leave it on as a general setting.

Outputs, which are all data

Nothing here draws. found (a boolean you can branch on), qr_count, and text - every payload one per line, straight into Preview as Text.

For visuals you pick: bboxes is a BOUNDING_BOX with one axis-aligned box per code plus the decoded text as its label, so core Draw BBoxes gives you a labelled overlay in one wire. corners is the exact (N4, 2) quads, and connections is an index-pair list that closes each quad - feed those two to CV Draw Connections when you want the true quad outline rather than the axis-aligned approximation. labels is a (N4,) string array carrying each code's text on its first corner and blanks elsewhere, which paired with corners and CV Draw Labels writes the payload once per code instead of four times.

texts is the (N,) payload array, where an empty entry means a code was located but not decoded - that distinction is useful, since a located-but-unreadable code usually means damage or resolution, not a detection failure. And straight_codes is an IMAGE batch of the rectified, binarised symbols the decoder read, white-padded where versions differ.

Installing

ComfyUI Manager → search "ComfyUI CV", or by hand:

cd ComfyUI/custom_nodes
git clone https://github.com/bmad4ever/comfyui_cv
# restart ComfyUI

Python ≥ 3.12, a recent ComfyUI on the V3 node API, and the pinned contrib wheel: opencv-contrib-python-headless~=5.0.0.93 alongside numpy and torch. The QR classes live in cv2's objdetect module, which the pack reaches through hand-written nodes because the generator only wraps plain functions.

Gotchas

One frame only. An IMAGE batch is processed as its first frame. To scan a clip, iterate.

Structured Append split messages decode as one joined message on the first part, with the rest blank. That's expected, not a bug - and it's how CV QR Encode's multi-code output comes back together when all parts are visible in one image.

Zero codes is a valid result, not a failure: empty outputs with found=false. If found is true but your text preview is empty, you're in the located-but-undecodable case, and straight_codes will show you why.

Broken image quality is a detection problem, not a QR problem. Heavy compression, motion blur and glare all defeat finder-pattern scanning before anything clever can help. If you're fighting codes in a pipeline that has also been through lossy steps, that's where to look first.