# Backend Environment Setup

Use Python 3.12. The `.venv/` directory is disposable and ignored by git.

## macOS CPU setup

```bash
cd backend/floor-visualizer
python3.12 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install -r requirements-mac.txt
VISUALIZER_CONFIG=visualizer.local.toml uvicorn app:app --host 0.0.0.0 --port 8002
```

## NVIDIA GPU setup

Use this on the GPU machine. This installs the CUDA 12.6 PyTorch wheels.

```bash
cd backend/floor-visualizer
python3.12 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install -r requirements-gpu-cu126.txt
VISUALIZER_CONFIG=visualizer.gpu.toml uvicorn app:app --host 0.0.0.0 --port 8002
```

The first GPU run downloads `shi-labs/oneformer_ade20k_swin_large` and the depth model into the Hugging Face cache.
It also downloads `Ruicheng/moge-2-vitl-normal`, the primary GPU geometry model.

## Notes

- Environment variables override TOML values, for example `SEGMENTATION_MODEL=segformer`.
- `requirements.txt` is a full freeze from an existing environment. Prefer the smaller platform files above when recreating `.venv`.

## Optional DigitalOcean Spaces upload archive

The `/viz2d/convert` endpoint can copy each uploaded room image to a private
DigitalOcean Spaces bucket in the background without changing the frontend
flow. Add these values to `backend/floor-visualizer/.env`:

```bash
SPACES_BUCKET="your-space-name"
SPACES_REGION="nyc3"
SPACES_ACCESS_KEY_ID="your-spaces-access-key"
SPACES_SECRET_ACCESS_KEY="your-spaces-secret-key"
SPACES_UPLOAD_PREFIX="room-uploads"
```

`SPACES_ENDPOINT_URL` is optional and defaults to
`https://$SPACES_REGION.digitaloceanspaces.com`. `SPACES_ACL` defaults to
`private`.

## Optional visual QA runner

The backend can also power the debug visualizer QA page without adding a
database. It lists images directly from DigitalOcean Spaces and writes each QA
run under `data/qa-runs/{run_id}/`.

Backend env:

```bash
QA_FRONTEND_URL="https://your-vercel-frontend.example"
QA_BACKEND_URL="https://your-backend.example"
QA_FRONTEND_DIR="/mnt/room-editor/frontend/viz2d-demo"
QA_MAX_IMAGES="50"
QA_MAX_TESTS="200"
```

For Hugging Face, `QA_FRONTEND_DIR` defaults to
`/app/frontend/viz2d-demo` in the Dockerfile.

The backend server needs Node and Playwright because the test runner opens the
hosted frontend in Chromium. On Hugging Face, the deploy workflow copies only
the text-based `frontend/viz2d-demo` QA runner files into the Space and the
Dockerfile installs these during rebuild. Real QA images are downloaded from
DigitalOcean during each run. On non-Hugging Face servers, install them
manually:

```bash
cd /mnt/room-editor/frontend/viz2d-demo
npm install
npx playwright install --with-deps chromium
```

The QA endpoints are:

```text
GET /qa/images
POST /qa/runs
GET /qa/runs/{run_id}
GET /qa/runs/{run_id}/events
GET /qa/runs/{run_id}/report
GET /qa/runs/{run_id}/report.md
```