计算机视觉 / 系统课时
检测二维码
检测二维码
二维码检测包含两个彼此独立的结果:先在图像中定位二维码区域,再对该区域进行解码。本节使用 OpenCV 的 QRCodeDetector 同时取得四角位置和文本数据,并根据“定位失败”与“解码失败”选择不同处理方向。
学习目标
- 使用
QRCodeDetector定位二维码并读取文本 - 根据四角坐标绘制检测区域并保存标注图
- 区分未定位、已定位但未解码和成功解码三种结果
定位与解码分别看
detectAndDecode 会尝试一次完成定位和解码,但返回值要分开判断。points 表示检测到的二维码四边形;data 是解码出的文本。两者不能混为一谈:有坐标但文本为空,说明二维码已经找到,只是内容尚未成功恢复。

四角坐标最直接的用途是画出检测框、裁剪二维码区域,或在视频中跟踪二维码位置。读取文本后仍应按业务规则验证内容,不应因为它来自二维码就默认可信。
完整检测示例
下面的程序读取单张图片,调用 detectAndDecode,输出文本和角点,并在成功定位时保存带绿色边框的标注图。示例针对单个二维码;同一画面有多个二维码时应改用多码接口。
import argparse
from pathlib import Path
import cv2
def detect_qrcode(input_path: str, output_path: str) -> None:
image = cv2.imread(input_path)
if image is None:
raise FileNotFoundError(f"无法读取图像: {input_path}")
detector = cv2.QRCodeDetector()
data, points, _ = detector.detectAndDecode(image)
if points is None:
print("localized: no")
print("decoded: <empty>")
return
# 保留检测器返回的四边形,既能做可视化,也方便后续裁剪。
corners = points.astype(int).reshape(-1, 2)
cv2.polylines(image, [corners], True, (0, 255, 0), 3)
if data:
print(f"decoded: {data}")
else:
print("decoded: <empty>")
print(f"corners: {corners.tolist()}")
output = Path(output_path)
output.parent.mkdir(parents=True, exist_ok=True)
if not cv2.imwrite(str(output), image):
raise OSError(f"无法写入图像: {output}")
print(f"saved: {output.resolve()}")
if __name__ == "__main__":
parser = argparse.ArgumentParser()
parser.add_argument("input", help="包含二维码的输入图片")
parser.add_argument("output", help="标注结果图片")
args = parser.parse_args()
detect_qrcode(args.input, args.output)预期输出
decoded: <VALUE>
corners: [[<VALUE>, <VALUE>], [<VALUE>, <VALUE>], [<VALUE>, <VALUE>], [<VALUE>, <VALUE>]]
saved: <PATH>这里假设输入图中的二维码可被正常识别;实际文本、坐标和保存路径会不同。如果程序输出 localized: no,说明定位阶段就失败,不应继续把问题归因到编码内容。
按失败阶段排查
未定位时先检查二维码在画面中的像素尺寸、对比度、遮挡和透视变形。二维码太小、严重模糊、边缘被裁掉或缺少足够留白,都可能让检测器无法形成稳定四边形。
已经得到 points 但 data 为空时,定位基本成功,此时重点检查运动模糊、强反光、过度透视和模块细节是否可分辨。可以先用原始分辨率重试,避免在检测前做过强压缩、锐化或二值化。
多二维码与视频场景
单个二维码使用 detectAndDecode 最直接;一张图里可能同时出现多个二维码时,可使用 detectAndDecodeMulti 获取多组文本与角点。视频场景则应在逐帧检测之外增加去重逻辑,避免同一个二维码连续几十帧被重复处理。
角点数组适合当作几何边界使用,不要在未验证接口约定的情况下依赖某个下标一定代表特定语义角。真正需要透视裁剪时,应先确认角点顺序,再建立目标四边形并执行透视变换。