语义分割背景替换：不只框住人，还要把人的轮廓抠出来

01目标：终端报 4 个实例，画面只留 3 个人

02问题：虚拟背景不是套框，可为什么报了 4 个只留 3 个

你天天在用的东西：线上会议点一下「背景虚化」，人就还在，身后那面墙变成了另一个房间。你只看到结果，中间发生了什么完全看不见 —— 这就是黑盒。

本实验要打开这个黑盒。第一次跑完，终端会出现这么两行（下一节完整演示）：

[seg] 4 instances
saved -> out.jpg

数字是 4，画面里是 3 个人，还有一整辆巴士凭空消失了。这个对不上的落差，就是这一节要问的三个问题。

把黑盒拆成两栏，左边是你看到的，右边是机器必须完成的：

这三个问号，拆成三个具体的问题：

① 每个像素归谁。框只有四个数，掩码有几十万个格子。机器凭什么说出「这一根头发是人、紧挨着的那块墙不是」？

② 报了 4 个，为什么只剩 3 个。终端明明写 [seg] 4 instances，out.jpg 里整辆巴士却一起黑了 —— 是谁把第 4 个丢掉的？

③ 边缘那圈暗边是哪来的。换成纯色或风景背景后，每个人轮廓外都挂着一圈旧背景的残影。是模型不干净，还是有个参数在替你取舍？

所以先看它跑出来什么样 —— 四张真图一次摆齐。

03现象：人贴着轮廓留下，巴士和街道一起变黑

🎬 现象速览 · 30 秒先看效果

你会看到：原图里三名行人站在一辆蓝色巴士前面；跑完之后，三名行人被贴着轮廓留下来，巴士和整条街道一起变黑。换 image 模式，人就被贴到了另一张照片里。终端只有两行要紧的：[seg] 4 instances 和 saved -> out.jpg。

四张真图，一条链走完（先照做，每步为什么下一节拆讲）：

怎么跑出这四张（三条命令）：第一条进目录、确认模型和素材在；第二条单图分割，把结果存成 out.jpg；第三条改配置后再跑一次，就换了一种背景。

cd ~/ros2_ws/src/xflz_eai_car1/vision/06_semantic_segmentation
ls models/ images/

models/: yolov8n-seg.rknn yolov8n-seg.onnx coco_80_labels_list.txt images/: bus.jpg + 20 张 COCO 量化校准图

python src/app.py --image images/bus.jpg --save out.jpg

[seg] 4 instances saved -> out.jpg ← 打开 out.jpg 就是上面第 ② 张图

启动时还会刷几行 W RKNN: … not match with rknn runtime version 和 query RKNN_QUERY_INPUT_DYNAMIC_RANGE error。这是静态 shape 模型的正常提示，不影响结果 —— 别以为出错了。

🔍 看什么：盯三处。

• 巴士为什么整辆没了 —— 不是模型没认出车（它认出了，就在那 4 个实例里），是被配置挡在了外面。第 04 节步骤 6 会指给你看。
• 人的边缘 —— 头发、手臂和背景交界处是贴着轮廓走的，不是方框。但仔细看第 ③ 张：轮廓外面挂着一圈颜色略暗的边，这就是第 02 节的第三问。
• 最右边那个人 —— 只露出半个身子、还被人挡住，照样被留下了。同一张画面里的三个人都能抠，说明这一步与人数无关。

这就是本实验最终要呈现的现象。此时照做、先看懂它就行；第 05 节会带你亲手跑出同样的画面，并补上实时相机那一路。

04原理：六格链路，把 32 个数拼成一个人的轮廓

这一节用六个步骤走完整条链。第 02 节的三个问题各有落点：① 每个像素归谁 → 步骤 4；② 报了 4 个为什么只剩 3 个 → 步骤 3 和步骤 6；③ 边缘那圈暗边哪来的 → 步骤 5。步骤 1、2 是把画面送进模型的必要准备。

1640×480 的画面，模型为什么非要一个 640 见方的黑边方块？

吃什么：任意尺寸的一帧 BGR 图（bus.jpg 是 810×1080）。做什么：按长边等比缩到 640，空出来的地方填纯黑，再把 BGR 换成 RGB。吐什么：一张 640×640×3 的 uint8 图。

算式很短：ratio = 640 / max(h, w) = 640 / 1080 ≈ 0.593，于是画面缩成 480×640，左右各补 (640-480)//2 = 80 像素黑边。这也是训练时喂给模型的固定形状 —— 神经网络只认死尺寸。

动它会怎样：填充色必须是 0 而不是常见的 114 灰边，通道必须是 RGB 而不是 OpenCV 默认的 BGR。这两处任何一个错，模型看到的分布就和训练时不一样 —— 症状不是报错，而是掩码整体错位或糊掉，很难反查。

2一次吐出 13 张张量，哪张是框、哪张是形状？

吃什么：那张 640 见方的图。做什么：过一遍 yolov8n-seg（3.2M 参数，3 个检测层）。吐什么：13 个 numpy 数组。

输出（每层 4 组）	是什么
box 64	4 条边 × 16 个 bin 的分布，用来还原框
cls 80	这一格属于 80 个 COCO 类各自的分数
cls_sum 1	80 个分数的和，分割模型特有
mc 32	掩码系数：形状要用多少（步骤 4 的主角）

第 13 张是 proto：32×160×160 的原型表，全局只有一份，不属于任何一个检测层。

动它会怎样：这 13 张布局与解码代码是死契约（postprocess.py 用 len(outputs)//3 分组）。换模型版本前先数输出数，少一张就会在解码时直接抛形状错误。

3几千个格子 × 80 个类别，怎么收敛成「画面里有 4 个东西」？

先猜一下：640 见方的图被切成 80×80、40×40、20×20 三种网格，一共 6400+1600+400 个格子。模型会吐出多少个候选框？几百个？还是几千个？—— 先写下你的答案，再看下面。

答案是 8400 个格子每格都有候选，几乎全是噪音。收敛靠三步：

• 还原框：64 个数是 4 条边各 16 个 bin 的分布，取加权期望得到偏移量，再加上格子中心与步长，得到 8400 个框。
• 筛分数：用 cls 最大分 × cls_sum 去比 score_thr = 0.25，绝大多格子在这一次比较里出局。
• 压重复：同一个物体周围一圈格子都会给框，用 NMS（iou_thr = 0.45）按重叠度只留一个。

剩下的就是那 4 个实例：3 个 person + 1 个 bus。终端打印的 4 就是这一步的结果。

动它会怎样：score_thr 调低 → 混进大量误检，画面里出现半透明的碎掩码；调高 → 只露出半个身子的人直接漏掉，整帧可能变黑。iou_thr 调低 → 画面里挤在一起的两个人都被并成一个。

432 个数乘 32 张模板图，怎么就叠出一个人的轮廓？

这是第 02 节第一问的答案，也是全节最反直觉的一步。模型没有画出这个人的轮廓，它只是报了一份 32 个数的「配料表」。

乘完再套一个 sigmoid，把数值压进 0~1。所以每人拿到的是一张概率小图：越靠近身体中心越接近 1，越往外越小，边界附近正好落在 0.5 上下。

动它会怎样：这一步没有可调参数 —— 它由 mc 和 proto 决定。这也是它最容易失效的地方：模板只有 160×160，一个人只占几十个像素、或者细到「一根手指」时，32 张低分辨率模板根本表达不出那个形状，边缘必然是圆钝的。

5160×160 的小图，凭什么贴到 640×640 上刚好合身？

三件事按顺序做，缺一件就会错位或多出残片：

1. 放大 4 倍：160 → 640，双线性插值。所以边缘天生是一条模糊的过渡带，不是刀切的硬边。
2. 框外清零：把这个实例的检测框以外全部置 0。少了这一步，一个人的掩码会顺着模板溢出到别人的框里，两人贴在一起时就粘成一团。
3. 切黑白：seg_img > mask_thr（默认 0.5）把概率图变成 True/False。

为什么 0.5 是默认值：sigmoid 在 0 处的取值正好是 0.5，所以 0.5 这条线基本落在「模型认为的边界」上。调高（0.7）→ 只保留更有把握的内部，边缘往里缩，头发和手指先丢；调低（0.3）→ 边界往外胀，把旧背景带进来一圈 —— 这就是第 02 节第三问那圈暗边的来源。

动它会怎样：mask_thr 是取舍而非精度。要「完整包含」时调到 0.3（量面积），要「一定有把握」时调到 0.7（确认这里确实有人）。0.5 是大多数场景的起点。

64 个实例里只留 3 个人，再把背景换掉 —— 到底谁在决定？

这是第 02 节第二问的答案，也是这个实验最容易被忽略的一处：1 个实例被丢掉，发生在后处理最末一段，不在模型里。

• 选类：把 N 张掩码按 model.classes 挑行（[0] 只留 person），再把挑中的若干张按位或成一张 —— 只要有一个实例在这一点上是人，这一点就是前景。多人场景下所有人才会都被保留。
• 缩回原图：这时掩码还是 640 见方。用步骤 1 存下的 pad_x / pad_y / ratio 反算，再用最近邻缩回 810×1080。必须最近邻：双线性会把 0/1 糊成小数，边缘又多一圈灰。
• 合成：compose() 做一次逐像素选择 —— 掩码为真的地方留原图，为假的地方填背景。三种模式只差「填什么」：black 填 0，solid 填 background.color，image 填一张缩放到同尺寸的背景图。

动它会怎样：classes 改成 [5] → 巴士留下、三个人变成黑色剪影（第 06 节给了这张图）；改成空列表 [] → 80 类全保留，什么都不会消失。background.color 是 BGR 顺序，想要红写 [0,0,255]。

先认识 4 个词

这张表五列，只看第 2、5 两列就能回答第 02 节的三问：第 2 列告诉你数据变成了什么，第 5 列告诉你哪个旋钮管哪一处。函数名放第四列，想追代码时再看 —— 它们都在 src/postprocess.py 与 src/app.py 里。

05实操：单图 / 三种背景 / 三线程三条命令

学员敲的是一条命令，脑子里却没有「这一帧经过了谁」。先把这张对照表摆出来 —— 每一行都是第 04 节某一格的落地，第 5 列写明它对应原理的哪一步。

第 03 节那四张图，现在亲手复现一遍。

1. 单图跑一遍，先看清 4 和 3约 3 分钟

   进目录，确认模型（yolov8n-seg.rknn，约 7MB）和素材都在。第一条命令不产出图，只是确认素材齐全。

   cd ~/ros2_ws/src/xflz_eai_car1/vision/06_semantic_segmentation
   ls models/ images/

   models/: yolov8n-seg.rknn yolov8n-seg.onnx coco_80_labels_list.txt images/: bus.jpg + 20 张 COCO 量化校准图

   单图模式：读一张图、只起 1 个 worker、跑一次、存盘退出。参数 --image 给输入，--save 给输出文件名。

   python src/app.py --image images/bus.jpg --save out.jpg

   [seg] 4 instances saved -> out.jpg

   打开 out.jpg：三名行人在，巴士和街道全黑。顺手试一次只给 --image 不给 --save —— 它会提示 use --save or --display for single image 然后退出，不会把图显示在你眼前。

2. 换三种背景，比一比边缘约 5 分钟

   背景由 background 这一段决定：mode 选模式，color 只在 solid 用（BGR 顺序），image 只在 image 用。这段是配置内容，不用执行：

   background:
     mode: black          # black | solid | image
     color: [0, 0, 0]     # solid 的填充色，BGR 顺序
     image: ""            # image 模式的背景图

   改一次配置跑一次，换个输出文件名好放在一起比（out_black.png 存出来的就是第 03 节第 ② 张）：

   python src/app.py --image images/bus.jpg --save out_black.png

   [seg] 4 instances saved -> out_black.png

   一定先试 black。纯黑最容易暴露问题：边缘有没有毛边、有没有把旧背景的残片带进来，一眼就看清。

   然后试 solid：把 mode 改成 solid、color 改成 [0, 200, 0]（BGR → 亮绿），重跑一次。那圈暗边会变得非常明显 —— 它就是第 04 节步骤 5 说的「往外胀」。

   最后试 image：mode 改 image，image 填一张现成的图，例如 images/000000075612.jpg（images/ 里那 20 张 COCO 图随便挑一张就行，不用另外找素材）。路径是按「你运行命令时所在的目录」解析的 —— 只要按本节在项目根下运行，写 images/xxx.jpg 就对了；写成不存在的文件，合成时会抛 cannot read background image。

3. 接上相机，看三线程把帧率抢回来约 8 分钟

   板上标准走法是 ROS 话题（HP60C 直连读不了，opencv 未编 libv4l）。两个终端，先起驱动再跑程序，两边的 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

   日志持续滚动，无 ERROR / 无红字

   终端二 · 跑分割 + 推流

   source /opt/ros/humble/setup.bash && source ~/ros2_ws/install/setup.bash
   export ROS_DOMAIN_ID=N
   cd ~/ros2_ws/src/xflz_eai_car1/vision/06_semantic_segmentation
   python src/app.py --ros

   [seg] 30帧平均帧率: xx.x det=1 ← workers: 1 时约 20~40，workers: 3 时约 40~60 ← 浏览器打开 http://<板IP>:8080/seg.mjpg

   想验证多线程真的起作用：把 pool.workers 从 3 改成 1，重跑一遍，对比终端那行帧率。注意 core_mask 默认是 auto（驱动自己调度），改成 round_robin 才会按 tid % 3 把三个 worker 分别钉在 NPU 的三个核上。帧率明显偏低时，这两个值一起看。

   对着镜头挥挥手、抓抓头发 —— 看边缘跟不跟得住。头发最难：如果头发边缘也抠得干净，说明效果很好。

   

命令 → 函数 → 文件：你敲的每一行到底经过了谁

你该看到的画面

踩坑速查

进阶（可选）

BGRA = 原图 + alpha 通道（掩码 * 255）
cv2.imwrite('cutout.png', BGRA)

请阅读这个语义分割项目的五个文件：src/app.py、src/preprocess.py、src/postprocess.py、src/background.py、src/rknnpool.py。
它们共同完成「读一帧图 → 抠出人 → 换成新背景」。
请输出一张表，每行一个模块，四列：模块名 / 一句话职责 / 被谁调用 / 从哪个参数取值。
要求指出每个模块的关键函数所在行号；说不清「谁调谁」的地方请明确标注，不要猜。

请按「主线程处理一帧」的视角，为 src/app.py 的 main() 画一张控制流流程图。
必须包含：四个输入分支（--image / --video / --camera / --ros）如何汇合；主循环里取帧失败、推理结果为空这两条异常路径；退出循环后释放池与服务。
每个框里写函数名，判断框写条件，不要用「处理」「分析」这类空词。

请为实时模式（--ros）画一张时序图，参与者必须使用真实名字：ros2_camera 节点、Ros2Camera 回调、RKNNPool 的 worker 线程、主线程、MjpegServer。
按时间顺序标出：话题消息到达、入队、worker 取帧推理、结果出队、render 合成、set_frame 推流。
并标注主线程与 worker 是并行流水线（不是同步等待）。

06互动：拖 mask_thr 和 classes，看 4 变 3、边缘胀缩

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

第 05 节里改一次配置只能出一个结果，还得重跑。这里把步骤 5 和步骤 6 搬到页面上：同一帧合成画面、同一套 4 个实例，两个参数随便拖，结果实时重算 —— 不用设备也能看清「谁决定留下谁、谁决定边缘在哪」。

怎么读出规律：先只看 classes —— 4 个实例的检出数不变，变的只是「放行几个」；再看 mask_thr —— 放行的实例不变，变的是每个人轮廓的胖瘦。两件事互不干扰，这正是第 04 节步骤 5 与步骤 6 的分工。

切到 [5] 只留 bus 时，真机上跑出来是这样 —— 巴士完整保留，三名行人变成纯黑剪影。注意这时终端打的仍然是 [seg] 4 instances，一个字都没变：检出数压根不受 classes 影响。

三种典型设置

07验证：三道小测

08章节总结：检出是模型的活，留谁是 classes 的活

这页讲了什么，它们怎么串起来

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

这套代码用在哪儿

• 视频会议 / 直播虚拟背景：每帧出 person 掩码 → 白处留原图、黑处贴背景图 → 推 http://<板IP>:8080/seg.mjpg；进阶 1 把背景源换成高斯模糊的原图，立刻变成「人清晰、背景柔化」。
• 证件照 / 海报抠图：把掩码当 Alpha 通道存成 cutout.png，产出一张透明背景人像，直接交给设计贴图 —— 必须 PNG，JPG 不支持透明。
• 工位人形检测与安全区判定：机器人只需知道「人形区域在哪」，就用这张前景掩码做避让区；classes 换成需要的类，同一套代码还能抠设备、车辆。
• 人流计数：进阶 3 用 np.unique(res.classes, ...) 数 person 实例，适合固定机位的粗粒度统计；要跨帧认人就得接 EXP-07。

下一个实验要把这张「这一帧谁是人」的掩码，变成「跨帧还是不是同一个人」的编号 —— 你现在拿到的每个实例掩码，就是 DeepSORT 的起点。