first community

README.md

@@ -0,0 +1,89 @@
+# 人脸裁剪与背景去除
+
+`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
+```