# 摄像头扫码工具:整板小码是怎么一次读全的
> CameraScanTool · Avalonia 11 + .NET 10 · 识别用 Emgu.CV(OpenCV)与 ZXingCpp
-–
## 现场是什么样的
产品是一块贴满小码的板子,常见规格 5×5、2×12,共 24 或 25 个码,每个码是 3 位字母数字的 DataMatrix。相机固定在板子上方,出图 1280×720,操作员按空格,等 3 秒看结果。
如果只是扫一个码,这活儿一天就干完了。难的是整板一次读全:
- 1280 像素宽要摊给十几列,单码只剩几十像素宽,模块宽度接近 1 个像素,整图直接解码什么都读不出来。
- 环形灯打光,板子中间和四角亮度差一截,固定阈值切不干净。
- 板子是手放上去的,歪两三度很正常,有些位置还没贴码。
精度再堆也解决不了这些,最后换了条路:同一块区域换条件反复读,再对字符逐位投票。
-–
## 链路长什么样
```mermaid
flowchart TD
A\[相机采集线程<br/>约 30fps,1280x720\] --> B\[帧缓冲复用\]
B --> C{识别入口}
C -->|自动检测 3 秒窗口| D\[有界帧队列<br/>容量 8,满则丢最旧\]
C -->|单次抓拍| E\[取最近一帧\]
C -->|图片文件| F\[读成字节\]
D --> G\[4 线程并行解码\]
E --> H\[ScanFrame\]
F --> I\[ImageMarkScanner.Scan<br/>BGRA→PNG 内存内编码\]
G --> I
H --> I
I --> J\[DataMatrix 投票解码\]
I --> K\[QR 多策略补漏\]
J --> L\[两路合并<br/>中心点 30px 去重\]
K --> L
L --> M\[多帧累积<br/>内容优先\]
M --> N\[倾斜校正 + 行聚类<br/>8 种编号方向\]
N --> O\[BoardGridMapper<br/>规格校验 + 空码区推算\]
O --> P\[位号卡片 / 预览标记\]
```
三条入口——自动检测、单次抓拍、打开图片文件——最后都汇到 `ImageMarkScanner.Scan`。做法是相机帧在内存里编码成 PNG 再交给识别层,不传 Mat,这样两条路只有一份识别代码。
-–
## 采集层:先别把 CPU 吃光
识别很贵,采集很频繁,所以这一层做减法。帧缓冲复用,采完归还,避开 30fps 下每帧 3.5MB 的分配:
```csharp
// 帧缓冲复用:后台线程写入,UI 消费后调用 NotifyFrameConsumed(),避免高频大对象分配
public void NotifyFrameConsumed() => Interlocked.Exchange(ref _frameInUse, 0);
```
采集固定 33ms 一帧(约 30fps)。不放开跑的理由很实际:识别窗口只有 3 秒,帧率再高也只是把队列灌满后丢帧,还要跟解码线程抢 CPU。
预览另有个 Avalonia 的坑:`WriteableBitmap` 原地更新后 `Image` 不重绘,所以用 A/B 两个位图交替赋值触发重绘。
-–
## DataMatrix:定位一次,解码很多次
`DataMatrixVoteDecoder` 的思路很朴素:单次解码出错往往只错一两个字符,那就换条件多解几次,逐字符数票。
先用 ZXing 全图定位(1x、2x 各跑一遍,按中心点 24px 去重),只拿四个角的坐标,文本解码留到后面单独做:全图一次性解出内容对小码不够稳,定位它倒是可靠。定位框经常贴着码边缘,Quiet Zone 缺几个像素就会失败,所以按码尺寸的 25% 往外扩边,扩出去可能带上邻码,于是每次尝试只取第一个合法结果:
```csharp
var pad = Math.Max(6, (Int32)Math.Round(Math.Min(box.Width, box.Height) * 0.25));
```
解码条件按三个维度组合,先在原尺寸读一遍,再进这个矩阵,一个 ROI 最多 25 次:
| 维度 | 取值 |
|------|------|
| 放大倍数 | 2x / 3x / 4x(Lanczos4) |
| 预处理 | 原图 / 直方图均衡化 |
| 二值化 | Otsu / 固定 100 / 固定 150 |
票是逐字符计的。不满足"3 位、全字母数字"的结果直接丢掉,不进票箱:
```csharp
// 只接受"3 位 + 全字母数字"的结果,其它丢弃不投票
if (String.IsNullOrEmpty(text) || text.Length != CodeLength || !text.All(Char.IsAsciiLetterOrDigit)) continue;
for (var i = 0; i < CodeLength; i++)
chars\[i\]\[text\[i\]\] = chars\[i\].*TryGetValue*(text\[i\], out var n) ? n + 1 : 1;
```
取众数时只要有一位是空票箱,整个码就判不可信,宁可不要(`if (c.Count == 0) return (“”, total);`)。长度和字符集这两个约束帮了大忙,半解出来的乱码进不来。
最后有个墙钟上限 `MaxScanMilliseconds = 2500`:画面糊的时候 ZXing 会报出一堆伪定位框,每个都要跑 25 次,到点就停,返回手上已有的结果。少读几个码,总比卡着强。
-–
## QR 那条兜底通道
产品码是 DataMatrix,但图上可能混着 QR,也可能某个批次整套换成 QR,所以这条路留着。从粗到细四级,数量凑够就不再往下走:
```csharp
var raw = DecodeScaled(bgr, 1.0, Inter.Linear);
if (NeedMore(raw, expectedCount)) raw.AddRange(DecodeScaled(bgr, 2.0, Inter.NearestExact));
if (NeedMore(raw, expectedCount)) raw.AddRange(DecodeScaled(bgr, 3.0, Inter.NearestExact));
if (NeedMore(raw, expectedCount)) raw.AddRange(DecodeByTiles(bgr));
// OpenCV 辅助定位兜底:解码失败但可定位的码以空内容框出
if (raw.Count == 0) raw.AddRange(DetectFramesByOpenCv(bgr));
```
切块按 4×6 分,带 15% 重叠(避免把码切在缝上),每块放大到长边 1500px 左右再解,坐标还原回原图后按中心点 24px 去重。最后那道 `DetectFramesByOpenCv` 是给读不出来的码留位置:界面上至少能看到这里有个码,而不是一片空白——前者会让人去查,后者容易被当成没贴码。
-–
## 两路合并
两路结果按中心点 30px 去重,比通道内部的 24px 宽松,因为两个解码器给的框大小本来就不一样。保留 DataMatrix 的结果:它的内容是投出来的,QR 只负责填空。
-–
## 3 秒窗口、4 个线程
单帧不可靠:反光、手抖、局部遮挡,都会让某个位号这帧读不到、下帧又读到。自动检测就在时间窗里尽量多分析几帧,把结果攒起来:
```csharp
private const Int32 AutoCaptureWindowMs = 3000; // 识别窗口
private const Int32 AutoFrameQueueCapacity = 8; // 帧队列,满则丢最旧
private const Int32 AutoDecodeWorkers = 4; // 并行解码线程,单帧约 0.2s
```
队列有界、满了丢最旧:解码永远追不上采集,留住最近的画面比留住全部有用。用完的缓冲还回池子,数量凑够期望值就直接收工。
攒结果时去重优先看内容,内容为空(只定到框没解出文本)才退回看位置。原因就是位置不稳、文本稳:3 秒里产品被碰一下,同一码的中心点能偏出几十像素,而 3 位文本不会变。
中途结果会回传界面,操作员能看到数字往上跳。自动检测和单次抓拍用 `Interlocked.Exchange(ref _scanning, 1)` 互斥,避免两路同时解码。
-–
## 板子歪了:5×5 被判成 7×5
识别出一堆 `(x, y, w, h, text)` 只是中间产物,业务要的是位号(`#01`、`#02`……),这一段踩的坑最典型。
板子倾斜 θ 角时,同一行两端的码在图面上的 Y 差是"行宽 × sinθ"。行越宽、角度越大,差值越大,超过行聚类容差就把一行劈成两行——板子只歪两三度,5×5 就被聚成 7×5,直接报"格式不符"。
修法是先把旋转扣掉再聚类。倾角取"每个码到自己最近邻的方向角"的中位数,最后折叠到 ±45°:
```csharp
// 最近邻必定是同一行或同一列的相邻码(对角相邻的距离更大),其方向即板面轴方向
angles.Sort();
return angles.Count % 2 == 1 ? angles[angles.Count / 2] : (angles[angles.Count / 2 - 1] + angles[angles.Count / 2]) / 2;
```
不需要直线拟合:最近邻是同排或同列的邻码,它的方向就是板面轴的方向,取中位数就够了,个别码定位偏一点也不会带歪整体角度。换算到板面坐标系之后(把旋转扣掉),聚类就是普通的一维容差分组,容差取码平均高度的 70%。
编号方向现场可选,一共 8 种(起止边、左右向、是否蛇形),实现上拆成三个布尔量,不写 8 个分支。行内按图面 X 排即可:旋转角小于 45° 时,图面 X 与板面 X 在同方向都单调。
-–
## 空码区:把"没读到"拆开
"某个位置没有码"有好几种可能,处理方式完全不一样:
| 原因 | 判断依据 | 处理 |
|------|----------|------|
| 那里本来就没贴码 | 网格对齐成功,该格空着 | 推算空码区(红框 + 「未贴码」),参与上报前确认 |
| 贴了但没识别出来 | 数量不足、无法对齐网格 | 不下结论,提示调整光照/位置重试 |
| 扫描板规格选错了 | 识别行列数超出配置 | 报"格式不符",禁止当成未贴码 |
校验和推算都在 `BoardGridMapper` 里,对外是一个四态结果,其中"数据不足"单独算一种:
```csharp
public enum BoardSpecState
{
Matched, *// 识别到的行/列数与配置一致*
Inferred, *// 识别到的行/列数少于配置,已按间距外推补齐*
Mismatch, *// 识别结果与配置不符(行列数或数量超出、无法对齐),需核对规格*
Unknown, *// 识别数据不足,无法判断格式*
}
```
数据太少时返回 `Unknown` 而不是 `Mismatch`,门槛是识别数不足期望数的四分之一。这两个状态在代码里都是"没成功",但前者让操作员摆正产品再按一次,后者让他去改规格配置,把"没看清"说成"规格错了"只会让人白折腾。
尺寸一律取中位数:画面里偶尔混进一个异常框(相邻两码被当成一个),平均值立刻被带偏。空位分两种补,夹在中间的空行空列靠相邻间距的倍数认出,缺在两端时没有间距可用,只能看画面哪边留白更多:
```csharp
// 间距接近 step 的整数倍时,多出的部分就是中间空出的行/列
var advance = Math.Max(1, (Int32)Math.Round((centers[i] - centers[i - 1]) / step));
```
补出来的空位也生成占位框(网格键 `R{r}C{c}`),和真实码一起排序编号:真实码用文本当稳定标识,空码区用网格键。于是 `#23` 既可能是一个码,也可能是"未贴码",上报时按位号映射,服务端和现场说的就是同一件事。
-–
## 参数一览
| 层级 | 参数 | 值 |
|------|------|-----|
| 采集 | 分辨率 / 帧率 | 1280×720,约 30fps(33ms 固定节流) |
| 自动检测 | 窗口 / 队列 / 线程 | 3000ms;队列 8(满丢最旧);解码线程 4 |
| DataMatrix | 定位 | 1x、2x,按中心点 24px 去重;ROI 外扩 25%(≥6px) |
| DataMatrix | 条件矩阵 | 2x/3x/4x × 原图/均衡化 × Otsu/100/150,最多 25 次 |
| DataMatrix | 时长上限 / 文本 | 2500ms;3 位字母数字 |
| QR | 策略 | 整图 1x→2x→3x → 4×6 切块(重叠 15%,放大至长边 1500px) |
| QR | 去重 | 中心点 24px(与 DataMatrix 合并时为 30px) |
| 累积 | 判重 | 内容优先,内容为空时按位置 30px |
| 编号 | 行聚类容差 | max(10, 平均码高 × 0.7),板面坐标系下聚类 |
| 网格 | 聚类容差 / 数据门槛 | max(10, 中位码尺寸 × 0.7);识别数 × 4 < 期望数 则 Unknown |
-–
## 几处当时纠结的地方
换策略而不是换解码器:每个策略都有盲区——整图解码漏小码,切块会切碎大码,二值化救反光但会吃掉低对比模块。堆起来再投票是把"不确定"压成"多数决"最土的办法,代价是耗时,所以必须配时长上限。
判重先看内容:只看位置的话,操作员手一碰产品、画面移动几十像素,同一批码就会被当成新码重复计入,位号数量很快失控。三位文本比坐标稳得多。
位号钉在首次出现的位置:累积过程中画面一直在动,每帧拿新位置重排的话,界面上的位号会不停跳。
倾斜校正是必修课,不是精度优化:板子斜两三度,5×5 就被聚成 7×5,操作员看到的是一个莫名其妙的"格式不符"。凡是按行列聚类的算法,接到真相机之后都得先把坐标系当回事。
提示文案要能对应到下一步动作:`Mismatch` 和 `Unknown` 的差别就在这儿;QR 通道全解不出内容时也要返回空文本加位置框,让"读不出来的码"跟"根本没贴码"看起来不一样。
-–
## 还不太满意的地方
| 现在的问题 | 想改的方向 |
|----------|----------|
| 3 秒窗口、4 个线程都是写死的经验值 | 按 CPU 核数自适应,或按首帧识别率动态延长窗口 |
| 每个码独立投票,没用上"整板都是 3 位码"这个先验 | 全板联合解码,已知码段范围时先约束候选 |
| 空位外推默认网格等距;定位全靠 ZXing | 加模板匹配或 Aruco 标定板辅助定位,支持异形载具 |
| 参数散在各个类的 `const` 里 | 收成一份可配置的识别参数,现场可调 |
-–
## 附录:相关文件
| 文件 | 职责 |
|------|------|
| `Services/CameraService.cs` | 采集循环、帧缓冲复用、设备枚举 |
| `Services/ImageMarkScanner.cs` | 识别入口(DataMatrix + QR 合并)、BGRA→PNG、结果累积判重 |
| `Services/DataMatrixVoteDecoder.cs` | DataMatrix 投票解码(定位 + 多策略重试 + 逐字符计票) |
| `Services/ImageQrScanner.cs` | QR 多策略识别(整图缩放 → 网格切块 → OpenCV 定位兜底) |
| `Services/BoardTilt.cs` | 板面倾角估计与画面 ↔ 板面坐标换算 |
| `Services/QrPositionSorter.cs` | 行聚类与 8 种编号方向排序 |
| `Services/BoardGridMapper.cs` | 规格校验状态机与空码区推算 |
| `Services/ScanBoardSpec.cs` | 扫描板规格(行 × 列 → 期望码数) |
| `ViewModels/MainWindowViewModel.cs` | 自动检测窗口编排、多帧累积、位号/卡片/标记刷新 |