1. 项目背景与核心价值最近在整理过去的项目资料翻到了2021年参加全国大学生智能汽车竞赛我们通常简称“国赛”时为F题“送药小车”编写的OpenMV巡线代码。当时为了赶进度代码写得比较“飞线”注释也是寥寥无几。现在回过头看虽然比赛已经过去几年但这段代码里涉及的图像处理思路、PID控制逻辑以及嵌入式编程的坑对于刚接触OpenMV做视觉巡线的新手来说依然有很强的参考价值。特别是看到网上很多同学在搜索“OpenMV巡线代码注释”、“国赛送药小车”这类关键词说明这个需求一直很旺盛但能找到的、带详细解说的完整代码并不多。所以我决定把这段代码重新拿出来逐行加上详细的注释并结合比赛中的实际调试经验把背后的原理、为什么这么写、以及调试时踩过的坑都讲清楚。这不仅仅是一份代码注释更像是一份浓缩了实战经验的视觉巡线开发笔记。无论你是正在备战智能车竞赛、电赛还是单纯想用OpenMV做个巡线小车相信都能从中获得直接的帮助。代码本身是基于OpenMV IDE使用MicroPython开发的核心任务是通过摄像头识别赛道上的黑色引导线计算出小车偏离中心的误差然后输出控制量给底层电机实现自动循迹。2. 代码整体结构与设计思路拆解2.1 核心需求与方案选型2021年国赛F题“送药小车”是一个典型的室内场景任务小车需要在模拟医院走廊的赛道上行驶完成送药任务。赛道通常由白色底板和黑色引导线组成有时会有十字路口、环岛等元素。我们的核心需求是稳定、快速地识别并跟踪这条黑线。为什么选择OpenMV而不是其他传感器当时主要基于几点考量信息丰富度相比单个红外对管或灰度传感器阵列摄像头能获取一行甚至一个区域的完整图像信息不仅能判断是否压线还能提前预知弯道曲率实现更前瞻、更平滑的控制。灵活性通过修改图像处理算法可以相对容易地适应不同光照、赛道材质的变化甚至后期扩展识别路口、数字等任务。开发效率OpenMV集成了MicroPython和丰富的机器视觉库对于学生团队来说从获取图像到输出控制量的开发周期比从零搭建一个基于单片机的图像处理系统要短得多。方案上我们采用了最经典也最可靠的“单行扫描重心法求偏差”策略。即不对整幅图像进行处理而是只提取图像中某一行通常是中间偏下的行的像素数据在这一行里寻找黑线所在的区域并计算该区域的中心位置。将这个中心位置与图像的中心线位置进行比较其差值就是横向偏差error。这个偏差值随后被送入PID控制器计算出电机调速的PWM占空比。2.2 代码文件与模块规划我们的主要代码通常写在一个main.py文件中这是OpenMV上电后自动执行的文件。代码结构大致分为以下几个部分初始化模块导入必要的库sensor,image,time,pyb等初始化摄像头传感器参数分辨率、像素格式、白平衡等。图像处理函数核心函数负责获取一帧图像提取特定行进行二值化寻找色块黑线并计算偏差。PID控制模块包含PID参数和计算函数将图像处理得到的偏差转化为控制输出。电机控制模块根据PID输出设置左右电机的PWM信号实现差速转向。主循环不断循环执行“图像采集-处理-计算偏差-PID运算-电机控制”这个流程并可以加入一些调试信息输出如通过串口发送偏差值、图像等方便上位机调参。这种模块化的思想虽然简单但在紧张的比赛调试中非常有效可以快速定位问题是出在图像识别不准还是PID参数不对或是电机驱动有问题。3. 核心代码逐行注释与原理详解下面我将以代码块的形式展示关键代码并附上详细的注释。请注意为了适应文章格式代码可能不是百分百原样但核心逻辑和注释完全一致。3.1 传感器与摄像头初始化import sensor, image, time, pyb # 初始化摄像头传感器 sensor.reset() # 重置并初始化摄像头传感器硬件 sensor.set_pixformat(sensor.GRAYSCALE) # 设置像素格式为灰度图。巡线通常不需要彩色信息灰度图处理速度更快内存占用更小。 sensor.set_framesize(sensor.QQVGA) # 设置图像分辨率为QQVGA (160x120)。分辨率越低处理速度越快但细节越少。QQVGA是巡线常用的平衡点。 sensor.skip_frames(time 2000) # 等待摄像头设置生效。刚启动时自动增益、白平衡等需要时间稳定跳过开始的2000帧让画面稳定。 sensor.set_auto_gain(False) # 关闭自动增益。自动增益会随环境光变化调整整体亮度可能导致二值化阈值失效必须关闭 sensor.set_auto_whitebal(False) # 关闭自动白平衡。理由同上保持图像处理条件稳定。 # 注意有时也需要关闭自动曝光sensor.set_auto_exposure但具体取决于环境光变化是否剧烈。 clock time.clock() # 创建一个时钟对象用于计算帧率FPS评估算法效率。关键点解析与避坑sensor.GRAYSCALE巡线任务中颜色信息往往是干扰。黑色引导线在灰度图下就是深色区域直接用灰度值阈值分割最简单可靠。除非赛道是彩色线否则不要用RGB。sensor.QQVGA (160x120)这是一个经验值。更高的分辨率如QVGA(320x240)会显著增加处理时间可能无法达到高帧率如30fps以上的要求导致控制延迟大。160x120足够在大多数场景下清晰分辨黑线。set_auto_gain(False)和set_auto_whitebal(False)这是巡线稳定的生命线如果开启摄像头会根据环境自动调整画面亮度/色温。早上和下午的光照不同可能导致同一阈值上午能识别黑线下午就识别不了了。固定这些参数意味着我们假设环境光相对稳定或者通过补光如在小车上加LED灯条来创造稳定光照条件。3.2 图像处理与偏差计算函数这是整个代码的核心我们将其封装为一个函数方便调用和调试。def find_line_error(img): 在图像中寻找黑线并计算横向偏差。 参数: img: 由 sensor.snapshot() 获取的图像对象。 返回: error: 计算出的横向偏差值单位像素。正数通常表示线在中心右侧负数表示在左侧。 found: 布尔值是否成功找到黑线。 # 1. 定义感兴趣区域(ROI)和扫描行 # 我们不需要处理整个图像只关心地面附近的区域。ROI可以排除天花板等干扰。 # roi格式: (x, y, width, height) roi (0, 80, 160, 40) # 从y80像素开始高度40像素的区域。这个值需要根据摄像头安装高度和角度调整。 scan_line_y roi[1] roi[3] // 2 # 取ROI中间的那一行进行扫描。这里是 y 80 20 100。 # 2. 提取扫描行的像素数据 # 获取图像第scan_line_y行的所有像素值灰度值0-255。 line img.get_pixel(scan_line_y, roi[0], roi[2]) # line现在是一个包含160个整数的列表因为宽度是160每个整数代表一个像素的灰度值。 # 3. 二值化与寻找黑线区域 threshold 50 # 二值化阈值。灰度值低于此值的被认为是黑线。需要根据实际赛道颜色和光照手动调整。 black_start None black_end None black_pixels [] # 记录被认为是黑线的像素的x坐标 for x in range(roi[0], roi[0] roi[2]): # 遍历ROI宽度内的每一个x坐标 # 注意img.get_pixel(y, x) 返回的是(x,y)坐标的灰度值。我们之前获取的line是按x顺序的。 # 这里我们直接使用line列表索引是 x - roi[0] index x - roi[0] pixel_value line[index] if index len(line) else 255 # 安全访问 if pixel_value threshold: black_pixels.append(x) # 记录黑点位置 if black_start is None: black_start x # 记录黑线区域的起始x坐标 black_end x # 不断更新最终记录黑线区域的结束x坐标 # 注意这里没有做区域合并等复杂处理假设黑线是连续的。 # 4. 计算偏差 error 0 found False img_center_x roi[0] roi[2] // 2 # ROI区域的水平中心x坐标本例中为80。 if black_pixels: # 如果找到了至少一个黑点 found True # 方法1使用黑线区域中心 if black_start is not None and black_end is not None: line_center_x (black_start black_end) // 2 error line_center_x - img_center_x # 偏差 线中心 - 图像中心 # 方法2使用所有黑像素的平均位置重心法抗干扰更好 # line_center_x sum(black_pixels) // len(black_pixels) # error line_center_x - img_center_x # 在图像上画出扫描线和识别到的黑线区域用于调试会消耗时间正式比赛可注释掉 img.draw_line(roi[0], scan_line_y, roi[0]roi[2], scan_line_y, color127) # 画扫描线 if black_start and black_end: img.draw_line(black_start, scan_line_y-2, black_end, scan_line_y-2, color0) # 画识别到的线段 # 如果没找到黑线可以根据上一帧的误差或设定一个默认值这里简单返回0并标记未找到。 # 实际应用中可能需要加入“丢线处理”逻辑比如保持上次转角或原地旋转寻线。 return error, found关键点解析与避坑ROI感兴趣区域这是提升处理速度和抗干扰的关键。摄像头画面可能包含远处的墙壁、天花板灯等。我们只关心地面附近的一条带状区域。roi的y值和height需要根据摄像头俯角物理调整。一个技巧是将小车放在赛道上在OpenMV IDE中查看实时画面确定黑线稳定出现的y轴范围。二值化阈值threshold这个值本例中为50不是固定的。它取决于赛道底色白和引导线黑的灰度对比度。需要在比赛现场的光照条件下进行校准。可以在代码中加入按键调整阈值的功能或者通过串口发送指令来微调。重心法 vs 起止点中心法注释中提到了两种计算线中心的方法。起止点中心法计算简单但如果黑线边缘有毛刺或噪声中心点容易跳动。重心法求所有黑点坐标的平均值对噪声的鲁棒性更好是更推荐的做法但计算量稍大。丢线处理if black_pixels:这个判断至关重要。当小车冲出赛道、遇到强光干扰导致全白或者遇到十字路口横向黑线时black_pixels可能为空。代码必须妥善处理这种情况否则error会保持为0小车可能直冲出去。高级策略包括使用上一次有效的误差、让小车减速并原地旋转直到重新找线、或者进入路口处理状态机。3.3 PID控制器实现得到偏差error后我们需要一个控制器来将其转化为平滑的控制指令。PID比例-积分-微分是首选。# PID 参数定义 Kp 0.5 # 比例系数。决定了对当前误差的反应强度。太大易震荡太小响应慢。 Ki 0.01 # 积分系数。用于消除静态误差例如小车长期偏向一侧。但容易积分饱和引起超调。 Kd 0.2 # 微分系数。预测误差变化趋势抑制振荡。对噪声敏感需要滤波。 # PID 变量初始化 error_last 0 # 上一次的误差 error_integral 0 # 误差积分项 output 0 # PID输出值 def pid_compute(error, dt): PID控制计算函数位置式PID。 参数: error: 当前误差值。 dt: 距离上次计算的时间间隔秒用于积分和微分。 返回: output: 计算出的控制量。 global error_last, error_integral # 比例项 P p_term Kp * error # 积分项 I (加入抗积分饱和) error_integral error * dt # 限制积分项防止积分饱和导致系统失控 integral_limit 100 # 积分限幅根据实际系统调整 if error_integral integral_limit: error_integral integral_limit elif error_integral -integral_limit: error_integral -integral_limit i_term Ki * error_integral # 微分项 D (使用不完全微分或对误差进行滤波会更好) d_term Kd * (error - error_last) / dt if dt 0 else 0 # 注意对误差直接微分会放大噪声。实践中常对误差进行低通滤波或使用“微分先行”等变种。 error_last error # 更新上次误差 # 总和输出 output p_term i_term d_term return output关键点解析与避坑参数整定Kp, Ki, Kd这三个参数需要现场调试。经典口诀是“先比例后积分再微分”。先将Ki和Kd设为0调Kp让小车能基本循迹但略有振荡然后加入较小的Ki来消除长期偏向一侧的误差最后加入Kd来抑制振荡使运行更平稳。积分饱和这是PID实践中的一个经典问题。当误差长时间存在比如卡在角落积分项会不断累积变得非常大一旦误差反向需要很长时间才能“消化”掉这个巨大的积分项导致控制反应迟钝甚至反向失控。代码中加入的integral_limit积分限幅是必须的防护措施。微分噪声微分项对误差的变化率敏感而摄像头识别带来的误差值本身可能有几个像素的跳动噪声这会被微分放大导致输出抖动。解决方案包括对误差error进行一阶低通滤波后再微分或者使用“微分先行”PID只对测量值微分而不对设定值微分。时间间隔dtPID计算需要知道两次计算的时间差。可以用time.ticks_ms()获取毫秒时间戳来计算dt。dt不准确会影响积分和微分的效果。3.4 电机控制与主循环整合最后我们将PID输出映射到左右电机的速度差实现转向。# 假设电机控制接口函数具体取决于你的电机驱动板可能是PWM、DIR引脚控制 def set_motor_speed(left_speed, right_speed): 设置左右电机速度。 参数: left_speed: 左电机速度范围例如 -100 到 100正数前进负数后退。 right_speed: 右电机速度。 # 这里需要根据你的硬件来写例如使用 pyb.PWM 对象 # left_pwm.duty(left_speed) # 伪代码 # right_pwm.duty(right_speed) # 伪代码 pass # 主循环 while(True): clock.tick() # 开始追踪这一帧的时间 img sensor.snapshot() # 拍摄一张图片 # 1. 找线计算误差 error, line_found find_line_error(img) # 2. 如果丢线执行丢线处理策略 if not line_found: # 策略示例减速并施加一个固定的旋转速度寻线 set_motor_speed(20, -20) # 原地左转寻线 # 或者保持上一次的output值 # 更复杂的策略可以记录丢线前的误差方向向那个方向旋转 continue # 跳过本次PID计算 # 3. 计算时间间隔 dt (秒) dt clock.avg() # clock.avg() 返回平均帧间时间秒。也可以使用 clock.diff() # 4. PID计算 turn_output pid_compute(error, dt) # 5. 将转向输出转换为电机速度 base_speed 50 # 基础前进速度 # 差速转向一个轮子加速一个轮子减速 left_motor_speed base_speed - turn_output right_motor_speed base_speed turn_output # 6. 限制电机速度在合理范围内例如0-100 left_motor_speed max(0, min(100, left_motor_speed)) right_motor_speed max(0, min(100, right_motor_speed)) # 7. 执行电机控制 set_motor_speed(int(left_motor_speed), int(right_motor_speed)) # 8. 调试用打印帧率和误差到串口 # print(clock.fps(), error)关键点解析与避坑差速转向模型左速 基础速度 - 转向输出右速 基础速度 转向输出。这是最常用的模型。当error为正线在右边turn_output为正则左轮减速右轮加速小车向左转以追线。速度限幅必须对计算出的电机速度进行限幅防止超过电机或驱动板能承受的PWM范围否则可能导致硬件损坏或控制异常。dt的获取clock.avg()返回的是平均帧时间用于PID计算是可行的。更精确的做法是使用time.ticks_diff()计算本次循环与上次循环的实际时间差。丢线处理主循环中加入了简单的丢线处理if not line_found。这里的示例是让小车原地左转。在实际比赛中你需要设计更鲁棒的策略比如判断丢线前最后几帧误差的趋势朝误差减小的方向旋转或者结合陀螺仪如果小车有进行角度控制寻线。4. 调试技巧与常见问题排查代码写完了调参和调试才是真正的战场。以下是一些血泪换来的经验。4.1 图像识别调试使用OpenMV IDE的“帧缓冲区”和“串行终端”把img.draw_line等绘图函数打开在IDE里实时查看摄像头看到了什么扫描线画在哪识别出的黑线区域是否准确。通过print()语句将threshold、error、black_pixels的长度等关键变量输出到串行终端。可以写一个简单的协议用键盘输入数字来动态调整阈值threshold这是现场调参的神器。光照是最大的敌人补光补光补光在小车摄像头周围加装LED灯条自己创造稳定的光照环境。这是提升巡线稳定性的最有效手段没有之一。注意灯光角度避免在赛道上形成反光点。可以尝试用磨砂纸柔化光线。如果赛场光线不可控可以考虑动态阈值算法比如大津法OTSU但计算量会增大。二值化阈值怎么定把小车放在赛道典型位置直道、弯道、明处、暗处在IDE中查看黑线和白底的灰度值。阈值取一个中间值例如(黑线最大灰度值 白底最小灰度值) / 2并留出足够的余量。4.2 PID参数调试“看波形”调试法将error偏差和outputPID输出通过串口发送到电脑用SerialPlot、CoolTerm等软件绘制实时曲线。理想状态小车在直道上error在0附近小幅波动进入弯道error平稳地偏向一侧output也随之平稳变化。问题诊断振荡严重Kp太大或Kd太小。响应迟钝过弯时压线甚至冲出Kp太小。长期偏向弯道内侧有静态误差需要增加Ki但一定要配合积分限幅。电机“抽搐”可能是Kd太大放大了误差噪声。尝试减小Kd或对误差进行滤波。“听声音”调试法在直道上电机应该发出平稳的“嗡——”声。如果发出“嗡-嗡-嗡-”有节奏的顿挫声说明Kp太大导致小车在直道上不断左右微调此时应减小Kp。4.3 常见问题速查表问题现象可能原因排查与解决思路完全找不到线1. 阈值threshold设置不当。2. 摄像头焦距不对画面模糊。3. ROI区域设置错误黑线不在扫描范围内。4. 环境光太强/太弱导致黑白对比度低。1. 用串口打印实时灰度值调整阈值。2. 手动调整摄像头焦距确保图像清晰。3. 在IDE中查看画面调整ROI的y坐标和高度。4. 加强补光或调整摄像头曝光参数。寻线抖动小车“画龙”1. 比例系数Kp过大。2. 微分系数Kd太小或为0。3. 图像识别出的error本身就在跳动噪声大。1. 逐步减小Kp。2. 适当增加Kd。3. 检查图像处理尝试对扫描行的灰度值进行中值滤波或采用多行扫描取平均误差。过弯时反应慢冲出赛道1. 比例系数Kp过小。2. 前瞻距离太短扫描行太靠下。3. 基础速度base_speed过高。1. 逐步增大Kp。2. 将扫描行scan_line_y上移减小y值让小车“看得更远”。3. 弯道前适当降低基础速度。直道上跑偏不居中存在静态误差需要积分项。1. 引入较小的Ki。2.务必同时设置integral_limit积分限幅。3. 检查小车机械结构是否对称轮胎摩擦力是否一致。遇到十字路口误判十字路口会出现横向黑线单行扫描可能识别为一个很宽的黑块中心计算错误。1. 加入路口识别逻辑当识别到的黑线宽度(black_end - black_start)超过某个阈值时判定为十字路口进入预设的路口处理程序如直行一段或根据标记转弯。2. 使用多行扫描判断黑线的连续性。帧率太低控制延迟大1. 图像分辨率设置过高。2. 图像处理算法太复杂如使用了彩色识别、复杂的滤波。3. 串口打印了太多调试信息。1. 使用QQVGA或更低分辨率。2. 优化代码只做必要的计算。关闭IDE中的图像传输功能以释放带宽。3. 正式运行时注释掉或减少print语句。5. 性能优化与进阶思路当基础巡线稳定后可以考虑以下优化来提升速度和鲁棒性以应对更复杂的赛道和更高的竞赛要求。5.1 图像处理优化多行扫描与前瞻控制只扫描一行虽然快但信息有限。可以扫描多行例如近处一行远处一行近处的误差用于快速反应保持稳定远处的误差用于提前预判弯道实现更平滑的转向。两者的误差可以加权融合。error_near, found_near find_line_error(img, scan_line_y100) # 近处 error_far, found_far find_line_error(img, scan_line_y60) # 远处 if found_near and found_far: error 0.7 * error_near 0.3 * error_far # 加权融合侧重近处动态ROI让ROI随着识别到的黑线位置动态移动。例如上一帧黑线在x50那么下一帧的ROI可以设置在x30到x70的范围内。这样可以进一步排除画面边缘的干扰并减少需要处理的像素数量提高速度。图像滤波如果赛道有污渍或光照不均原始灰度图噪声会很大。可以在二值化前对line数组进行简单的软件滤波比如一个窗口大小为3的中值滤波能有效去除孤立的噪声点。5.2 控制算法优化变参数PID让PID参数根据误差大小或小车速度动态变化。例如当误差很小时使用一组较小的Kp来保证直道平稳当误差很大急弯时切换为一组较大的Kp来快速响应。也可以根据车速调整参数高速时参数应更柔和。分段PID对直道、弯道、十字路口等不同赛道元素使用完全不同的PID参数组和控制逻辑。这需要配合一个状态机来识别当前所处的赛道阶段。结合其他传感器纯视觉在高速或复杂环境下有其局限性。可以融合编码器测速进行速度闭环控制融合陀螺仪IMU进行角度辅助控制。例如在长直道上可以用陀螺仪来维持航向角减少对视觉的依赖从而允许小车跑得更快。5.3 工程实践要点电源管理OpenMV、单片机、舵机、电机驱动共用电池时电机启动的瞬间会产生很大的电压跌落可能导致OpenMV重启。务必在电源处加入大电容如4700uF进行缓冲并使用稳压模块为OpenMV单独供电。机械结构摄像头安装高度和俯角直接影响ROI的设置。安装要牢固避免抖动导致图像模糊。车轮的对称性和传动机构的顺滑度直接影响控制的对称性机械问题是很多“玄学”bug的根源。代码版本管理调试过程中会频繁修改参数。一定要做好版本记录每次只改变一个变量并记录下效果。可以用注释、或者简单的文本文件来记录每次测试的参数和表现。回过头来看这份代码的注释工作更像是对那段备赛时光的一次复盘。从最初的摄像头画面一片模糊到调通第一版PID小车能踉跄走完全程再到最后为了提升0.1秒的成绩而反复打磨参数和算法每一个环节都充满了挑战和解决问题的乐趣。视觉巡线作为嵌入式与机器视觉的经典结合点其核心思想——感知、处理、决策、控制——在更广阔的机器人领域也是相通的。希望这份详细的注释和心得能帮你少走一些我们曾经走过的弯路更顺畅地驶入智能车开发的精彩世界。如果在实现过程中遇到具体问题不妨从图像是否清晰、误差计算是否准确、PID输出是否合理这三个维度像剥洋葱一样一层层去排查大概率能找到问题的根源。