yovision/Brain/README.md

YoVision Brain 单路工程原型

T-017 提供一条可见、可重复的工程链路：单路 frame source → 匿名人员检测/fixture → track → 归一化多边形区域 → zone_entry 候选事实。它不是生产模型、不是 NVR，也没有 Brain→Bell transport。

环境

• Python 3.10.11
• NumPy 1.26.4
• OpenCV 4.9.0.80

本任务复用本机已验证版本；新环境显式安装：

python -m pip install -r Brain/requirements-demo.txt

本机冻结的是 opencv-python；同一环境只能安装一种提供 cv2 命名空间的 OpenCV wheel。不要同时安装标准、headless 和 contrib 变体。后续生产容器若改用 headless，必须在独立任务核对 wheel、许可证与完整回归，不能在本版本号下静默替换包名。

启动

无需摄像头的确定性合成回放：

python -m Brain.yovision_brain --source synthetic

打开 http://127.0.0.1:8090/brain-demo。合成人员框由 fixture 提供，页面和事件均显式标识，不得拿它证明模型效果。

使用真实流时，把完整 RTSP URL 写入仓库外绝对路径文件。推荐指向 Sense 管理的 MediaMTX path，而不是绕过 Sense 固化摄像头地址：

python -m Brain.yovision_brain --source stream --stream-url-file D:\private\brain-stream.url

URL 文件只允许一行、最多 4096 字节，服务不会在状态、页面和错误中返回其内容。演示服务只接受 127.0.0.1、localhost 或 ::1；没有暴露到局域网的开关。

真实流使用 OpenCV 内置 HOG/SVM 人员检测和轻量 centroid tracker，只验证可替换端口与区域链路。它不是 M3 生产模型，不能据此承诺召回率、误报率、GPU 容量或 16/128 路能力。

验证

python -m unittest discover -s Brain/tests -p "test_*.py" -v
python -m compileall -q Brain

单文件 UI 原型位于 docs/design/brain/index.html，可直接打开；此时使用明确标识的离线原型数据。由本地服务打开时，同一文件消费回环 API，并用临时页面 token 保护区域写入。

边界

• source_event_id 由 Brain 产生，平台 evt_ ULID 由 Bell 产生。
• 事件只保留在最多 100 项的内存环中；重启即丢失是刻意边界。
• T-018 冻结并实现身份映射、候选契约、持久 Outbox、HMAC、幂等和 Bell ingress。
• D:\OPC\silver_pose 保持独立，不是本模块的源码目录、运行依赖或模型来源路径。