libcimbar：彩色图标矩阵条形码库使用教程

项目概述

libcimbar 是一个实验性的高密度二维条形码格式，专门设计用于通过摄像头进行空隔离数据传输。该库能够实现高达850千比特/秒（约106KB/秒）的传输速度，仅需计算机显示器和智能手机摄像头即可完成数据交换。

项目结构

核心目录结构

libcimbar/
├── CMakeLists.txt          # CMake构建配置文件
├── LICENSE                 # 开源许可证
├── README.md               # 英文说明文档
├── README.zh-cn.md         # 中文说明文档
├── DETAILS.md              # 技术细节文档
├── PERFORMANCE.md          # 性能指标文档
├── TODO.md                 # 待办事项文档
├── src/                    # 源代码目录
│   ├── lib/                # 核心库模块
│   │   ├── bit_file/       # 位文件处理
│   │   ├── cimb_translator/ # CIMB转换器
│   │   ├── encoder/        # 编码器
│   │   ├── extractor/      # 提取器
│   │   └── fountain/       # 喷泉码实现
│   ├── exe/                # 可执行文件
│   │   ├── cimbar/         # 主程序
│   │   ├── cimbar_send/    # 发送程序
│   │   └── cimbar_recv/    # 接收程序
│   └── third_party_lib/    # 第三方库
├── web/                    # Web相关文件
│   ├── index.html          # 主页面
│   ├── recv.html           # 接收页面
│   └── main.js             # 主JavaScript文件
├── bitmap/                 # 位图资源
└── test/                   # 测试文件

核心实现模块

• 编码器(Encoder)：将数据转换为彩色图标矩阵条形码
• 解码器(Decoder)：从图像中提取和解码数据
• 纠错模块(Reed Solomon)：提供错误检测和纠正功能
• 喷泉码(Fountain Codes)：支持大文件分块传输和重组
• 压缩模块(Zstd)：内置数据压缩功能

安装与构建

系统依赖

在开始构建前，需要安装以下依赖库：

# Ubuntu/Debian系统
sudo apt install libopencv-dev libglfw3-dev libgles2-mesa-dev

构建步骤

1. 克隆项目仓库

git clone https://gitcode.com/GitHub_Trending/li/libcimbar
cd libcimbar

2. 配置和构建

cmake .
make -j7
make install

默认情况下，构建产物将安装在 ./dist/bin/ 目录下。

使用教程

基本编码操作

将文本文件编码为cimbar图像：

./cimbar --encode -i inputfile.txt -o outputprefix

此命令将生成一系列PNG图像文件，名称以 outputprefix 开头。

基本解码操作

从cimbar图像中提取文件：

./cimbar outputprefix*.png -o /tmp

实时传输模式

使用窗口显示编码内容：

./cimbar_send inputfile.pdf

Web版本使用

libcimbar还提供Web版本，可通过浏览器访问：

1. 打开 web/index.html 文件
2. 选择要编码的文件
3. 屏幕将显示动态条形码
4. 使用配套的手机应用进行扫描解码

技术原理

编码过程

libcimbar使用8x8像素的彩色图块网格来编码数据。每个图块可以表示4-6位数据：

• 4位符号数据：16种不同的图标形状
• 2位颜色数据：4种不同的颜色（默认配置）

错误纠正

采用Reed-Solomon纠错算法，默认配置为30/155，即每125字节数据添加30字节纠错信息，确保在1%错误率下仍能正确解码。

喷泉码技术

对于大文件传输，libcimbar使用wirehair喷泉码技术：

• 支持最大33.55MB文件传输
• 允许乱序接收和数据包丢失
• 只需收到N+1个数据包即可完整重建文件

性能指标

根据性能测试文档，libcimbar在不同模式下表现如下：

• Mode B (8x8 4-color)：852 kbit/s (~106 KB/s)
• Mode 4C (传统模式)：838 kbit/s (~104 KB/s)
• Mode 8C (8色模式)：943 kbit/s (~118 KB/s)

实际应用场景

空隔离数据传输

适用于需要在不连接网络的情况下传输数据的场景：

• 安全环境下的文件传输
• 受限网络环境
• 临时数据交换

移动设备间传输

通过手机摄像头扫描电脑屏幕上的条形码，实现设备间快速数据传输。

离线Web应用

Web版本支持离线使用，可作为渐进式Web应用安装。

常见问题解答

Q: 传输大文件时需要注意什么？

A: 大文件传输可能生成大量PNG图像，请确保有足够的磁盘空间。

Q: 解码失败怎么办？

A: 确保拍摄环境光线充足，摄像头正对屏幕，避免反光和角度倾斜。

Q: 支持哪些文件格式？

A: libcimbar可以传输任何类型的文件，包括文本、图片、压缩包等。

进阶配置

自定义纠错级别

可以通过修改ECC参数来调整纠错级别：

./cimbar --ecc 40 --encode -i file.txt -o output

WebAssembly构建

要构建WebAssembly版本，请参考WASM.md文档中的详细说明。

开发资源

• API文档：查看各模块的头文件了解详细API
• 测试用例：test目录包含完整的单元测试
• 示例代码：参考src/exe中的实现了解使用方法

libcimbar作为一个开源项目，欢迎开发者参与贡献和改进，共同推进空隔离数据传输技术的发展。