# C#摄像头识图开发

**URL:** <https://lifes.fun/t/topic/182>\
**Category:** 开发调优\
**Tags:** csharp\
**Created:** [2026 年9 月 30 日 01:26 UTC](https://lifes.fun/t/topic/182 "2026-09-30T01:26:34Z")\
**Posts on this page:** 1\
**Page:** 1

<div class="post-metadata">

**Author:** ![outlaw\_zhangsan](https://lifes.fun/letter_avatar_proxy/v4/letter/o/958977/32.png) [@outlaw\_zhangsan](https://lifes.fun/u/outlaw_zhangsan)\
**Post date:** [2026 年9 月 30 日 01:26 UTC](https://lifes.fun/t/topic/182/1 "2026-09-30T01:26:35Z")

</div>

# 摄像头扫码工具：整板小码是怎么一次读全的

\> 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` | 自动检测窗口编排、多帧累积、位号/卡片/标记刷新 |
