# SyringeMeter

从摄像头画面，到稳定读数与可追溯的记录。

一个在本地 CPU 上运行的针筒视觉测量应用。定位、方向、量程和活塞位置共同生成连续容量读数，再接上实时曲线和由用户控制的 CSV 记录。这份案例记录了一个视觉原型如何走到桌面交互、失败处理与 Windows 分发。

[网站原文](https://zzzxc.com/projects/syringe-meter)

## 一次检测，怎样变成连续测量？

起点是一支出现在摄像头里的针筒。它可能倾斜，活塞会移动，颜色标记也可能暂时看不清。检测框只能告诉系统目标在哪里；要回答“现在还有多少容量”，还需要确认方向、量程与活塞位置，并让这些证据落在同一帧、同一套坐标里。

当读数走进桌面应用，问题也随之扩大：界面要保持响应，曲线要跟上测量，开始和停止必须有明确含义，异常退出时也不能把记录状态留给用户猜测。SyringeMeter 因而围绕从画面到记录的整条工作流展开。

## 先统一方向，再计算容量

系统先用 YOLO OBB 定位带有旋转角度的针筒区域，再把这块画面转换成方向统一的局部测量区域。针筒在摄像头里转动时，后续判断仍然可以使用一致的坐标。

在这个区域里，绿色标记提供方向，双红色量程线给出测量范围，活塞位置提供当前容量的依据。只有这些条件共同成立，才会产生连续容量结果，再经过时间稳定处理，进入界面的读数和曲线。

- 目标定位：确定针筒在画面中的位置和角度。
- 局部测量：将方向、量程和活塞放进统一坐标。
- 结果展示：把有效容量转换成可持续观察的读数与曲线。

## 稳定读数，也要诚实地失效

平滑可以减轻跳动，也可能掩盖丢失的证据。如果当前帧的颜色标记、量程锚点或上游判断无效，应用会明确显示没有有效读数，不继续沿用上一帧容量。这样，屏幕上的稳定仍然对应眼前的画面。

运行时把不同的数据分开处理。子进程独占摄像头、模型、视觉测量和 CSV 写入；父进程负责 Qt 界面与用户操作。视频通道只保留最新画面，测量样本则使用有界无损通道，让显示的流畅性与记录的完整性各自有明确的处理方式。

## 每一段记录，都由用户明确开始

打开摄像头不等于开始保存数据。只有点击 Start，应用才会创建记录会话并写入标量 CSV。产品不保存摄像头图片或视频，留下的是测量数据，以及能与这次操作对应的时间记录。

Start、Stop、Reset 和退出命令都在处理帧的边界生效。Reset 会结束当前会话、清空曲线并回到 READY；下一次显式 Start 才创建新的 CSV，从 0 ms 重新计时。一次重置因此有清楚的前后边界。

- 观看：实时查看容量与曲线，不自动开始 CSV 记录。
- 记录：点击 Start，开启一次独立的测量会话。
- 重置：关闭当前会话，清空曲线，等待下一次 Start。

## 把原型交付成可以安装的应用

项目把摄像头、连续测量、Qt 交互、曲线和 CSV 串成了端到端链路，并为单元逻辑、集成行为、界面、进程和记录建立测试。接口约定与文档也进入验证范围，便于区分代码行为、测试结果和真实设备证据。

v0.2.0 提供 Windows x64 CPU-only 安装程序和便携 ZIP，由 GitHub Actions 配合 PyInstaller 与 Inno Setup 构建。发布任务对两份分发产物执行校验；模型不进入 Git 历史，只经获批的 Release 链路，在 SHA-256 校验后装入产物。

这些工作建立了可重复的构建与分发路径。安装包在目标机器上的安装、摄像头与真实推理，需要单独完成硬件验证，不能由自动化构建结果替代。

## 我的角色：定义系统应该如何成立

这是我主导的个人工程项目。我负责定义问题、产品目标、测量语义、失败边界和验收标准，并推动算法、运行时、桌面交互与 Windows 分发形成完整工作流。最终发布决策也由我作出。

AI 工具参与实现、重构、测试和文档整理。我持续判断哪些行为值得实现、哪些证据足以接受，以及哪些结果还必须回到真实硬件上确认。这个项目也是一次 AI-native 协作实践：让迭代最终收敛成行为明确、结果可验证、责任清楚的系统。

## 当前证据与适用边界

SyringeMeter 是受控场景中的工程 MVP，当前展示围绕带标记的单支针筒展开。它不是医疗设备，不宣称适用于任意针筒、光照或部署环境。

本页视频来自 macOS Python 源码运行，只证明该次演示中可见的行为。v0.2.0 的 Windows 构建和 Release 已完成自动化验证；当前 Windows 包的安装、摄像头和真实推理尚未重新完成目标机实测。源码、自动化检查、演示与安装包验证分别记录，最新进展以项目验证状态为准。

## 从画面到记录

### 采集画面

摄像头提供当前帧，在本地处理。

### 定位针筒

YOLO OBB 找到目标位置与旋转角度。

### 统一坐标

转换局部画面，建立一致的测量方向。

### 读取证据

结合绿色方向标记、双红线量程与活塞位置。

### 稳定容量

质量检查与时间稳定共同决定有效读数。

### 显示与记录

实时读数和曲线；显式开始后写入标量 CSV。

## 继续查看项目

- [源码与项目文档](https://github.com/agenticnoob/syringe-meter)
- [Windows v0.2.0 发布包](https://github.com/agenticnoob/syringe-meter/releases/tag/v0.2.0)
- [当前验证状态](https://github.com/agenticnoob/syringe-meter/blob/main/docs/status/current.yaml)

[内容目录](https://zzzxc.com/agent/zh/index.md)