| --- |
| 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: |
| ```bash |
| 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: |
| ```bash |
| python tools/patch_and_install_basicsr.py |
| ``` |
| 4. Install the remaining requirements: |
| ```bash |
| pip install -r requirements.txt |
| ``` |
|
|
| ### Running the App |
| Start the Streamlit server locally: |
| ```bash |
| 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](https://huggingface.co/) 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. |
|
|
