LiYing

简体中文 | English

LiYing is an automated photo processing program designed for automating the post-processing workflow of ID photos in general photo studios.

🧭 Project Introduction

LiYing can automatically identify human bodies and faces, correct angles, change background colors, crop passport photos to any size, and automatically arrange them.

LiYing can run completely offline. All image processing operations are performed locally.

Workflow

Showcase


(1-inch on 5-inch photo paper - 3x3)	(2-inch on 5-inch photo paper - 2x2)	(1-inch on 6-inch photo paper - 4x2)

Note: This project is specifically for processing passport photos and may not work perfectly on any arbitrary image. The input images should be standard single-person portrait photos.

It is normal for unexpected results to occur if you use complex images to create passport photos.

Getting Started

Bundled Package

If you are a Windows user and do not need to review the code, you can download the bundled package (tested on Windows 7 SP1 & Windows 10).

The bundled package does not include any models. You can refer to the Downloading the Required Models section for instructions on downloading the models and placing them in the correct directory.

If you encounter issues while running the program, please first check the Prerequisites section to ensure your environment is properly set up. If everything is fine, you can ignore this step.

Running the bundled package

Run the BAT script:

cd LiYing
run.bat ./images/test1.jpg

Run the WebUI interface:

# Run WebUI
cd LiYing
run_webui.bat
# Open your browser and visit 127.0.0.1:7860

🛠 Prerequisites

Dependencies
- LiYing depends on AGPicCompress
- AGPicCompress requires mozjpeg and pngquant
- You may need to manually install pngquant, refer to the pngquant official documentation
pngquant Configuration Location
- Environment variables (recommended)
- LiYing/src directory
- ext directory under LiYing/src
System Requirements
- Windows users need to install the latest Microsoft Visual C++ Redistributable.
- If you are using Windows, your minimum version should be Windows 7 SP1 or higher.

🧪 Building from Source

Clone the project:

git clone https://github.com/aoguai/LiYing
cd LiYing ## Enter the LiYing directory
pip install -r requirements.txt # Install Python helpers' dependencies

Note: If you are using Windows 7, ensure you have at least Windows 7 SP1 and onnxruntime==1.14.0, orjson==3.10.7, gradio==4.44.1.

GPU-Accelerated Inference (Optional)

To leverage an NVIDIA GPU for accelerated inference, proceed with the following measures:

Ensure that both the CUDA Toolkit and the cuDNN library are correctly installed on your system.
Consult the official compatibility matrix to determine the required versions for ONNX Runtime, CUDA, and cuDNN that correspond with one another.

Install the GPU-enabled build of the ONNX Runtime library:

# First, uninstall the CPU-only variant if it is currently installed.
pip uninstall onnxruntime
# Install the GPU-enabled version, ensuring its compatibility with your environment.
pip install onnxruntime-gpu

The current version of the system is engineered to automatically detect the presence of a compatible GPU. Upon detection, it will prioritize the GPU for inference operations, seamlessly reverting to the CPU in its absence. This functionality requires no additional configuration.

Should any complications arise, it is imperative to first verify the mutual compatibility between your installed versions of Python, CUDA, cuDNN, and onnxruntime-gpu.

📦 Downloading the Required Models

Download the models used by the project and place them in LiYing/src/model, or specify the model paths in the command line.

Purpose	Model Name	Download Link	Source
Face Recognition	Yunnet	Download Link	Yunnet
Subject Recognition and Background Replacement	RMBG-1.4/2.0	1.4 Download Link/2.0 Download Link	BRIA AI
Body Recognition	yolov8n-pose	Download Link	ultralytics

Note: For the yolov8n-pose model, you need to export it to an ONNX model. Refer to the official documentation for instructions.

We also provide pre-converted ONNX models that you can download and use directly:

Download Method	Link
Google Drive	Download Link
Baidu Netdisk	Download Link (Extraction Code: ahr9)
GitHub Releases	Download Link

🚀 Running

View CIL help:

cd LiYing/src
python main.py --help

For Windows users, the project provides a batch script for convenience:

# Run BAT script
cd LiYing
run.bat ./images/test1.jpg

Run WebUI:

cd LiYing/src/webui
python app.py

🧾 CLI Parameters and Help

python main.py --help
Usage: main.py [OPTIONS] IMG_PATH

Options:
  -y, --yolov8-model-path PATH    Path to YOLOv8 model
  -u, --yunet-model-path PATH     Path to YuNet model
  -r, --rmbg-model-path PATH      Path to RMBG model
  -sz, --size-config PATH         Path to size configuration file
  -cl, --color-config PATH        Path to color configuration file
  -b, --rgb-list RGB_LIST         RGB(A) channel values list (comma-separated)
                                  for image composition (optional alpha:
                                  0-255)
  -s, --save-path PATH            Path to save the output image
  -p, --photo-type TEXT           Photo types
  -ps, --photo-sheet-size TEXT    Size of the photo sheet
  -c, --compress / --no-compress  Whether to compress the image
  -sv, --save-corrected / --no-save-corrected
                                  Whether to save the corrected image
  -bg, --change-background / --no-change-background
                                  Whether to change the background
  -sb, --save-background / --no-save-background
                                  Whether to save the image with changed
                                  background
  -lo, --layout-only              Only layout the photo without changing
                                  background
  -sr, --sheet-rows INTEGER       Number of rows in the photo sheet
  -sc, --sheet-cols INTEGER       Number of columns in the photo sheet
  -rt, --rotate / --no-rotate     Whether to rotate the photo by 90 degrees
  -rs, --resize / --no-resize     Whether to resize the image
  -svr, --save-resized / --no-save-resized
                                  Whether to save the resized image
  -al, --add-crop-lines / --no-add-crop-lines
                                  Add crop lines to the photo sheet
  -ts, --target-size INTEGER      Target file size in KB. When specified,
                                  ignores quality and size-range.
  -szr, --size-range SIZE_RANGE   File size range in KB as min,max (e.g.,
                                  10,20)
  -uc, --use-csv-size / --no-use-csv-size
                                  Whether to use file size limits from CSV
  -lp, --layout-position INTEGER RANGE
                                  Layout position (0-8): 0=top-left, 1=top,
                                  2=top-right, 3=middle-left, 4=center,
                                  5=middle-right, 6=bottom-left, 7=bottom,
                                  8=bottom-right  [0<=x<=8]
  -psp, --photos-spacing INTEGER  Pixel spacing between photos in the sheet
                                  (default: 0)
  --help                          Show this message and exit.

🗂 Configuration Files

In this version, the data directory contains standard ID photo configuration files (size_XX.csv) and commonly used color configurations (color_XX.csv). You can modify, add, or remove configurations based on the provided CSV template format.

🐳 Docker Deployment

️1. Build the Image

Build with docker-compose

Run the following command in the project root directory:

docker compose build

Manually build the image

Run the following command in the project root directory:

docker build -t liying/webui:latest .

2. Start the Service

Start the Gradio Web UI service with the following command:

docker compose up -d

Once started, open your browser and visit:

http://127.0.0.1:7860

If you encounter any issues, please first verify that at least one model file is placed in src/model/ and ensure the port is not already in use.

For more details or advanced configuration, check the Dockerfile and docker-compose.yml.

🧱 Changelog

Note: This version includes changes to CIL parameters. Please carefully read the latest CIL help documentation to avoid issues.

2026/02/16 Update
- Added Docker deployment support.
- Added GPU-accelerated inference support.
- Added photos-spacing option.
- Added layout-position option.
- Added support for transparent background output and fast background preview.
- Added batch upload/processing and batch downloads for WebUI.
- Optimized WebUI image download for server deployment.
- Fixed other known bugs.

Previous Changelog

2025/06/30 Update
- Added size_range option, allowing users to input a min and max file size, attempting to maintain quality while keeping the file size within the range.
- Added target_size option to control the photo file size.
- Added support for RMBG-2.0 and higher iterations of yolov8 (requires Latest environment).
- Added automatic builds for CLI/BAT/WEBUI versions.
- Added model path configuration options.
- Fixed known bugs.
2025/02/07 Update
- Added WebUI
- Optimized configuration method by replacing INI files with CSV
- Added CI/CD for automated builds and testing
- Added options for layout-only photos and whether to add crop lines on the photo grid
- Improved fallback handling for non-face images
- Fixed known bugs
- Added and refined more photo sizes
2024/08/06 Update
- Added support for entering width and height in pixels directly for photo-type and photo-sheet-size, and support for configuration via data.ini.
- Fixed issues related to some i18n configurations; now compatible with both English and Chinese settings.
- Fixed other known bugs.

🙏 Acknowledgments

The project was created to help my parents complete their work more easily. I would like to thank my parents for their support.

Related Projects

Special thanks to the following projects and contributors for providing models and theories:

You might also be interested in the image compression part, which is another open-source project of mine:

AGPicCompress

It depends on:

🤝 Contribution

LiYing is an open-source project, and community participation is highly welcomed. To contribute to this project, please follow the Contribution Guide.

📄 License Notice

LiYing is open-sourced under the AGPL-3.0 license. For details, please refer to the LICENSE file.

💖 Sponsors

If this project is helpful to you, feel free to give any appreciation, it helps me a lot, thank you for your support!

USDT(TRON):TWFDp8aZMWZHPXjBodyhfPeK8LUyrWe9mi

Navigation Menu

Uh oh!

LiYing

🧭 Project Introduction

Workflow

Showcase

Getting Started

Bundled Package

Running the bundled package

🛠 Prerequisites

🧪 Building from Source

GPU-Accelerated Inference (Optional)

📦 Downloading the Required Models

🚀 Running

🧾 CLI Parameters and Help

🗂 Configuration Files

🐳 Docker Deployment

️1. Build the Image

Build with docker-compose

Manually build the image

2. Start the Service

🧱 Changelog

🙏 Acknowledgments

Related Projects

🤝 Contribution

📄 License Notice

💖 Sponsors

⭐ Star History

Uh oh!

FilesExpand file tree

README-EN.md

Latest commit

History

README-EN.md

File metadata and controls

LiYing

🧭 Project Introduction

Workflow

Showcase

Getting Started

Bundled Package

Running the bundled package

🛠 Prerequisites

🧪 Building from Source

GPU-Accelerated Inference (Optional)

📦 Downloading the Required Models

🚀 Running

🧾 CLI Parameters and Help

🗂 Configuration Files

🐳 Docker Deployment

️1. Build the Image

Build with docker-compose

Manually build the image

2. Start the Service

🧱 Changelog

🙏 Acknowledgments

Related Projects

🤝 Contribution

📄 License Notice

💖 Sponsors

⭐ Star History