| | --- |
| | title: FaceForge |
| | emoji: 🧑🎨 |
| | colorFrom: indigo |
| | colorTo: pink |
| | sdk: gradio |
| | sdk_version: "4.44.1" |
| | app_file: app.py |
| | pinned: false |
| | --- |
| | |
| | # faceforge |
| | Interactive latent space editor for face generation using pretrained GANs and diffusion models. |
| |
|
| | ## 🚀 Deploy on Hugging Face Spaces (Recommended) |
| |
|
| | FaceForge is ready to run as a Gradio app on [Hugging Face Spaces](https://huggingface.co/spaces): |
| |
|
| | 1. **Push your code to a public GitHub repository.** |
| | 2. **Create a new Space** at https://huggingface.co/spaces (choose the Gradio SDK or Docker SDK). |
| | 3. **Add your `requirements.txt` and the provided `Dockerfile` to your repo.** |
| | 4. **Set the entrypoint to `app.py`** (which integrates both the API and UI components). |
| | 5. **Deploy!** Your app will be live at `https://<your-username>.hf.space`. |
| |
|
| | ### Example Dockerfile (already included): |
| | ```Dockerfile |
| | FROM huggingface/transformers:latest |
| | WORKDIR /app |
| | COPY requirements.txt ./ |
| | RUN pip install --no-cache-dir -r requirements.txt |
| | RUN pip install --no-cache-dir transformers |
| | COPY . . |
| | EXPOSE 7860 |
| | ENV PYTHONPATH="/app" |
| | ENV PYTHONUNBUFFERED=1 |
| | ENV API_URL="/api" |
| | ENV MOCK_API="true" |
| | ENV BASE_URL="" |
| | CMD ["python", "app.py"] |
| | ``` |
| |
|
| | ## Local Development (Optional) |
| |
|
| | You can still run FaceForge locally: |
| |
|
| | ```bash |
| | pip install -r requirements.txt |
| | python main.py |
| | ``` |
| |
|
| | This will start the integrated application with both the API and UI components available: |
| | - UI accessible at http://localhost:7860/ |
| | - API accessible at http://localhost:7860/api/ |
| |
|
| | ## Architecture |
| |
|
| | FaceForge uses a modular architecture: |
| |
|
| | 1. **Core Components** (`faceforge_core/`): Core algorithms and utilities |
| | 2. **API Layer** (`faceforge_api/`): FastAPI endpoints for model interaction |
| | 3. **UI Layer** (`faceforge_ui/`): Gradio interface for user interaction |
| |
|
| | The main application integrates these components into a single FastAPI application where: |
| | - The API is mounted at `/api/` |
| | - The Gradio UI is mounted at the root path `/` |
| |
|
| | ## Features |
| | - Latent space exploration and manipulation |
| | - Attribute direction discovery (PCA/classifier) |
| | - Custom attribute-preserving loss |
| | - Modular, testable core |
| | - Gradio UI for interactive exploration |
| |
|
| | ## Controls (Gradio UI) |
| | - Enter prompts (comma-separated) |
| | - Choose sampling mode (distance/circle) |
| | - Adjust player position sliders |
| | - Click "Generate" to see results |
| |
|
| | ## Testing |
| | Run all tests with: |
| | ```bash |
| | pytest tests/ |
| | ``` |
| |
|
| | ## Debugging |
| |
|
| | If you encounter Gradio schema-related errors like: |
| | ``` |
| | TypeError: argument of type 'bool' is not iterable |
| | ``` |
| |
|
| | The application includes a patch that should fix the issue automatically. This patch addresses a known issue with schema processing in older Gradio versions. |
| |
|
| | ### Common Issues: |
| |
|
| | #### API Connection Errors |
| |
|
| | If you see errors like: |
| | ``` |
| | Invalid URL '/api/generate': No scheme supplied. Perhaps you meant https:///api/generate? |
| | ``` |
| |
|
| | This indicates an issue with URL formatting. The application should handle this automatically with the following settings: |
| |
|
| | 1. For the integrated app, set `BASE_URL=""` in the environment |
| | 2. For separate UI/API components, set `BASE_URL="http://localhost:7860"` (or your server URL) |
| | 3. Using relative URLs within the same server requires the correct base URL configuration |
| |
|
| | The updated app uses proper URL formatting that works in both integrated and separated modes. |
| |
|
| | #### Missing Dependencies |
| |
|
| | If you see errors about missing Python packages like `transformers`, you have options: |
| |
|
| | 1. Install the missing package: `pip install transformers` |
| | 2. Use mock mode: Set `MOCK_API="true"` in environment variables |
| | 3. Use the Docker image which includes all dependencies: `docker build -t faceforge .` |
| |
|
| | #### Environment Variables |
| |
|
| | - `MOCK_API`: Set to "true" to use mock API responses (for testing without ML dependencies) |
| | - `API_URL`: Override the API endpoint URL |
| | - `BASE_URL`: Base URL for relative API paths (leave empty for integrated deployment) |
| | - `PORT`: Set the port for the server (default: 7860) |
| |
|
| | ## Notes |
| | - The backend and frontend are fully integrated for Spaces deployment. |
| | - The application will use the actual ML framework when dependencies are available, and fall back to mock implementations when they're missing. |
| | - For custom model integration, edit the core and backend modules as needed. |
| |
|
