OrangePi3588Media/FaceRecognition_SchemeB.md

人脸识别方案 B（ai_face_det + ai_face_recog）设计文档

目标：在现有 Graph(DAG)+Plugin Node 框架中，实现“有人脸库，可识别具体姓名/陌生人”。

约束：

• 插件化接入：新能力以 Node 插件形式加入 pipeline；不改动主业务流程即可启用/禁用。
• 与现有 publish 对 Frame::user_meta 的使用不冲突。
• 运行平台：RK3588（RKNN/NPU 优先），CPU 负责检索与业务逻辑。

---

1. 总体架构

1.1 现有框架要点（与本方案的衔接）

• Node 插件接口：INode（Init/Start/Process/Stop/UpdateConfig），通过 REGISTER_NODE 导出符号加载。
• 数据承载：Frame 内含图像数据（DMA/CPU）以及元数据：
  • frame->det：当前用于通用检测（DetectionResult）
  • frame->user_meta：扩展元数据（当前 publish 会写入编码包 meta）
• 推理：AiScheduler 支持 RKNN 模型加载与推理（可复用）。

1.2 方案 B 的节点拆分

新增两个 Filter 插件：

1. ai_face_det：人脸检测（可选输出关键点）

• 输入：RGB/BGR/NV12（根据你的 preprocess 输出）
• 输出：人脸框列表（可含 5 点关键点）、检测置信度

2. ai_face_recog：人脸对齐/裁剪 + 特征提取 + 人脸库检索 + 陌生人判定

• 输入：原始 Frame + ai_face_det 的检测结果
• 输出：识别结果（person_id/name/similarity/unknown）、可选把“姓名”写回可视化/告警侧

推荐拓扑：

[input_*] → [preprocess] → [ai_face_det] → [ai_face_recog] → [osd/alarm/publish/storage]

---

2. 数据与元数据协议（关键设计点）

2.1 为什么不直接复用 Frame::user_meta

当前 publish 节点会写 frame->user_meta（编码包 meta）。如果 ai_face_* 也直接写同一字段，会出现覆盖/冲突。

2.2 推荐的元数据承载方式（二选一）

选项 1（推荐，长期干净）：扩展 Frame 结构新增专用字段，例如：

• std::shared_ptr<FaceDetResult> face_det;
• std::shared_ptr<FaceRecogResult> face_recog;

优点：不与 user_meta 冲突，类型清晰，插件协作简单。

选项 2（兼容性强，侵入更小）：引入“MetaBundle”统一承载多类 meta，并把 Frame::user_meta 变成 bundle。

• user_meta 保存 std::shared_ptr<MetaBundle>，由 bundle 内部维护多个 typed slot（例如 publish_meta、face_meta…）。

优点：不新增 Frame 字段；缺点：需要先统一改造现有写 user_meta 的插件（至少 publish/alarm）。

本文后续描述以 选项 1 为主（更直观）。

2.3 FaceDetResult 数据结构（建议）

• faces[]：每个元素包含
  • bbox（x,y,w,h，图像坐标）
  • score
  • landmarks[5]（可选：左眼/右眼/鼻尖/左嘴角/右嘴角）
  • track_id（可选，后续可加跟踪）

2.4 FaceRecogResult 数据结构（建议）

• items[]：每个元素与一个人脸对应
  • bbox
  • best_person_id / best_name / best_sim
  • unknown（bool）
  • second_sim（可选，用于 margin 判定/调试）
  • embedding（可选：用于注册/调试；生产可关闭以省内存）

---

3. 算法与模型选型

3.1 检测模型（ai_face_det）

推荐轻量：SCRFD/RetinaFace 类人脸检测（可带 5 点）。

• 输入分辨率：320/640 任选（权衡精度与速度）
• 输出：bbox + score +（可选）5 点

3.2 特征模型（ai_face_recog）

推荐：ArcFace 系列轻量 backbone（MobileFaceNet 等）。

• 输入：112x112 aligned face
• 输出：128D 或 512D embedding
• 后处理：L2 normalize

3.3 相似度与陌生人判定

• 相似度：cosine（归一化后点积）
• 判定规则建议：
  • top1_sim >= T_accept 且（可选）top1_sim - top2_sim >= T_margin → 识别为该人
  • 否则 unknown

阈值需要按你的数据集标定（不同模型差别大），但架构层支持动态配置。

---

4. 人脸库（Gallery）设计

4.1 存储形态

建议分两层：

• 内存索引：运行时检索用（向量矩阵 + person 映射）
• 持久化存储：用于重启恢复/管理

持久化方案：

1. SQLite（推荐）：

   • person(id, name, created_at, updated_at, extra_json)
   • embedding(person_id, emb BLOB, normed, created_at)

2. 文件（简化版）：

   • gallery.bin（向量）+ gallery.json（person 映射）

4.2 多样本策略

• 每人保存 N 个样本 embedding（建议 3~10）。
• 运行时维护 centroid（平均向量再归一化）提高稳定性；检索可先比 centroid，再必要时比多样本。

4.3 检索实现

• 小库（≤几千人）：CPU 暴力点积足够。
• 大库（≥几万人）：再考虑 ANN（HNSW/Faiss），属于后续优化，不影响方案 B 的接口。

---

5. 两个节点的职责、接口与配置

5.1 ai_face_det（插件）

职责：

• 从 Frame 获取图像（必要时做色彩/resize）
• 调用 AiScheduler 推理检测模型
• 生成 FaceDetResult 写入 frame->face_det

配置建议（示例）

{
  "id": "face_det",
  "type": "ai_face_det",
  "role": "filter",
  "enable": true,
  "model_path": "/models/scrfd_640.rknn",
  "conf": 0.6,
  "nms": 0.4,
  "max_faces": 10,
  "output_landmarks": true,
  "input_format": "rgb" 
}

5.2 ai_face_recog（插件）

职责：

• 读取 frame->face_det
• 对每个 face：
  • （可选）按 5 点对齐（affine）
  • crop/resize 到识别模型输入
  • AiScheduler 推理得到 embedding，并 L2 normalize
  • 在人脸库检索，输出 best match 或 unknown
• 写入 frame->face_recog

配置建议（示例）

{
  "id": "face_recog",
  "type": "ai_face_recog",
  "role": "filter",
  "enable": true,
  "model_path": "/models/arcface_112.rknn",
  "gallery": {
    "backend": "sqlite",
    "path": "/data/face_gallery.db",
    "load_on_start": true,
    "cache_in_memory": true
  },
  "threshold": {
    "accept": 0.45,
    "margin": 0.05
  },
  "max_faces": 10,
  "align": true,
  "emit_embedding": false
}

---

6. 与 OSD / Alarm / Publish 的集成策略

6.1 OSD 显示姓名

现状：osd 只读 frame->det 并通过 cls_id → labels 显示类别名，不支持动态姓名。

推荐方案：

• 扩展 osd：若 frame->face_recog 存在，则在 bbox 处绘制 name(sim)；否则保持原逻辑。
• 或新增 osd_face 插件专门画人脸识别结果（与原 osd 并存）。

6.2 Alarm 规则与上报

推荐：在 alarm 中新增一种事件源：

• 读取 frame->face_recog，按规则触发（例如：出现黑名单人员、陌生人出现、某人出现次数/停留时间）。

6.3 Publish/Storage

• 与人脸识别无强耦合：只要不覆盖 user_meta，推流/录像可照常工作。

---

7. 性能与线程模型建议

• ai_face_det 和 ai_face_recog 都是 filter 节点，由 GraphMgr 驱动 Process(frame)。
• 推理层复用 AiScheduler（其内部对每个 model context 有互斥保护），可减少重复加载。
• 关键优化点：
  • 尽量在 preprocess 输出 RGB/BGR，避免在两个节点重复色彩转换。
  • 对齐与裁剪尽量复用 CPU SIMD 或 RGA（若你已有 RGA 路径）。
  • 检索使用批量点积（向量矩阵乘），人数不大时可用简单循环即可。

---

8. 一步步实现计划（后续按此执行）

你确认开始开发后，我们将严格按以下步骤逐步实现与验证。

Step 0：确定元数据承载方式（必须先定）

• 选择“Frame 新字段（face_det/face_recog）”或“MetaBundle”。
• 若选择新字段：需要同步更新相关 include、序列化/metrics（如有）以及 OSD/Alarm 读取逻辑。

Step 1：新增公共头文件与数据结构

• 定义 FaceDetResult / FaceRecogResult（include 目录下）。

Step 2：实现插件 ai_face_det

• CMake 加入新插件目标
• 使用 AiScheduler 加载/推理检测模型
• 输出 FaceDetResult

Step 3：实现插件 ai_face_recog

• 读取 FaceDetResult
• 对齐/裁剪/推理/归一化
• 实现 Gallery：SQLite 或文件（先做最简单可用版本）
• 输出 FaceRecogResult

Step 4：OSD/Alarm 接入（最小可用）

• OSD：显示 name/unknown
• Alarm：支持“陌生人出现/指定人员出现”触发

Step 5：配置与热更新

• UpdateConfig 支持阈值、gallery reload 等

Step 6：验证

• 使用样例视频/RTSP 流验证：识别准确率、误认率、性能、内存