README.md

metadata

title: Custom AI Face Enhancer
emoji: ✨
colorFrom: purple
colorTo: pink
sdk: docker
pinned: false
license: apache-2.0

Custom AI Face Enhancer & Restorer

A self-hosted, local AI image enhancement web application built using Python, Streamlit, PyTorch, and OpenCV. It integrates the state-of-the-art CodeFormer model locally for face restoration with custom blending controls.

This project is configured to run out-of-the-box both locally on your CPU/GPU and hosted on Hugging Face Spaces.

---

Key Features

• Local Execution: Runs directly on local CPU or NVIDIA GPU (via CUDA) for maximum privacy and processing speed.
• Fidelity Weight Tuning ($w$): Control the balance between generating rich realistic details (low $w$) and keeping high resemblance to the original face (high $w$).
• Custom Blending Softness: Exposes an adjustable soft mask feathering parameter to ensure smooth, seamless pasting of restored faces back into the upscaled background image.
• Multiple Face Detectors: Choose between highly accurate detectors (RetinaFace) or faster detectors for groups (YOLOv5).
• Dark Mode UI: Designed with custom glassmorphism and modern Outfit typography.

---

Local Execution Instructions

Prerequisites

• Python 3.11
• Git

Setup

1. Clone this repository to your local machine.
2. Initialize the virtual environment and install dependencies:

   python -m venv .venv
   .venv\Scripts\activate      # On Windows (PowerShell/CMD)
   source .venv/bin/activate   # On Linux/macOS
   

3. Run the custom BasicSR package patching script:

   python tools/patch_and_install_basicsr.py
   

4. Install the remaining requirements:

   pip install -r requirements.txt
   

Running the App

Start the Streamlit server locally:

streamlit run app.py

Open http://localhost:8501 in your browser. The app will automatically download the pretrained model weights on its first run.

---

Hugging Face Spaces Deployment

This repository deploys as a Docker Space, not a Streamlit SDK Space. The Dockerfile installs the pinned Python 3.11 CPU runtime and starts Streamlit on port 7860.

1. Log in to Hugging Face and create a new Space.
2. Set the Space SDK to Docker and select a CPU hardware tier appropriate for CodeFormer inference.
3. Push this repository to the Space. Keep Git LFS enabled: the tracked weights/CodeFormer/codeformer.pth model is required at build/runtime.
4. Wait for the Space build to complete, then open the Space URL. Additional optional model files are downloaded by the application only if unavailable.

GitHub Actions sync

The included workflow syncs main to the configured Hugging Face Space and uploads Git LFS objects first. Add a Hugging Face write token as the GitHub Actions secret HF_TOKEN; do not place a token in a Git remote URL or commit it to the repository. The sync intentionally does not force-push, so resolve any divergent Space changes before running it again.