README.md

metadata

title: FaceEnhance
emoji: 😎
colorFrom: red
colorTo: green
sdk: gradio
sdk_version: 5.25.2
app_file: demo.py
pinned: false

FaceEnhance

A tool for improving facial consistency and quality in AI-generated images. Dramatically enhance facial fidelity while preserving the original image's background, lighting, and composition.

Installation

Prerequisites

• Python 3.11 or higher
• 1 GPU with 48GB VRAM
• At least 60GB of free disk space

Setup

1. Log into Hugging Face and accept their terms of service to download Flux.1-dev

2. Create the virtual environment:

   python -m venv venv
   source venv/bin/activate
   python -m pip install -r requirements.txt
   

   If you want a specific PyTorch+CUDA version

   python -m pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu124
   python -m pip install xformers --index-url https://download.pytorch.org/whl/cu124
   

3. Run the install script:

   python install.py
   

   This will

   • Install ComfyUI, custom nodes, and remaining dependencies to your venv
   • Download all models to HF_HOME and create symlinks to FaceEnhance/ComfyUI/models/

4. Run inference on one example:

   python test.py --input examples/dany_gpt_1.png --ref examples/dany_face.jpg --out examples/dany_enhanced.png
   

   Arguments

   • --input (str): Path to the input image.
   • --ref (str): Path to the reference face image.
   • --output (str): Path to save the output image.
   • --id_weight (float): Face ID weight. Default: 0.75.

Gradio Demo

A simple web interface for the face enhancement workflow. Run python demo.py

ComfyUI

Run python run_comfy.py. There are two workflows:

• FaceEnhance/workflows/FaceEnhancementProd.json for face enhancement
• FaceEnhance/workflows/FaceEmbedDist.json for computing the face embedding distance

Notes

• The script and demo run a ComfyUI server ephemerally
• Gradio demo is faster than the script because the models remain loaded in memory and ComfyUI server is booted up.
• Images are saved in FaceEnhance/ComfyUI/input/scratch/
• face_enhance.py was created with the ComfyUI-to-Python-Extension and re-engineered for efficiency and function.
• Face cropping, upscaling, and captioning are unavailable; these will be added in an update.

Troubleshooting

• Out of memory errors: If your GPU has less than 48 GB VRAM, install Flux.1-dev at fp8 precision.
• Face detection issues: This method works for photorealistic images of people. It may not work on cartoons, anime characters, or non-human subjects.
• Downloading models fails: Check your Hugging Face token has proper permissions.

Examples

Target image	Face image	Enhanced image