File size: 3,084 Bytes
172229a fd6554d 172229a d09b963 172229a d09b963 172229a d09b963 172229a d09b963 | 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 | ---
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.
|