FaceSwap 如何用 sort 工具按 yaw、roll 与 face 相似度整理训练人脸数据集？

准备模型训练数据集时，一个常见问题是：同一张脸的正脸、侧脸、歪头照混杂在一起，无法快速判断哪些角度覆盖得少、哪些帧对齐失败。FaceSwap 自带一个 sort 工具（位于 tools/sort/，通过主入口 tools.py 调用），它能读取对齐人脸 PNG 文件头中嵌入的对齐数据，把图片按 yaw（左右偏转）、roll（旋转）、face 相似度等指标重新命名或分箱，得到一套可按顺序翻检的人脸序列。前提是图片集由 Faceswap 的 Extract 流程生成（PNG 头里带有 alignments 数据），且环境满足 tools.py 入口的要求：至少 Python 3.11，否则直接抛出 This program requires at least python 3.11。

运行前提：目录里必须是对齐人脸，而不是原始照片

yaw、pitch、roll、size 这类基于对齐指标的方法（SortAlignedMetric，见 tools/sort/sort_methods_aligned.py）在打分时会读取每张图的 alignments 数据。如果图片头里没有这些内容，工具会直接报错退出：

The images to be sorted do not contain alignment data. Images must have been generated by
Faceswap's Extract process.
If you are sorting an older face set, then you should re-extract the faces from your source
alignments file to generate this data.

也就是说，排序对象必须是 Extract 流程产出的对齐人脸目录；老版本人脸集需要先按上面的提示从源 alignments 文件重新提取。另外，如果目录里没有任何可处理的图片，工具会以 No images to process in location: '...' 退出。若至少一张脸缺少面部 landmark 数据，工具只会打出一条警告 You have selected to sort by an aligned metric, but at least one face does not contain facial landmark data. This probably won't work，不会中断。

三个关键选项决定了输出形态

完整参数可用 python tools.py sort -h 查看（参数定义见 tools/sort/cli.py），本文用到的是：

• -i/--input：输入目录，必填，放对齐人脸的文件夹。
• -o/--output：输出目录。不指定时，选了 -k 会在输入目录下新建 sorted 子目录；不选 -k 则就地移动并重命名，直接改写原目录。
• -s/--sort-by：排序方法，可选 none、yaw、roll、face 等（默认 face）。选择排序方法后，图片会按该方法中的次序获得 000000_原文件名 形式的顺序文件名。
• -g/--group-by：分箱方法（默认 none）。选择后图片会被移动或复制进编号子文件夹（bin）；与 -s 组合时，先按 -s 重命名，再按 -g 分箱，文件夹名形如 <bin>_by_<sort方法>。
• -b/--bins：分箱数量，默认 5。对 yaw/pitch/roll 这类方向方法，bin 数量决定 180 度被切成多少份：选 18 时每个文件夹对应 10 度增量，第 0 号文件夹放偏转方向最负的脸（yaw 即最偏左，pitch 即最偏下），最后一个文件夹放最偏右/最偏上的脸；空 bin 会被删除，最终文件夹数可能少于 -b。
• -t/--threshold：face、face-cnn、hist 分箱时的相似度阈值。face 方法默认 0.25，文档建议 0.1（更多 bin）到 0.5（更少 bin）之间取值；图片很多时阈值过于极端会生成大量文件夹。
• -k/--keep：保留原图，重命名后的副本写入输出目录；不加 -k 则是原文件被移动并重命名。
• -I/--identity：按 face 排序/分组使用的身份模型，默认 t-face（InsightFace ResNet 模型，有轻重两个变体），可换 vggface2（较旧的 VGG Network 插件）。
• -l/--log-changes 与 -f/--log-file：记录每次改名或移动/复制；不指定 -f 时日志写在输入目录的 sort_log.json，-f 支持 json 或 yaml。

注意 -s 与 -g 每次运行各只能取一个值，所以"按 yaw、roll、face 相似度整理"需要分多次运行；同时两者都为 none 时工具会以 Both sort-by and group-by are 'None'. Nothing to do. 退出。

按 yaw 整理：把左右偏转排成一条序列

python tools.py sort -i <aligned_faces_dir> -o <yaw_out_dir> -s yaw -k -l

其中 <aligned_faces_dir> 替换为你对齐人脸目录的路径，<yaw_out_dir> 替换为本次排序的输出目录。运行结束后，输出目录里的文件按 yaw 从最负到最大排列，文件名依次为 000000_...png、000001_...png……按下标翻文件即可从最偏左一路看到最偏右。原目录因加了 -k 保持不变，-l 会在输入目录生成 sort_log.json。

如果需要把偏转角切成固定区间便于抽查，可把 -s 换成与 -g 配合：

python tools.py sort -i <aligned_faces_dir> -o <yaw_bins_dir> -s none -g yaw -b 18 -k -l

s none + g yaw 时文件保留原文件名，只按 yaw 分箱；-b 18 表示每 10 度一个文件夹。若想让箱内文件也按 yaw 排序重命名，把 -s none 改为 -s yaw，此时文件夹名会带上 _by_yaw 后缀。

按 roll 整理：找出对齐失败的脸

对齐成功的脸 roll 值应接近 0；roll 离 0 越远，这张脸对齐失败的可能性越大（这是 roll 方法帮助文本给出的判断依据）。因此按 roll 排序后，序列两端（000000_ 开头和最大下标）的文件就是最需要检查的对象：

python tools.py sort -i <aligned_faces_dir> -o <roll_out_dir> -s roll -k -l

也可以像 yaw 一样按度数分箱，便于直接删掉歪头严重的区间：

python tools.py sort -i <aligned_faces_dir> -o <roll_bins_dir> -s none -g roll -b 18 -k -l

roll 分箱的逻辑与 pitch/yaw 相同：18 个 bin 对应 180 度每 10 度一档，文件夹名包含度数区间（例如 roll_000_0degrees_to_10 这类命名，实际以运行为准），空箱自动删除。

按 face 相似度整理：让相似的脸排在一起

face 方法是 -s 的默认值，它使用成对聚类算法检查集合中每张脸的 512 个特征之间的距离，然后按相似度给图片定序：

python tools.py sort -i <aligned_faces_dir> -o <face_out_dir> -s face -k -l

想换身份模型时用 -I，例如 -I vggface2。如果目的是把数据集切成"长相/光线相近"的若干组而不是单一序列，用分箱：

python tools.py sort -i <aligned_faces_dir> -o <face_groups_dir> -s none -g face -t 0.25 -k -l

-t 对 face 分箱的含义是：0.1 得到更多 bin、0.5 得到更少 bin，留默认（-1.0）时 Faceswap 使用内置值 0.25。数据集较大时不建议把 -t 调得过小，否则会创建大量文件夹。

验证结果：看输出结构、日志和 Done 提示

一次运行结束时，日志最后输出 Done.。判断结果是否符合预期可以核对三点：

1. 排序模式（只有 -s）：输出目录中文件名从 000000_ 连续递增，下标即该指标下的名次；抽查首尾文件即可确认排序方向（例如 roll 两端应是歪头最明显的脸）。
2. 分箱模式（含 -g）：输出目录中出现编号子文件夹，文件夹名包含度数区间或 bin 名；空箱已被删除，所以文件夹数可能小于 -b。
3. 变更日志（加了 -l）：输入目录（或 -f 指定位置）生成 sort_log.json，内容是"源文件路径 → 目标文件路径"的映射。由于不加 -k 时文件是被移动/重命名的，这份日志是核对每个文件去向、以及恢复原名的依据。

限制与注意点

• -s、-g 每个运行只能各选一个方法，多指标整理要多次运行并指定不同 -o；不加 -o 且不加 -k 时是就地改写原目录，整理前请先确认可以接受。
• face-cnn/hist 分箱阈值（默认 face-cnn 7.2、hist 0.3）与 face 不同，本文不涉及的方法以 -h 输出为准。
• 批量场景可用 -B/--batch-mode：此时 -i 指向包含多个人脸子文件夹的父目录，各子文件夹的结果会分别输出到 -o 下对应的子文件夹，便于一次性整理多组人脸集。
• 各方法的完整参数与行为描述见 tools/sort/cli.py 的帮助文本和 API 文档 docs/full/tools/sort.rst。