HivisionIDPhoto

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

👋 加入我们的微信群

相关项目：

SwanLab：训练人像抠图模型全程用它来分析和监控，以及和实验室同学协作交流，大幅提升了训练效率。

🤩 最近更新

在线体验：、、
2024.09.14: Gradio Demo增加自定义DPI功能，增加日语和韩语支持，增加调整亮度、对比度、锐度功能
2024.09.12: Gradio Demo增加美白功能 | API接口增加加水印、设置照片KB值大小、证件照裁切
2024.09.11: Gradio Demo增加透明图显示与下载功能
2024.09.10: 增加新的人脸检测模型 Retinaface-resnet50，以稍弱于mtcnn的速度换取更高的检测精度，推荐使用
2024.09.09: 增加新的抠图模型 BiRefNet-v1-lite | Gradio增加高级参数设置和水印选项卡
2024.09.08: 增加新的抠图模型 RMBG-1.4 | ComfyUI工作流 - HivisionIDPhotos-ComfyUI 贡献 by AIFSH
2024.09.07: 增加人脸检测API选项 Face++，实现更高精度的人脸检测
2024.09.06: 增加新的抠图模型 modnet_photographic_portrait_matting.onnx

项目简介

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

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

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

HivisionIDPhoto 可以做到：

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

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

🏠 社区

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

HivisionIDPhotos-windows-GUI：Windows客户端应用，由 zhaoyun0071 构建
HivisionIDPhotos-ComfyUI：ComfyUI证件照处理工作流，由 AIFSH 构建

HivisionIDPhotos-NAS: 群晖NAS部署中文教程，由 ONG-Leo 贡献
HivisionIDPhotos-wechat-weapp: 微信证件照小程序，基于HivisionIDphotos算法驱动，由 no1xuan 贡献

🔧 准备工作

环境安装与依赖：

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

方式二：直接下载

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

modnet_photographic_portrait_matting.onnx (24.7MB): MODNet官方权重，下载
hivision_modnet.onnx (24.7MB): 对纯色换底适配性更好的抠图模型，下载
rmbg-1.4.onnx (176.2MB): BRIA AI 开源的抠图模型，下载后重命名为rmbg-1.4.onnx
birefnet-v1-lite.onnx(224MB): ZhengPeng7 开源的抠图模型，下载后重命名为birefnet-v1-lite.onnx

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

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

5. 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 文档，包含以下请求示例：

🐳 Docker 部署

1. 拉取或构建镜像

以下方式三选一

方式一：拉取最新镜像：

docker pull linzeyi/hivision_idphotos

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

在确保将模型权重文件hivision_modnet.onnx放到hivision/creator/weights下后，在项目根目录执行：

docker build -t linzeyi/hivision_idphotos .

方式三：Docker compose 构建：

确保将模型权重文件 hivision_modnet.onnx 放在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····`

docker使用环境变量示例：

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

📖 引用项目

MTCNN:

@software{ipazc_mtcnn_2021,
    author = {ipazc},
    title = {{MTCNN}},
    url = {https://github.com/ipazc/mtcnn},
    year = {2021},
    publisher = {GitHub}
}

ModNet:

@software{zhkkke_modnet_2021,
    author = {ZHKKKe},
    title = {{ModNet}},
    url = {https://github.com/ZHKKKe/MODNet},
    year = {2021},
    publisher = {GitHub}
}

Q&A

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

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

如何修改水印字体？

将字体文件放到hivision/plugin/font文件夹下
修改hivision/plugin/watermark.py的font_file参数值为字体文件名

📧 联系我们

如果您有任何问题，请发邮件至 zeyi.lin@swanhub.co

贡献者

Zeyi-Lin、SAKURA-CAT、Feudalman、swpfY、Kaikaikaifang、ShaohonChen、KashiwaByte

感谢支持

Lincese

This repository is licensed under the Apache-2.0 License.

antonizhubar/HivisionIDPhotos