# LiYing: an offline ID photo pipeline for photo studios

> LiYing is a Python program from aoguai that chains face detection, pose correction, background replacement, cropping and sheet layout into one command. It is built for studio batches, not for rescuing bad portraits.

**aoguai/LiYing** — LiYing is an automated photo processing program designed for automating the post-processing workflow of ID photos in general photo studios. | LiYing 是一套适用于自动化 完成一般照相馆后期证件照处理流程的照片自动处理的程序。

- Repository: https://github.com/aoguai/LiYing
- Stars: 3,665 · Forks: 338
- Language: Python
- License: AGPL-3.0
- Published: 2026-09-23 · Updated: 2026-09-23 · Language: en
- Canonical page: https://hysenlabs.com/projects/aoguai-liying

## What LiYing automates in a studio's post-processing chain

A photo studio handling ID photos repeats the same sequence hundreds of times: find the face, straighten the head, cut the subject out, drop in a white or blue background, crop to a specification, then tile copies onto a sheet for printing. LiYing packages that sequence as one program. The README describes it as automating the post-processing workflow of ID photos in a general photo studio, and lists the steps it covers: automatic body and face recognition, automatic angle correction, automatic replacement of the background with any color, automatic cropping to any ID photo size, and automatic layout. The intended user is the studio operator, not the end customer. The README is explicit that the input should be a single-person portrait photo meeting ordinary requirements, and that unexpected results on complex images are normal rather than a bug. That boundary matters: this is not a general photo editor and not a portrait retoucher. It assumes the photographer already did their job.

## How the detection, cutout and layout stages fit together

The pipeline is assembled from three ONNX models, each with one job. YuNet handles face detection. yolov8n-pose handles body recognition, which is what makes angle correction possible: a pose model gives you keypoints, and keypoints give you the tilt to correct. RMBG (1.4 or 2.0) handles subject segmentation for background replacement. The README points to the model download table and states that all image processing runs locally and that LiYing can run fully offline. That is the architectural decision worth noting: there is no API call to a segmentation service, so the quality ceiling is whatever those local models deliver, and the install cost is carrying them. The CLI exposes each stage as a switch, which tells you the order of operations is not fixed. Options include --change-background, --save-background, --save-corrected, --resize, --save-resized, --rotate, --add-crop-lines and --layout-only. The presence of --layout-only, described as laying out photos without changing the background, means you can run the layout stage against images you already cut out elsewhere. The repository also has a tests/ directory, though the README does not document a test command.

## Installing LiYing and running a first portrait

There are two install paths. On Windows, the README points to a packaged build on the releases page, tested on Windows 7 SP1 and Windows 10, and states that the package never includes models, so you download them separately and place them in LiYing/src/model. The source path is a clone plus a requirements install:

```bash
git clone https://github.com/aoguai/LiYing
cd LiYing
pip install -r requirements.txt
```

On Windows 7 the README pins minimum versions: onnxruntime==1.14.0, orjson==3.10.7 and gradio==4.44.1. Before running anything, deal with pngquant. LiYing depends on AGPicCompress, which depends on mozjpeg and pngquant, and the README says you may need to install pngquant manually. It looks for it in three places: the environment variable, the LiYing/src directory, or LiYing/src/ext. Windows users also need the latest Microsoft Visual C++ Redistributable. Then fetch the models. YuNet comes from the OpenCV zoo, RMBG-1.4 or 2.0 from BRIA AI on Hugging Face, and yolov8n-pose from the ultralytics assets release, which the README says you must export to ONNX yourself unless you take the pre-converted copy offered on Google Drive, Baidu Netdisk or the GitHub releases page. A first run through the CLI looks like this:

```bash
cd LiYing/src
python main.py --help
python main.py ../images/test1.jpg
```

The first command prints the option list, including the model path flags -y, -u and -r if your models live outside the default location. The second processes a portrait with the defaults. If you prefer a browser, the README gives the WebUI route: run run_webui.bat from the LiYing directory and open 127.0.0.1:7860, or from source run python app.py inside LiYing/src/webui. Docker is also provided: docker-compose.yml builds an image tagged liying/webui:latest, publishes port 7860, and mounts ./src/model and ./output as volumes, so the model directory has to exist on the host before the container starts.

## Model files are a manual step, and the README does not remove it

The single most likely reason a first run fails is an empty model directory. LiYing ships no weights, and the README repeats this for the packaged build as well. You need YuNet, one RMBG variant and an ONNX export of yolov8n-pose in LiYing/src/model, or you must pass paths with -u, -r and -y. The yolov8n-pose step is the awkward one: the upstream asset is a .pt file, and the README tells you to export it to ONNX using the ultralytics documentation, with a pre-converted ONNX offered as an alternative. That is a real friction point for anyone without a Python environment already set up. GPU acceleration is optional and, to the project's credit, self-configuring: the README states the current version detects GPU support automatically and falls back to CPU, with no extra configuration. The cost is version alignment. If you install onnxruntime-gpu, you own the compatibility matrix between your Python version, CUDA, cuDNN and onnxruntime-gpu, and the README says to check those first when something breaks. There is no documented rollback procedure, no model version pinning in requirements.txt, and no stated minimum for the CPU path beyond the Windows 7 SP1 floor.

## Where LiYing is the wrong tool

LiYing is narrow on purpose, and the README says so twice. The input should be a single-person portrait meeting ordinary requirements, and the project targets ID photo processing rather than promising that any photo will process perfectly. Feed it a group shot and the face detector has to choose, which the documentation does not describe a policy for. Feed it a casual photo with a busy background and the RMBG cutout is the weak link; the README's own framing is that unexpected results on complex images are normal. There is also no documented retouching stage. Skin, stray hair and clothing cleanup are not in the step list, so a studio that currently delivers retouched portraits will still need that work done somewhere else. Finally, the CLI is a batch-shaped tool, not an interactive one. If your workflow is one photo at a time with a human deciding each crop, the WebUI is the relevant surface, and the README describes the CLI as the primary interface.

## LiYing against a general image pipeline

The obvious alternative is composing the same stages yourself from OpenCV, rembg and Pillow. That gives you control over every threshold and lets you swap the segmentation model when a better one appears. The difference is not capability but packaging: LiYing already wires face detection, pose-based angle correction, cutout, background fill, cropping and sheet layout into one invocation, and the CLI flags map to the stages rather than to library calls. If your studio needs a specific crop rule that the size config file cannot express, or a background treatment RMBG handles badly, the assembled pipeline is the better fit. If your need is exactly the standard sequence and you would rather not maintain the glue, LiYing is the shorter path. A narrower alternative is using only the layout half: --layout-only lets you keep your existing cutout process and hand LiYing the tiling, sheet rows and columns, crop lines and target file size. That split is the most useful thing in the option list, and the README does not call attention to it.

## Licence and the cost of staying current

LiYing is AGPL-3.0. For a studio running it internally to process customer photos, that is unremarkable. If you intend to wrap LiYing inside a service you offer to others, or ship a modified version, the AGPL's network-use terms are the part to read, and this is a question for your own legal review rather than something the README answers. The upgrade picture is mixed. Releases are infrequent and unevenly spaced: v3.0.0 in February 2025, v3.1.1 in June 2025, v3.2.0 in February 2026, with the last push to master on 2026-08-09. The repository is not archived. requirements.txt uses lower bounds rather than pins for onnxruntime, orjson and gradio, while the Dockerfile pins its own higher floors, so a fresh pip install and a fresh container build can land on different dependency versions. If you deploy via Docker, the image is reproducible from the Dockerfile; if you deploy from source, expect to test after dependency upgrades.

## Conclusion

Adopt LiYing if you run a studio workflow that produces single-portrait ID photos in volume and you want the whole chain, from background replacement to a printed sheet layout, to stay on your own machine. Do not adopt it if your inputs are group shots, casual photos or anything the README would call a complex image; the project says unexpected results there are normal. Before committing, verify the three model files are in LiYing/src/model, confirm pngquant is on PATH or in src/ext, and run one real portrait through run.bat to see whether your sheet size and photo type are already in the size and color config files.

## FAQ

### Does LiYing need an internet connection to process photos?

No. The README states that LiYing can run completely offline and that all image processing operations run locally. You do need a connection once, to download the model files.

### What models does LiYing need and where do they go?

YuNet for face detection, RMBG-1.4 or 2.0 for background replacement, and yolov8n-pose for body recognition. The README says to place them in LiYing/src/model, or to specify the path in the CLI.

### Can LiYing use an NVIDIA GPU for inference?

Yes, optionally. The README says the current version detects GPU support automatically and prefers it, falling back to CPU with no extra configuration. It notes that the Python, CUDA, cuDNN and onnxruntime-gpu versions must be compatible.

### How do I open the LiYing WebUI?

Run run_webui.bat from the LiYing directory, or run python app.py inside LiYing/src/webui, then open 127.0.0.1:7860 in a browser. The Docker setup publishes the same port 7860.

## Sources

- [aoguai/LiYing on GitHub](https://github.com/aoguai/LiYing)
- [Issues](https://github.com/aoguai/LiYing/issues)
- [License: AGPL-3.0](https://github.com/aoguai/LiYing/blob/master/LICENSE)
- [README](https://github.com/aoguai/LiYing/blob/master/README.md)
- [Releases](https://github.com/aoguai/LiYing/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/aoguai-liying