# smart_frame

**Repository Path**: bloomf/smart_frame

## Basic Information

- **Project Name**: smart_frame
- **Description**: 魔法电子相框。相框中是静态图片，携带一个摄像头。当用户对着相片微笑时，相片中的人物会给于反馈（同样微笑或者其他行为）。本质上通过表情或者动作驱动相片做对应变动。

- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-04-06
- **Last Updated**: 2026-04-09

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 智能情感交互电子相框

基于 dlib 人脸特征点检测的实时表情驱动电子相框系统。通过捕捉用户面部表情（微笑强度），动态切换对应的表情帧，实现有趣的情感交互体验。

![Demo](docs/demo.png)

## 使用场景

### 产品愿景

想象这样一个场景：

> 你将心爱的照片上传到电子相册，选择想要的表情风格——微笑、惊喜、或是其他情绪。系统自动生成一系列表情过渡图片，让照片中的人物"活"了起来。
>
> 当你坐在相框前，展露笑容时，相框里的人也跟着微笑；当你安静阅读时，TA也恢复平静。这种无声的情感交流，仿佛照片中的人真的在陪伴着你，为你提供温暖的情绪价值。

### 应用场景

- **桌面陪伴**: 放置在办公桌或床头，提供情感陪伴
- **情绪调节**: 通过表情互动，缓解压力和孤独感
- **创意展示**: 用于咖啡厅、展厅等场所的互动展示
- **特殊关怀**: 为独居老人或留守儿童提供情感寄托

### 当前阶段

**原型机 v1.0** - 核心功能验证完成

| 功能 | 状态 | 说明 |
|------|------|------|
| 微笑检测 | ✅ 完成 | 实时识别微笑强度 (0.0-1.0) |
| 表情跟随 | ✅ 完成 | 照片表情随人脸实时变化 |
| 平滑过渡 | ✅ 完成 | 57 帧渐变序列，自然流畅 |
| 多表情支持 | 🚧 规划中 | 未来支持生气、惊讶等多种表情 |
| AI 自动生成 | 🚧 规划中 | 未来接入图像生成 API |

**当前使用方式**: 用户需手工准备 3 张关键表情帧（中性、微笑、大笑），可通过 AI 绘图工具生成。

## 功能特性

- **实时表情捕捉**: 基于 dlib 68 点人脸特征点检测，精确识别微笑强度（0.0-1.0）
- **光流跟踪优化**: 采用稀疏光流算法，将表情识别速度提升 11 倍
- **平滑表情过渡**: 57 帧预生成表情序列，配合可调平滑系数，实现自然的表情变化
- **双输入模式**: 支持摄像头实时采集和视频文件循环播放
- **双窗口显示**: 主表情窗口 + 摄像头画中画窗口
- **性能监控**: 实时显示 FPS、微笑强度、表情帧索引

## 技术栈

| 技术 | 版本 | 用途 |
|------|------|------|
| **dlib** | 19.10+ | 人脸检测 + 68 点特征点预测 |
| **OpenCV** | 4.5+ | 图像处理、光流跟踪、显示 |
| **nlohmann/json** | 3.10+ | 配置文件解析 |
| **CMake** | 3.15+ | 构建系统 |
| **C++** | 17 | 开发语言 |

## 快速开始

### 1. 依赖安装

```bash
# Ubuntu/Debian
sudo apt update
sudo apt install -y \
    build-essential cmake \
    libopencv-dev \
    libdlib-dev \
    nlohmann-json3-dev \
    libgtest-dev
```

### 2. 下载模型文件

下载 dlib 68 点人脸特征点检测模型：

| 方式 | 链接 |
|------|------|
| 百度网盘 | https://pan.baidu.com/s/1vI9ElguPbRTVXr51ADu6wg?pwd=linu (提取码: linu) |
| 官方源 | http://dlib.net/files/shape_predictor_68_face_landmarks.dat.bz2 |

下载后解压并将 `shape_predictor_68_face_landmarks.dat` 放在项目根目录。

### 3. 编译

```bash
mkdir build && cd build
cmake .. -DCMAKE_BUILD_TYPE=Release
make -j$(nproc)
```

### 4. 准备表情帧

用户只需准备 **3 张关键帧**（不笑、微笑、大笑），程序会自动生成中间过渡帧。

**准备关键帧：**
```bash
# 创建关键帧目录
mkdir -p frames/keyframes

# 放入 3 张关键表情图片（命名无严格要求，建议使用有意义的文件名）：
# - neutral.png  (中性表情)
# - smile.png    (微笑)
# - laugh.png    (大笑)
```

**生成中间帧：**
```bash
# 使用 Python 脚本生成 57 帧（每两张关键帧间插入 19 帧）
python3 scripts/preprocess.py frames/keyframes frames/character_002 -n 19 -p expression

# 或生成 29 帧（每两张关键帧间插入 9 帧）
python3 scripts/preprocess.py frames/keyframes frames/character_002 -n 9 -p expression
```

参数说明：
- `-n` 每段关键帧之间的插值数量
- `-p` 输出文件名前缀（默认 `frame`，建议使用 `expression`）

生成完成后，更新 `config.json` 中的 `paths.frames_dir` 路径为 `frames/character_002`。

### 5. 运行

```bash
# 使用默认配置 (config.json)
./build/bin/smart_frame

# 使用自定义配置
./build/bin/smart_frame my_config.json
```

按 `q` 或 `ESC` 退出程序。

## 配置说明

`config.json` 配置项：

```json
{
    "camera": {
        "video_file": "",           // 留空使用摄像头，或填写视频路径
        "device_id": 0,             // 摄像头设备ID
        "width": 640,
        "height": 480,
        "fps": 30
    },
    "expression": {
        "smooth_factor": 0.4,       // 表情跟随速度 (0.0-1.0)
        "smile_threshold": 0.15,     // 微笑检测阈值 (0.0-1.0)
        "face_lost_decay": 0.1,      // 人脸消失时表情回落速度 (0.0-1.0)
        "intensity_jump_threshold": 0.4, // 强度突变检测阈值
        "detection_interval": 6      // 人脸检测间隔（帧数）
    },
    "paths": {
        "frames_dir": "./frames/character_002_extended_59",
        "log_file": "./app.log"
    },
    "display": {
        "fullscreen": false,
        "pip_width": 240,           // 画中画宽度
        "pip_height": 180,          // 画中画高度
        "font_scale": 0.6
    }
}
```

### 表情参数说明

| 参数 | 范围 | 效果 | 建议值 |
|------|------|------|--------|
| `smooth_factor` | 0.1-0.6 | **表情跟随速度**：值越大反应越快，越小越平滑 | 0.3-0.4 |
| `smile_threshold` | 0.05-0.4 | **微笑检测灵敏度**：值越低越敏感 | 0.15-0.25 |
| `face_lost_decay` | 0.05-0.3 | **表情回落速度**：值越小回落越快 | 0.1-0.15 |
| `detection_interval` | 3-12 | **检测精度**：值越小越准确但越慢 | 6 |

### 调优建议

**问题：表情变化太慢**
- 增加 `smooth_factor` 到 0.5-0.6
- 增加 `face_lost_decay` 到 0.2

**问题：表情变化太快/抖动**
- 减少 `smooth_factor` 到 0.2-0.3
- 减少 `face_lost_decay` 到 0.05

**问题：容易误触发笑容**
- 增加 `smile_threshold` 到 0.25-0.35

**问题：笑容检测不灵敏**
- 减少 `smile_threshold` 到 0.1-0.15
- 减少 `detection_interval` 到 3-4
```

## 性能指标

| 指标 | 数值 |
|------|------|
| 帧率 | 20-25 FPS |
| 表情检测延迟 | ~200ms (dlib) / ~5ms (光流) |
| CPU 占用 | ~70% |
| 光流跟踪间隔 | 每 6 帧 |

## 项目结构

```
demo2/
├── CMakeLists.txt              # 主构建文件
├── config.json                 # 配置文件
├── src/                        # 源代码
│   ├── main.cpp                # 主入口
│   ├── camera/                 # 摄像头采集模块
│   ├── expression/             # 表情识别模块（dlib + 光流）
│   ├── renderer/               # 表情渲染模块
│   ├── ui/                     # UI 与配置模块
│   └── common/                 # 共享状态定义
├── tests/                      # 单元测试
├── tools/                      # 辅助工具
│   └── generate_intermediate_frames.cpp
├── docs/                       # 文档
│   └── plans/                  # 设计文档
└── frames/                     # 表情帧资源（不纳入版本控制）
```

## 表情识别算法

### 当前实现（临时方案）

系统采用**多特征融合算法**计算微笑强度，基于 dlib 68 点人脸特征点：

```cpp
微笑强度 = 3.0 × 嘴角上扬 + 0.5 × 嘴巴张开 + 0.15 × 笑眼程度

// 嘴角上扬计算（动态基线）
baseline = 前30帧的平均(嘴角中心Y - 鼻尖Y) / 嘴宽
lift = (baseline - 当前值) / (baseline × 0.3)

// 嘴巴张开
open = 上下唇距离 / 嘴宽

// 笑眼程度
eye_smile = (8.0 - 平均眼高) / 3.0
```

#### 性能优化策略

1. **动态基线学习**: 启动时采集30帧学习中性表情，避免硬编码阈值
2. **光流跟踪**: 每6帧使用dlib检测，中间帧用光流跟踪特征点（速度提升11倍）
3. **内容突变检测**: 通过帧差检测视频循环，自动重置跟踪状态
4. **平滑滤波**: 使用指数移动平均减少抖动

#### 当前方案的局限性

> ⚠️ **这是临时原型方案，准确性不高，不建议用于生产环境。**

| 问题 | 原因 |
|------|------|
| **误检测严重** | 基于几何距离的启发式算法，对不同人脸差异敏感 |
| **角度依赖** | 仅适用于正面人脸，侧脸时特征点相对位置变化大 |
| **光照敏感** | dlib检测在弱光或强光下性能下降 |
| **表情单一** | 只能检测微笑，无法识别愤怒、惊讶等复杂表情 |
| **个体差异** | 不同人的五官比例差异大，基线学习无法完全消除 |

### 改进建议

#### 短期改进（保持当前技术栈）

1. **增加更多特征**
   - 使用面部动作单元 (Action Units, AU)
   - 添加鱼尾纹检测（眼角皱纹）
   - 结合头部姿态估计

2. **自适应权重**
   - 根据检测置信度动态调整特征权重
   - 使用卡尔曼滤波替代简单的平滑

3. **多模态融合**
   - 结合语音情感识别
   - 添加心率检测（通过摄像头）

#### 长期方案（推荐）

| 方案 | 优点 | 缺点 | 推荐度 |
|------|------|------|--------|
| **深度学习模型** | 准确率高、泛化能力强 | 需要GPU、推理延迟高 | ⭐⭐⭐⭐⭐ |
| **MediaPipe Face Mesh** | 轻量级、跨平台、实时性好 | 精度略低于深度学习 | ⭐⭐⭐⭐⭐ |
| **云端API** | 无需本地计算资源 | 网络延迟、隐私问题 | ⭐⭐⭐ |

**推荐技术选型**：

```python
# 方案1: MediaPipe Face Mesh (推荐用于实时应用)
import mediapipe as mp
mp_face_mesh = mp.solutions.face_mesh
# 可直接提取表情特征，支持468个面部关键点

# 方案2: 预训练深度学习模型
# - OpenFace (AU识别)
# - AffectNet (表情分类)
# - DeepFace (轻量级表情识别)

# 方案3: 自定义轻量级CNN
# 基于MobileFaceNet微调表情分类任务
```

## 测试

```bash
cd build
ctest --output-on-failure
```

当前测试覆盖率：
- `test_camera_capture` - 摄像头采集测试
- `test_config_loader` - 配置加载测试
- `test_expression_recognizer` - 表情识别测试
- `test_expression_renderer` - 表情渲染测试
- `test_shared_state` - 共享状态测试
- `test_ui_manager` - UI 管理器测试

## 常见问题

### Q: 检测不到人脸？

检查以下几点：
1. 确认摄像头工作正常
2. 调整 `detection_interval` 为较小值（如 3-6）
3. 增大摄像头分辨率缩放比例（修改 `src/main.cpp` 中的 `scale_ratio`）
4. 确保光线充足

### Q: 表情变化太慢/太快？

调整 `expression.smooth_factor`：
- 增大（如 0.5-0.6）- 反应更快
- 减小（如 0.2-0.3）- 更平滑自然

### Q: 视频循环后表情不恢复？

已修复：通过帧差检测内容突变，自动重置跟踪状态。

## 开发路线图

- [x] dlib 人脸检测集成
- [x] 光流跟踪优化
- [x] 57 帧表情预生成
- [x] 摄像头/视频双输入模式
- [x] 可调平滑系数
- [x] 视频循环检测
- [ ] 多人脸支持
- [ ] 更多表情类型（生气、惊讶等）
- [ ] WebRTC 远程摄像头支持

## 许可证

MIT License

## 致谢

- [dlib](http://dlib.net/) - C++ 工具库，提供优秀的人脸检测算法
- [OpenCV](https://opencv.org/) - 计算机视觉库