HivisionIDPhoto: An Offline-First AI Pipeline for Standard ID Photos

What It Solves and Who It Is For

HivisionIDPhoto addresses a narrow but recurring problem: turning a casual portrait into a compliant ID photo with the correct background color, dimensions, and print layout. Instead of relying on a photo booth or a cloud service, this project provides a local pipeline that does matting, face detection, and layout generation. The intended users are developers who want to embed ID photo generation into their own applications, such as a WeChat mini-program or a web service. The README lists community projects that do exactly that, including a ComfyUI workflow and several mini-program implementations. It is also useful for individuals who need an emergency ID photo and have Python installed. The project's claim of 'lightweight' is central: the default matting model runs on CPU in about 0.2 seconds on the test hardware, which makes it practical for real-time or near-real-time use.

The Pipeline: Matting, Face Detection, and Layout

The architecture is a three-stage pipeline. First, a matting model separates the subject from the background. The README lists four matting models: MODNet, hivision_modnet, rmbg-1.4, and birefnet-v1-lite. Each is an ONNX model that you download separately. Second, a face detection model locates the face to determine the proper crop and alignment. The default is MTCNN, which is described as millisecond-speed but lower accuracy. RetinaFace is a slower but more accurate offline alternative, and Face++ is an online API with higher accuracy. Third, the system generates the final ID photo according to specified size parameters, including custom dimensions in millimeters and standard print layouts like six-inch or A4. The pipeline is modular: you can mix and match matting and face detection models. For example, you can use MODNet for matting and RetinaFace for detection, or switch to birefnet-v1-lite for better segmentation. This modularity is a strength, but it also means you must understand the trade-offs between speed and quality.

Getting It Running: Commands and Configuration

Setup is straightforward if you are comfortable with Python. The README instructs you to clone the repository, then install dependencies with two pip commands: 'pip install -r requirements.txt' and 'pip install -r requirements-app.txt'. You need Python 3.7 or higher, with 3.10 as the primary test version. After that, you must download the model weights. The recommended way is to run 'python scripts/download_model.py --models all', which fetches all matting models. Alternatively, you can download individual ONNX files and place them in 'hivision/creator/weights'. For face detection, MTCNN is included by default, but RetinaFace requires a manual download to 'hivision/creator/retinaface/weights'. The README also documents a Gradio demo that you can launch, and an API service for deployment. The API supports parameters like 'dpi' and 'face_alignment', and recent versions added base64 image input and a beauty filter parameter. This gives you a clear path from local experimentation to a deployed service.

Performance Reality: Speed vs. Memory

The README includes a performance table from a Mac M1 Max with 64GB RAM, using CPU inference. With MODNet and MTCNN, memory usage is 410MB and inference takes about 0.207 seconds for a 512x715 image. Switching to RetinaFace increases time to 0.571 seconds. The birefnet-v1-lite model, which offers the best segmentation accuracy, jumps to 6.2GB memory and over 7 seconds for the same image. This is a significant trade-off. If you need high accuracy, you need a machine with substantial RAM. The README notes that birefnet-v1-lite is the only model that can be GPU-accelerated, requiring 16GB of VRAM. This means the 'lightweight' claim applies to the default setup, not to the highest-quality option. For a production service, you must decide whether speed or accuracy matters more, and budget accordingly. The project does not provide a benchmark for lower-end hardware, so you should test on your own target machine.

A Real Limitation: Model Weight Management

One practical limitation is that the model weights are not bundled with the repository. You must download them separately, and the URLs point to GitHub releases, Hugging Face, and other sources. If any of those URLs change or become unavailable, the download script may fail. The README offers a fallback: download from SwanHub. But this adds a manual step. Another limitation is the Face++ online API option, which requires network access and an API key. That contradicts the offline-first promise, but it is optional. The README also lists 'smart suit change' as a feature that is 'waiting', meaning it is not yet implemented. So if you need that feature, this project is not ready. The community extensions, such as the C++ version and Windows GUI, are not maintained by the core team, so their quality and compatibility are uncertain. The project itself is under active development, with the latest release in January 2025, but the core team's focus appears to be on the Python library and Gradio demo.

Alternatives: How They Differ

The most direct alternative is a commercial cloud API like Face++'s ID photo service, which the project itself integrates for face detection. That service offers high accuracy without local computation, but it requires sending photos to a third party, which raises privacy concerns. Another alternative is to use a general-purpose matting library like rembg, which can remove backgrounds but does not generate ID photo layouts or enforce size standards. You would need to build the layout logic yourself. A third option is to use a dedicated photo editing tool like Photoshop, which gives full control but is not programmable. HivisionIDPhoto sits in between: it is a specialized pipeline that handles the entire ID photo workflow, from matting to print layout, in a few lines of Python. The key difference is that HivisionIDPhoto is purpose-built for ID photos, so it includes face alignment, size conversion, and print sheet generation out of the box. The trade-off is that you must manage the model weights and accept the performance characteristics of the chosen models.

Maintenance and License Considerations

The project is licensed under Apache-2.0, which permits commercial use, modification, and distribution, provided you include the original license and notice. This is a permissive license, but you should verify the licenses of the underlying models. For example, rmbg-1.4 is from BRIA AI, and birefnet-v1-lite is from ZhengPeng7. These models may have their own terms, especially for commercial use. The README does not clarify this, so you must check each model's license before shipping a product. The maintenance cadence is active: releases in September 2024, November 2024, and January 2025 show regular updates. The changelog mentions new features like print layouts, base64 input, and beauty parameters. However, the project is primarily maintained by a small team, and community contributions are accepted but not guaranteed. The documentation is in Chinese, with an English README available, but the FAQ and some docs may be Chinese-only. This could be a barrier for non-Chinese developers.

Editorial conclusion

Adopt HivisionIDPhoto if you need an offline, self-hosted ID photo generator that runs on CPU and can be integrated into a web service or desktop app. Skip it if you require the highest matting accuracy without a large memory footprint, or if you need a production-ready API with ongoing support. Before adopting, verify that the model weights download URLs are still reachable, test the chosen matting model on representative portraits, and measure memory usage on your target hardware, especially if you plan to use birefnet-v1-lite.

Official sources

1. Official documentation
2. Official README
3. Project repository
4. Release notes