local_web/README.md

# 本地 Web 版 · 手势识别

解决"浏览器调摄像头失败 / Hugging Face Static Space 没有 `*.hf.space` 域名"的问题。
后端（OpenCV）直接打开摄像头，浏览器只显示视频流和交互控制台，**全程无需任何授权**。

## 安装

```bash
python3 -m venv .venv && source .venv/bin/activate  # Windows: .venv\Scripts\activate
pip install -r requirements.txt
```

## 下载模型

`serve.py` 默认在脚本所在目录找 `model_quantized.onnx` + `config.json`，可也用 `--model-dir` 指定：

```bash
# 方式 A：从 HF 仓库下载到本目录
huggingface-cli download keytic/hand_gestures_onnx \
  --local-dir . \
  --include "model_quantized.onnx" "config.json"

# 方式 B：复用 workspace 里的 onnx_pub
# （直接把 onnx_pub 里的两个文件复制到本目录）
```

相册示例图：默认会自动到 `../static-space/examples/` 找，也可 `--examples-dir` 指定。

## 启动

```bash
python serve.py
# 浏览器打开 http://localhost:8000
```

常用参数：
```bash
python serve.py --camera 0 --interval-ms 300 --port 8000
```

## 工作原理

```
[摄像头] ──OpenCV──> [后端推理 (ONNX Runtime)]
                       │
                       ├── 稳定判定 + 触发交互动作（点赞/开关/相册/暂停）
                       ├── /video     MJPEG 视频流 ────────────> 浏览器
                       └── /state     JSON 状态 (~每 300ms 拉取) ──> 浏览器
```

**浏览器从不调用 `getUserMedia`**，所以没有授权问题、没有跨域、没有 *.hf.space 404。

## 手势动作映射

| 手势 | 动作 |
|------|------|
| 👍 like | 点赞 +1 |
| 👌 ok | 开关切换 |
| ✊ fist | 相册上一张 |
| 🖐️ palm | 相册下一张 |
| ✌️ peace | 暂停/恢复识别 |
| 🤘 rock | 重置点赞与日志 |

## Linux 系统注意事项

- 摄像头权限：当前用户需要在 `video` 组：`sudo usermod -aG video $USER` 然后重登。
- OpenCV 报错 `Cannot open camera`：检查设备路径（`ls /dev/video*`），必要时换 `--camera 1`。
- 无图形界面（headless）也能跑，浏览器在另一台机器上访问 `http://<服务器IP>:8000` 即可。