SETUP.md

Backend Environment Setup

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

macOS CPU setup

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.

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:

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:

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:

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

The QA endpoints are:

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