多边形轮廓：把"一团像素"简化成"几个顶点"

01目标：三个形状标出顶点数、中心和面积

02问题：一堆白点，机器人拿它没法用

想象一条分拣线：传送带上过来三角形、四边形、圆盖三种工件，下游要按形状分流。相机装在上方，上节课那套颜色阈值能把工件从皮带背景里抠出来 —— 可抠出来的结果是一张白花花的面具。你要跟 PLC 说"3 号口来一个三角件"，它听不懂"这里有一万两千个白像素"。它要的是：什么形状、在画面哪个位置、偏了多少度。

把标题那句话拆开 —— 「一堆白点，机器人拿它没法用」，其实是三问：

• ① 怎么把白点变成几个点？一万多个边界点，凭什么敢丢到只剩 3 个还不失真？（本节的四步瘦身）
• ② 变成点以后，到底能干什么？哪些活儿是"有顶点就能干"的，哪些还差得远？
• ③ 什么情况下这招不灵？光照一变、工件挨在一起、形状本身是凹的 —— 分别会怎么坏？（invert / min_area / use_hull）

03现象：形状被多边形勒住，画面标出顶点数

🎬 现象速览 · 先单图，再接相机

你会看到：一幅双栏图 —— 左栏原始画面，右栏纯黑背景上每个形状被一条彩色多边形线勒住、中心有一个同色实心圆点（质心）、多边形第一个顶点上方标着顶点数（本例 3 / 4 / 8）。

① 先跑单图（30 秒，不需要相机）。源码目录自带一张示例图 image.png：三个几何形状 + 5 个孤立噪点。配套的 config/image_demo.yaml 是专为这张图准备的参数（binary 阈值 90、核 11×11），先把这一刻的"该看到什么"对上，再谈原理：

cd ~/ros2_ws/src/xflz_eai_car1/vision/05_line_following
python src/app.py --image image.png --config config/image_demo.yaml --save out.png

saved -> out.png ← 终端只打印这一行；形状和顶点数全在 out.png 里，终端不打印

⚠ 必须带 --config。不带就用了主配置 line_config.yaml（adaptive），它对这张纯色底的图会把整片背景判成前景：检测结果是「1 个轮廓、面积 306081」，也就是把整张 640×480 画面当成一个目标，右栏只会剩一条贴边框的线和中间一个质心点 —— 看起来像"什么都没框出来"，其实是参数和场景不匹配。

② 再接相机跑实时。终端 1 起相机驱动（ROS_DOMAIN_ID 各终端必须一致），终端 2 跑程序——注意实时模式用的是主配置 line_config.yaml（adaptive），参数要按你面前的场景调，调法见第 05 节：

source /opt/ros/humble/setup.bash && source ~/ros2_ws/install/setup.bash
export ROS_DOMAIN_ID=N
ros2 launch ascamera hp60c.launch.py

cd ~/ros2_ws/src/xflz_eai_car1/vision/05_line_following
python src/app.py --ros

30帧平均帧率: 151.3 30帧平均帧率: 153.4 ← 稳定在 140~160 FPS；顶点数在画面上的多边形旁边，不在终端

浏览器打开 http://<板IP>:8080/polygon.mjpg，把形状逐个放到镜头前。

③ 想边调边看，加 --tune：滑杆窗口开在板子桌面（远程用 noVNC 看），换参数不用改文件，细节见第 05 节。

python src/app.py --tune --ros

🔍 看什么：① 右栏黑底上，每个形状被彩色线勒住、中心有实心圆点（质心）；② 第一个顶点上方的数字就是顶点数 —— 三角 3、四方 4、圆会给出 8 个以上；③ 左栏是原始画面，没有任何叠加，两栏并排就是为了让你一眼对回"这条线勒的是哪个形状"。

单图模式用来"把每一步看清楚"（可重复、不依赖相机）；实时模式用来"接场景"。两者跑的是同一套 pipeline，只是输入源不同。

04原理：从一帧彩色画面到几个顶点

八个环节，从相机拍到的一帧彩色画面，到最后贴在画面上的形状标签。前半段一直在做减法（彩色 → 灰度 → 黑白 → 去掉噪点 → 1716 个点 → 3 个顶点），最后两步做加法：把数字变回人能看懂的名字。

下面这张图来自源码目录自带的 image.png：8 个环节每一步都是 src/pipeline.py 真跑出来的，参数用 config/image_demo.yaml（binary 阈值 90、核 11×11）。看图顺序：上排从左到右，再下排从左到右。

八个环节：谁在干活、数据变成什么、为什么少不了

n = len(poly)
if n == 3:      name = 'TRIANGLE'
elif n == 4:    name = 'QUAD'
elif n >= 8:    name = 'CIRCLE'
else:           name = 'POLY%d' % n

先认识 4 个词

它吃什么、吐什么

参数从哪来：一份 YAML 怎么变成画面上的效果

前面八个环节里所有"调大会怎样"的参数，代码里一个都没有写死 —— 它们全从配置文件读进来。整条路是这样走的：

为什么参数要外置？换台面、换工件、换光照，代码一行不用动 —— 这是把"算法"和"现场标定"分开的基本做法。代价是：配置写错，程序启动即失败，所以 config.py 有一层校验：

完整参数清单（下面是示例图配的那份 image_demo.yaml，主配置 line_config.yaml 结构完全一样，只是数值不同。这是配置内容，不用执行，改完存盘再跑程序）：

preprocess:
  threshold_mode: adaptive    # binary | adaptive
  threshold_value: 50
  invert: false               # 亮物暗底用 false；暗物亮底改 true
  morph_kernel: 3

contour:
  min_area: 100               # 小于这个面积的轮廓直接丢掉

polygon:
  approx_epsilon: 0.02       # 最该调的那个数（× 轮廓周长）
  use_hull: true              # 先凸包再逼近

05实操：--tune 一条命令，八个滑杆调到底

1. 终端 1：先起相机约 2 分钟

   相机话题必须先由驱动节点发出来，程序才读得到；ROS_DOMAIN_ID 各终端保持一致（N 取 0~101 任一整数，每台设备各选各的）。

   source /opt/ros/humble/setup.bash && source ~/ros2_ws/install/setup.bash
   export ROS_DOMAIN_ID=N
   ros2 launch ascamera hp60c.launch.py

2. 终端 2：用 --tune 跑起来约 1 分钟

   加 --tune 会弹出八个滑杆，画面照常推 MJPEG —— 这是本实验最该先学的命令，后面所有参数都在这里拖出来：

   cd ~/ros2_ws/src/xflz_eai_car1/vision/05_line_following
   python src/app.py --tune --ros

   30帧平均帧率: 55.5 30帧平均帧率: 53.2 ← 约 55 FPS（比纯 --ros 的 150 FPS 低，因为多了滑杆窗口的渲染开销）；参数实时叠在画面左上角

   滑杆窗口开在板子的桌面上：接了显示器就直接看；远程用浏览器打开 http://<板IP>:6080/vnc.html（板端自带 noVNC）就能拖。MJPEG 同时在推，http://<板IP>:8080/polygon.mjpg 可以另开一窗对照。

3. 拖滑杆试参数，Ctrl+C 收工约 10 分钟

   对照下面那张参数表逐个拖，看画面怎么变。调满意后按 Ctrl+C，终端会打印一段能直接粘回 config/line_config.yaml 的配置片段 —— 滑杆值不用手抄：

   调参结果（改 config/line_config.yaml 后重跑即生效）: preprocess: threshold_mode: binary threshold_value: 90 invert: false morph_kernel: 11 contour: min_area: 100 polygon: approx_epsilon: 0.020 use_hull: true color: enabled: false

   一次只改一个滑杆，否则出了变化你不知道是谁的功劳。

八个滑杆各管什么：拖一下，画面怎么变

前五个滑杆决定"哪些像素算目标"，后三个决定"目标被描述成什么形状"。两边各有一张图对照：

关键代码：全链路只有三个函数

源码 src/pipeline.py 里，一条完整链路就是这三段（下面贴的是真源码，行号对应仓库文件）：

def to_binary(bgr, cfg):
    gray = cv2.cvtColor(bgr, cv2.COLOR_BGR2GRAY)
    if p["threshold_mode"] == "adaptive":
        mask = cv2.adaptiveThreshold(gray, 255, cv2.ADAPTIVE_THRESH_MEAN_C,
                                     cv2.THRESH_BINARY, 11, 2)
    else:
        _, mask = cv2.threshold(gray, p["threshold_value"], 255, cv2.THRESH_BINARY)
    if p["invert"]:
        mask = cv2.bitwise_not(mask)
    k = cv2.getStructuringElement(cv2.MORPH_ELLIPSE, (p["morph_kernel"],) * 2)
    return cv2.morphologyEx(mask, cv2.MORPH_OPEN, k)

块外说明：自适应阈值固定用 blockSize=11、常数 C=2（这两个数没放进配置文件，是代码里写死的）；invert 在阈值之后做反相；最后一步开运算用椭圆核去毛刺。

def fit_polygon(contour, epsilon_ratio=0.02, use_hull=True):
    shape = contour
    if use_hull:
        shape = cv2.convexHull(contour)
    peri = cv2.arcLength(shape, True)
    return cv2.approxPolyDP(shape, epsilon_ratio * peri, True)

块外说明：顺序是"先凸包、再量周长、再逼近"。注意周长量的是凸包的周长 —— 所以关掉 use_hull 时，同一个 epsilon 的绝对容差也会跟着变。

你该看到的画面

踩坑速查

进阶（可选）

圆度 = 4π × 面积 / 周长²

offset = (质心x - 画面中心x) / (画面宽/2)   # 归一化到 -1 ~ +1
角速度 = -k × offset                       # 正偏移（偏右）→ 负角速度（左转）

pts = cv2.approxPolyDP(hull, 0.02 * cv2.arcLength(hull, True), True)
if len(pts) == 4:
    src = order_corners(pts.reshape(4, 2))          # 排成 左上 右上 右下 左下
    dst = np.float32([[0, 0], [W, 0], [W, H], [0, H]])
    M = cv2.getPerspectiveTransform(src, dst)
    warped = cv2.warpPerspective(img, M, (W, H))

x, y, w, h = cv2.boundingRect(contour)          # 正框（水平垂直）
(cx, cy), (w, h), angle = cv2.minAreaRect(contour)  # 旋转框 + 角度

代码复盘：这套代码是怎么搭起来的

技术框架（分层） —— 每格都是仓库里的真实文件，没有"数据处理模块"这种空话：

关键模块（改它会发生什么 / 什么时候失效）：

用 Python + OpenCV 写一个循环，逐帧处理摄像头画面：
- 读一帧，读不到就退出
- 转灰度，做自适应阈值得到黑白掩膜
- 掩膜可能反相，用配置里的开关控制
- 用椭圆核做开运算去掉小噪点
- 找最外层轮廓
- 面积小于阈值的轮廓丢掉
- 每个轮廓先求凸包，再用 approxPolyDP 简化，容差 = 比例 × 凸包周长
- 在画面上描出多边形、标出顶点数和质心
- 把画面推成 MJPEG 流，端口从参数读
参数全部从 YAML 配置文件读，不要硬编码

06互动：把 --tune 的八个滑杆搬进页面

📌 这一节是「掌握检查」：亲手改参数，看现象是否朝你预期的方向变，还要能说出为什么 —— 说得出，才算掌握。

第 05 节那条 python src/app.py --tune --ros 会在板上弹出一个滑杆窗口。下面这个是它的网页版：同一张 image.png、同样 8 个参数，而且不是提前画好的示意图 —— 浏览器里真的把 cvtColor → threshold / adaptiveThreshold → morphologyEx → findContours → convexHull → approxPolyDP 重跑一遍，参数口径与源码逐项对齐。

它不是「猜一个看起来合理的结果」：这套重写对着 260 组参数组合、用同一份 pipeline.py 跑出的 OpenCV 结果逐条比对过，轮廓数、顶点数、面积一致；只有 1 组（use_hull=0 + epsilon≈0.009）顶点数差 1，属边角情况。对照值是用 cv2 5.0 生成的，板上 venv 是 cv2 4.11 —— 这两版之间 approxPolyDP / convexHull 的算法没变，但如果板上和这里差 1 个顶点，先怀疑版本差异，别急着改参数。

七个预设：先猜结果，再按按钮

每个预设下面这行「应该看到」都是从板上真值抄下来的，不是描述性说法。按完对不上，说明你漏看了某张面板。

epsilon 在这张图上的实际效果

同一帧、其余参数取默认，只动 epsilon（= 容差比例 × 凸包周长）：

八个参数各改哪一层

两个从源码里读出来、但界面上看不出的坑：

• morph_kernel 的滑杆上限是 9（createTrackbar("morph_kernel", win, …, 9, …)），而 config/image_demo.yaml 写的是 11 —— 也就是说这个值在滑杆窗口里到不了。上面这个面板放开到 11，方便你对比它和 9 的差别（面积会差 0.3% 左右）。
• threshold_value 只在 adaptive=0 时有用。代码里 blockSize=11、C=2 是写死的，走的不是 YAML。所以 adaptive=1 时怎么拖 thr 都没反应 —— 板上会显示 thr=xx(bin only)，就是这个意思。

调参顺序（和现场一样）：先看 ② 掩膜对不对（thr / invert / adaptive / color 决定「目标有没有被切出来」）→ 再看 ③ 顶点数对不对（epsilon / use_hull 决定「形状判得准不准」）→ 最后看 min_area 有没有把该留的滤掉。顺序反了会白折腾：掩膜里根本没有目标时，调 epsilon 是把噪声拟合得更漂亮而已。

07验证：三道小测

08章节总结：这些概念怎么串起来、能带去哪

前置依赖 · 缺一样就跑不起来

这套代码用在哪儿（每一条都能对回上面那几个几何量：顶点数、面积、质心、朝向）：

• 分拣线按形状分流（本章直接产出）：传送带上方装相机，顶点数 + 面积判三角/四方/圆盖，质心坐标决定推杆往哪拨。适合高对比、形状规则、节拍快、成本敏感的线体 —— 这也是不用上深度学习就能搞定的那一类活。
• 工件框选与朝向（+1 个函数）：minAreaRect 给出最小旋转框的中心、宽高与角度，机械臂据此决定"夹爪转多少度"。
• 文档 / 单据扫描矫正（+2 个函数）：手机拍纸质表单，找到四个纸角 → 透视变换拉正，再送 OCR。经典的四点矫正 pipeline，前半截就是本章。
• 缺陷与破损判断（+1 个函数）：convexityDefects 把"凸包和真实轮廓之间的缺口"量出来，缺角、崩边一目了然。
• 不该用它的场合：弱光杂乱背景、柔性件变形、工件堆叠遮挡、需要细分材质或纹理 —— 这些交给第 2 阶段的 YOLO；相机标定与完整视觉抓取也不在本章，分别见 core/calibration 与机械臂课程的视觉抓取实验。

下一个实验换一种完全不同的思路：不再自己算几何，而是调一个成熟的接口把黑白格子读成字符串 —— 顺便看看"写成什么、读回什么"的闭环是什么感觉。