# 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 |