HivisionIDPhotos: 打造轻量级与高效的AI证件照制作工具

一、引言

在当今数字化时代，证件照已成为我们日常生活和工作中不可或缺的一部分。然而，传统的证件照拍摄和制作过程往往繁琐且耗时，尤其是在需要不同尺寸和规格的证件照时。为此，我们推出了HivisionIDPhotos——一个轻量级且高效的AI证件照制作工具，旨在通过智能化手段简化证件照的制作流程。

二、项目简介

背景与目标

HivisionIDPhotos项目起源于对图像处理和人工智能技术的深入探索。我们的目标是开发一种实用且系统性的证件照智能制作算法，能够自动识别用户拍照场景、进行抠图处理，并生成符合多种标准尺寸的证件照。通过利用先进的AI模型和工作流程，我们希望能够为用户提供一种便捷、高效的证件照制作体验。

核心功能

HivisionIDPhotos具备以下核心功能：

1. 轻量级抠图

   ：我们的算法能够在纯离线环境下，仅凭CPU实现快速且准确的抠图处理。

2. 多尺寸生成

   ：根据用户需求，可以生成不同尺寸和规格的标准证件照，以及六寸排版照。

3. 离线与端云推理

   ：支持纯离线处理和端云协同推理，满足不同场景下的使用需求。

4. 美颜功能

   ：通过AI技术实现智能美颜，提升证件照的整体美感。

5. 智能换正装

   （开发中）：未来还将支持智能换正装功能，让用户无需自备正装即可获得专业的证件照效果。

三、最新进展与功能更新

在线体验与更新日志

为了让用户更直观地体验HivisionIDPhotos的功能，我们在SwanHub Demo平台上提供了在线体验服务。以下是近期的功能更新日志：

• 2024.11.20

  ：Gradio Demo增加了打印排版选项卡，支持六寸、五寸、A4、3R、4R五种排版尺寸，方便用户进行打印和排版。

• 2024.11.16

  ：API接口增加了美颜参数，用户可以通过API接口调整美颜程度，满足不同审美需求。

• 2024.09.25

  ：增加了五寸相纸和JPEG下载选项，默认照片下载支持300DPI高分辨率，确保打印质量。

• 2024.09.24

  ：API接口增加了base64图像传入选项，Gradio Demo增加了排版照裁剪线功能，提升用户体验。

• 2024.09.22

  ：Gradio Demo增加了野兽模式，用户可设置内存加载策略以优化性能；API接口增加了dpi和face_alignment参数，提供更精细的控制。

• 2024.09.18

  ：Gradio Demo增加了分享模版照功能和美式证件照背景选项，丰富用户选择。

• 2024.09.17

  ：Gradio Demo增加了自定义底色-HEX输入功能，允许用户自由设置证件照底色；C++版本HivisionIDPhotos-cpp由社区贡献者zjkhahah开发完成，拓展了项目的跨平台能力。

• 2024.09.16

  ：Gradio Demo增加了人脸旋转对齐功能和自定义尺寸输入支持毫米单位，提升证件照的准确性和灵活性。

四、技术亮点与实现原理

AI模型与工作流程

HivisionIDPhotos的核心在于其完善的AI模型和工作流程。我们采用先进的深度学习技术，训练了多个神经网络模型，包括人脸检测、分割、对齐和生成等模块。这些模型能够协同工作，实现对用户拍照场景的快速识别和处理。

轻量级抠图技术

为了实现纯离线环境下的快速抠图处理，我们采用了轻量级的神经网络架构，并进行了针对性的优化。通过减少模型参数和计算量，我们成功实现了在CPU上的高效推理。

多尺寸生成与排版

为了满足不同尺寸和规格的证件照需求，我们设计了灵活的尺寸生成算法。用户可以通过输入目标尺寸和规格，自动生成符合要求的证件照。同时，我们还提供了多种排版选项，方便用户进行打印和排版。

五、社区

我们分享了一些由社区构建的HivisionIDPhotos的有趣应用和扩展：

HivisionIDPhotos-ComfyUI	HivisionIDPhotos-wechat-weapp
ComfyUI证件照处理工作流	证件照微信小程序（JAVA后端+原生前端）

HivisionIDPhotos-Uniapp	HivisionIDPhotos-web
证件照微信小程序（uniapp）	证件照应用网页版

• HivisionIDPhotos-cpp

  : HivisionIDphotos C++版本，由 zjkhahah 构建

• ai-idphoto

  : HivisionIDPhotos-wechat-weapp 的uniapp多端兼容版，由 wmlcjj 贡献

• HivisionIDPhotos-uniapp-WeChat-gpto1

  : 由gpt-o1辅助完成开发的证件照微信小程序，由 jkm199 贡献

• HivisionIDPhotos-windows-GUI

  ：Windows客户端应用，由 zhaoyun0071 构建

• HivisionIDPhotos-NAS

  : 群晖NAS部署中文教程，由 ONG-Leo 贡献

六、安装部署

环境安装与依赖：

• Python >= 3.7（项目主要测试在 python 3.10）

• OS: Linux, Windows, MacOS

1. 克隆项目

git clone https://github.com/Zeyi-Lin/HivisionIDPhotos.gitcd HivisionIDPhotos

2. 安装依赖环境

建议 conda 创建一个 python3.10 虚拟环境后，执行以下命令

pip install -r requirements.txt pip install -r requirements-app.txt

3. 下载人像抠图模型权重文件

方式一：脚本下载

python scripts/download_model.py --models all#如需指定下载某个模型#python scripts/download_model.py --models modnet_photographic_portrait_matting

方式二：直接下载

模型均存到项目的hivision/creator/weights目录下：

人像抠图模型	介绍	下载
MODNet	MODNet 官方权重	下载 (24.7MB)
hivision_modnet	对纯色换底适配性更好的抠图模型	下载 (24.7MB)
rmbg-1.4	BRIA AI  开源的抠图模型	下载 (176.2MB)后重命名为rmbg-1.4.onnx
birefnet-v1-lite	ZhengPeng7  开源的抠图模型，拥有最好的分割精度	下载 (224MB)后重命名为birefnet-v1-lite.onnx

如果下载网速不顺利：前往SwanHub下载。

4. 人脸检测模型配置（可选）

拓展人脸检测模型	介绍	使用文档
MTCNN	离线 人脸检测模型，高性能CPU推理（毫秒级），为默认模型，检测精度较低	Clone此项目后直接使用
RetinaFace	离线 人脸检测模型，CPU推理速度中等（秒级），精度较高	下载 后放到hivision/creator/retinaface/weights目录下
Face++	旷视推出的在线人脸检测API，检测精度较高，官方文档	使用文档

5. 性能参考

测试环境为Mac M1 Max 64GB，非GPU加速，测试图片分辨率为 512x715(1) 与 764×1146(2)。

模型组合	内存占用	推理时长(1)	推理时长(2)
MODNet + mtcnn	410MB	0.207s	0.246s
MODNet + retinaface	405MB	0.571s	0.971s
birefnet-v1-lite + retinaface	6.20GB	7.063s	7.128s

6. GPU推理加速（可选）

在当前版本，可被英伟达GPU加速的模型为birefnet-v1-lite，并请确保你有16GB左右的显存。

如需使用英伟达GPU加速推理，在确保你已经安装CUDA与cuDNN后，根据onnxruntime-gpu文档找到对应的onnxruntime-gpu版本安装，以及根据pytorch官网找到对应的torch版本安装。

#假如你的电脑安装的是CUDA 12.x, cuDNN 8#安装torch是可选的，如果你始终配置不好cuDNN，那么试试安装torchpip install onnxruntime-gpu==1.18.0 pip install torch --index-url https://download.pytorch.org/whl/cu121

完成安装后，调用birefnet-v1-lite模型即可利用GPU加速推理。

TIPS: CUDA 支持向下兼容。比如你的 CUDA 版本为 12.6，torch 官方目前支持的最高版本为 12.4（<12.6），torch仍可以正常使用CUDA。

⚡️ 运行 Gradio Demo

python app.py

运行程序将生成一个本地 Web 页面，在页面中可完成证件照的操作与交互。

Python 推理

核心参数：

• -i

  : 输入图像路径

• -o

  : 保存图像路径

• -t

  : 推理类型，有idphoto、human_matting、add_background、generate_layout_photos可选

• --matting_model

  : 人像抠图模型权重选择

• --face_detect_model

  : 人脸检测模型选择

更多参数可通过python inference.py --help查看

1. 证件照制作

输入 1 张照片，获得 1 张标准证件照和 1 张高清证件照的 4 通道透明 png

python inference.py -i demo/images/test0.jpg -o ./idphoto.png --height 413 --width 295

2. 人像抠图

输入 1 张照片，获得 1张 4 通道透明 png

python inference.py -t human_matting -i demo/images/test0.jpg -o ./idphoto_matting.png --matting_model hivision_modnet

3. 透明图增加底色

输入 1 张 4 通道透明 png，获得 1 张增加了底色的 3通道图像

python inference.py -t add_background -i ./idphoto.png -o ./idphoto_ab.jpg  -c 4f83ce -k 30 -r 1

4. 得到六寸排版照

输入 1 张 3 通道照片，获得 1 张六寸排版照

python inference.py -t generate_layout_photos -i ./idphoto_ab.jpg -o ./idphoto_layout.jpg  --height 413 --width 295 -k 200

5. 证件照裁剪

输入 1 张 4 通道照片（抠图好的图像），获得 1 张标准证件照和 1 张高清证件照的 4 通道透明 png

python inference.py -t idphoto_crop -i ./idphoto_matting.png -o ./idphoto_crop.png --height 413 --width 295

⚡️ 部署 API 服务

启动后端

python deploy_api.py

请求 API 服务

详细请求方式请参考 API 文档，包含以下请求示例：

• cURL

• Python

🐳 Docker 部署

1. 拉取或构建镜像

以下方式三选一

方式一：拉取最新镜像：

docker pull linzeyi/hivision_idphotos

方式二：Dockrfile 直接构建镜像：

在确保将至少一个抠图模型权重文件放到hivision/creator/weights下后，在项目根目录执行：

docker build -t linzeyi/hivision_idphotos .

方式三：Docker compose 构建：

在确保将至少一个抠图模型权重文件放到hivision/creator/weights下后，在项目根目录下执行：

docker compose build

2. 运行服务

启动 Gradio Demo 服务

运行下面的命令，在你的本地访问 http://127.0.0.1:7860 即可使用。

docker run -d -p 7860:7860 linzeyi/hivision_idphotos

启动 API 后端服务

docker run -d -p 8080:8080 linzeyi/hivision_idphotos python3 deploy_api.py

两个服务同时启动

docker compose up -d

环境变量

本项目提供了一些额外的配置项，使用环境变量进行设置：

环境变量	类型	描述	示例
FACE_PLUS_API_KEY	可选	这是你在 Face++ 控制台申请的 API 密钥	7-fZStDJ····
FACE_PLUS_API_SECRET	可选	Face++ API密钥对应的Secret	VTee824E····
RUN_MODE	可选	运行模式，可选值为beast(野兽模式)。野兽模式下人脸检测和抠图模型将不释放内存，从而获得更快的二次推理速度。建议内存16GB以上尝试。	beast
DEFAULT_LANG	可选	Gradio Demo启动时的默认语言	en

docker使用环境变量示例：

docker run  -d -p 7860:7860 \    -e FACE_PLUS_API_KEY=7-fZStDJ···· \    -e FACE_PLUS_API_SECRET=VTee824E···· \    -e RUN_MODE=beast \    -e DEFAULT_LANG=en \    linzeyi/hivision_idphotos  

七、问题解决FAQ

1. 如何修改预设尺寸和颜色？

• 尺寸：修改size_list_CN.csv后再次运行 app.py 即可，其中第一列为尺寸名，第二列为高度，第三列为宽度。

• 颜色：修改color_list_CN.csv后再次运行 app.py 即可，其中第一列为颜色名，第二列为Hex值。

2. 如何修改水印字体？

1. 将字体文件放到hivision/plugin/font文件夹下

2. 修改hivision/plugin/watermark.py的font_file参数值为字体文件名

3. 如何添加社交媒体模板照？

1. 将模板图片放到hivision/plugin/template/assets文件夹下。模板图片是一个4通道的透明png。

2. 在hivision/plugin/template/assets/template_config.json文件中添加最新的模板信息，其中width为模板图宽度(px)，height为模板图高度(px)，anchor_points为模板中透明区域的四个角的坐标(px)；rotation为透明区域相对于垂直方向的旋转角度，>0为逆时针，<0为顺时针。

3. 在demo/processor.py的_generate_image_template函数中的TEMPLATE_NAME_LIST变量添加最新的模板名

4. 如何修改Gradio Demo的顶部导航栏？

• 修改demo/assets/title.md

5. 如何添加/修改「打印排版」中的尺寸？

• 修改demo/locales.py中的print_switch字典，添加/修改新的尺寸名称和尺寸参数，然后重新运行python app.py

八、结语

HivisionIDPhotos作为一个轻量级且高效的AI证件照制作工具，已经在多个方面取得了显著的成果和进展。通过不断优化和完善算法模型和工作流程，我们致力于为用户提供更加便捷、高效的证件照制作体验。未来，我们将继续探索和创新，推动HivisionIDPhotos在更多领域的应用和发展。如果你对我们的工作感兴趣或有任何建议，请随时与我们联系：zeyi.lin@swanhub.co。

项目地址：

https://github.com/Zeyi-Lin/HivisionIDPhotos