DOCSEARCHbyAlgolia
Submit Docs

HivisionIDPhoto

repository·master·Indexed 12 days ago

https://github.com/zeyi-lin/hivisionidphotos

An intelligent AI system for creating professional ID photos, featuring portrait matting, face detection, beautification, and layout generation. It supports multiple face detection models including MTCNN, RetinaFace, and Face++, and offers GPU acceleration for the birefnet-v1-lite model. The system can be used via a CLI, a Gradio-based web interface, or a dedicated API backend, and is deployable via Docker.

Tokens
18.1K
Snippets
56
Records
81
Agent score
96%

What's inside HivisionIDPhoto

  1. Configure face detection models

    master

    HivisionIDPhoto supports different face detection models depending on your needs for speed or accuracy:

    • MTCNN (Default): Offline model, high-performance CPU inference (millisecond level), but lower accuracy. Available immediately after cloning.
    • RetinaFace: Offline model, medium CPU speed (second level), higher accuracy. To use, download retinaface-resnet50.onnx and place it in hivision/creator/retinaface/weights.
    • Face++: Online API with high accuracy. Requires configuration via Face++ documentation. See docs/face++_CN.md for setup.

  5. Add Social Media Template Photos

    master

    To add new social media templates, follow these three steps:

    1. Add Image: Place a 4-channel transparent PNG template in hivision/plugin/template/assets.
    2. Configure Metadata: Add the template details to hivision/plugin/template/assets/template_config.json. Required keys:
      • width: Template width (px).
      • height: Template height (px).
      • anchor_points: Coordinates (px) of the four corners of the transparent area.
      • rotation: Rotation angle of the transparent area (degrees). >0 is counterclockwise, <0 is clockwise.
    3. Register Template: Add the template name to the TEMPLATE_NAME_LIST variable within the _generate_image_template function in demo/processor.py.

  6. Deploy via Docker

    master

    You can deploy the project using three methods:

    1. Pull the latest image: docker pull linzeyi/hivision_idphotos
    2. Build from Dockerfile: Ensure at least one matting model weight file is placed in hivision/creator/weights, then run docker build -t linzeyi/hivision_idphotos . in the project root.
    3. Build with Docker Compose: Ensure weights are in hivision/creator/weights, then run docker compose build.

    Running the services

    • Gradio Demo (UI): Access at http://127.0.0.1:7860
      docker run -d -p 7860:7860 linzeyi/hivision_idphotos
    • API Backend:
      docker run -d -p 8080:8080 linzeyi/hivision_idphotos python3 deploy_api.py
    • Both services simultaneously:
      docker compose up -d
    docker pull linzeyi/hivision_idphotos

  7. Set Face++ Environment Variables

    master

    Set the following environment variables to allow the application to authenticate with Face++. Replace Your_API_KEY and Your_API_SECRET with the actual values obtained from the Face++ console.

    # Linux / macOS
export FACE_PLUS_API_KEY="Your_API_KEY"
export FACE_PLUS_API_SECRET="Your_API_SECRET"
    # Windows
set FACE_PLUS_API_KEY="Your_API_KEY"
set FACE_PLUS_API_SECRET="Your_API_SECRET"

  8. Run Docker services

    master

    After building or pulling the image, you can run the services in different modes:

    Start Gradio Demo service (UI): Access via 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 (using Docker Compose):

    docker compose up -d

  9. Download model weights

    master

    HivisionIDPhoto requires pre-trained model weights. You can download all models using the provided script, or download specific files manually and place them in the hivision/creator/weights directory.

    # Download all models via script
python scripts/download_model.py --models all

  10. Run Python inference via CLI

    master

    Use inference.py to perform various image processing tasks via the command line.

    Core Parameters:

    • -i: Input image path
    • -o: Output image path
    • -t: Inference type. Options: idphoto, human_matting, add_background, generate_layout_photos
    • --matting_model: Selection of the portrait matting model weight
    • --face_detect_model: Selection of the face detection model

    For a full list of parameters, run python inference.py --help.

    Example 1: Create an ID photo Generates one standard ID photo and one high-resolution 4-channel transparent PNG.

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

    Example 2: Human Matting (Portrait Segmentation) Extracts the person from the background into a 4-channel transparent PNG.

    python inference.py -t human_matting -i demo/images/test0.jpg -o ./idphoto_matting.png --matting_model hivision_modnet
    # Create an ID photo
python inference.py -i demo/images/test0.jpg -o ./idphoto.png --height 413 --width 295

# Human matting
python inference.py -t human_matting -i demo/images/test0.jpg -o ./idphoto_matting.png --matting_model hivision_modnet

  11. Install and set up HivisionIDPhoto

    master

    To use HivisionIDPhoto, follow these steps to clone the repository, install dependencies, and download necessary model weights.

    Prerequisites

    • Python: >= 3.7 (3.10 is recommended)
    • OS: Linux, Windows, or MacOS

    1. Clone the repository

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

    2. Install dependencies

    It is recommended to use a conda virtual environment with Python 3.10.

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

    3. Download model weights

    You can download all models using the provided script:

    python scripts/download_model.py --models all

    Alternatively, you can download specific models (e.g., modnet_photographic_portrait_matting) or download them manually and place them in the hivision/creator/weights directory.

    git clone https://github.com/Zeyi-Lin/HivisionIDPhotos.git
cd  HivisionIDPhotos
pip install -r requirements.txt
pip install -r requirements-app.txt
python scripts/download_model.py --models all

  12. Enable GPU inference acceleration

    master

    The birefnet-v1-lite model can be accelerated using an NVIDIA GPU (requires ~16GB VRAM). Ensure CUDA 12.x and cuDNN 8 are installed, then install the appropriate onnxruntime-gpu and torch versions.

    # For systems with CUDA 12.x and cuDNN 8
pip install onnxruntime-gpu==1.18.0
pip install torch --index-url https://download.pytorch.org/whl/cu121