quirc - QR 码识别示例

📁 源码位置: samples/modules/quirc 查看源码

概述

这个示例展示了如何使用 quirc QR 码识别库的基本功能。

功能特性

  • 创建和销毁 quirc 对象

  • 设置图像尺寸

  • 获取图像缓冲区

  • QR 码识别和解码

  • 错误处理

  • 多种规格 QR 码测试

quirc 库简介

quirc 是一个用于从图像中提取和解码 QR 码的库，具有以下特点：

  • 快速: 在现代 x86 核心上处理 VGA 帧大约需要 50ms

  • 鲁棒性强: 能正确识别旋转和倾斜的 QR 码

  • 易于使用: 简单的 API 接口

  • 小巧: 无依赖，易于嵌入

  • 内存占用小: 每个像素一个字节，加上解码器对象的几 KB

使用说明

基本测试（无真实 QR 码数据）

  1. 构建项目：

bash build.sh

  1. 烧录到开发板后运行

此模式仅演示 quirc 库的基本 API 使用方法。

使用真实 QR 码数据测试

1. 生成 QR 码测试数据

首先需要安装 Python 依赖：

pip3 install -r tools/requirements.txt

然后运行生成脚本：

bash tools/generate_qr.sh

或者手动运行 Python 脚本：

# 生成所有格式（合并和单独的头文件）
python3 tools/qr_generator.py -a

# 仅生成合并的头文件
python3 tools/qr_generator.py -c

# 仅生成单独的头文件
python3 tools/qr_generator.py -s

# 指定输出目录
python3 tools/qr_generator.py -o gen_qrcode -a

生成的文件：

  • tools/output/qr_*.png - QR 码图片

  • tools/output/qr_*.h - 单个 QR 码的头文件

  • tools/output/qr_test_data.h - 合并的测试数据头文件

  • src/qr_test_data.h - 自动复制到源码目录

2. 启用测试数据

编辑 src/main.c，取消注释以下行：

// #define USE_QR_TEST_DATA

改为：

#define USE_QR_TEST_DATA

3. 构建和运行

bash build.sh

烧录到开发板后运行，程序将自动测试所有预生成的 QR 码。

测试的 QR 码规格

生成的测试数据包含以下类型的 QR 码：

#

名称

QR 版本

尺寸

纠错级别

数据内容

数据类型

1

small_low

1

21x21

L (Low)

“Hello World”

字节

2

small_medium

1

21x21

M (Medium)

“QUIRC”

字节

3

medium_high

3

29x29

H (High)

URL

字节

4

large_quartile

5

37x37

Q (Quartile)

“QR Code Test Data 12345”

字节

5

numeric_only

1

21x21

L (Low)

“1234567890”

数字

6

alphanumeric

2

25x25

M (Medium)

“ABC-123”

字母数字

7

chinese_text

4

33x33

M (Medium)

“聆思科技”

字节(UTF-8)

测试覆盖：

  • QR 码版本：Version 1-5（尺寸从 21x21 到 37x37）

  • 错误纠正级别：L/M/Q/H 四个级别

  • 数据类型：数字、字母数字、字节、UTF-8 编码文本

项目结构

samples/modules/quirc/
├── CMakeLists.txt          # CMake 配置
├── Kconfig                 # 配置选项
├── prj.conf                # 项目配置
├── build.sh                # 构建脚本
├── sample.yaml             # 示例描述
├── README.md               # 本文件
├── src/
│   ├── main.c              # 主程序
│   └── qr_test_data.h      # QR 码测试数据（生成后）
└── tools/
    ├── qr_generator.py     # QR 码生成器
    ├── requirements.txt    # Python 依赖
    ├── generate_qr.sh      # 生成脚本
    └── output/             # 生成的文件输出目录
        ├── qr_*.png        # QR 码图片
        └── *.h             # 头文件

QR 码生成器选项

qr_generator.py 支持以下参数：

  • -o, --output DIR - 指定输出目录（默认：output）

  • -c, --combined - 仅生成合并的头文件

  • -s, --separate - 仅生成单独的头文件

  • -a, --all - 生成所有格式（默认）

自定义 QR 码测试数据

编辑 tools/qr_generator.py 中的 QR_CONFIGS 数组来添加自定义的 QR 码配置：

{
    "name": "custom_qr",
    "version": 2,  # QR 码版本 (1-40)
    "error_correction": qrcode.constants.ERROR_CORRECT_M,  # L/M/Q/H
    "data": "Your custom data",
    "box_size": 10,
    "border": 4,
}

注意事项

  • 默认模式下，示例仅演示 quirc 库的基本 API 使用方法，不包含真实的 QR 码图像数据

  • 要测试真实的 QR 码解码，需要生成测试数据并启用 USE_QR_TEST_DATA

  • 在实际应用中，QR 码数据通常来自摄像头或图像文件

  • 确保图像数据已转换为灰度格式再送入 quirc 解码

参考文档

更多信息请参考：

  • quirc 库的 README.md 文件（modules/quirc/README.md）

  • quirc API 文档（modules/quirc/lib/quirc.h）