NANOKVM-MaixCDK-MIRROR/projects/app_line_tracking/README.md

1. 简介

本程序是基于MaixCam硬件平台和LVGL图形界面开发的实时寻线识别应用，核心通过LAB颜色空间阈值筛选实现图像中的线条检测，支持用户自定义LAB阈值参数、实时查看像素颜色信息、可视化寻线结果，并可将用户配置的参数持久化保存，同时通过串口协议上报检测数据，适用于巡线小车、视觉检测等场景的基础寻线功能开发与验证。

2. 主要功能

1. LAB阈值配置：支持自定义LAB颜色空间的L（亮度）、A（红绿色差）、B（蓝黄色差）阈值范围，默认配置为L(0-27)、A(-128-127)、B(-128-127)，且参数修改后自动保存；
2. 像素颜色采集：点击屏幕任意位置可采集对应像素的RGB及LAB值，并在界面上展示；
3. 寻线检测：基于设定的LAB阈值对摄像头画面进行线条检测，识别线条的坐标、角度等信息；
4. 可视化展示：
   • 检测到的线条以绿色线条标注在画面中；
   • 线条角度判断后显示左/右方向标识；
   • 支持开启“二值化模式”，直观查看阈值筛选后的黑白图像；
5. 数据上报：通过串口通信协议将检测到的线条坐标、角度等信息上报，支持与外部设备（如MCU、上位机）交互；
6. 参数持久化：程序退出时自动保存用户配置的LAB阈值，下次启动自动加载。

3. 使用说明

3.1 程序操作流程

3.1.1 首次启动

1. 运行程序后，自动初始化并加载默认LAB阈值（L:0-27、A:-128-127、B:-128-127），界面显示摄像头实时画面；
2. 若配置文件不存在，程序自动创建并写入默认参数，日志提示“use default lab config for user”。

3.1.2 阈值调整

1. 在界面上找到Lmin/Lmax、Amin/Amax、Bmin/Bmax对应的调节控件（如滑块、输入框）；
2. 调整对应数值，程序实时更新检测阈值，日志会打印当前配置的阈值（格式：{Lmin, Lmax, Amin, Amax, Bmin, Bmax}）；
3. 调整后无需手动保存，退出程序时自动持久化。

3.1.3 像素颜色采集

1. 点击屏幕任意位置，程序采集该位置像素的RGB和LAB值；
2. 界面上的“颜色框”会依次显示采集到的颜色及对应数值，同时日志打印触摸坐标（touch (x, y)）。

3.1.4 寻线检测与可视化

1. 程序默认实时进行寻线检测，检测到线条后画面中显示绿色线条；
2. 线条角度>0且<90°时显示右方向标识，否则显示左方向标识；
3. 开启“二值化模式”（界面“眼睛”按钮）：
   • 点击“眼睛开启”，画面切换为二值化图像（阈值内像素为白色，其余为黑色）；
   • 点击“眼睛关闭”，恢复摄像头原始画面。

3.1.5 退出程序

1. 通过界面“退出”按钮触发退出，日志提示“exit!”；
2. 程序自动保存当前LAB阈值，日志打印“save user's lab config”及保存的参数。

3.2 自定义扩展

1. 调整寻线精度：修改app_loop中以下参数可优化检测效果：
   • x_stride/y_stride：检测步长（值越小精度越高，性能消耗越大）；
   • area_threshold/pixels_threshold：面积/像素阈值（过滤小面积噪声线条）；
   • roi：检测区域（默认全屏，可缩小区域减少计算量）；
2. 通信协议扩展：修改APP_CMD_REPORT_FIND_LINES（指令码9）或priv.ptl->report()的参数，适配外部设备的通信格式；
3. 可视化优化：调整ui_show_left_or_right中的位置（x/y）、缩放比例（transform_scale）等，适配不同尺寸屏幕。

4. 串口通信协议（uart protocol）

程序检测到线条（色块）后，会将相关坐标信息通过串口协议上报，便于外部设备解析和交互。

4.1 数据格式示例

上报内容示例：AA CA AC BB 14 00 00 00 E1 08 EE 00 37 00 15 01 F7 FF 4E 01 19 00 27 01 5A 00 A7 20

4.2 字段解析

• 08：本次消息的命令码（十六进制0x08），用于标识当前上报的是寻线/色块检测数据；
• EE 00 37 00 15 01 F7 FF 4E 01 19 00 27 01 5A 00：4个顶点的坐标值，按顺序排列，每个顶点由2字节x坐标+2字节y坐标组成（小端模式）：
  • EE 00（x） + 37 00（y） → 第一个顶点坐标为(238, 55)；
  • 15 01（x） + F7 FF（y） → 第二个顶点坐标为(277, -9)；
  • 4E 01（x） + 19 00（y） → 第三个顶点坐标为(334, 25)；
  • 27 01（x） + 5A 00（y） → 第四个顶点坐标为(295, 90)。

4.3 解析说明

• 坐标值为小端模式（低字节在前，高字节在后），解析时需先拼接高低字节再转换为十进制；
• 负数坐标以补码形式表示（如F7 FF转换为十进制为-9）；
• 串口波特率、校验位等参数需与外部设备保持一致（默认参数可参考Maix平台串口配置）。

5. 注意事项

1. 阈值合理性：
   • L值范围为0-100，A/B值范围为-128-127，超出范围可能导致检测失效；
   • 调整阈值时建议先采集目标线条的LAB值，再以该值为中心小幅调整范围；
2. 硬件性能：开启二值化模式或缩小检测步长会增加计算量，可能导致画面帧率下降；
3. 触摸采集精度：触摸屏校准不准确会导致采集的像素坐标偏差，建议先校准触摸屏；
4. 配置文件异常：若配置文件损坏，程序会加载默认参数，可删除配置文件后重启恢复；
5. 资源释放：程序退出时会自动释放通信协议对象（priv.ptl），请勿强制终止程序，避免内存泄漏；
6. 串口通信：
   • 确保串口外设未被其他程序占用，否则会导致数据上报失败；
   • 外部设备解析数据时需严格按照小端模式解析坐标，避免数值错误；
7. 日志排查：运行异常时查看日志，重点关注：
   • “protocol init failed!”：通信协议初始化失败，检查内存是否充足；
   • “camera read failed”：摄像头读取失败，检查硬件连接；
   • 阈值打印信息：确认是否与界面配置一致。

6. 更多介绍

源码

MaixCAM MaixPy 小车巡线