# 人脸裁剪与背景去除

`extract_faces.py` 会批量检测正脸及左右侧脸，按 MediaPipe 三维人脸网格生成面部轮廓，再用 GrabCut 细化边缘。结果保存为带透明通道的 PNG，只保留面部区域，不包含头发、耳朵和衣服。

## 运行

```powershell
python -m pip install -r requirements.txt
python extract_faces.py . --output faces_no_bg
```

也可以处理单张图片：

```powershell
python extract_faces.py yolo_white_left.jpg --output faces_no_bg
```

## 常用参数

- `--padding 0.04`：人脸周围透明边距比例。
- `--expand 0.004`：向外扩展面部蒙版，避免切掉边缘皮肤。
- `--feather 0.002`：透明边缘羽化比例。
- `--edge-band 0.05`：覆盖自动姿态估计，手动指定轮廓细化带宽度。
- `--max-refine-size 960`：轮廓细化使用的最大局部图尺寸。
- `--no-edge-refine`：关闭 GrabCut，仅使用人脸网格轮廓。
- `--recursive`：递归处理输入目录中的图片。
- `--rotate-left`：检测前将每张输入图逆时针旋转 90 度，不修改原图。

原图不会被覆盖，输出文件名格式为 `<原文件名>_face.png`。

## 仅保留面部皮肤

`extract_face_skin.py` 使用语义分割保留皮肤、鼻子、眼睛、眉毛和嘴唇，排除头发、耳朵、颈部与背景。第一次运行会下载通用预训练模型。

```powershell
python extract_face_skin.py "输入目录" --output "输出目录" --recursive --rotate-left
```

默认按模型训练分辨率 `512×512` 做语义分割。

## 保留头发并输出 Mask

`extract_head_mask.py` 先根据人脸位置和朝向自适应扩展发顶、两侧与后脑区域，再分割脸、耳朵和头发。每张输入图会得到：

- `<原名>_mask.png`：与旋转后原图等大的灰度 Alpha Mask。
- `<原名>_head.png`：使用平滑 Mask 截取的黑色背景 RGB PNG。

```powershell
python extract_head_mask.py "输入目录" --output "输出目录" --recursive --rotate-left
```

输入根目录含有其它结果文件夹时，可以重复使用 `--exclude-dir` 排除：

```powershell
python extract_head_mask.py "输入目录" --output "输出目录" --recursive --rotate-left --exclude-dir faces_no_bg --exclude-dir output
```

如需只分发一个业务脚本，可使用功能相同且不导入其它本地脚本的单文件版：

```powershell
python -m pip install -r requirements-head-mask.txt
python extract_head_mask_single.py "输入目录" --output "输出目录" --recursive --rotate-left
```

最小分发内容为 `extract_head_mask_single.py`、`requirements-head-mask.txt` 和本说明文档。建议使用 Windows 64 位及 Python 3.9；GPU 可选，语义分割默认自动选择 CUDA 或 CPU，人脸检测固定使用 CPU。

## 模型下载与离线运行

首次运行会下载以下两个模型，模型文件不会嵌入 Python 脚本：

- 语义分割模型：[`jonathandinu/face-parsing`](https://huggingface.co/jonathandinu/face-parsing)，默认缓存到 `%USERPROFILE%\.cache\huggingface\hub\models--jonathandinu--face-parsing`。
- 人脸检测模型：[`buffalo_l.zip`](https://github.com/deepinsight/insightface/releases/download/v0.7/buffalo_l.zip)，默认解压到 `%USERPROFILE%\.insightface\models\buffalo_l`，实际检测文件是 `det_10g.onnx`。

离线分发时，在联网电脑上先运行一次脚本，再准备以下文件：

1. 将 Hugging Face 缓存中同一 `snapshots\<版本>` 目录内的 `config.json`、`preprocessor_config.json` 和 `model.safetensors` 复制到分发目录的 `models\face-parsing`。
2. 将整个 `buffalo_l` 目录复制到离线电脑的 `%USERPROFILE%\.insightface\models\buffalo_l`，确保 `det_10g.onnx` 直接位于该目录内。
3. 使用本地语义模型运行：

```powershell
python extract_head_mask_single.py "输入目录" --output "输出目录" --recursive --rotate-left --model ".\models\face-parsing"
```

Python 第三方依赖也需要预先安装。可在相同 Windows/Python 环境的联网电脑下载离线安装包：

```powershell
python -m pip download -r requirements-head-mask.txt --dest wheels
python -m pip install --no-index --find-links .\wheels -r requirements-head-mask.txt
```