# rebucca

**Repository Path**: fwhome/rebucca

## Basic Information

- **Project Name**: rebucca
- **Description**: 基于北小菜 Rebucca（多路视频接入与智能布控分析平台）深度定制的人员 ReID 落地系统： 摄像头拍到人 → 自动建档 → 跨摄像头归并 → 轨迹照片证据链 → 人工复核闭环。
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 1
- **Created**: 2026-08-28
- **Last Updated**: 2026-08-28

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Rebucca 定制版 —— 人员身份识别与轨迹跟踪平台

> 基于北小菜 Rebucca（多路视频接入与智能布控分析平台）深度定制的**人员 ReID 落地系统**：
> 摄像头拍到人 → 自动建档 → 跨摄像头归并 → 轨迹照片证据链 → 人工复核闭环。

| 链接 | |
|------|--|
| 上游项目 | [北小菜 Rebucca](https://gitee.com/Vanishi/rebucca)（MIT License，保留全部上游能力） |
| 本定制仓库 | https://gitee.com/ericzhangeric/rebucca.git |
| 交接文档 | `HANDOFF.md`（当前运行状态 / 坑位清单 / 待办，**接手必读**） |

**上游保留能力**：RTSP / GB28181 接入、ZLMediaKit 转发、YOLO 小模型检测、大模型复核、多边形布控（区域入侵/越线/方向/密度/滞留/计数）、报警管理、录像、ONVIF 发现、多语言。

---

## 一、定制核心：人员身份识别与轨迹跟踪

### 1.1 识别链路

```
RTSP 拉流（ffmpeg QSV 硬解，失败自动回退 OpenCV 软解）
  → MOG2 运动门控 + 周期强制检测（3s，防静止目标被背景吸收）
  → YOLO 检测（OpenVINO，共享推理池）
  → OSNet ReID 嵌入（512 维，仅对连续命中 ≥3 帧的 track，过滤孤立误检）
  → PersonMatcher 人工底库（thr 0.55，命中显示姓名）
  → StrangerMatcher 陌生人自动建档（thr 0.55，未命中自动建 ST-xxxx）
      · 单帧内身份唯一（exclude_ids，同帧多人不并档）
      · 特征 EMA 样本封顶 64（防"平均向量黑洞"）
      · 自动合并分裂身份（sim≥0.85）+ 人工复核黑名单（禁自动合并）
  → 事件落库（每 10s 限流，含归一化 box + 人像截图）
```

### 1.2 关键阈值（业务命脉，改动前先读 HANDOFF §2.1）

| 阈值 | 值 | 依据 |
|---|---|---|
| 陌生人主匹配 | **0.65** | MSMT17 训练版 OSNet 实测校准（异人分布上移，0.55 误并 70% 观测） |
| 特征更新（EMA） | sim ≥ **0.70** 才更新 | 防误收样本把特征平均化（滚雪球事故教训） |
| 自动合并 | sim ≥ **0.85** | 异人相似度可波动至 ~0.65，0.85 以上才安全 |
| track 关联嵌入 | 0.60 / 兜底 **0.68** | 新模型分布上移后再校准 |
| 人工底库匹配 | **0.65**（与主匹配对齐） | 0.5 会把临界陌生人误标成已知姓名 |
| track 连续命中 | ≥ **3 帧** | 孤立单帧检出多为墙面/杂物误检 |
| 最小人像 | 宽 ≥36 且高 ≥72 px | 过小 crop 的 ReID 无区分能力 |
| 图像质量门控 | mean 40~238 且 std ≥14 | 过曝帧（曾致 2F 全白）不进身份链路 |
| 人脸否决 | face sim ≤ **0.20** 否决 | 可选通道：body 命中但人脸强烈不符时防误并 |

### 1.3 人工复核闭环（HITL）

在 **陌生人员 / 识别实况** 页的详情弹窗中：

1. **轨迹照片证据链**：跨机位轨迹链（每机位缩略图 + 时间 + 次数）+ 出现时间线（每条事件带人像截图）
2. **相似身份对比**：自动列出 embedding 最相似的其他身份（并排照片 + 相似度红绿标色）
3. **标记**：
   - `同一人(合并)` → 记录标注并走合并流程
   - `不是同一人` → 落库 `av_stranger_review` 并进匹配黑名单，**系统永不再自动合并这对身份**
4. **规则验证报告**：统计"系统判同人（sim≥0.55）但人工判不同"的误并案例数与清单——即识别规则的人工实测准确率
5. **事件级拆分**：`openStrangerMoveEvent` 把单条出现记录移到另一身份（Split）

---

## 二、部署与运行（Windows 10 / Intel Arc A770 实机）

```powershell
# 一键启停
F:\rebucca\start.bat    # Django(10001) + ZLM 检查 + 按默认楼层启动分析
F:\rebucca\stop.bat     # 全部停止

# 重启分析（改 app/*.py 后必须跑 —— 热重载会杀掉全部分析子进程）
.venv\Scripts\python.exe -X utf8 restart_analysis.py                # 按 config.json analysisFloors
.venv\Scripts\python.exe -X utf8 restart_analysis.py --floors 4F    # 指定楼层
.venv\Scripts\python.exe stop_analysis.py                           # 只停分析
```

- 访问：`http://127.0.0.1:10001`（admin / admin888）
- **全新部署**：`copy rebucca_seed.sqlite3 rebucca.sqlite3`（种子库含全部表结构、默认算法与管理员账号，不含任何业务/隐私数据；正式库 rebucca.sqlite3 已 gitignore）
- **默认楼层**：`config.json` 的 `analysisFloors`（如 `["4F"]`），在「分析控制」页勾选保存
- **解码模式**：默认优先 ffmpeg QSV 硬解（Intel Arc 显存），失败自动回退软解；
  设环境变量 `REBUCCA_QSV_DECODE=0` 强制软解（驱动不稳/蓝屏排查时用）
- 数据库：`rebucca.sqlite3`（**含人员轨迹与摄像头凭据，已 gitignore，严禁入库**）

## 三、页面导航

| 页面 | 路径 | 说明 |
|---|---|---|
| 控制面板 | `/` | 总览 |
| 视频管理 | `/stream/index` | 摄像头 CRUD |
| 实时画面 | `/stream/online` | 楼层懒加载快照墙 |
| 布控管理 | `/control/index` | 区域/规则/报警配置 |
| 人员识别 | `/person/index` | 人工底库录入（照片→embedding） |
| **陌生人员** | `/person/strangers` | 自动身份库：头像列表 + 详情（轨迹链/时间线/复核） |
| **识别实况** | `/person/reid` | 快照墙（楼层懒加载）+ 实时事件流 + 人工复核 |
| **分析控制** | `/analysis/index` | 楼层分组批量启停 + 默认楼层持久化 |
| 报警管理 | `/alarm/index` | 报警检索 |
| 启动配置 | `/system/config` | 端口/流媒体/分析参数 |

## 四、主要 API（身份相关）

```
GET  /person/openStrangerIndex          身份列表（带头像）
GET  /person/openStrangerDetail         详情：history(带box/图) + trajectory(轨迹链) + 代表图
GET  /person/openStrangerEvents         实时事件流（前端轮询）
POST /person/openStrangerConfirm        人工确认身份
POST /person/openStrangerMerge          合并两身份
POST /person/openStrangerDel / Clear   删除 / 清空
GET  /person/openStrangerSimilar        相似身份 Top-5（人工对比）
POST /person/openStrangerReview         人工标记 same / different（different 进黑名单）
GET  /person/openStrangerReviewStats    复核统计 + 规则误并清单
POST /person/openStrangerMoveEvent      事件级拆分（Split）
GET  /analysis/openFloors               楼层分组 + 各路状态
POST /analysis/saveFloors               保存默认楼层
POST /analysis/openStart / openStop     单路启停
GET  /analysis/openStatus               运行状态（含 decode_mode=qsv/opencv）
```

## 五、代码结构（定制重点）

```
app/analysis/
  frames.py            帧源：QSV 硬解管道（ffprobe 探测+重试）→ 自动回退软解
  pipeline.py          单路分析主流程：门控/检测/跟踪/身份/快照/布控后处理
  tracker.py           IoU+嵌入联合关联（低帧率嵌入兜底 emb_only=0.60）
  stranger_matcher.py  陌生人自动建档/归并/黑名单/EMA 封顶
  person_matcher.py    人工底库匹配
  manager.py           分析生命周期管理（子进程 spawn）
  process_worker.py    子进程入口（日志 log/pipeline_<id>.log）
app/views/
  PersonView.py        身份/轨迹/复核 全部 API
  AnalysisView.py      分析控制/楼层配置
  NvrView.py           快照（QSV，非 shell 模式防进程残留）
templates/app/person/  strangers.html / reid.html（照片证据链 + 复核 UI）
templates/app/analysis/index.html  分析控制页
restart_analysis.py    重启脚本（--floors / 默认楼层）
HANDOFF.md             交接文档（状态/坑位/待办）
```

## 六、已知问题与注意事项

1. **2F 摄像头过曝**（画面均值 250/255 几乎全白）——摄像头侧需调宽动态/背光补偿；已有质量门控防护，但根治要现场调机
2. **QSV 多路解码曾触发蓝屏**（0x3B ×3，Intel 驱动 32.0.101.8864）——已切软解；升级驱动后删环境变量 `REBUCCA_QSV_DECODE` 恢复硬解
3. OSNet 整体人体 ReID 对**同款着装+相似体型**区分度有限（灰带 0.55~0.62）——靠人工复核兜底；长期可换 CLIP-ReID 类模型或加人脸辅助
4. YOLO 偶发墙面/水印误检——已用尺寸门槛 + track 连续性 + 面积择优三道防线压制，残余垃圾身份用页面人工删除
5. 改 `app/*.py` 必跑 `restart_analysis.py`（热重载杀子进程）

---

## 上游原版能力文档

多路视频接入与智能布控分析平台（GB28181 / RTSP、YOLO 检测、OpenAI 兼容大模型复核、多边形布控与结构化报警）。

| 链接 | |
|------|--|
| 官网 | https://www.yuturuishi.com |
| 上游 Gitee | https://gitee.com/Vanishi/rebucca |
| 上游 GitHub | https://github.com/beixiaocai/rebucca |
| 作者 | 北小菜 · [哔哩哔哩](https://space.bilibili.com/487906612) |

**开源协议：** MIT License。环境要求：Python 3.10+、FFmpeg、ZLMediaKit（`zlm/` 随仓库分发，Linux 需进 `zlm/bin.x86.gcc9.4` 或 `zlm/bin.arm.gcc9.4` 确认 `./rebucca_zlm` 可执行）。