HivisionIDPhotos/README_EN.md

HivisionIDPhoto

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

Related Projects：

• SwanLab: Used throughout the training of the portrait matting model for analysis and monitoring, as well as collaboration with lab colleagues, significantly improving training efficiency.

Table of Contents

• Recent Updates
• Project Overview
• Community
• Preparation
• Demo Startup
• Python Inference
• API Service Deployment
• Docker Deployment
• Contact Us
• Contributors

🤩 Recent Updates

• Online Experience: 、

• 2024.09.09: Added new Matting Model BiRefNet-v1-lite | Gradio added advanced parameter settings tab

• 2024.09.08: Added new Matting Model RMBG-1.4 | ComfyUI Workflow - HivisionIDPhotos-ComfyUI contributed by AIFSH

• 2024.09.07: Added Face Detection API Option Face++, achieving higher precision in face detection

• 2024.09.06: Added new matting model modnet_photographic_portrait_matting.onnx

• 2024.09.05: Updated Restful API Documentation

• 2024.09.02: Updated Adjust Photo KB Size, DockerHub

• 2023.12.01: Updated API Deployment (based on fastapi)

Project Overview

🚀 Thank you for your interest in our work. You may also want to check out our other achievements in the field of image processing, feel free to reach out: zeyi.lin@swanhub.co.

HivisionIDPhoto aims to develop a practical and systematic intelligent algorithm for producing ID photos.

It utilizes a comprehensive AI model workflow to recognize various user photo-taking scenarios, perform matting, and generate ID photos.

HivisionIDPhoto can achieve:

1. Lightweight matting (purely offline, fast inference with CPU only)
2. Generate standard ID photos and six-inch layout photos based on different size specifications
3. Support pure offline or edge-cloud inference
4. Beauty effects (waiting)
5. Intelligent formal wear change (waiting)

---

If HivisionIDPhoto helps you, please star this repo or recommend it to your friends to solve the urgent ID photo production problem!

🏠 Community

We have shared some interesting applications and extensions of HivisionIDPhotos built by the community:

• HivisionIDPhotos-windows-GUI: Windows client application built by zhaoyun0071
• HivisionIDPhotos-ComfyUI: ComfyUI ID photo processing workflow built by AIFSH

🔧 Preparation

Environment installation and dependencies:

• Python >= 3.7 (project primarily tested on Python 3.10)
• OS: Linux, Windows, MacOS

1. Clone the Project

git clone https://github.com/Zeyi-Lin/HivisionIDPhotos.git
cd  HivisionIDPhotos

2. Install Dependency Environment

It is recommended to create a python3.10 virtual environment using conda, then execute the following commands

pip install -r requirements.txt
pip install -r requirements-app.txt

3. Download Weight Files

Method 1: Script Download

python scripts/download_model.py --models all

Method 2: Direct Download

Store in the project's hivision/creator/weights directory:

• modnet_photographic_portrait_matting.onnx (24.7MB): Official weights of MODNet, download
• hivision_modnet.onnx (24.7MB): Matting model with better adaptability for pure color background replacement, download
• rmbg-1.4.onnx (176.2MB): Open-source matting model from BRIA AI, download and rename to rmbg-1.4.onnx
• birefnet-v1-lite.onnx(224MB): Open-source matting model from ZhengPeng7, download and rename to birefnet-v1-lite.onnx

4. Face Detection Model Configuration (Optional)

Extended Face Detection Model	Description	Documentation
MTCNN	Offline face detection model, high-performance CPU inference, default model, lower detection accuracy	Use it directly after cloning this project
Face++	Online face detection API launched by Megvii, higher detection accuracy, official documentation	Usage Documentation

5. GPU Inference Acceleration (Optional)

If you need to use NVIDIA GPU for accelerated inference, ensure that you have installed CUDA and cuDNN, then find the corresponding onnxruntime-gpu version to install according to the documentation, for example:

# CUDA 12.x, cuDNN 8
pip install onnxruntime-gpu==1.18.0

After completing this, calling models like birefnet-v1-lite will utilize GPU acceleration for inference.

🚀 Run Gradio Demo

python app.py

Running the program will generate a local web page where you can perform operations and interact with ID photos.

🚀 Python Inference

Core parameters:

• -i: Input image path
• -o: Save image path
• -t: Inference type, options include idphoto, human_matting, add_background, generate_layout_photos
• --matting_model: Selection of portrait matting model weights
• --face_detect_model: Selection of face detection model

More parameters can be viewed by running python inference.py --help

1. ID Photo Production

Input 1 photo to obtain 1 standard ID photo and 1 high-definition ID photo in 4-channel transparent png

python inference.py -i demo/images/test.jpg -o ./idphoto.png --height 413 --width 295

2. Portrait Matting

python inference.py -t human_matting -i demo/images/test.jpg -o ./idphoto_matting.png --matting_model hivision_modnet

3. Add Background Color to Transparent Image

Input 1 4-channel transparent png to obtain 1 image with added background color

python inference.py -t add_background -i ./idphoto.png -o ./idphoto_ab.jpg  -c 4f83ce -k 30 -r 1

4. Obtain Six-Inch Layout Photo

Input 1 3-channel photo to obtain 1 six-inch layout photo

python inference.py -t generate_layout_photos -i ./idphoto_ab.jpg -o ./idphoto_layout.jpg  --height 413 --width 295 -k 200

⚡️ Deploy API Service

Start Backend

python deploy_api.py

Request API Service

For detailed request methods, please refer to the API Documentation, which includes the following request examples:

• cURL
• Python
• Java
• Javascript

🐳 Docker Deployment

1. Pull or Build Image

Choose one of the following methods

Method 1: Pull the latest image:

docker pull linzeyi/hivision_idphotos

Method 2: Directly build the image from Dockerfile:

After ensuring that the model weight file hivision_modnet.onnx is placed in hivision/creator/weights, execute the following in the project root directory:

docker build -t linzeyi/hivision_idphotos .

Method 3: Build using Docker Compose:

Ensure that the model weight file hivision_modnet.onnx is placed in hivision/creator/weights, then execute the following in the project root directory:

docker compose build

2. Run Services

Start Gradio Demo Service

Run the following command, and you can access it locally at http://127.0.0.1:7860.

docker run -d -p 7860:7860 linzeyi/hivision_idphotos

Start API Backend Service

docker run -d -p 8080:8080 linzeyi/hivision_idphotos python3 deploy_api.py

Start Both Services Simultaneously

docker compose up -d

Environment Variables

This project provides some additional configuration options, which can be set using environment variables:

Environment Variable	Type	Description	Example
FACE_PLUS_API_KEY	Optional	This is your API key obtained from the Face++ console	7-fZStDJ····
FACE_PLUS_API_SECRET	Optional	Secret corresponding to the Face++ API key	VTee824E····

Example of using environment variables in Docker:

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

📖 Cite Projects

1. MTCNN:

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

2. ModNet:

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

💻 Development Tips

1. How to Modify Preset Sizes?

Modify size_list_EN.csv and then run app.py again, where the first column is the size name, the second column is the height, and the third column is the width.

📧 Contact Us

If you have any questions, please email zeyi.lin@swanhub.co

Contributors

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

StarHistory