HivisionIDPhotos
HivisionIDPhotos copied to clipboard
⚡️HivisionIDPhotos: a lightweight and efficient AI ID photos tools. 一个轻量级的AI证件照制作算法。
相关项目:
- SwanLab:训练人像抠图模型全程用它来分析和监控,以及和实验室同学协作交流,大幅提升了训练效率。
目录
- 最近更新
- 项目简介
- 社区
- 准备工作
- Demo启动
- Python推理
- API服务部署
- Docker部署
- 联系我们
- FAQ
- 感谢支持
- License
- 引用
🤩 最近更新
-
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增加人脸旋转对齐功能,自定义尺寸输入支持毫米单位
-
2024.09.14: Gradio Demo增加自定义DPI功能,增加日语和韩语支持,增加调整亮度、对比度、锐度功能
-
2024.09.12: Gradio Demo增加美白功能 | API接口增加加水印、设置照片KB值大小、证件照裁切
项目简介
🚀 谢谢你对我们的工作感兴趣。您可能还想查看我们在图像领域的其他成果,欢迎来信:[email protected].
HivisionIDPhoto 旨在开发一种实用、系统性的证件照智能制作算法。
它利用一套完善的AI模型工作流程,实现对多种用户拍照场景的识别、抠图与证件照生成。
HivisionIDPhoto 可以做到:
- 轻量级抠图(纯离线,仅需 CPU 即可快速推理)
- 根据不同尺寸规格生成不同的标准证件照、六寸排版照
- 支持 纯离线 或 端云 推理
- 美颜
- 智能换正装(waiting)
如果 HivisionIDPhoto 对你有帮助,请 star 这个 repo 或推荐给你的朋友,解决证件照应急制作问题!
🏠 社区
我们分享了一些由社区构建的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.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。
⚡️ 运行 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. 如何修改水印字体?
- 将字体文件放到
hivision/plugin/font
文件夹下 - 修改
hivision/plugin/watermark.py
的font_file
参数值为字体文件名
3. 如何添加社交媒体模板照?
- 将模板图片放到
hivision/plugin/template/assets
文件夹下。模板图片是一个4通道的透明png。 - 在
hivision/plugin/template/assets/template_config.json
文件中添加最新的模板信息,其中width
为模板图宽度(px),height
为模板图高度(px),anchor_points
为模板中透明区域的四个角的坐标(px);rotation
为透明区域相对于垂直方向的旋转角度,>0为逆时针,<0为顺时针。 - 在
demo/processor.py
的_generate_image_template
函数中的TEMPLATE_NAME_LIST
变量添加最新的模板名
4. 如何修改Gradio Demo的顶部导航栏?
- 修改
demo/assets/title.md
📧 联系我们
如果您有任何问题,请发邮件至 [email protected]
🙏 感谢支持
贡献者们:
Zeyi-Lin、SAKURA-CAT、Feudalman、swpfY、Kaikaikaifang、ShaohonChen、KashiwaByte
📜 Lincese
This repository is licensed under the Apache-2.0 License.
📚 引用
如果您在研究或项目中使用了HivisionIDPhotos,请考虑引用我们的工作。您可以使用以下BibTeX条目:
@misc{hivisionidphotos,
title={{HivisionIDPhotos: A Lightweight and Efficient AI ID Photos Tool}},
author={Zeyi Lin and SwanLab Team},
year={2024},
publisher={GitHub},
url = {\url{https://github.com/Zeyi-Lin/HivisionIDPhotos}},
}