# cface

**Repository Path**: lonmi/cface

## Basic Information

- **Project Name**: cface
- **Description**: 人脸视觉开源框架 人脸检测/人脸识别/活体检测/人脸属性
- **Primary Language**: Python
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 1
- **Created**: 2026-11-06
- **Last Updated**: 2026-11-06

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# cface

**代码仓库**：[Gitee](https://gitee.com/beixiaocai/cface) · [GitHub](https://github.com/beixiaocai/cface) ｜ [English](README_en.md)

**作者**：小菜 ｜ **微信**：y1632999

> 人脸检测、人脸识别（1:1 与 1:N）、人脸属性分析，训练到部署一套流程。

**当前版本**：v1.001（核心库与桌面 UI 同步）。

```bash
pip install -r requirements.txt      # Python 3.12 + CUDA 12.1 实测
python cface.py list                # 任务与动作
python cface.py det test --ckpt runs/det/train/weights/best.pt --img data/det/bus.jpg
```

- CLI：`python cface.py <task> <action> [参数...]`，任务 `det` / `attr` / `rec`
- 参数：任意动作加 `--help` 查看（如 `python cface.py attr cascade --help`）
- 训练：`cface.engine.BaseTrainer` 统一主循环（优化器、调度、EMA、早停、续训、指标）
- 产物：`runs/<task>/`、`data/<task>/`、`pretrain/<task>/`，自动累加、不覆盖历史
- 部署：PyTorch → ONNX → ONNX Runtime（x86/GPU）/ OpenVINO IR / NCNN / RKNPU（RK3588 / RK3576 / RK3568）

## 任务

| 任务 | 内容 | 模型 | 参考指标 |
|---|---|---|---|
| det | 整帧图 → 人脸框 | anchor-free 单阶段 + 特征金字塔 + 解耦头，one2many 训练 / one2one 部署免 NMS | 2.50M；640 输入 mAP@0.5 ≈ 0.64；OpenVINO CPU 13–14 ms |
| attr | 性别 / 年龄 / 表情 / 口罩 / 眼镜 / 帽子 / 胡子 / 肤色（8 头） | PConv + 倒残差 + SE，112 输入 | 0.54M；约 2 ms |
| rec | 128 维嵌入，1:1 核验 / 1:N 检索 | 轻量卷积骨干 + L2 归一化嵌入，在线三元组 + 角度间隔 | 3.34M；LFW 10 折 0.9898；约 4 ms |

```
整帧图 ──det──▶ 裁脸 ──attr──▶ 性别 / 年龄 / 表情 / 口罩 / 眼镜 / 帽子 / 胡子 / 肤色
                    └──rec───▶ 128 维特征 ──▶ 余弦比对
```

### det — 人脸检测

- 茎 + 跨阶段块 + SPP → P3/P4/P5；`--p2` 增 P2/4 层，配 `--imgsz 960` 提升 16px 以下小脸召回
- 解耦 anchor-free 头，ltrb 直接回归；`--landmarks 1` 加 5 点分支（标签每行 14 值）
- 数据为 YOLO 格式：`data.yaml` + 同名 `.txt`，每行 `cls cx cy w h`（归一化），`nc=1`
- 预处理 letterbox 补 114、RGB、/255，输出框已 map_back 回原图

```bash
python cface.py det prepare --labelme <标注目录> --out <输出目录>
python cface.py det test-ov --ckpt runs/det/train/weights/best.pt --img data/det/bus.jpg --compare
```

- 推理输出 `runs/det/infer*/`：画框图 + `detections.json`
- 数据：WIDER FACE（CC BY-NC-ND），仅限研究

### attr — 人脸属性

- 茎 3×3 s2 → PConv 块 ×2 → 倒残差 + SE ×4 ×2 → Conv1×1 + GAP → **八头**（gender 1 / age 101 / expr 7 / mask 1 / glasses 1 / hat 1 / beard 1 / skin 7）
- 性别与口罩 / 眼镜 / 帽子 / 胡子均为 sigmoid 二分类（`0=无 / 1=有`，性别 `0=male / 1=female`）
- 表情 7 类：angry / disgust / fear / happy / sad / surprise / neutral；肤色 7 类：White / Black / Indian / East Asian / Southeast Asian / Middle Eastern / Latino_Hispanic
- 年龄按 101 档分布学习（σ=2 高斯软标签）+ 期望值 L1；表情用类逆频权重 + label smoothing
- 验证分 `score = 0.3·性别acc + 0.3·表情acc + 0.1·年龄项 + 0.3·新属性平均acc`，据此早停与保存；验证与保存均用 EMA

```bash
python cface.py attr build-dataset --root D:/datasets/face/attr
python cface.py attr test-ov --ckpt runs/attr/train/weights/best.pt --img data/attr/Adrien_Brody_0001.jpg --compare
```

`cascade` 输出 `runs/attr/infer*/`：画框图（8 项属性 + 检测分）、`crops/` 裁片、`pipeline.json` 结构化结果。

- ONNX 图内已含 `/255`，推理端直接喂 0–255，不要再归一化
- 数据：UTKFace / AgeDB / FER2013 / CelebA / FairFace / 口罩集，均限研究用途（非口罩源统一标注无口罩，肤色来自 FairFace）

### rec — 人脸识别

- 骨干 stage1–3 → 4×4×1024 → GAP → Linear 1024→128 → BN → L2；112 直接 resize，不 letterbox
- 训练额外挂角度间隔分类头（s=64, m=0.5）联合三元组损失；`--batch` 必须是 3 的倍数
- 数据：`cls_id;绝对路径` 描述文件，由 `create-train` / `unpack-emore` 生成；LFW 用 `create-lfw`

```bash
python cface.py rec unpack-emore
python cface.py rec create-train
python cface.py rec create-lfw
python cface.py rec test-ov --ckpt runs/rec/train/weights/model_best_lfw0.9898_ep067.pth \
    --image1 data/rec/Adrien_Brody_0001.jpg --image2 data/rec/Adrien_Brody_0012.jpg --compare
```

阈值（余弦，越大越相似；上线前按 FAR/FRR 调整）：

| 场景 | 阈值 |
|---|---|
| 1:1 核验 | 0.40 |
| 1:N 检索（N≈1e4） | 0.55 ~ 0.65 |
| 聚类去重 | 0.70 |

- 导出 `1×3×112×112` → `1×128` 已归一化，opset 10，仅 batch 维动态
- 数据：MS1MV2 / LFW，学术研究用途

## 参数

示例命令，逐个说明用到的参数；未写出的参数用默认值，`--help` 可查全量。

### det

```bash
python cface.py det train --data D:/datasets/face/det/data/data.yaml --epochs 300 --batch 8 --imgsz 960 --p2 --workers 4
```

- `--data` 数据集 yaml（path + train/val），必填
- `--epochs` 训练轮数
- `--batch` 单卡批大小
- `--imgsz` 输入边长，开 `--p2` 时常用 960
- `--p2` 增加 P2/4 小目标层，提升小人脸召回
- `--workers` 数据加载进程数（Windows 建议 0~4）

```bash
python cface.py det test --ckpt runs/det/train/weights/best.pt --img data/det/bus.jpg --conf 0.25 --branch one2one
```

- `--ckpt` 权重；省略自动取 `runs/det/train*` 最新 `best.pt`
- `--img` 图片，可多张；省略则测 `data/det/` 全部
- `--conf` 置信度阈值
- `--branch` `one2one` 免 NMS，`one2many` 需 NMS

```bash
python cface.py det export --ckpt runs/det/train/weights/best.pt --out det.onnx --layout merged
```

- `--ckpt` / `--out` 必填
- `--layout merged` 导出单张量 `(1, 5, 8400)`；默认 `split` 为多头

### attr

```bash
python cface.py attr train --data D:/datasets/face/attr/data --epochs 120 --batch 128 --w-gender 2.0 --w-expr 2.0
```

- `--data` 数据集目录（含 manifest CSV）
- `--epochs` / `--batch` 轮数与批大小
- `--w-gender` / `--w-expr` 性别 / 表情损失权重，年龄为 `--w-age`（默认 1.0）；八头新增 `--w-mask`（默认 2.0）与 `--w-glasses` / `--w-hat` / `--w-beard` / `--w-skin`（默认 1.0）

```bash
python cface.py attr cascade --det-ckpt runs/det/train/weights/best.pt --attr-ckpt runs/attr/train/weights/best.pt --img data/attr/Adrien_Brody_0001.jpg --conf 0.25 --margin 0.2
```

- `--det-ckpt` / `--attr-ckpt` 检测 / 属性权重；省略则各取最新
- `--img` 待测图片，可多张
- `--conf` 检测置信度阈值
- `--margin` 裁脸外扩比例，0.2 表示每边再扩 10%

```bash
python cface.py attr export --ckpt runs/attr/train/weights/best.pt --out attr.onnx
```

- `--ckpt` / `--out` 必填；`--imgsz` 默认 112

### rec

```bash
python cface.py rec train --data D:/datasets/face/ms1mv2/train.txt --epochs 100 --batch 384 --lr 5e-4 --samples-per-epoch 600000
```

- `--data` 训练描述文件，每行 `cls_id;绝对路径`
- `--batch` 必须是 3 的倍数（anchor / positive / negative）
- `--lr` 基础学习率
- `--samples-per-epoch` 每轮采样张数
- `--epochs` 训练轮数

```bash
python cface.py rec test --ckpt runs/rec/train/weights/model_best_lfw0.9898_ep067.pth --img data/rec/Adrien_Brody_0001.jpg data/rec/Adrien_Brody_0012.jpg --threshold 0.40
```

- `--ckpt` 权重；省略自动取最新 `model_best*.pth`
- `--img` 恰好两张图片
- `--threshold` 余弦阈值，≥ 该值判为同人

```bash
python cface.py rec export --ckpt runs/rec/train/weights/model_best_lfw0.9898_ep067.pth --out rec.onnx
```

- `--ckpt` / `--out` 必填

## 训练

三个任务共用 `cface.engine.BaseTrainer`：优化器、调度、warmup、EMA、梯度裁剪、AMP、早停、checkpoint、续训、CSV 指标只实现一次。
任务侧实现 `build_model()`、`build_loaders()`、`compute_loss()`、`validate()` 四个钩子，其余按需覆盖。

```
<run>/weights/best.pt   {state_dict: EMA 权重, epoch, val_loss, score, ...}
<run>/weights/last.pt   训练权重 + opt/sched/ema/args，续训用 --resume
```

读取权重统一走 `cface.deploy.load_ckpt()`，兼容裸 state_dict。

## 产物与目录

```
runs/<task>/train、train1 …   训练实验，权重在 <run>/weights/
runs/<task>/infer、infer1 …   推理输出
data/<task>/                  样例数据
pretrain/<task>/              预训练权重
```

- 日志 `train-<日期时间>.log`、指标 `train_log.csv` / `metrics.json` 随实验目录
- 转换产物随源模型，命名 `cface_<task>_<年月日-时分秒>.onnx`
- 路径统一走 `cface.paths`：`task_runs` / `task_data` / `task_pretrain`；日志用 `cface.log.get_logger`

## 部署

| | OpenVINO（x86） | RKNPU（边缘端） |
|---|---|---|
| det 布局 | `--layout merged` 单张量 `(1,5,8400)` | 多头 `[reg0, cls0, …]` |
| 输入 | fp32，[0,1] | UINT8 原图，mean=0 / std=255 |
| 精度 | fp32 | int8，转换时用真实场景校准图 |

共同前提：静态 shape、Conv+BN 已折叠、图内不含 NMS。导出后建议跑一次 `<task> test-ov --compare` 对拍。

## 推理后端与模型转换

默认 `requirements.txt` 只含 ONNX / ONNX Runtime；其余后端按需手动安装：

```
pip install -r requirements-openvino.txt   # OpenVINO IR 转换与推理
pip install -r requirements-ncnn.txt       # PNNX 转换与 ncnn 推理
pip install -r requirements-rknpu.txt      # RKNN 转换（仅 x86 Linux；板端另装 rknn-toolkit-lite2）
```

| 格式 | 转换命令 | 推理命令 |
|---|---|---|
| ONNX | `python cface.py <task> export` | `python cface.py <task> test-ort` |
| OpenVINO IR | `python cface.py <task> convert --format ov` | `python cface.py <task> test-ov` |
| NCNN | `python cface.py <task> convert --format ncnn` | `python cface.py <task> test-ncnn` |
| RKNN | `python cface.py <task> convert --format rknn --target-platform rk3588` | `python cface.py <task> test-rknn` |

- 转换默认从 `runs/<task>/train*` 取最新权重，先导出 ONNX 再转目标格式；`--onnx` 可直接指定已有 ONNX，`--out` 指定产物路径，`--force-export` / `--force-convert` 强制重做
- 推理入口按需自动导出 / 转换，产物与 ONNX 同 stem（`.xml/.bin`、`.param/.bin`、`.rknn`）；`--device`（CPU/GPU/AUTO、CUDA）与 `--threads` 控制设备与线程
- NCNN：转换走 PNNX，转换后自动用 ONNX Runtime 对拍（偏差 > 0.5 告警）；PNNX 以 fp16 存权重，故误差在 1e-2 量级；图内输入 `/255` 的标量算子会折算进首层卷积权重，规避部分 ncnn 构建上的崩溃
- OpenVINO：默认导出 fp32 IR，不压缩 fp16
- RKNN：转换需 x86 Linux 上的 rknn-toolkit2，量化加 `--quantize --dataset <校准集.txt>`；板端推理用 rknn-toolkit-lite2

## 桌面客户端 ui/

`ui/` 是独立子项目：客户端虚拟环境 `venv_ui/`、模型 `models/` 与打包产物都在仓库根目录，不依赖训练环境的 torch / OpenVINO，仅通过 ONNX Runtime 读取模型。

- 名称：统一为 cface（软件名、包名、CLI、exe 为 cface / cface-ui）
- 技术栈：Python 3.12 + ONNX Runtime CPU + customtkinter / Pillow / numpy / OpenCV，见根目录 `requirements-ui.txt`
- 功能：检测、识别、属性任意组合；1:1 参考比对、1:N 人脸库检索；文件夹浏览、缩放平移、标注图与 JSON 导出
- 人脸库：独立「人脸库管理」弹框（主界面右上角入口）。每条记录包含裁剪人脸、原始照片、唯一编号、序号与添加时间，支持登记时自动提取人脸、单条改名/删除/新增；元数据写入库目录 `gallery.json`，人脸图存于 `.faces/`
- 摄像头：拍照送主界面分析、实时识别（预览上叠框与姓名）、采集入库、MP4 录像（`设备序号 0/1/2` 可切换）
- 模型：`models/{det,rec,attr}.onnx` 外置随包分发（已入库，开箱即用）
- 开发运行：根目录执行 `venv_ui\Scripts\python.exe ui\app.py`
- 打包：`ui\build.ps1` → 根目录 `dist\cface-ui\cface-ui.exe`，分发时保留整个 `dist\cface-ui` 目录
- 入库范围：`ui/app.py`、`ui/cfacetest/`、`ui/assets/`、`ui/build.ps1`、根目录 `requirements-ui.txt` 与 `models/*.onnx`；`venv*/`、`dist/`、`build/` 已忽略

### 本地编译桌面客户端

前提：Windows 10/11 + Python 3.12，在仓库根目录（如 `D:\project\cface`）执行。

```powershell
python -m venv venv_ui
.\venv_ui\Scripts\python.exe -m pip install -r requirements-ui.txt
powershell -ExecutionPolicy Bypass -File .\ui\build.ps1
```

- `build.ps1` 固定使用根目录 `venv_ui`，并自动安装 `requirements-ui.txt` 与 PyInstaller
- 产物在 `dist\cface-ui\`，`models\` 会自动复制进包内；分发时整个目录一起拷贝
- 开发调试：`.\venv_ui\Scripts\python.exe .\ui\app.py`
- `ui\cface-ui.spec` 由 PyInstaller 每次打包时生成，不入库（已在 `.gitignore` 忽略）

## 扩展

1. 建包 `cface/tasks/<your_task>/`，动作模块暴露 `main(argv=None) -> int`
2. 训练继承 `BaseTrainer`，实现四个钩子
3. 在 `cface/tasks/__init__.py` 的 `TASKS` 注册动作，并在 `cface/paths.py` 的 `TASKS` 加任务名

## 目录结构

```
cface/
├── cface.py            统一 CLI，任务 × 动作分发
├── requirements.txt    锁定版本的训练/转换依赖清单
├── requirements-ui.txt 桌面客户端依赖清单
├── LICENSE
├── cface/              共享库 + 任务
│   ├── paths.py        路径与产物命名
│   ├── log.py          日志封装
│   ├── deploy.py       权重加载、预处理、坐标映射、画框、ONNX→IR
│   ├── engine/         BaseTrainer、优化器、EMA、指标、数据配置
│   └── tasks/          人脸任务
│       ├── __init__.py 任务注册表与校验
│       ├── det/        人脸检测
│       ├── attr/       人脸属性
│       └── rec/        人脸识别
├── ui/                 独立桌面客户端源码（ONNX Runtime + customtkinter）
│   ├── app.py          入口
│   ├── cfacetest/      界面、推理引擎、配置
│   ├── assets/         图标
│   └── build.ps1       Windows 打包
├── models/             外置 ONNX 模型（入库，开箱体验）
├── data/               样例数据（入库）
├── runs/               训练与推理产物（git 忽略）
├── pretrain/           预训练权重（git 忽略）
├── venv/               训练环境（git 忽略）
├── venv_ui/            桌面客户端环境（git 忽略）
└── dist/ build/        打包产物（git 忽略）
```

## 许可与数据

代码以 **MIT** 发布，见 [`LICENSE`](LICENSE)。代码许可不覆盖训练数据与模型权重。

- `det` 用 WIDER FACE（CC BY-NC-ND），`attr` 用 UTKFace / AgeDB / FER2013 / CelebA / FairFace / 口罩集，`rec` 用 MS1MV2，均为研究用途，商用请用自有或已授权数据重训
- `pretrain/` 下权重仅用于研发期热启动；`runs/`、`pretrain/` 不入库，`data/` 与 `models/` 的样例/推理模型已入库
- 人脸属敏感个人信息，采集、训练与上线需满足单独同意、最小必要、可撤回与去标识化

本项目各模块为独立实现，未复制或依赖第三方训练框架源码。

## 未来方向（人脸基础算法）

- **检测**：侧脸/遮挡/低照度/红外人脸、密集小脸、旋转框
- **关键点与对齐**：5/68/98 点、3D 关键点、仿射/透视矫正
- **识别**：ArcFace/CosFace、跨姿态/跨年龄/遮挡/低质人脸识别、开集识别、特征融合
- **质量与安全**：人脸质量评估、静默活体、Deepfake 检测、对抗样本鲁棒性
- **属性与解析**：人脸语义分割、AU/微表情、头部姿态、视线估计
- **3D 与生成**：3DMM/FLAME 重建、超分/去噪/修复、换脸与重演
- **检索与聚类**：ANN 索引、人脸聚类、模板融合
- **视频人脸**：单/多目标跟踪、跨帧关联