README.md

metadata

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.

Quick macOS CPU run:

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:

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:

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:

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:

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

GPU run:

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.