Skip to content

Latest commit

 

History

History
401 lines (267 loc) · 15.2 KB

README_EN.md

File metadata and controls

401 lines (267 loc) · 15.2 KB
hivision_logo

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

  • Online Experience: SwanHub Demo、Spaces

  • 2024.09.11: Added transparent image display and download feature to Gradio Demo.

  • 2024.09.10: Added a new face detection model Retinaface-resnet50, which offers higher detection accuracy at a slightly slower speed compared to mtcnn. Recommended for use.

  • 2024.09.09: Added a new Background Removal Model BiRefNet-v1-lite | Gradio added Advanced Parameter Settings and Watermark tabs

  • 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


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: [email protected].

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:


🔧 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
RetinaFace Offline face detection model, moderate CPU inference speed (in seconds), and high accuracy Download and place it in the hivision/creator/retinaface/weights directory
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:


🐳 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}
}
  1. ModNet:
@software{zhkkke_modnet_2021,
    author = {ZHKKKe},
    title = {{ModNet}},
    url = {https://github.com/ZHKKKe/MODNet},
    year = {2021},
    publisher = {GitHub}
}

💻 Development Tips

How to modify preset sizes and colors?

  • Size: After modifying size_list_EN.csv, run app.py again. The first column is the size name, the second column is the height, and the third column is the width.
  • Color: After modifying color_list_EN.csv, run app.py again. The first column is the color name, and the second column is the Hex value.

How to Change the Watermark Font?

  1. Place the font file in the hivision/plugin/font folder.
  2. Change the font_file parameter value in hivision/plugin/watermark.py to the name of the font file.

📧 Contact Us

If you have any questions, please email [email protected]


Contributors

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


StarHistory

Star History Chart