README.md

---
title: Floor Visualizer
emoji: 🏆
colorFrom: indigo
colorTo: purple
sdk: docker
app_port: 7860
pinned: false
license: mit
short_description: Visualize custom texture or tiles on your floor
---

Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference

## Local setup

The Python virtual environment is disposable. To recreate it after deleting `.venv`,
use the platform-specific commands in [SETUP.md](SETUP.md).

Quick macOS CPU run:

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

Optional Gemini tile refinement:

```bash
export GEMINI_API_KEY="your-google-ai-studio-key"
export GEMINI_IMAGE_MODEL="gemini-3.1-flash-image"
```

When configured, the frontend can send the final tile-rendered image to
`/gemini/refine-tile-render` for a conservative reflection, shadow, and detail
polish pass.

Optional DigitalOcean Spaces upload archive in `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"
```

When these are set, `/viz2d/convert` keeps the current frontend flow unchanged
and uploads a copy of each room image to Spaces in the background.

Visual QA runner:

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

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

The debug visualizer QA page calls `/qa/images`, `/qa/runs`,
`/qa/runs/{run_id}/events`, and `/qa/runs/{run_id}`. `/qa/images` lists
DigitalOcean Spaces directly through the S3 API, deduplicates exact object
matches by `ETag` and size, and does not use a database. `/qa/runs` deduplicates
the selected image keys again, downloads the unique Spaces images into
`data/qa-runs/{run_id}/`, starts the Playwright test suite from
`QA_FRONTEND_DIR`, and stores file-backed run status/results in that run folder.
The Playwright suite uploads each selected image once, then applies the selected
tiles one by one, removing the previous tile before applying the next tile.
`/qa/runs/{run_id}/events` streams run updates as Server-Sent Events so the
debug page does not need to poll while a run is active. Playwright writes
incremental progress after every completed test, so the `completed`, `passed`,
and `failed` counters update before the final report is generated.
`/qa/runs/{run_id}/report` renders a shareable HTML report with screenshot URLs;
`/qa/runs/{run_id}/report.md` returns the compact Markdown summary.

On Hugging Face, the deploy workflow copies a minimal `frontend/viz2d-demo` QA
runner folder into the Space: npm manifests, Playwright config, e2e tests, and
the Markdown report script. It intentionally does not copy frontend image
assets or `test-images`; real QA images are downloaded from DigitalOcean during
each run. The Dockerfile installs Node, npm, Playwright, and Chromium during the
Space rebuild. For non-Hugging Face servers, install the Node runner
dependencies manually:

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

GPU run:

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

Hugging Face GPU Spaces use the Dockerfile in this directory. It installs the
CUDA 12.6 PyTorch stack and starts FastAPI on port `7860` with
`visualizer.gpu.toml`.

The GPU profile uses `shi-labs/oneformer_ade20k_swin_large` for segmentation,
`Ruicheng/moge-2-vitl-normal` for metric point maps, surface normals, and camera
intrinsics, and `depth-anything/Depth-Anything-V2-Metric-Indoor-Large-hf` for
metric depth. If MoGe cannot load or its floor-plane fit is unreliable, the
service falls back to Depth Anything V2 metric depth, then to the existing
image-space homography.