🎨 Artmorph

Welcome! This project lets you run an AI-powered app with both a backend (server) and a frontend (website).

Research & Engineering Overview

Artmorph is a hybrid generative image stylization system that combines perceptual optimization (Neural Style Transfer) with diffusion-based sampling to address stability, color drift, and convergence issues observed in classical NST pipelines.

The project was motivated by three recurring problems:

1. Instability of Gram-matrix loss across deep feature layers
2. Unpredictable color drift in stylized outputs
3. Long optimization times with limited controllability

To address these, the system integrates:

• Perceptual style loss as a deterministic anchor
• Diffusion sampling with classifier-free guidance (CFG)
• PCA-based color alignment to stabilize chromatic components

Experimental Notes

Experiments were conducted by varying:

• VGG layer depth used for Gram-matrix computation
• CFG values during diffusion sampling
• PCA alignment strength for color correction

Key observations:

• Lower-level VGG layers (conv1_1, conv2_1) produced more stable gradients
• CFG values above ~3.5 introduced structural artifacts
• PCA alignment reduced perceptual color drift by approximately 15–20%

Metrics used during evaluation:

• SSIM for perceptual similarity
• ΔE2000 for color deviation
• End-to-end inference time

No deep technical knowledge needed — just follow the steps in order.

---

🚀 1. Setup the Environment

You only need to do this once.

What you need

• Python 3.10
• Node.js 18
• Internet connection (to fetch dependencies & models)

Step A — Clone or unzip the project

Put the project folder somewhere easy, e.g. Desktop/project.

Step B — Create a Python environment

Windows (PowerShell):

python -m venv .venv
.\.venv\Scripts\Activate

macOS / Linux:

python3 -m venv .venv
source .venv/bin/activate

Step C — Install Python dependencies

pip install -r requirements.txt

Step D — Install Node.js dependencies (frontend)

npm install

---

📥 2. Pre-Download AI Models (important!)

To avoid delays when first running, download the models now.

python dev/download_all.py

(This script will fetch all required AI weights into the models/ folder. Only needed once.)

---

▶️ 3. How to Run the App

You need two terminals (keep both open).

Terminal 1 — Start the backend

uvicorn backend.server:app --host 127.0.0.1 --port 8000 --reload

You should see: INFO: Uvicorn running on http://127.0.0.1:8000

Terminal 2 — Start the frontend

npm run dev

You should see: Local: http://localhost:5173

👉 Open that link in your browser. Done!

---

✅ 4. How to Run the Tests

This project ships with two kinds of tests:

1. Backend tests (fast) — check the server.
2. Frontend E2E tests (optional) — open the website in a real browser and click through actions.

0) What you need once

• Python 3.10+
• Node.js 18+ (only if you want browser tests)
• About 1–2 minutes

(Windows tip: open PowerShell, copy-paste the commands)

---

1) Run backend tests (recommended)

# activate environment first (see above)
pip install -r tests/backend/requirements.txt
pytest -q tests/backend

What success looks like:

3 passed, 2 skipped in 0.05s

---

2) Run frontend tests (optional)

Keep the frontend running (npm run dev), then:

cd tests/e2e
npm i
npm run e2e:install   # one-time browser download
npm run e2e           # headless run
npm run e2e:headed    # visible browser run

Success looks like:

2 passed

(If short on space, see Playwright cache note in tests/README.)

---

3) What the tests actually check

• Backend: server health, bad inputs rejected, large images handled, tiny smoke pipeline (optional).
• Frontend: homepage loads, upload works, errors shown correctly.

---

🛠 5. Developer Quick Commands

All important commands in one place:

# Setup
python -m venv .venv && .\.venv\Scripts\Activate   # (Windows)
pip install -r requirements.txt
npm install
python dev/download_all.py

# Run backend
uvicorn backend.server:app --host 127.0.0.1 --port 8000 --reload

# Run frontend
npm run dev

# Run backend tests
pytest -q tests/backend

# Run frontend tests
cd tests/e2e && npm i && npm run e2e

---

🎯 That’s it!

• First run: setup → download models → start backend + frontend.
• Later runs: just activate the venv and start backend + frontend.
• Tests are optional but show everything works.

---