HivisionIDPhotos
Zeyi-Lin/HivisionIDPhotos加载项目详情…
本应用为开源项目，仅供学习研究，请遵守其开源协议。
微信扫码咨询客服
POMOAI — 让开源 AI 即刻运行
加载项目详情…
本应用为开源项目，仅供学习研究，请遵守其开源协议。
你有没有过这样的经历：
报名参加一场重要考试，或者办理一张新的银行卡，却被告知需要提交「白底证件照」，而你手头只有一张自拍。或者，你好不容易去照相馆拍了照片，却发现尺寸比例不对，还得重新跑一趟。这种来回折腾的烦恼，催生了一个让人眼前一亮的开源项目——HivisionIDPhotos。
这个由开发者 Zeyi-Lin 创建的 Python 项目，自 2023 年开源以来，已在 GitHub 斩获超过 21,000 颗星标，成为 AI 图像处理领域的现象级工具。它解决的问题非常直接：把一张普通照片，变成符合官方规范的证件照——全程不需要复杂的操作，也不需要昂贵的商业软件。
图1：项目 Logo
HivisionIDPhotos 的设计理念可以用一个词概括：专注。它没有试图成为全能型图像处理工具，而是把「证件照制作」这一个场景做到极致。整体架构分为三个核心模块：
（一）人像抠图模块（human_matting）
这是整个流水线的第一步，也是最关键的一步。项目内置了多套人像分割（Portrait Matting）ONNX 模型，存放在 hivision/creator/weights/ 目录下，支持 ModNet、RMBG-1.4 等主流模型。模型推理基于 ONNX Runtime，这意味着即使没有 CUDA 加速，也能在 CPU 上完成推理；对有 GPU 的用户，则可以通过 ONNX Runtime 的 GPU Provider 实现加速。项目使用 Python 3.10 + OpenCV（opencv-python >= 4.8）作为图像处理基础库，numpy 做数值计算，确保了跨平台兼容性。
抠图的效果直接决定了最终证件照的质量。对于边缘细节（头发丝、配饰等），项目采用了额外的人像边缘优化策略，避免了传统抠图常见的「锯齿」和「毛边」问题。
（二）人脸检测模块（face_detector）
抠图完成后，系统需要知道「人脸在哪里」，才能进行后续的比例计算和裁剪。项目支持三种人脸检测方案：
这种多方案并存的设计很聪明——个人用户可以用免费的 MTCNN，企业用户可以接入 Face++ 获得更高精度。
（三）布局计算与图像生成（layout_calculator + photo_adjuster）
拿到人脸位置和抠图结果后，系统根据预设的证件照规格（一寸、二寸等）计算裁剪区域，支持自定义尺寸（包括毫米单位），还能自动调整人脸在画面中的位置，确保符合「眼睛处于画面1/3处」等摄影构图规范。最终输出的照片还可以进行 DPI 设置，满足打印需求。
打开 HivisionIDPhotos 的 Gradio Web UI，映入眼帘的是一个清晰的功能面板。它不只是一个「上传图片→生成证件照」的单向工具，而是一套完整的证件照处理工作流：
图2：Gradio Web UI 主界面
1. 证件照制作
上传任意照片（自拍、相机照皆可），选择目标尺寸（一寸、二寸、美签、欧签等常见规格）和背景颜色（白底、蓝底、红底及自定义 HEX 颜色），系统自动完成抠图→换底色→比例调整→输出的全流程。处理结果可以直接下载，也可以一键发送到「排版照」模块。
2. 人像抠图
单独使用抠图功能，将人物从原图中分离出来，适用于需要透明背景 PNG 素材的场景。这个功能在电商、媒体、设计师群体中也有广泛需求。
3. 透明图增加底色
为已有透明背景的人像图添加指定颜色的背景，快速获得合规证件照。
4. 六寸排版照
这是非常实用的一个功能——很多人不知道的是，照相馆打印证件照通常是用「六寸相纸」（6×8英寸）排版后裁切。项目内置了标准六寸排版模板，一键将多张证件照排列到一张标准相纸上，可以直接拿去冲洗，省去了手动排版的麻烦。
图3：证件照制作效果示例
5. 美式证件照特殊支持
项目还特别支持美式证件照的规格（50mm×50mm，白底），并针对美国签证照片等特殊需求提供了专门的背景色选项。这体现了开发者的细致考量——很多同类工具只考虑了亚洲市场的规格需求。
对于非技术用户来说，「安装 Python 环境」「下载模型权重」「配置依赖」这些步骤可能让人望而却步。HivisionIDPhotos 提供了开箱即用的 Docker 部署方案，彻底消除了这个门槛。
项目根目录包含：
部署流程极度简化：
git clone https://github.com/Zeyi-Lin/HivisionIDPhotos.git
cd HivisionIDPhotos
docker-compose up -d
5-10 分钟后，打开浏览器访问 http://localhost:7860，即可看到完整的 Gradio Web UI。整个过程不需要配置任何环境变量，不需要安装任何本地依赖。
图4：原图与证件照处理效果对比
除了 Web UI，项目还提供了完整的 REST API 服务（deploy_api.py），基于 FastAPI + Starlette 构建，兼容 OpenAPI/Swagger 文档。API 支持：
开发者可以将这个 API 集成到自己的业务系统中，比如：报名平台自动生成合规证件照、HR 系统批量处理员工照片、身份证办理自助终端等。Starlette 的 CORS 中间件默认允许跨域调用，降低了前后端分离架构的集成成本。
从代码结构来看，项目采用了分层模块化设计：
hivision/：核心算法层（抠图、人脸检测、布局计算），与界面完全解耦demo/：展示层（Gradio UI、处理器胶水代码）app.py：Web UI 入口deploy_api.py：API 服务入口这种架构的好处是：即使 Gradio 不再流行，核心算法也可以无缝迁移到其他 UI 框架（如 Streamlit、Flask、甚至小程序）。
项目还支持插件机制（hivision/plugin/ 目录），允许用户扩展抠图模型种类和布局模板，满足个性化需求。README 中详细说明了如何添加自定义尺寸规格和水印字体，这部分文档质量很高，降低了二次开发的门槛。
代码质量方面，模块之间职责清晰，错误处理完善（hivision/error.py 定义了 FaceError 等异常类型），整体符合生产级代码水准。测试覆盖虽然不是项目的重点，但考虑到这是一个快速迭代的工具型项目，现有代码结构为后续补充测试留好了空间。
作为一个轻量级开源项目，HivisionIDPhotos 也有它的局限：
1. 对极端照片的处理能力有限
对于侧脸、遮挡严重（用手遮住部分脸）、光线极暗或过曝的照片，抠图和检测效果会明显下降。AI 模型的能力边界在这里体现得很清楚——它无法「无中生有」地重建被遮挡的人脸信息。
2. 人脸检测精度依赖模型选择
默认的 MTCNN 在简单场景下够用，但对于小脸、模糊脸、多人合照中截取单人等场景，RetinaFace 或 Face++ 是更可靠的选择——但这两者都需要额外的配置或付费。
3. GPU 加速需要额外配置
虽然项目支持 ONNX Runtime GPU 推理，但默认安装的 requirements.txt 不会自动启用 GPU 支持，需要额外安装 CUDA 版本的 ONNX Runtime 包。对于没有 NVIDIA 显卡的用户，CPU 推理速度大约在 5-10 秒/张，在可接受范围内，但无法实现实时处理。
HivisionIDPhotos 的成功，折射出一个趋势：AI 工具正在从「高深莫测」走向「随手可用」。
过去，AI 抠图、人像处理是需要专业软件（Photoshop）和专业技能的事情。现在，一个 Python 脚本就能完成同等效果。这降低了内容创作的技术门槛，也让 AI 技术在日常生活中变得更可见。
更重要的是，这个项目带动了一个小型生态的诞生：
从 21,000 颗星标和持续活跃的社区贡献来看，HivisionIDPhotos 不仅仅是解决了一个具体问题，更代表了开源 AI 工具的一种成功范式：垂直场景 + 简单易用 + 开放扩展。
如果你正在寻找一个可以快速集成到业务中的证件照处理方案，或者想了解如何用 Python 构建生产级 AI 图像处理流程，HivisionIDPhotos 都是一个值得研究的目标项目。