图片人脸批量戴口罩

要解决什么问题

活动海报、班级合影、证件照批量脱敏时，手工抠脸贴口罩既慢又难统一。远景小脸、侧脸、自拍俯角会让传统 Haar 级联漏检或误检（黑板纹理、腰带、膝盖等），单模板又容易在侧脸上错位。

技能如何工作

核心脚本是 scripts/add_mask_with_image.py，批量入口为 scripts/batch_process.py。首次运行会从 OpenCV 官方仓库拉取 ResNet-10 SSD 权重（res10_300x300_ssd_iter_140000.caffemodel，约 10MB），之后本地复用，无需重复下载。

检测流程大致是：全图 300×300 推理 + 多尺度分块（标准 2×2～4×4，增强 --enhanced 可到 8×8 并做后排/右半区等局部加强）→ NMS 去重 → 位置与尺寸规则、空间关系（排除脸下方误检）、肤色 HSV 校验等后处理。v4.3 支持 --manual-faces "x,y,w,h;..." 补漏检，批量模式可 复用已加载的 DNN 与口罩图。

贴罩逻辑按脸框高度从约 30%（眼下）到 125%（下巴下） 定位，宽度左右各外扩 10%；正侧脸用 AR 偏差、边缘不对称、梯度偏置等组合打分选 mask_front.png / mask_side.png，侧脸方向自动水平翻转。PNG 模板会识别已有 alpha，否则自动去黑/白底再 alpha 合成，JPEG 输出质量默认 95。无检测到人脸时原图拷贝到输出目录。

适用边界与注意

• 增强模式更慢，适合 20+ 人的密集场景；标准模式对中等规模合影通常够用。
• v4.2 起会跳过动漫/插画等「非真人」脸，若业务需要给虚拟角色戴口罩需改过滤逻辑。
• 权重不在技能包内，首跑需联网；环境需 Python 3.7+ 与 OpenCV、Pillow、NumPy。
• 双模板批量可用 --front / --side；自拍/广角脸框偏高时 v4.3 会自适应上移口罩起点（如 fh/fw > 1.35 时从 30% 调到约 15%）。