ARCHITECTURE.md

# Floor Visualizer Architecture

This document summarizes the floor detection and tile rendering pipeline for client communication.

## Previous Pipeline

```mermaid
flowchart TD
  A[Room image upload] --> B[OneFormer semantic segmentation]
  B --> C[Initial floor mask]
  C --> D[OpenCV mask cleanup]
  D --> E[MoGe / Depth geometry]
  E --> F[Floor plane + UV mapping]
  F --> G[Canvas tile renderer]
  G --> H[Final room preview]
```

The previous system mainly depended on semantic segmentation to identify the floor, then used geometry to place the tile texture in perspective. This worked well when the segmentation mask was clean, but weak floor edges, rugs, furniture bleed, and wall/floor boundary mistakes could make the tile placement look less realistic.

## Current GPU Pipeline

```mermaid
flowchart TD
  A[Room image upload] --> B[OneFormer semantic segmentation]
  B --> C[Initial floor class mask]
  C --> D[OpenCV edge fixing and mask cleanup]
  D --> E[SAM2 mask refinement]
  E --> F[MoGe metric geometry]
  F --> G[Dominant floor plane filtering]
  G --> H[Surface UV / perspective mapping]
  H --> I[Lighting and reflection transfer]
  I --> J[Material-aware tile renderer]
  J --> K[Final room preview]

  E --> L{SAM2 unavailable or weak result?}
  L -->|Yes| M[Fallback to cleaned OneFormer mask]
  M --> F
  L -->|No| F
```

## What Changed

- **OneFormer still detects the floor class.** It remains responsible for identifying which pixels are likely floor.
- **OpenCV edge fixing runs before refinement.** We clean the raw semantic mask with morphology, contour filling, protected wall/object removal, and edge coverage repair before using it downstream.
- **SAM2 now refines the cleaned floor mask on GPU deploy.** SAM2 receives the cleaned floor region as prompt context and improves the actual boundary quality.
- **MoGe geometry validates the floor plane.** After segmentation/refinement, MoGe provides metric geometry so we can reject pixels that do not belong to the dominant floor plane.
- **Rendering now uses material and lighting controls.** The canvas renderer supports tile scale, rotation, grout, roughness, gloss, room light, reflection transfer, and perspective-aware UV mapping.
- **Safe fallback is preserved.** If SAM2 fails to load or produces a weak mask, the backend falls back to the cleaned OneFormer + MoGe path instead of failing the job.

## Client Summary

Before, the system used semantic segmentation plus geometry. Now, the GPU pipeline adds a refinement stage: OneFormer finds the floor, OpenCV cleans and fixes the mask edges, SAM2 sharpens the floor boundary, MoGe validates the actual floor plane, and the renderer applies the tile with perspective, lighting, and material controls. This should reduce boundary errors and make the tile look more integrated with the original room.