Skip to content

INSTALL.md

Latest commit

 

History

History
200 lines (147 loc) · 6.09 KB

INSTALL.md

File metadata and controls

200 lines (147 loc) · 6.09 KB
Raw

Installation and Setup Guide

This guide details how to install, set up, and configure the Selfie Rectification pipeline on Windows and macOS.

💻 System Requirements

Windows

  • Operating System: Windows 10 or 11 (64-bit)
  • Python: Python 3.10 (3.10.11 recommended)
  • NVIDIA GPU: Required for hardware acceleration (e.g., RTX 30-series/40-series with CUDA support, RTX 3050 Laptop 6GB tested).
  • Disk Space: ~15 GB (for deep learning model weights, dependencies, and datasets)
  • Git: Installed and added to system PATH.

macOS

  • Operating System: macOS 12 Monterey or later
  • Python: Python 3.10 or 3.11
  • Hardware: Apple Silicon (M1/M2/M3 recommended) for Metal Performance Shaders (MPS) hardware acceleration, or Intel CPU.
  • Disk Space: ~10 GB.
  • Git: Xcode Command Line Tools installed (xcode-select --install).

🛠️ Step-by-Step Installation

First, clone the repository (if you haven't already):

git clone https://github.com/YTFL/UnDistort-Selfie.git
cd UnDistort-Selfie

All commands below assume you are inside the SelfieRectification/ sub-directory.

1. Windows Installation (CUDA GPU-Accelerated)

Open a PowerShell terminal as a regular user:

# Move to the source folder
cd SelfieRectification

# Create a virtual environment
python -m venv .venv

# Activate the virtual environment
.\.venv\Scripts\Activate.ps1

# Upgrade pip package manager
python -m pip install --upgrade pip

# Install PyTorch with CUDA 11.8 support
python -m pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu118

# Install remaining pipeline dependencies
python -m pip install -r requirements.txt

2. macOS Installation (Apple Silicon MPS / CPU)

Open a standard Terminal:

# Move to the source folder
cd SelfieRectification

# Create a virtual environment
python3 -m venv .venv

# Activate the virtual environment
source .venv/bin/activate

# Upgrade pip package manager
python3 -m pip install --upgrade pip

# Install PyTorch for macOS
python3 -m pip install torch torchvision torchaudio

# Install remaining macOS dependencies
python3 -m pip install -r requirements-mac.txt

🔬 Model Weights Cache Setup

On first execution, the pipeline automatically warms its cache by downloading:

  1. Depth Anything V2 Small: Automatically downloaded to cache/ via HuggingFace Hub.
  2. InsightFace (buffalo_sc): Automatically downloaded to your user directory (~/.insightface/).

However, if you wish to pre-download all weights to avoid runtime downloads, run:

python -m scripts.download_weights

To stream and pre-cache benchmark images from FFHQ and CelebA-HQ academic datasets:

python -m scripts.download_datasets

🧪 Verification and Testing

Verify that your Python, CUDA, PyTorch, and third-party dependencies are properly configured:

# Check library paths and hardware devices
python -m scripts.verify_setup

# Test CUDA tensor allocation and speed
python -m scripts.test_gpu

Expected Output of verify_setup

============================================================
SETUP VERIFICATION
============================================================
PyTorch version: 2.2.2+cu118
CUDA available: True
GPU: NVIDIA GeForce RTX 3050 6GB Laptop GPU
Device: cuda

[OK] MediaPipe installed
[OK] OpenCV installed
[OK] Transformers installed
[OK] Diffusers installed
[OK] Gradio installed

Repository status:
  [OK] mediapipe
  [OK] Depth-Anything-V2
  ...
============================================================

▶️ Running the Application

Option A: Gradio Web Interface

The Gradio Web UI provides a slide-to-compare interface, diagnostic meshes, vector outputs, and sliders to control lens setback parameters.

  • Windows: Simply double-click launch.bat or execute: 
    .\.venv\Scripts\Activate.ps1
.\launch.bat
  • macOS: 
    source .venv/bin/activate
python -m scripts.gradio_app

Open http://localhost:7860 in your browser.

Option B: Command Line Interface (CLI)

To run the pipeline on an image and generate evaluation metrics:

# Activate virtual environment
source .venv/bin/activate    # macOS
.\.venv\Scripts\Activate.ps1 # Windows

# Run pipeline
python -m scripts.main <path_to_selfie>

Output files will be saved under outputs/<timestamp>/, along with a base64-embedded interactive HTML report saved under outputs/reports/.

❌ Troubleshooting Common Issues

1. ModuleNotFoundError: No module named 'basicsr.version'

This occurs due to a known packaging bug in basicsr. The setup script should resolve this automatically, but if it persists, execute:

python -m scripts.verify_setup

This programmatically creates the missing version.py file inside your virtual environment libraries.

2. CUDA Out of Memory (OOM) on Windows

If you run out of GPU memory during Stable Diffusion img2img texture refinement:

  • The pipeline runs with Stable Diffusion disabled by default. If you enable it, use the --no-diffusion or Gradio toggles.
  • Reduce input image resolution (tested up to 1024x1024 on 6GB VRAM).
  • Check that PyTorch is using fp16 half-precision (default).

3. UnicodeEncodeError on Windows Command Prompt

If you receive crash logs printing UnicodeEncodeError when trying to print emojis or UTF-8 characters:

  • Standard Windows console encoding defaults to CP1252.
  • We have replaced all decorative console emojis with ASCII prefixes ([OK], [WARN], [INFO], [ERROR]).
  • Run chcp 65001 in CMD before running the python script to force UTF-8 support.

4. Apple Silicon (M1/M2/M3) Performance Issues

  • Ensure you have installed native ARM64 Python, not Intel Python via Rosetta 2.
  • The pipeline automatically falls back to CPU-only execution for libraries that do not fully support MPS (e.g. MediaPipe). PyTorch tensor calculations will leverage MPS.