<div align="center"> <img alt="hivision_logo" src="assets/hivision_logo.png" width=120 height=120> <h1>HivisionIDPhoto</h1>

English / 中文 / 日本語 / 한국어

[![][release-shield]][release-link] [![][dockerhub-shield]][dockerhub-link] [![][github-stars-shield]][github-stars-link] [![][github-issues-shield]][github-issues-link] [![][github-contributors-shield]][github-contributors-link] [![][github-forks-shield]][github-forks-link] [![][license-shield]][license-link]
[![][wechat-shield]][wechat-link] [![][spaces-shield]][spaces-link] [![][swanhub-demo-shield]][swanhub-demo-link] [![][modelscope-shield]][modelscope-link] [![][modelers-shield]][modelers-link] [![][compshare-shield]][compshare-link] [![][atomgit-shield]][atomgit-link]

[![][trendshift-shield]][trendshift-link] [![][hellogithub-shield]][hellogithub-link]

<img src="assets/demoImage.jpg" width=900> </div>

相关项目：

• SwanLab：一个开源、现代化设计的深度学习训练跟踪与可视化工具，同时支持云端/离线使用，国内好用的Wandb平替；适配30+主流框架（PyTorch、HuggingFace Transformers、LLaMA Factory、Lightning等），欢迎使用！

<br>

目录

• 最近更新
• 项目简介
• 社区
• 准备工作
• Demo启动
• Python推理
• API服务部署
• Docker部署
• 联系我们
• FAQ
• 感谢支持
• License
• 引用

<br>

🤩 最近更新

• 在线体验： 、[![][modelscope-shield]][modelscope-link]、[![][modelers-shield]][modelers-link]、[![][compshare-shield]][compshare-link]

• 2024.11.20: Gradio Demo增加打印排版选项卡，支持六寸、五寸、A4、3R、4R五种排版尺寸

• 2024.11.16: 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 贡献 by zjkhahah

• 2024.09.16: Gradio Demo增加人脸旋转对齐功能，自定义尺寸输入支持毫米单位

<br>

项目简介

🚀 谢谢你对我们的工作感兴趣。您可能还想查看我们在图像领域的其他成果，欢迎来信:zeyi.lin@swanhub.co.

HivisionIDPhoto 旨在开发一种实用、系统性的证件照智能制作算法。

它利用一套完善的AI模型工作流程，实现对多种用户拍照场景的识别、抠图与证件照生成。

HivisionIDPhoto 可以做到：

1. 轻量级抠图（纯离线，仅需 CPU 即可快速推理）
2. 根据不同尺寸规格生成不同的标准证件照、六寸排版照
3. 支持 纯离线 或 端云 推理
4. 美颜
5. 智能换正装（waiting）

<div align="center"> <img src="assets/demo.png" width=900> </div>

---

如果 HivisionIDPhoto 对你有帮助，请 star 这个 repo 或推荐给你的朋友，解决证件照应急制作问题！

<br>

🏠 社区

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

| [HivisionIDPhotos-ComfyUI][community-hivision-comfyui] | [HivisionIDPhotos-wechat-weapp][community-hivision-wechat] | | :----------------------------------------------------------------------------------------------------------------------------------------------: | :------------------------------------------------------------------------------------------------------------------------------: | | <a href="https://github.com/AIFSH/HivisionIDPhotos-ComfyUI"> <img src="assets/comfyui.png" width="900" alt="ComfyUI workflow"> </a> | <a href="https://github.com/no1xuan/HivisionIDPhotos-wechat-weapp"> <img src="assets/community-wechat-miniprogram.png" width="900" alt="ComfyUI workflow"> </a> | |ComfyUI证件照处理工作流 | 证件照微信小程序（JAVA后端+原生前端） |

| [HivisionIDPhotos-Uniapp][community-hivision-uniapp] | HivisionIDPhotos-web| | :------------------------------------------------------------------------------------------------------------------------------: | :------------------------------------------------------------------------------------------------------------------------------: | | <a href="https://github.com/soulerror/HivisionIDPhotos-Uniapp"> <img src="assets/community-uniapp-wechat-miniprogram.png" width="900" alt="HivisionIDPhotos-uniapp"> </a> | <a href="https://github.com/jkm199/HivisionIDPhotos-web"> <img src="assets/community-web.png" width="900" alt="HivisionIDPhotos-uniapp"> </a> | | 证件照微信小程序（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 贡献

<br>

🔧 准备工作

环境安装与依赖：

• Python >= 3.7（项目主要测试在 python 3.10）
• OS: Linux, Windows, MacOS

1. 克隆项目

git clone https://github.com/Zeyi-Lin/HivisionIDPhotos.git
cd  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，那么试试安装torch
pip 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。

<br>

⚡️ 运行 Gradio Demo

python app.py

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

<img src="assets/harry.png" width=900> <br>

🚀 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

<br>

⚡️ 部署 API 服务

启动后端

python deploy_api.py

请求 API 服务

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

• cURL
• Python

<br>

🐳 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_idphot