README_zh.md

# 微表情识别与检测

**中文文档** | [English](README.md)

基于 PyTorch 的端到端**微表情识别**（短片段）与**长视频微表情检测**框架，内置 Web 可视化平台。

支持数据集：CASME2 / SAMM / SMIC-HS / CAS(ME)³

---

## 快速开始

### 1. 配置环境

```bash
conda create -n me-env python=3.10
conda activate me-env

# GPU（CUDA 12.1）
conda install pytorch torchvision torchaudio pytorch-cuda=12.1 -c pytorch -c nvidia

# 仅 CPU
# conda install pytorch torchvision torchaudio cpuonly -c pytorch

pip install -r requirements.txt
```

### 2. 下载模型权重

```python
from huggingface_hub import snapshot_download

snapshot_download(
    repo_id="ghy-cmd/micro-expression-weights",
    local_dir=".",  # 自动还原 checkpoints/ 和 weights/ 目录
)
```

### 3. 启动 Web 平台

```bash
python -m webapp.app
# 浏览器访问 http://localhost:5001
```

---

## 功能说明

| 功能 | 说明 |
|------|------|
| **微表情识别** | 上传短视频片段，自动预处理后用模型进行情绪分类 |
| **长视频微表情检测** | 上传任意长视频，自动人脸裁剪 + 滑窗推理，定位所有微表情区间 |

---

## 模型说明

### 功能一 · 微表情识别

对短片段分类为 **3 类情绪**：正向 / 负向 / 惊讶

- HRNet 特征提取器，作用于 onset + apex 帧 → (2, 256, 64, 64)
- TV-L1 光流（u, v, strain）→ (3, 256, 256)
- Transformer 编码器，注意力融合（16 头 × 4 阶段，full guidance）
- LOSO 交叉验证训练，训练集：Composite（CASME2 + SMIC-HS + SAMM）

### 功能二 · 长视频微表情检测

对任意长度视频定位所有微表情区间，并分类为 **4 类**：正向 / 负向 / 惊讶 / 其他

- 滑窗推理（窗口 0.4s，步长 0.2s，@ 30fps）
- 6 种尺度的多尺度时序特征
- 双任务预测头：检测分数 + 情绪分类
- 训练集：CAS(ME)³-LV
- 评估指标：有重叠即 TP 的 F1

---

## 预处理流水线

两个功能共用同一套预处理，与数据集预处理保持一致：

1. **人脸裁剪**（dlib 68点关键点）→ 256×256
2. **顶点帧检测**（光应变 + UPC）— 仅功能一
3. **HRNet 特征提取** → (2, 256, 64, 64)
4. **光流提取**（TV-L1）→ (3, 256, 256)

---

## 训练

```bash
# 识别 — LOSO 训练
python train_loso.py --config configs/train_loso.yaml --dataset composite

# 检测 — LOSO 训练
python detection/train_detection.py --config configs/detection_config.yaml
```

详见 [docs/TRAINING_GUIDE.md](docs/TRAINING_GUIDE.md)。

---

## 项目结构

```
├── webapp/                  # Web 可视化平台（Flask）
│   ├── app.py               # 入口 → http://localhost:5000
│   ├── api/                 # REST API（识别 + 检测）
│   └── core/                # 推理封装
├── models/                  # 模型结构
├── detection/               # 检测训练与评估
├── trainers/                # 识别训练工具
├── configs/                 # YAML 配置文件
├── datasets/                # 数据集加载器
├── utils/                   # 公共工具
├── docs/                    # 文档与可视化脚本
├── train_loso.py            # 识别 LOSO 训练脚本
└── requirements.txt
```

---

## 许可证

[CC BY-NC 4.0](https://creativecommons.org/licenses/by-nc/4.0/) — 允许学术研究与个人使用，**禁止商业用途**。