Skip to content

HOWTO.md

Latest commit

 

History

History
178 lines (123 loc) · 4.82 KB

HOWTO.md

File metadata and controls

178 lines (123 loc) · 4.82 KB
Raw

How to Run UPIQAL

Prerequisites

  • Python 3.9 or later
  • Git

1. Clone the repository

git clone <repository-url>
cd FR-IQA-Algo

2. Create and activate a virtual environment

python3 -m venv venv

Activate it:

  • macOS / Linux: 
    source venv/bin/activate
  • Windows: 
    venv\Scripts\activate

Your prompt should now show (venv).

3. Install dependencies

pip install --upgrade pip
pip install -r requirements.txt

Core dependencies

Package Purpose
torch + torchvision VGG16 backbone, GPU-accelerated tensor ops
numpy Array math and windowing functions
scipy Cholesky decomposition, wavelet transforms
scikit-image Multi-scale pyramid, Canny edge detector, morphological ops
Pillow Image I/O (PNG, JPEG, TIFF …)
opencv-python Convolutional filters, morphological dilation
POT Sinkhorn–Knopp optimal transport (EMD approximation)
colour-science sRGB → Oklab color space conversion

4. Download the VGG16 model

The pipeline requires pre-trained VGG16 weights (~528 MB). Run the download script once:

python weights/download_vgg16.py

The file is saved to weights/vgg16-397923af.pth. If the file already exists the script exits immediately.

5. Run the CLI script

The CLI currently supports PNG images only as input.

python upiqal_cli.py --reference ref.png --target tgt.png --output-dir results/
Flag Description
--reference Path to the reference (pristine) PNG image
--target Path to the target (distorted) PNG image
--output-dir Directory to save results (default: auto-generated with timestamp)
--name Custom label for the auto-generated output directory name
--max-side Maximum pixel dimension for the longer side (default: 512)

The output directory will contain diagnostic heatmap PNGs and a report.json with the overall quality score and artifact breakdown.

6. Start the web server

Install uvicorn if not already included in your requirements:

pip install uvicorn

Start the server:

uvicorn main:app --app-dir web --reload --port 8000

The API will be available at http://localhost:8000.

Flag Description
main:app Module web/main.py, FastAPI instance named app
--app-dir web Sets web/ as the working directory for the app
--reload Auto-reloads on code changes (development only)
--port 8000 Port to listen on

Remove --reload in production.

7. Deactivate the virtual environment

deactivate

Troubleshooting

ModuleNotFoundError: No module named 'torch' Make sure the virtual environment is active (source venv/bin/activate) before running any script.

colour package not found Install it explicitly: pip install colour-science.

8. Deploy — Vercel + CPU host split

The inference stack (PyTorch + 528 MB VGG16 weights) is too large for Vercel's serverless Python runtime. The recommended topology:

  • Vercel — serves the static frontend from web/public/ and a one-file proxy api/proxy.py that forwards /api/* requests upstream.
  • CPU host (Fly.io / Render / Railway) — runs the full FastAPI app from the top-level Dockerfile.

8.1 · Deploy the backend to Fly.io

brew install flyctl        # or curl -L https://fly.io/install.sh | sh
fly auth login
fly launch --copy-config --name upiqal --no-deploy
fly deploy
# note the resulting URL, e.g. https://upiqal.fly.dev
curl https://upiqal.fly.dev/healthz     # should return {"ok":true,"device":"cpu"}

Adjust memory in fly.toml (default 2048 MB) if you see OOMs on large uploads.

8.2 · Deploy the backend to Render (alternative)

Push to GitHub; create a new Web Service pointed at this repo. Render discovers render.yaml automatically. Keep the plan at Standard or higher (2 GB+) — Starter will OOM.

8.3 · Wire Vercel to the backend

vercel login
vercel link
vercel env add BACKEND_URL production    # paste https://upiqal.fly.dev
vercel --prod

Open the deployed URL. The analyzer calls /api/compare, which Vercel rewrites to /api/proxy, which forwards to ${BACKEND_URL}/api/compare.

8.4 · Lock CORS in production

On the backend host, set:

UPIQAL_ALLOWED_ORIGINS = https://your-vercel-domain.vercel.app

This restricts cross-origin POSTs to just your Vercel frontend.

8.5 · Local end-to-end smoke test with vercel dev

# terminal 1 — backend
uvicorn web.main:app --host 127.0.0.1 --port 8000

# terminal 2 — vercel dev with the proxy pointed at the local backend
BACKEND_URL=http://127.0.0.1:8000 vercel dev

Open the URL vercel dev prints and run an analysis; requests should traverse Vercel → api/proxy.py → local FastAPI.