libcimbar命令行工具全解析：cimbar_send与cimbar

libcimbar命令行工具全解析：cimbar_send与cimbar_recv使用指南

【免费下载链接】libcimbar Optimized implementation for color-icon-matrix barcodes 项目地址: https://gitcode.com/GitHub_Trending/li/libcimbar

libcimbar是一个基于彩色图标矩阵条形码（Color-Icon-Matrix Barcode）的高效数据传输库，通过屏幕与摄像头之间的视觉通信实现设备间无线数据传输。本文将详细介绍其核心命令行工具cimbar_send（发送端）和cimbar_recv（接收端）的使用方法，帮助用户快速掌握跨设备数据传输能力。

工具概述与安装准备

cimbar_send和cimbar_recv是libcimbar提供的命令行实用程序，分别负责将文件编码为视觉条码流并通过屏幕显示，以及通过摄像头捕获并解码这些条码流恢复原始文件。两者配合使用可实现无网络环境下的设备间数据传输，传输速率可达20-50KB/s（取决于摄像头帧率和环境光照）。

环境要求

发送端：带显示器的Linux/Windows/macOS设备
接收端：带摄像头的设备（推荐1080p及以上分辨率）
编译依赖：CMake 3.14+、C++17编译器、OpenCV 4.2+、zstd库

源码获取与编译

# 克隆仓库
git clone https://gitcode.com/GitHub_Trending/li/libcimbar
cd libcimbar

# 编译核心库与工具
mkdir build && cd build
cmake ..
make -j$(nproc)

# 安装工具到系统路径
sudo make install

核心工具源码位于项目的src/exe/目录下，其中cimbar_send实现发送功能，cimbar_recv负责接收解码。

cimbar_send：文件编码与发送

cimbar_send将文件数据编码为一系列彩色矩阵图像，通过窗口循环显示供接收端摄像头捕获。支持多文件轮播发送、压缩级别调整和错误校正配置，适应不同传输场景需求。

基础语法与参数说明

cimbar_send [选项] <输入文件...>

核心参数说明（可通过-h查看完整列表）：

参数	全称	描述	默认值
`-i`	`--in`	输入文件路径（支持多个文件）	必选
`-c`	`--colorbits`	颜色位深度（0-3），影响色彩利用效率	3
`-e`	`--ecc`	错误校正字节数，值越高容错性越强	16
`-f`	`--fps`	显示帧率，影响传输速度	15
`-m`	`--mode`	编码模式（4C/B/Bm），对应不同矩阵配置	4C
`-z`	`--compression`	ZSTD压缩级别（0-22），0为不压缩	3

参数解析逻辑在send.cpp中实现，使用cxxopts库处理命令行输入。

典型使用场景

1. 单文件标准传输

cimbar_send -i document.pdf -f 30 -e 32

此命令将以30fps帧率、32字节ECC保护发送PDF文件，适合中等大小文档（<10MB）的传输。编码过程中会自动启用ZSTD压缩（默认级别3），可通过-z 0禁用。

2. 多文件轮播发送

cimbar_send -i image.jpg data.csv -m B -fps 20

使用B模式（0.6.x新增）同时发送图片和表格文件，发送端窗口会循环显示两个文件的编码流，接收端将自动分离并保存到不同文件。

3. 高容错模式传输

cimbar_send -i firmware.bin -c 2 -e 64 -z 10

降低颜色位深度（2bits）以换取更高的错误校正能力（64字节ECC），并提高压缩级别至10，适合在光照条件较差环境下传输大型二进制文件。

运行界面与状态指示

执行命令后将启动显示窗口（默认大小由Config.h定义），显示周期性变化的彩色矩阵图案：

窗口标题显示当前发送文件名和进度
矩阵边框颜色指示发送状态（绿色=正常，黄色=压缩中，红色=错误）
终端输出包含帧率、数据速率和文件切换信息

cimbar_recv：摄像头捕获与解码

cimbar_recv通过摄像头捕获发送端显示的条码图像，实时解码并重组为原始文件。支持视频源选择、输出目录指定和接收进度跟踪，确保数据准确恢复。

基础语法与参数说明

cimbar_recv [选项] <输入源> <输出目录>

核心参数说明：

参数	全称	描述	默认值
`-i`	`--in`	视频源（摄像头ID或视频文件）	必选
`-o`	`--out`	解码文件保存目录	必选
`-c`	`--colorbits`	颜色位深度，需与发送端匹配	3
`-e`	`--ecc`	错误校正字节数，需与发送端一致	16
`-f`	`--fps`	捕获帧率，建议不低于发送端帧率	30
`-m`	`--mode`	解码模式，必须与发送端相同	B

视频源处理逻辑在recv.cpp中实现，使用OpenCV VideoCapture接口读取摄像头数据。

典型使用场景

1. 摄像头实时接收

cimbar_recv -i 0 -o ./received_files -m 4C -f 30

使用默认摄像头（ID 0）接收4C模式编码流，解码文件保存到received_files目录。接收过程中终端会输出进度信息：

[100%, 100%, 85%]  # 每个文件的接收完成度
got some bytes 1536  # 单次解码成功的字节数

2. 从视频文件解码

cimbar_recv -i recorded_stream.mp4 -o ./restored -c 2

离线解码预先录制的条码视频，适合弱网环境下的延迟传输。需确保视频帧率与编码时一致（通过-f参数调整）。

3. 高帧率快速传输

cimbar_recv -i 1 -o ./fast_transfer -fps 60 -e 16

使用外置摄像头（ID 1）以60fps捕获，牺牲部分容错性（16字节ECC）换取更高传输速度，理想状态下可达50KB/s以上。

接收进度与错误处理

接收进度跟踪通过fountain_decoder_sink实现，在recv.cpp中打印每个文件的恢复百分比。常见错误情况处理：

捕获失败：检查摄像头连接或视频文件路径，确认-i参数正确
解码成功率低：调整光源环境，确保发送窗口无反光、摄像头对焦清晰
模式不匹配：发送端与接收端必须使用相同-m参数，否则无法正确解码

编码模式与参数优化

libcimbar提供多种编码模式和参数组合，适应不同传输距离、设备性能和环境条件。合理配置可显著提升传输成功率和速度。

编码模式对比

模式	矩阵尺寸	颜色利用	兼容性	适用场景
4C	16x16	RGB+亮度	0.5.x及以上	标准传输
B	24x24	高色域	0.6.x+	新设备高速传输
Bm	24x24	单色优化	0.6.x+	低光照环境

模式切换逻辑在send.cpp中实现，通过配置config_mode变量选择不同矩阵生成策略。

参数调优指南

1. 速度与可靠性平衡

优先速度：-m B -f 30 -e 16 -z 1（B模式+高帧率+低ECC+快速压缩）
优先可靠：-m 4C -e 64 -c 1 -z 0（4C模式+高ECC+低色深+无压缩）

2. 文件类型适配

文本/代码：-z 15（高压缩比，节省传输时间）
图片/视频：-z 0（已压缩文件无需重复压缩）
小文件（<100KB）：-e 8（降低ECC开销）

3. 环境适配

明亮环境：-c 3 -m B（最大色彩利用）
低光环境：-c 0 -m Bm（单色模式提高对比度）
远距离传输：-m 4C（更大矩阵单元，提升识别距离）

高级功能与扩展应用

libcimbar命令行工具支持通过参数组合实现复杂传输需求，结合项目提供的其他组件可构建完整的视觉通信系统。

批量编码与Web集成

项目提供package-cimbar-html.py脚本，可将cimbar_send编码的图像序列转换为HTML页面，实现无客户端的Web端发送。配合web/recv.html页面，可构建纯浏览器的接收方案：

# 生成HTML发送页面
python3 package-cimbar-html.py -i document.pdf -o send_page.html

性能测试与优化

PERFORMANCE.md文档记录了不同配置下的传输性能基准，典型场景下：

4C模式：15fps时约15KB/s，误码率<0.1%
B模式：30fps时约35KB/s，误码率<0.3%

可通过调整Config.h中的图像尺寸参数（image_size_x/image_size_y）进一步优化性能。

错误处理与日志

发送端解码错误会在send.cpp中输出到stderr，常见错误包括：

文件读取失败：检查输入路径权限
编码初始化失败：可能是不支持的文件类型
窗口创建失败：确保图形环境正常（需要OpenGL支持）

接收端解码状态在recv.cpp中输出，got some bytes表示成功解码的数据量，持续为0需检查发送端与接收端的模式匹配。

总结与最佳实践

cimbar_send和cimbar_recv提供了灵活高效的跨设备数据传输能力，通过合理配置可适应从近距离高速传输到远距离容错传输的各类场景。最佳实践建议：

初次使用：从默认参数开始（cimbar_send -i test.txt + cimbar_recv -i 0 -o ./out），熟悉基本流程后再调整高级参数
文件大小：单个文件建议不超过20MB，大文件可通过分卷工具分割后传输
环境控制：保持发送窗口与摄像头距离30-50cm，避免直射光和屏幕反光
版本匹配：确保发送端与接收端使用相同的libcimbar版本，避免模式兼容性问题

项目TODO.md中记录了计划开发的功能，包括二维码混合编码和多摄像头协同接收，持续关注可获取工具更新信息。通过掌握这些命令行工具，用户可快速构建基于视觉通信的设备互联方案，实现无网络环境下的安全数据传输。

【免费下载链接】libcimbar Optimized implementation for color-icon-matrix barcodes 项目地址: https://gitcode.com/GitHub_Trending/li/libcimbar

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考