# Analog Gauge 隔离运行环境

`ethz-asl/analog_gauge_reader` 依赖 Python 3.8、Torch 2.0 和为 CPython 3.8
预编译的 MMCV 2.0 wheel，不能安全地安装进本项目的 Python 3.10 主环境。本目录是一个
独立的 uv project，只服务 `gauge.analog_reader@1` 子进程。

## 创建环境

运行：

```bash
bash server/gauge/worker/bootstrap.sh
```

脚本安装 uv 管理的 Python 3.8，并按照本目录的 `uv.lock` 创建 `.venv`。不会改动根目录
`.venv`。MMCV URL 是 Linux x86_64、CPython 3.8、Torch 2.0 CPU 的专用 wheel，因此
当前部署配置不支持其他平台。

## 进程协议

主进程由 `gauge.analog_reader@1` 自动启动 worker，无需手工常驻。worker 使用
`cmvr.external-worker/v1`：4 字节大端 JSON header 长度、JSON header，随后按
`blob_lengths` 顺序传输 raw blob。图像不做 base64 二次复制。

worker 启动后首先返回 `ready`；每个请求使用一个 JPEG/PNG blob，响应包含标量读数、
单位、耗时、诊断和可选 `annotated` blob。Ultralytics/MMOCR 和上游项目的 stdout 已被
重定向到 stderr，协议流单独持有启动时复制的 stdout FD，日志不会污染二进制帧。
worker 会先解析图片头并按 `--max-pixels` 检查 `width * height`，超限时不会创建临时
输入文件，也不会进入 Pillow/OpenCV 或上游 pipeline。

明确的“未检测到仪表、OCR 数字不足、椭圆拟合失败、未找到指针”属于业务无结果，返回
`no_result`。checkpoint 不兼容、依赖缺失和其他推理/部署异常返回相关联的 `failed`
response；帧本身损坏时无法继续可靠解析边界，进程会退出并由主框架在下一次请求时重建。

版本基线来自上游项目：Torch 2.0.0、Torchvision 0.15.1、MMCV 2.0.0、MMEngine
0.7.2、MMDetection 3.0.0、MMOCR 1.0.0、Ultralytics 8.0.66 和
scikit-learn 1.2.2。NumPy/OpenCV/SciPy 额外固定在仍支持 Python 3.8 且已知兼容的版本，
避免未来解析得到 NumPy 2 或停止支持 Python 3.8 的 wheel。Setuptools 固定为
75.3.2，因为旧版 Ultralytics 启动时仍会导入其中的 `pkg_resources`。