二维码：自己生成一张，再让相机读回来

01目标：生成二维码再读回，文字一字不差

说清这页的起点和终点 —— 整页的八节都在回答"怎么从左边走到右边"：

02问题：一堆黑白格子，机器怎么读出文字

"嘀"一声就出字，可这活从头到尾是机器在干 —— 人只负责把码对准镜头。机器人更苛刻：它拿到的只是一帧像素画面，码可能歪着、被光打白、还被夹爪挡住一角。一堆黑白格子，机器凭什么把文字读出来？

把标题拆开 —— 「一堆黑白格子，机器怎么读出文字」，其实是三问：

• ① 一堆黑白格子 —— 凭什么是码，码在哪？画面里几百×几百个像素，凭什么说中间这块是二维码、不是别的黑白花纹？（对应上表第 1 行）
• ② 怎么读 —— 歪了、暗了、挡住了还读得出吗？斜着拍、屏幕反光、灯光偏暗、被夹爪挡住一角 —— 哪些情况还能救，哪些直接读不出？（对应上表第 2、3 行）
• ③ 文字 —— 格子怎么变回一行字？错了怎么办？解出来的是一字不差的字符串，还是可能出错的猜测？出错了靠什么兜底？（对应上表第 4 行）

这三问不是凭空来的 —— 二维码是今天机器人最便宜、最可靠的"身份标签"，到处都在用，所以"怎么读"必须搞得懂：

• 贴在货架上 → 机器人一扫就知道"这是 3 号库位的零件 A"
• 贴在工位上 → 相机一扫就知道"现在该执行哪道工序"
• 贴在门上 → 巡检机器人一扫就知道"我到 2 楼了"

成本？一张纸。可靠性？被遮住一部分还能读出来。

把刚才那三问落到工程上，就是下面四个子问题 —— 注意它们"有先后"：顺序不能换，每一步都卡着下一步。

四步一路解下来，才拿到最开始要的那行 [QR] https://example.com。这就是本节给你的结论：不是"机器很神奇"，而是四个具体问题被逐个解决。

03现象：写一句话，30 秒读回一字不差

🎬 现象速览 · 30 秒先看效果

你会看到：自己写一句话 → 程序画出一张二维码 → 再让程序把它读回来，打印出的文字和你写进去的一字不差。全程不用相机，30 秒闭环。

图 3-1｜下面两条命令的全部产物：左边是你写进去的码，右边是程序读回来的结果 —— 框上方那行 https://example.com 与写进去的一字不差

三步跑出这个画面（先照做，每步为什么下一节拆讲）：

① 进目录，生成你自己的码。把引号里的文字换成你自己的（学号、名字都行）：

cd ~/ros2_ws/src/xflz_eai_car1/vision/04_qrcode
python src/app.py --generate "https://example.com" --save my_qr.png

② 喂给检测器读回来。绿框套住整张码、终端打印出 [QR] https://example.com 就算成功：

python src/app.py --detect --image my_qr.png --save out.png

③ 换你自己的字符串再来一遍。读回必须一字不差 —— 写进去什么、读出来就是什么，这就是闭环。

🔍 看什么：打开 out.png，绿框是不是套住整张码？码上三个「回」字角标在哪 —— 记住它们的位置，下一节讲机器怎么靠这三个角把歪着的码扶正。

04原理：二维码是怎么被认出来的

这一节就按 02 节拆出来的四个子问题走 ——四个子问题 → 四个步骤，一步解一层，走完就答完了：

1机器凭什么先找到这张码？

它不认识"二维码"，只认两件事：一种黑白比例、三个"回"字的摆法。一张码拆开是这四块：

还有两块不显眼但缺一不可：格式信息（第 8 行与第 8 列交叉处那圈黑白点）记着纠错等级和掩码编号；版本信息只有版本 7 以上才有 —— 本页这只码是版本 2，所以没有。

① 凭什么"认得出来" —— 一条线扫过去，黑白正好是 1 : 1 : 3 : 1 : 1

② 凭什么知道"哪边是上" —— 三个角标摆成 L，缺的那角在右下

正因为缺的那一角本身就带着方向信息，第四个"回"字绝不能出现 —— 哪怕是数据区凑巧拼出来的。生成时把数据打散（步骤 3 的掩码），压的就是这个概率。

2画面歪了，怎么扶正？

先说清"扶正"在链条里的位置。下面六格是真机拍到的全过程，顺序就是识别的顺序 —— 你要解的"扶正"，就是第 ③④ 格；前后几格是它的上下文，顺便一起看：

只看中间那列，六句话看完：

回到这一步要解的"扶正"：第 ③ 格给出四个角点，第 ④ 格按这四个点做透视 —— 梯形就变回了正方形。 这一步不改变码的内容，只改变"形状"；但它决定了后面能不能按格均匀采样：格子间距不齐，"一格多大"就无从算起。

这 6 步在代码里由一个函数全包了 —— 具体是谁、参数在哪改，05 节的 图 5-1 流程图和它下面那张环节表里有。

3一格格黑白，怎么变成文字？

位置有了、画面也正了，真正的难题才开始：这一格黑、那一格白，到底代表什么？它们代表 0 和 1。但只有 0/1 还不够，还得知道怎么打包成字。下面两张图就是答案。

问题一：黑白凭什么变成 0 和 1？

问题二：这些格子看起来毫无规律，为什么？因为写进去之前，数据被刻意打散过 —— 这层"格子布"叫掩码：

4脏了、缺角了，怎么救回来？

上面读出来的是"干净的理想情况"。可现场从来不是：贴纸盖住一块、纸角撕了、手指压住半边。为什么有的还能读、有的直接废？因为码里的数据不是随便填的 —— 它和"多算的那几个点"一起，落在同一条曲线上：

那到底能救多少？因为补回一个错，要花掉两个校验点 —— 这是它的预算：

校验点多留几个，是可以选的 —— 这就是"纠错等级"：

代价看第二列和第三列：校验越多，格子越密 —— 同样的内容会被顶到更大的版本，打印和拍摄的要求也跟着变高。06 节的实验台可以拖着看这个取舍。

补看：这张码当初是怎么造出来的？选读 2 分钟

造和读是一对逆操作：读是"格子 → 文字"，造是"文字 → 格子"。看懂造，读会更顺 —— 因为你会知道那些"奇怪的格子"当初是怎么摆进去的。

三步就完了：文字打包成字节（编码）→ 排成 25×25 矩阵（含角标、时序线、校验位、掩码）→ 每格染成 5 像素、四周留 4 格白边，得到 165×165 的 PNG。中间那条公式值得记：165 = (25 + 4×2) × 5。

先认识 4 个词

它吃什么、吐什么

# 配置里的生成参数
generate:
  version: 1              # 1-40，fit=True 时自动扩版
  error_correction: M     # L/M/Q/H — 本板实测别用 H
  box_size: 5             # 每格 5 像素
  border: 4               # 白边 4 格

detect:
  scale: 0.5              # 检测前先缩一半，提速

05实操：三条命令：生成 / 图片读回 / 实时扫

这一节把原理那四步落到具体函数上。先看全貌：两条线、每一步在哪个文件、吃哪个参数、对应原理的第几步 —— 下面再挨个拆。

先把 ③ 那格拆开看一眼 —— 它是整条识别线里唯一"看不见里面"的函数，而原理讲的四步，正好全在它里面：

看清楚了就动手：下面三条命令依次跑一遍，跑完再回来对参数。

1. 生成一个二维码约 1 分钟

   先站到源码目录，再让程序把 --generate 后面的文字画成码。文字换成你自己的也行（学号、名字都能写，中文也可以）：

   cd ~/ros2_ws/src/xflz_eai_car1/vision/04_qrcode
   python src/app.py --generate "https://example.com" --save my_qr.png

   QR 已保存: /home/iflytek/ros2_ws/src/xflz_eai_car1/vision/04_qrcode/my_qr.png

   这行命令背后发生了什么：src/app.py 先 load_config()（读 config/qrcode_config.yaml），再把文字交给 src/qr.py 的 generate_qr()，拿回一张 numpy 图，最后 cv2.imwrite 存盘。三个环节全在 04 节的图 4-9 里，你现在把它跑了一遍。

   参数都在 yaml 的 generate: 下面：version（起点版本）、error_correction（纠错等级）、box_size（每格几像素）、border（静区几格）。不要去改源码里的默认值，改配置就够了 —— 源码只是把配置读进来用。

   ⚠️ 打印出来的这一行是绝对路径：程序把 --save 的值 resolve 成了完整路径。图片默认落在你当前所在目录（所以必须先 cd 进去，否则会散落在别处）。

2. 解析一个二维码约 1 分钟

   不用相机，直接把刚生成的图喂给检测器 —— 这是最快的自检，也正好对应 04 节图 4-4 的六步：

   python src/app.py --detect --image my_qr.png --save out.png

   [QR] https://example.com saved -> out.png

   两行回执分工明确：第一行 [QR] 后面是解出来的原文（src/app.py 里 print(f"[QR] {r.text}")），第二行是保存标注图的回执（saved -> {args.save}）。读回的文字和写进去的一模一样，闭环就成立了。

   这一步只有一个可调参数：detect.scale（默认 0.5）。它决定"检测前把画面缩小多少倍"，也就是图 4-4 的第 2 步。另外两个写死在 src/qr.py 里的数值值得记住：MAX_DETECT_PASSES = 8（一张图最多找 8 个码）和标注文字 40 字符的截断（超过只显示前 37 个加 ...）。

   打开 out.png 看一眼：绿框套在码上、文字画在框上方 —— 这就是图 4-4 ⑥。

3. 接上相机实时扫约 3 分钟

   两句 source 必须都执行，缺一句 ros2 就找不到包：

   终端一 · 起相机驱动

   source /opt/ros/humble/setup.bash && source ~/ros2_ws/install/setup.bash
   ros2 launch ascamera hp60c.launch.py

   日志里出现 publish color(rgb) info 就说明相机出来了。

   把 my_qr.png 在电脑或手机上打开，举到相机前：

   终端二 · 开识别

   cd ~/ros2_ws/src/xflz_eai_car1/vision/04_qrcode
   python src/app.py --detect --ros

   Streams index: http://<板子IP>:8080 Available streams: http://<板子IP>:8080/qrcode.mjpg -------------------------------- Press Ctrl+C to stop the server [QR] https://example.com 30帧平均帧率: 33.4

   判据：先出现 Streams index: 那几行（它把流地址直接打给你了），然后每检测到一次码就打印一行 [QR]，每 30 帧打一次帧率（这块板子 640×480、scale: 0.5 实测约 31~33 fps）。浏览器打开输出里那个 …/qrcode.mjpg 地址，就是实时画面，绿框和文字都在上面。

   实时模式多了两个模块：取帧换成 src/ros2_source.py 的 Ros2Camera.read()（从 ROS 话题拿图），输出多了 src/mjpeg_server.py 的 MjpegServer.set_frame()（把画好的帧推成网页视频流）。识别那段代码一行没变 —— 还是 detect_qr 和 draw_qr。

   ⚠️ 板上别用 --camera 0。这块板的相机是 Orbbec HP60C 深度相机，不走 V4L2 索引，实测会报 can't open camera by index 后退出。要用相机就走 --ros。

   试试这几个动作，观察识别率怎么变：正对 → 斜着、近 → 远、把码挡掉一个角。第三个特别有意思 —— 挡一个角它还能读出来，这就是纠错码在工作。

逐环节对参数：每个函数在干什么、参数怎么影响它

图 5-2 已经把那个"一条龙"剪开了。下面把 图 5-1 的五个环节逐个对上函数与参数 —— 哪些能调、调坏了画面会怎样。

把 图 5-1 逐步对上函数与参数 —— 只看第 3 列就够了，前两列是查名字用的：

补一句实话：OpenCV 其实还给检测器留了三个旋钮 —— setEpsX / setEpsY（角点容差）、setUseAlignmentMarkers（要不要用校正图形），本项目一个都没动。真遇到"特别花、特别小的码"时，它们才是下一批该试的参数。

一句话记住两条线的差别：生成线是"把点摆到曲线上"—— 摆几个点、摆多密、留几格余量，你都能定（box_size、border、error_correction）；识别线是"从曲线上把点读回来"—— 除了 scale，其余全在 OpenCV 里面。

配置参数一览：改哪个、动它会怎样

全部在 config/qrcode_config.yaml；改完重新跑命令就生效，不用改源码。想试不同参数又不想动原文件，可以复制一份用 --config 你的.yaml 指过去。

对着 02 节那四个子问题看这张表，参数就不是一堆名字了：detect.scale、box_size、border 决定的是子问题 1、2 成不成立（能不能找到、能不能按格读）；error_correction 决定的是子问题 4（脏了、缺角能不能救回来）；而 version 是被"要塞多少字"和前三个子问题一起挤出来的。06 节拖滑杆，拖的就是这四条边界。

你该看到的画面

踩坑速查

关键代码：这套程序的核心只有两段

跑通之后回头看代码 —— 生成 16 行、检测 32 行，没有一行是"魔法"。下面是 src/qr.py 里的两个函数原文（src/app.py 只是个命令行外壳，负责读参数、调它们、存图）。

① 生成：把文字交给 qrcode 库，它按编码规则画格子。四个参数全来自 config/qrcode_config.yaml；fit=True 的意思是"从 version 这个版本起步，装不下就自动升版" —— 所以配置里写 version: 1 但你存 19 个字符时，它会自己升到能装下的版本。最后一行别忽略：库吐出来的是 RGB 顺序，OpenCV 全程用 BGR，这里转一次，不转的话颜色通道会错位。

def generate_qr(data: str, cfg: dict) -> np.ndarray:
    g = cfg["generate"]
    qr = qrcode.QRCode(
        version=g["version"],
        error_correction=error_correction_level(g["error_correction"]),
        box_size=g["box_size"],
        border=g["border"],
    )
    qr.add_data(data)
    qr.make(fit=True)
    img = qr.make_image(fill_color=tuple(g["fill_color"]),
                        back_color=tuple(g["back_color"])).convert("RGB")
    return cv2.cvtColor(np.array(img), cv2.COLOR_RGB2BGR)

② 检测：一次 detectAndDecode 拿到内容和四个角点，然后把那块涂白再找下一个。三个细节对应本页讲的三件事：① 开头那段 resize 就是 detect.scale —— 小于 1 才缩，缩完记下放大倍数 factor，最后把坐标乘回去，所以框永远画在原图坐标上；② points 就是三个角标定位出来的四个角，透视摆正和切格子都在 detectAndDecode 内部完成，我们拿不到中间结果；③ 那个 while 式循环 + 涂白，就是"一帧能框出多个码"的实现，MAX_DETECT_PASSES = 8 是防死循环的上限。

def detect_qr(img: np.ndarray, scale: float = 0.5) -> list[QRResult]:
    h, w = img.shape[:2]
    work = img
    factor = 1.0
    if 0 < scale < 1.0:
        work = cv2.resize(img, (int(w * scale), int(h * scale)))
        factor = 1.0 / scale

    detector = cv2.QRCodeDetector()
    results: list[QRResult] = []
    for _ in range(MAX_DETECT_PASSES):
        data, points, _ = detector.detectAndDecode(work)
        if not data:
            break
        if points is None or points.size == 0:
            break
        pts = points[0].astype(np.float32)
        xs = pts[:, 0] * factor
        ys = pts[:, 1] * factor
        results.append(QRResult(
            text=data,
            x1=int(xs.min()), y1=int(ys.min()),
            x2=int(xs.max()), y2=int(ys.max()),
        ))
        # 掩掉已识别区域，继续找下一个
        x1 = int(max(0, xs.min() * scale - 2))
        y1 = int(max(0, ys.min() * scale - 2))
        x2 = int(min(work.shape[1], xs.max() * scale + 2))
        y2 = int(min(work.shape[0], ys.max() * scale + 2))
        work[y1:y2, x1:x2] = 255
    return results

想改它会发生什么：把 scale 改小到 0.3 → 远处小码直接糊掉、框不出现；把 MAX_DETECT_PASSES 改成 1 → 一帧只能框出第一个码，多码场景漏检；把最后那行 work[...] = 255 注释掉 → 同一个码被反复读，一张图会打印 8 遍 [QR]（上限 8 次兜住了，不会真的卡死，但结果里同一句话重复 8 条）。什么时候失效：缩放后每个格子只剩一两个像素时就开始丢细节（本实验 box_size: 5 + scale: 0.5 恰好是每格 2.5 像素，还能读），再小就散架；另外码被遮到角标看不见时，detectAndDecode 直接返回空串 —— 它不会区分"没找到码"和"找到了但读不出"，这两种情况在程序里长得一模一样。

进阶（可选）

06互动：拖纠错等级，看抗遮挡换密度

📌 这一节是「掌握检查」：亲手改一个参数，看现象是否朝你预期的方向变，还要能说出为什么 —— 说得出，才算掌握。

上面几节你已经在板子上造过码、读过码。这一节把整条链路做成一个不用设备也能玩的模拟器：输入任意文字 → 真的生成一张码 → 拖参数 → 盖上遮挡块，每一步都对应 04 节讲过的环节和 05 节的配置项。

动手做这个实验：① 把文字换成你自己的学号或一句中文，点「生成」—— 看模块数和版本怎么变（中文每个字 3 字节，同样字数会占更多格子）；② 把「遮挡面积」拉过当前等级的上限，红块盖住码中心 —— 用手机直接扫屏幕，看还能不能读出原文（中心遮挡比随机污损更狠，理论上限不是保险箱）；③ 把「检测缩放」拉到 0.2，看右边那张“检测器看到的”糊成什么样 —— 这就是远处小码读不出的原因；④ 把 box_size 调到 3，再想象一下把它打印出来贴到货架上；⑤ 把「静区格数」改成 0 —— 格子会直接顶到图片四个边，四周一点白都不剩；实测这一步会让检测器连码都找不到，这就是标准要求静区至少 4 格的原因。

对照真实产物：同一句话、四个纠错等级

实验台上拖的是模拟；下面这四张是板上真跑 --generate 出来的 PNG，同样一句话、同样 box_size: 5，只有纠错等级不同。

nano config/qrcode_config.yaml

generate:
  error_correction: M   ← 改成 L / Q / H 各试一次
  box_size: 5
  border: 4

改完重新生成同一个内容 —— 每换一级跑一次，集齐四张，对比四张图：

python src/app.py --generate "https://example.com" --save qr_L.png

⚠️ 每换一级要改两处：配置里的 error_correction，和命令末尾的 --save 文件名（依次改成 qr_M.png / qr_Q.png / qr_H.png）。只改等级不改名字，四张会互相覆盖，最后只剩一张。

📱 拿手机实扫：四张码里装的都是同一句话 https://example.com —— 逐个扫一遍，四张都应该读出完全相同的内容。扫完再回看格子：L / M / Q 都是 25×25 格，只有 H 为了硬塞 30% 冗余自动升版到 29×29，格子明显更密 —— 这就是「校验占格子」长的样子。注意 L 和 Q 在这条内容上格数一样多：因为"https://example.com"这 19 个字符在 L 级下也装不进 21×21，库把三档都推到了同一个版本。等级的差别这时只体现在冗余多少上，等你要存更短或更长的内容，版本差异才会跳出来。

07验证：三道小测

08章节总结：先靠角标找到码，再靠纠错码把内容读回来

前置依赖 · 缺一样就跑不起来

这套代码用在哪儿

• 库位 / 工序标识：码贴在货架或工位上 → --detect 吐出的是一行字节级精确的字符串（如 A3-07），直接拿去当库位号、工序号，喂给调度系统查「这是 3 号库位的零件 A」「现在该执行哪道工序」。
• AGV 地标定位：地上贴一排码、内容编码成坐标（A3 表示第 3 列第 2 行），车底相机读到哪个码就知道自己在哪一格；再把框的中心位置拿出来 —— 中心偏左说明车靠右了，得往左微调，和 EXP-01 的色块中心偏移是同一个思路。
• 带 logo 的品牌码：中间那块区域的数据实际被弃用，靠纠错码补回来，所以要选 H 级 —— 代价是版本被顶大一档（本页四张里唯一变成 29×29 的那张），格子更密、更依赖清晰度。这就是「拿到抗造性，付出密度」的真实账。