first commit

README.md

@@ -0,0 +1,137 @@
+# macOS DETR 车辆动态打标
+
+这是一个参考 `../VideoPipe` 思路实现的 macOS 友好版 Python 项目：
+
+```text
+RTSP/HLS/本地文件源节点 -> DETR 车辆检测推理节点 -> OSD 画框节点 -> FastAPI 远程输出节点
+```
+
+本项目不直接移植 VideoPipe 的 C++、TensorRT、CUDA、GStreamer RTSP Server 工程，而是保留它的“源节点 → 推理节点 → OSD → 输出节点”思想，使用 Python、OpenCV、PyTorch、Transformers DETR 和 FastAPI，方便在 Mac mini / Apple Silicon 上运行。
+
+## 架构和推理流程
+
+```mermaid
+flowchart LR
+    A[devicelist.env 摄像头列表] --> B[DeviceManager 默认选择第一个设备]
+    B --> C[能力开放接口获取 RTSP 地址]
+    C --> D[OpenCV VideoCapture 读取视频流]
+    D --> E[StreamWorker 抽帧]
+    E --> F[DetrVehicleDetector 车辆检测]
+    F --> G[OpenCV OSD 画框]
+    G --> H[FastAPI MJPEG /video]
+    G --> I[WebSocket /ws/detections]
+    H --> J[浏览器动态打标画面]
+    I --> J
+```
+
+```mermaid
+flowchart TD
+    A[读取一帧 BGR 图像] --> B{是否达到 FRAME_SKIP}
+    B -- 否 --> F[复用上一轮检测结果]
+    B -- 是 --> C[转换为 RGB]
+    C --> D[Transformers ImageProcessor 预处理]
+    D --> E[PyTorch DETR 推理]
+    E --> G[按 DETR_CONFIDENCE 过滤车辆类别]
+    F --> H[绘制检测框和标签]
+    G --> H
+    H --> I[JPEG 编码]
+    I --> J[FastAPI 输出到远程浏览器]
+```
+
+## 安装
+
+```bash
+python3 -m venv .venv
+source .venv/bin/activate
+pip install -r requirements.txt
+```
+
+## 配置
+
+视频流地址通过环境变量传入，不要把 RTSP/HLS token 写进代码或文档。
+
+```bash
+export STREAM_URL='rtsp://你的摄像头或视频流地址'
+export DETR_CONFIDENCE=0.6
+export FRAME_SKIP=5
+```
+
+可选配置：
+
+```bash
+export DETR_MODEL='facebook/detr-resnet-50'
+export JPEG_QUALITY=80
+export RESIZE_WIDTH=960
+export VEHICLE_LABELS='car,motorcycle,bus,truck,bicycle'
+```
+
+配置说明：
+
+- `STREAM_URL`：RTSP、HLS 或本地视频文件路径，必填。
+- `DETR_CONFIDENCE`：检测置信度阈值，默认 `0.6`。
+- `FRAME_SKIP`：每隔多少帧做一次 DETR 推理，默认 `3`。数值越大，负载越低。
+- `RESIZE_WIDTH`：可选，设置后会按宽度等比缩小视频帧，降低 Mac mini 压力。
+- `VEHICLE_LABELS`：需要保留的 COCO 车辆类别。
+
+## 运行
+
+```bash
+uvicorn app.main:app --host 0.0.0.0 --port 8000
+```
+
+本机访问：
+
+```text
+http://127.0.0.1:8000
+```
+
+局域网远端访问：
+
+```text
+http://<Mac-IP>:8000
+```
+
+## 接口
+
+- `GET /`：中文浏览器看板。
+- `GET /video`：MJPEG 动态打标视频流。
+- `GET /detections`：最近一帧检测结果 JSON。
+- `GET /status`：运行状态、模型、设备、帧号、FPS。
+- `WS /ws/detections`：实时推送检测元数据。
+
+## RTSP 和 HLS 选择
+
+建议优先使用 RTSP，实时性更好。HLS `.m3u8` 通常更稳定，但会有几秒到十几秒延迟。
+
+OpenCV 需要带 FFmpeg 支持才能打开很多 RTSP/HLS 地址。如果无法打开远端流，可以先用本地视频文件验证项目，再考虑增加 PyAV 或 ffmpeg-python 输入后端。
+
+## macOS 远端访问检查
+
+如果其他机器访问不到页面，检查 macOS 防火墙，并确认服务监听在 `0.0.0.0`。
+
+```bash
+curl http://127.0.0.1:8000/status
+curl http://<Mac-IP>:8000/status
+lsof -i :8000
+```
+
+## 性能建议
+
+DETR 原版模型较重。Mac mini 上建议先这样跑：
+
+```bash
+export FRAME_SKIP=5
+export RESIZE_WIDTH=960
+```
+
+Apple Silicon 上会优先使用 PyTorch MPS；不可用时自动回退到 CPU。
+
+## 与 VideoPipe 的对应关系
+
+| VideoPipe 概念 | 本项目实现 |
+| --- | --- |
+| 源节点 | `StreamWorker` 中的 OpenCV `VideoCapture` |
+| 推理节点 | `DetrVehicleDetector` |
+| OSD 节点 | `StreamWorker._draw()` |
+| 输出节点 | FastAPI `/video`、`/detections`、`/ws/detections` |
+| 分析看板 | 浏览器中文 Dashboard |