HivisionIDPhoto

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

Related Projects:

• SwanLab: Used for analyzing, monitoring, and collaborating with lab colleagues throughout the training of portrait matting models, significantly improving training efficiency.

Table of Contents

• Project Updates
• Overview
• Preparation
• Running Demo
• Python Inference
• API Service Deployment
• Docker Deployment
• Links
• Contact Us
• Contributors

🤩 Project Updates

• Online Experience: 、

• 2024.09.08: Added a new background removal model RMBG-1.4 | ComfyUI Workflow - HivisionIDPhotos-ComfyUI contributed by AIFSH

• 2024.09.07: Added Face Detection API Option Face++ for higher accuracy 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 Photo Size Adjustment

• 2023.12.01: Updated API Deployment (based on fastapi)

• 2023.06.20: Updated Preset Size Menu

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 contact us at: zeyi.lin@swanhub.co.

HivisionIDPhoto aims to develop a practical and systematic algorithm for intelligent ID photo creation.

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

HivisionIDPhoto can achieve:

1. Lightweight matting (purely offline, fast inference with just CPU)
2. Generating standard ID photos of different sizes and six-inch layout photos
3. Supporting pure offline or edge-cloud inference
4. Beauty enhancement (waiting)
5. Intelligent formal wear swapping (waiting)

---

If HivisionIDPhoto is helpful to you, please star this repo or recommend it to your friends to solve urgent ID photo creation issues!

🔧 Preparation

Environment installation and dependencies:

• Python >= 3.7 (mainly 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 Dependencies

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

Option 1: Script Download

python scripts/download_model.py --models all

Option 2: Direct Download

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

• modnet_photographic_portrait_matting.onnx (24.7MB): Official weights from MODNet, Download
• hivision_modnet.onnx (24.7MB): A matting model better suited for solid background swapping, Download
• mnn_hivision_modnet.mnn (24.7MB): MNN converted matting model by zjkhahah, Download
• rmbg-1.4.onnx (176.2MB): Open source matting model from BRIA AI, download it and rename it to rmbg-1.4.onnx.

4. Face Detection Model Configuration

This is an optional step.

Extended Face Detection Model	Description	Documentation
MTCNN	Offline face detection model, high-performance CPU inference, default model with lower detection accuracy	Directly use after cloning this project
Face++	An online face detection API launched by Megvii, with higher detection accuracy, Official Documentation	Usage Documentation

🚀 Running Gradio Demo

python app.py

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

🚀 Python Inference

Core parameters:

• -i: Input image path
• -o: Output image path
• -t: Inference type, options include idphoto, human_matting, add_background, generate_layout_photos
• --matting_model: Selection of portrait matting model weights, options are hivision_modnet, modnet_photographic_portrait_matting

For more parameters, you can check using python inference.py --help.

1. ID Photo Creation

Input 1 photo to obtain 1 standard ID photo and 1 high-definition ID photo in 4-channel transparent PNG format.

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. Adding 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 ./idhoto_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 ./idhoto_ab.jpg -o ./idhoto_layout.jpg  --height 413 --width 295 -k 200

⚡️ Deploying API Service

Start Backend

python deploy_api.py

Request API Service - Python Request

For request methods, please refer to the API Documentation, including cURL, Python, Java, Javascript request examples.

1. ID Photo Creation

Input 1 photo to obtain 1 standard ID photo and 1 high-definition ID photo in 4-channel transparent PNG format.

import requests

url = "http://127.0.0.1:8080/idphoto"
input_image_path = "demo/images/test.jpg"

files = {"input_image": open(input_image_path, "rb")}
data = {"height": 413, "width": 295}

response = requests.post(url, files=files, data=data).json()

# response is a json-formatted dictionary containing status, image_base64_standard, and image_base64_hd
print(response)

2. Adding Background Color

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

import requests

url = "http://127.0.0.1:8080/add_background"
input_image_path = "test.png"

files = {"input_image": open(input_image_path, "rb")}
data = {"color": '638cce', 'kb': None}

response = requests.post(url, files=files, data=data).json()

# response is a json-formatted dictionary containing status and image_base64
print(response)

3. Obtain Six-Inch Layout Photo

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

import requests

url = "http://127.0.0.1:8080/generate_layout_photos"
input_image_path = "test.jpg"

files = {"input_image": open(input_image_path, "rb")}
data = {"height": 413, "width": 295, "kb": 200}

response = requests.post(url, files=files, data=data).json()

# response is a json-formatted dictionary containing status and image_base64
print(response)

🐳 Docker Deployment

1. Pull or Build the Image

Choose one of the following three methods.

Option 1: Pull the latest image:

docker pull linzeyi/hivision_idphotos

Option 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 .

Option 3: Build using Docker Compose:

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 compose build

2. Run the Service

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 that can be set using environment variables:

Environment Variable	Type	Description	Example
FACE_PLUS_API_KEY	Optional	This is the API key you applied for in the Face++ console	7-fZStDJ····
FACE_PLUS_API_SECRET	Optional	The Secret corresponding to the Face++ API key	VTee824E····

Example of using environment variables with Docker:

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

🌲 Links

• HivisionIDPhotos-windows-GUI

📖 Citations

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_CN.csv and run app.py again, where the first column is the size name, the second column is height, and the third column is 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