# face

**Repository Path**: lin-san03/face

## Basic Information

- **Project Name**: face
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: face-away-lock
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-06-27
- **Last Updated**: 2026-07-01

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# face-away-lock

摄像头实时人脸检测 + 人脸识别，离席自动锁屏，主人回归自动解锁。陌生人无法解锁。用于开放工位 / 共用电脑的隐私防窥与无人值守自动锁屏。

## 功能

- **人脸检测**：dlib HOG 检测器，纯 CPU 运行，多线程采集 + 帧间隔 + 降采样优化
- **离席锁屏**：人脸消失超过阈值秒数 → loginctl 真锁屏（自动识别 X11/Wayland 图形会话）
- **主人解锁**：人脸识别（dlib ResNet 128维特征 + 欧氏距离匹配），仅录入的"主人"能触发解锁
- **陌生人防护**：陌生人脸不计入"在座"，触发锁屏后陌生人无法解锁
- **防抖稳定**：连续 N 次检测确认才切换状态，避免单帧误检/漏检导致的抖动
- **前后台双模式**：前台显示图像窗口（绿框=主人/红框=陌生人），后台 `--headless` 无界面纯运行
- **配置化**：所有参数通过 `config/config.yaml` 调整，无需重编译
- **开机自启**：systemd user service，图形会话启动后自动运行
- **优雅退出**：sigaction 处理 SIGINT/SIGTERM，退出时打印性能报告

## 运行环境

- Ubuntu 20.04+（或其他 Linux 桌面发行版），仅 CPU
- 摄像头 `/dev/video0`
- 图形会话（X11 或 Wayland），用于 loginctl 锁屏

## 依赖

```bash
sudo apt install build-essential cmake
sudo apt install libopencv-dev
sudo apt install libdlib-dev
sudo apt install libyaml-cpp-dev
# dlib DNN 人脸识别需要 BLAS 加速
sudo apt install libblas-dev liblapack-dev
```

## 模型文件

人脸识别需要两个 dlib 模型（体积大，不入库，按需下载到 `../model/` 目录）：

| 文件 | 大小 | 用途 | 下载地址 |
|------|------|------|---------|
| `dlib_face_recognition_resnet_model_v1.dat` | 22MB | ResNet 人脸特征提取 | http://dlib.net/files/dlib_face_recognition_resnet_model_v1.dat.bz2 |
| `shape_predictor_5_face_landmarks.dat` | 9MB | 5点人脸关键点对齐 | http://dlib.net/files/shape_predictor_5_face_landmarks.dat.bz2 |

```bash
mkdir -p ../model && cd ../model
# 下载并解压（示例）
wget http://dlib.net/files/dlib_face_recognition_resnet_model_v1.dat.bz2
bzip2 -d dlib_face_recognition_resnet_model_v1.dat.bz2
wget http://dlib.net/files/shape_predictor_5_face_landmarks.dat.bz2
bzip2 -d shape_predictor_5_face_landmarks.dat.bz2
```

> 人脸检测（HOG）内置在 dlib 库中，无需额外模型文件。

## 编译

```bash
cd code/face-away-lock
mkdir build && cd build

# 启用真锁屏（生产部署用）
cmake -DENABLE_REAL_LOCK=ON ..
make -j

# 或：原型机模式（仅打日志不真锁屏，调试用）
cmake ..
make -j
```

## 运行

### 前台模式（带图像窗口）

```bash
cd code/face-away-lock
./build/bin/face-away-lock
# 首次启动会弹出录入画面，正对摄像头采满 20 帧后自动保存主人特征
# 后续运行自动加载主人特征，主人=绿框，陌生人=红框
# 按 ESC 退出
```

### 后台模式（无界面，systemd 用）

```bash
./build/bin/face-away-lock --headless --config config/config.yaml
# 无图像窗口，仅日志输出，Ctrl+C 退出
```

### 命令行参数

```
face-away-lock [--config cfg.yaml] [--headless] [--bench ...]
  --config PATH    指定配置文件（默认 config/config.yaml）
  --headless       无界面模式（后台/systemd 运行用，关闭图像窗口）
  --bench          合成帧性能测试模式（不需摄像头/显示器）
  --interval N     覆盖检测帧间隔
  --resize W       覆盖降采样宽度
  --frames N       bench 帧数
  --cam-delay N    模拟采集延迟(ms)
  --threads        启用多线程采集
  --show           bench 显示窗口
```

> **路径提示**：程序使用相对路径，必须从 `code/face-away-lock/` 目录运行，否则 `config/config.yaml`、`../model/`、`data/` 都会找不到。

## 配置

编辑 `config/config.yaml`，关键参数：

```yaml
detection:
  frame_interval: 5      # 每 N 帧检测一次（性能优化）
  resize_max: 320        # 检测前缩放长边，越小越快但精度下降
  threads: true          # 多线程采集/检测分离
  display: true          # 显示图像窗口（--headless 可覆盖为 false）

timing:
  away_threshold_sec: 5.0      # 人脸消失多少秒后锁屏
  return_threshold_sec: 1.0    # 人脸连续出现多少秒后解锁
  away_confirm_frames: 3       # 连续 N 次无人脸才进 AWAY（防抖）
  present_confirm_frames: 3    # 连续 N 次有人脸才回 PRESENT（防抖）

face_recognition:
  enable: true                 # 启用人脸识别（关闭则任何人均可解锁）
  model_dir: "../model"        # 模型目录
  owner_face_file: "data/owner_face.dat"  # 主人特征文件
  enroll_frames: 20            # 录入采集帧数（取平均作为模板）
  distance_threshold: 0.4      # 欧氏距离阈值，越小越严格（dlib 推荐 0.6）
```

### 换主人 / 重新录入

删除主人特征文件，下次启动自动重新录入：

```bash
rm data/owner_face.dat
./build/bin/face-away-lock
```

## 状态机

```
        人脸消失(连续N次)         超时
PRESENT ────────────────→ AWAY ────────→ LOCKED
  ↑                         │              │
  │                         │              │ 主人回归(连续N次+持续1秒)
  │    人脸回来(连续N次)     │              │
  └─────────────────────────┴──────────────┘
```

- **PRESENT**：检测到主人人脸，不锁屏
- **AWAY**：主人人脸消失，倒计时 `away_threshold_sec` 后锁屏
- **LOCKED**：已锁屏，主人连续出现 `present_confirm_frames` 次且持续 `return_threshold_sec` 秒后解锁；陌生人不计入

## 性能

参考 [docs/perf.md](docs/perf.md)，推荐配置 `interval=5 + resize=320 + 多线程 + Release -O3`：

| 配置 | 检测耗时 | 等效 FPS |
|------|---------|----------|
| 每帧检测 640px（基线） | 24.5ms | 41 |
| interval=5 + 320px | 6.8ms | 740 |
| interval=10 + 240px | 4.1ms | 3405 |

人脸识别模式（ResNet 推理）检测耗时约 10-45ms（P99），仍可实时运行。

## 开机自启（systemd）

```bash
# 安装到系统
sudo cmake --install build        # 二进制→/usr/local/bin, 配置→/usr/local/etc, service→/usr/local/lib/systemd/user

# 启用开机自启
systemctl --user daemon-reload
systemctl --user enable --now face-away-lock.service

# 查看状态/日志
systemctl --user status face-away-lock
journalctl --user -u face-away-lock -f
```

> service 文件已配置 `--headless`，后台运行无图像窗口。

## 项目结构

```
face-away-lock/
├── CMakeLists.txt              # 构建脚本（含 ENABLE_REAL_LOCK 开关、安装目标）
├── config/config.yaml          # 配置文件
├── src/main.cpp                # 全部实现（检测/识别/状态机/锁屏/日志/线程）
├── deploy/face-away-lock.service  # systemd user service
├── docs/                       # 设计文档/开发日志/性能数据/AI使用说明
├── data/                       # 主人特征文件（gitignore，不入库）
└── README.md
```

## 开发文档

- [docs/designed.md](docs/designed.md) — 系统设计与状态机
- [docs/devlog.md](docs/devlog.md) — 开发过程日志
- [docs/perf.md](docs/perf.md) — 性能优化与基准测试数据
- [docs/ai_usage.md](docs/ai_usage.md) — AI 辅助开发说明