HivisionIDPhotos README

The project's README from github.com/Zeyi-Lin/HivisionIDPhotos. As one markdown file: README.md.

hivision_logo

HivisionIDPhoto

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


相关项目：

  • TRIO：一个新型的AI计算平台（Tinker Like），让模型训练者无需维护复杂GPU基础设施，在个人电脑就可以轻松做llm sft/rl训练，训推均按token计费而非GPU时，支持弹性扩展，同时开20个实验不再困难。

目录


🤩 最近更新


项目简介

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

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

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

HivisionIDPhoto 可以做到：

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

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


🏠 社区

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

HivisionIDPhotos-ComfyUI HivisionIDPhotos-wechat-weapp
ComfyUI workflow ComfyUI workflow
ComfyUI证件照处理工作流 证件照微信小程序（JAVA后端+原生前端）
HivisionIDPhotos-Uniapp HivisionIDPhotos-web
HivisionIDPhotos-uniapp HivisionIDPhotos-uniapp
证件照微信小程序（uniapp） 证件照应用网页版

🔧 准备工作

环境安装与依赖：

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 推理

核心参数：

更多参数可通过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/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. 如何修改预设尺寸和颜色？

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的顶部导航栏？

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


📧 联系我们

如果您有任何问题，请发邮件至 [email protected]


🙏 感谢支持

Stargazers repo roster for @Zeyi-Lin/HivisionIDPhotos

Forkers repo roster for @Zeyi-Lin/HivisionIDPhotos

Star History Chart

贡献者们：

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}},
}

HivisionIDPhotos (Zeyi-Lin/HivisionIDPhotos)

Searching Database…

21.6K ·GitHub
HivisionIDPhotos
这是什么?一个开源的 AI 证件照制作工具:它用抠图模型把人从普通照片里抠出来,并生成各种尺寸、背景颜色符合要求的标准证件照。
它是需要安装的应用、一个库,还是网页服务?既是本地 Gradio 网页应用,也是 Python 命令行工具(inference.py),还提供 FastAPI 接口服务和 Docker 镜像;社区版本还有 Windows 图形界面客户端和微信小程序。
我怎么把它跑起来?克隆仓库,配好 Python 3.7+(推荐用 conda 装 3.10),安装依赖,把一个抠图模型权重放到 hivision/creator/weights 目录,然后运行 app.py —— 或者直接拉取 Docker 镜像,用 docker compose 也行。
在它能用之前,我需要装好什么?需要 Python 3.7+,外加一个抠图模型权重(MODNet 只有 24.7MB;注重精度的 birefnet-v1-lite 是 224MB)。MTCNN 人脸检测开箱即用;RetinaFace 和 Face++ API 是可选的增强项。
没有显卡的笔记本能跑吗?能 —— 在 Mac M1 Max 上纯 CPU 运行,MODNet + MTCNN 每张照片约 0.2 秒,内存占用约 410MB。更清晰的 birefnet-v1-lite 负担更重(约 6.2GB 内存、约 7 秒),而且用它做 GPU 加速需要约 16GB 显存。
它能生成哪些尺寸和排版?一次输入会得到一张标准证件照和一张高清证件照,都是带透明通道的 PNG 格式;预设尺寸存放在一个可编辑的 CSV 里,排版标签页可以把照片排成 6 寸、5 寸、A4、3R 和 4R 相纸的打印版式,并支持 300DPI 下载。
如果我想开发自己的应用,它的 API 提供什么?一个 FastAPI 后端,可以独立运行也可以放在 Docker 里,接受 base64 图片输入,并提供 DPI、人脸对齐和美颜等参数;文档里附有 cURL 和 Python 请求示例。
除了把人抠出来,它还能做什么?还有:美颜、人脸转正对齐、通过输入 HEX 值自定义背景色、加水印以及社交媒体模板照片;智能换装已公布,但仍标记为'等待中'。
有没有基于它做好的现成应用?有好几个社区项目:一个 ComfyUI 工作流、微信小程序(原生版和 uniapp 版)、一个网页版、一个 C++ 移植版、一个 Windows 图形界面客户端,以及一份群晖 NAS 部署指南 —— 全部都在 README 里附了链接。
What are similar projects?insightface, rembg, face_recognition, AutoFigure-Edit, lama, facenet, video-subtitle-remover, manga-image-translator
Which topics is it in?unet, face-recognition, face-detection, demo, cnn, segmentation, tools, gradio, onnx, lightweight, fastapi, image-processing
Creator
Zeyi-Lin
Size
47.8 MB
Stars
21.6K
Updated
CommitJul 03Releasev1.3.1Jan 21
Age
3y
Commits · 90 Days