anime-character-image-preprocessing

• Anime Character Image Preprocessing
  • Introduction
    • Image Processing Comparison (All images below are generated by SD)
  • Usage and Project Features
    • Requirements
    • Installation
    • Background Removal
    • Boundary Cropping
    • Smart Cropping
    • Image Tagging
    • Image Enlargement
    • Image Naming
    • PIXIV Image Downloader
    • Mixed Commands
  • Reference
  • License

Introduction

A Python-based character image preprocessing tool that transforms character images into a dataset suitable for training through background transparency, boundary cropping, smart cropping, image tagging, image enlargement, etc.

Image Processing Comparison (All images below are generated by SD)

Quick Start

Option A: Download Pre-built Release (Recommended)

Download the latest release for your platform from Releases:

Platform	File
Windows x64	AnimePreprocessing-windows-x64.zip
macOS (Apple Silicon)	AnimePreprocessing-macos-arm64.tar.gz
Linux x64	AnimePreprocessing-linux-x64.tar.gz

Extract and run the AnimePreprocessing executable — the Web UI will open in your browser automatically.

Option B: Run from Source

Requires uv (Python package manager).

1. Clone the repository:

   git clone https://github.com/Inupedia/sd-character-image-preprocessing
   cd sd-character-image-preprocessing
   

2. Install dependencies (creates .venv automatically):

   uv sync
   

3. Copy the configuration template:

   cp module/config_temp.py module/config.py
   

4. Launch the Web UI:

   uv run python app.py
   

   Open http://localhost:7860 in your browser.

Web UI (Gradio)

Launch with python app.py. All features are available through an intuitive tabbed interface — no command-line knowledge required.

Background Removal

Upload images and select a model (recommended: isnet-anime for anime characters). The background is replaced with white.

Boundary Cropping

Automatically detects character boundaries and removes excess whitespace. Best used after background removal.

Smart Cropping

Face-based intelligent cropping using YOLO or OpenCV Cascade detection. Supports multi-character images (each face produces a separate crop). Adjustable scale factor controls how much area around the face is preserved.

Image Tagging

Generates Booru-style tags using WD Tagger, directly usable for Stable Diffusion training. Adjustable confidence threshold.

Image Upscaling

Super-resolution upscaling using Real-ESRGAN (4× anime model). Ideal for enhancing low-resolution cropped images.

Batch Rename

Sequentially renames uploaded images with a custom prefix (e.g. illust_0.jpg, illust_1.jpg, …).

Pixiv Downloader

Download artworks by artist ID or keyword search. Requires valid Pixiv credentials in module/config.py.

CLI Usage

Each function can also be executed from the command line, or combined through mixed commands.

Requirements

• Python 3.11 or higher
• uv (or run pip install against pyproject.toml)
• Git (optional)

Background Removal

Background removal is based on the character detection model. Please choose the model according to your needs (such as isnet-anime corresponds to secondary character).

1. All models are downloaded and saved in the user home folder in the .u2net directory.

   The available models are:

• u2net (download, source): A pre-trained model for general use cases.
• u2netp (download, source): A lightweight version of u2net model.
• u2net_human_seg (download, source): A pre-trained model for human segmentation.
• u2net_cloth_seg (download, source): A pre-trained model for Cloths Parsing from human portrait. Here clothes are parsed into 3 category: Upper body, Lower body and Full body.
• silueta (download, source): Same as u2net but the size is reduced to 43Mb.
• isnet-general-use (download, source): A new pre-trained model for general use cases.
• isnet-anime (download, source): A high-accuracy segmentation for anime character.
• sam (download encoder, download decoder, source): A pre-trained model for any use cases.

2. Modify the following configurations in config.py, the format is as follows:

    IMAGE_CONFIG = {
        # Change to the corresponding model name, such as isnet-anime
        "REMBG_MODEL": "u2net",
    }
   

3. Put the images that need to be processed into the src/input folder.
4. run main.py:

   python main.py --remove-bg
   

Boundary Cropping

Boundary cropping uses an algorithm to find the boundary of the object and remove excess space.

1. Modify the following configurations in config.py, the format is as follows:

    IMAGE_CONFIG = {
        # Modify the target path for cropping images and the path for saving. By default, modify the files under src/output and save them as "original_name_crop.png" in the same path. If you need a different path, please generate the corresponding path first
        "BOUNDARY_CROP_INPUT_DIR": "./src/rm_bg_output/",
        "BOUNDARY_CROP_OUTPUT_DIR": "./src/boundary_crop_output/",
    }
   

2. Run main.py：

   python main.py --boundary-crop
   

Smart Cropping

Smart cropping can be used in conjunction with background removal. Please note that when the image resolution is not high, the cropped character will be below 512x512, so it is recommended to enlarge the image after cropping. In the case of multiple people in one picture, multiple images will be automatically cropped based on facial features, but it’s not applicable for too dense scenarios.

1. Modify the following configurations in config.py, the format is as follows:

    IMAGE_CONFIG = {
        # Modify the target path for cropping images and the path for saving. By default, modify the files under src/output and save them as "original_name_smartcrop_number.png" in the same path. If you need a different path, please generate the corresponding path first
        "SMART_CROP_INPUT_DIR": "./src/rm_bg_output/",
        "SMART_CROP_OUTPUT_DIR": "./src/smart_crop_output/",
        # Model address, no need to change
        "HF_REPO_ID": "inupedia/anime-character-image-preprocessing",
        "HF_MODEL_DIR": "./module/model/",
    }
   

2. Run main.py：

    python main.py --smart-crop auto # Recommended, scale factor parameter can be adjusted, for example --smart-crop auto 1.5
    python main.py --smart-crop auto-fast # Based on lbpcascade_animeface.xml for automatic cropping, fast speed, but may miss some characters
   

Image Tagging

Original Image	Tagger (50% Confidence)
^1	boat, lily pad, flower, multiple girls, 2girls, water, watercraft, lotus, hanfu, sitting, outdoors, black hair, hair flower, hair ornament, chinese clothes, day, holding, long hair, long sleeves, sash, smile, pink flower, looking at another, bangs, hair bun, sidelocks, braid, single hair bun

1. Modify the following configurations in config.py, the format is as follows:

    IMAGE_CONFIG = {
        "IMAGE_TAGGER_INPUT_DIR": "./src/input/", # Directory of images that need tags
        "IMAGE_TAGGER_CONFIDENCE": 0.5, # Confidence, the higher the more accurate, but some tags may be missed
    }
   

2. The model will be automatically downloaded to the corresponding folder. You can manually download wd-v1-4-convnextv2-tagger-v2 model and selected_tags into the module/image_tagger/model folder.
3. Run main.py：

   python main.py --tag
   

Image Upscaling

Upscale images using Real-ESRGAN with the realesr-animevideov3 model optimized for anime. The model (~2.4 MB) is downloaded automatically on first use.

python main.py upscale       # 4× by default
python main.py upscale 2     # 2× scale

Image Naming

1. Modify the following configurations in config.py, the format is as follows:

     IMAGE_CONFIG = {
        # Change to the corresponding prefix name, such as illust, it will generate illust_1.jpg, illust_2.jpg, etc.
        "IMAGE_PREFIX": "illust",
     }
   

2. Put the images that need to be processed into the src/input folder.
3. Run main.py：

   python main.py --rename
   

PIXIV Image Downloader

This function mainly meets two needs, one is to download all the works of the artist through the artist ID, and the other is to download relevant works through keywords (the number will be downloaded according to the corresponding pages).

1. Please abide by Pixiv’s relevant regulations for crawling

2. Modify the following configurations in config.py, the format is as follows:

     NETWORK_CONFIG = {
        # Proxy settings (no need to modify for Clash, port number needs to be modified for SSR)
        "PROXY": {"https": "127.0.0.1:7890"},
    }
    USER_CONFIG = {
        "USER_ID": "Change to your own uid, refer to the URL of the personal profile page https://www.pixiv.net/users/{UID}",
        "COOKIE": "Change to your own cookie, the acquisition method refers to the following graphic",
    }
   

   • How to get cookies：
     1. Log in to pixiv
     2. Press F12 to open the developer tools
     3. Click on Network
     4. Visit the ranking list and refresh the page
     5. Find ranking.php and copy the cookie from its Request Headers
        

3. Crawl its pixiv images according to the artist ID:

   python main.py --pixiv-user artist_ID
   

4. Download according to keywords:

   1. Modify the following configurations in config.py, the format is as follows:

        IMAGE_CONFIG = {
            "KEYWORD_ORDER": True,  # True: Sort by popularity, False: Sort by newest
            "KEYWORD_N_PAGES": 5,  # 1 page is 60 images, the actual number per page will be more than 60 because some galleries will have multiple images
            "KEYWORD_MODE": "safe",  # safe / r18 / all
        }
      

   2. (PIXIV member feature) Keywords can be searched accurately by combining, such as “50000users AND hutao”

      python main.py --pixiv-keyword "keyword"
      

Mixed Commands

Mixed commands can satisfy multiple tasks to be executed in order. If you want to use multiple commands at the same time, you can use the combination as follows.

python main.py --rename --remove-bg --boundary-crop # Rename first, then remove the background of the image and crop the edge

Building Standalone Releases

The project includes a GitHub Actions workflow that automatically builds standalone executables when a version tag is pushed:

git tag v1.0.0
git push origin v1.0.0

This builds executables for Windows, macOS (Intel + Apple Silicon), and Linux, and attaches them to a GitHub Release. You can also trigger a build manually from the Actions tab.

To build locally:

uv sync
uv pip install pyinstaller
cp module/config_temp.py module/config.py
uv run pyinstaller AnimePreprocessing.spec --noconfirm
# Output: dist/AnimePreprocessing/

Reference

• PixivCrawler
• rembg
• Real-ESRGAN
• anime_object_detection
• wd-v1-4-convnextv2-tagger-v2

License

MIT License