| # 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 |
| ``` |
|
|
