explaingit

zeyi-lin/hivisionidphotos

★ 21,059PythonAudience · developerComplexity · 2/5MaintainedLicenseSetup · moderate

TLDR

AI tool that transforms regular photos into official ID photos by detecting faces, removing backgrounds, and formatting to standard sizes, runs offline on CPU.

Mindmap

mindmap
  root((repo))
    What it does
      Face detection
      Background removal
      ID photo formatting
      Print layouts
    How to use
      Gradio web interface
      FastAPI API
      Docker deployment
    Input & Output
      Regular photos
      Base64 images
      Standard ID sizes
    Tech Stack
      Python
      MODNet models
      MTCNN RetinaFace
    Key Features
      Offline CPU only
      Multiple bg models
      Beauty filters
      Optional GPU support

Things people build with this

USE CASE 1

Generate official ID photos from smartphone pictures without visiting a photo studio.

USE CASE 2

Build a batch processing pipeline to create formatted ID photos for employee badges or documents.

USE CASE 3

Deploy as a self-hosted web service for organizations that need offline photo processing without cloud dependencies.

USE CASE 4

Create print-ready sheets with multiple ID photos in standard layouts for passport or visa applications.

Tech stack

PythonGradioFastAPIDockerMODNetMTCNNRetinaFace

Getting it running

Difficulty · moderate Time to first run · 30min

Docker build and model downloads on first run add setup time; CPU inference may be slow for batch processing.

Use freely for any purpose including commercial. Keep the notice and disclose changes to the patent grant.

In plain English

HivisionIDPhotos is a Python tool for making official-style ID photos automatically, the kind of passport, visa, or work-permit photo where the subject is centred on a plain background at a specific size. Normally you would pay a photo shop or fight with a photo editor to get the background colour, framing, and print sizing right. This project takes a regular photo of a person and runs it through an AI pipeline that cuts the subject out from the original background, places them on a clean background, aligns the face, and produces the result at standard ID photo specifications. It works by chaining a person-cutout model (the README lists several options including MODNet, hivision_modnet, rmbg-1.4, and birefnet-v1-lite) with a face-detection model (MTCNN, RetinaFace, or the Face++ online API). The README emphasises that the default models are lightweight enough to run entirely offline on a regular CPU; only the larger birefnet-v1-lite model benefits from an Nvidia GPU. The project also ships a Gradio web demo, a FastAPI service for programmatic use, and a Docker deployment path. Features called out include multiple ID and print-layout sizes such as six-inch and A4, a beauty-retouch option, custom HEX background colours, face-rotation alignment, JPEG download, and a 300 DPI default. Someone would use it when they need a passable ID photo without a studio visit, when they want to self-host an ID-photo service, or when they want to plug ID-photo generation into another product through an API. It runs on Linux, Windows, and macOS with Python 3.7 or newer, and the topics list mentions CNN, face recognition, FastAPI, Gradio, and Docker as the main technologies.

Copy-paste prompts

Prompt 1
Show me how to use HivisionIDPhotos to convert a regular photo into a standard ID photo format using the Gradio interface.
Prompt 2
How do I set up HivisionIDPhotos as a FastAPI service and call it from my application to process photos programmatically?
Prompt 3
What background removal models does HivisionIDPhotos support, and how do I switch between them for different quality needs?
Prompt 4
How can I deploy HivisionIDPhotos using Docker so it runs offline without GPU requirements?
Prompt 5
Show me how to generate print-ready sheets with multiple ID photos in six-up or five-inch formats using HivisionIDPhotos.
Open on GitHub → Explain another repo

Generated 2026-05-21 · Model: sonnet-4-6 · Verify against the repo before relying on details.