---
title: PlanPalette
emoji: 🎨
colorFrom: green
colorTo: blue
sdk: gradio
sdk_version: "4.44.1"
python_version: "3.10"
app_file: app.py
pinned: false
---

# PlanPalette

PlanPalette is a Hugging Face Spaces Gradio app for fast architectural floor-plan visualization. It accepts a colored reference floor plan and a black-and-white CAD floor plan, extracts the reference palette, and uses a fast text-to-image model to generate a furnished architectural plan render.

## Hackathon Description

Architectural visualization artists often need quick mood-board style studies before a full rendering pass. PlanPalette is an MVP for that workflow: it transfers the visual language of one plan onto another with a small, controllable image-generation model instead of a giant multimodal model or manual masking.

The app currently performs:

- Reference image upload
- Raw CAD floor-plan upload
- Side-by-side input display
- Dominant palette extraction
- DreamShaper XL Lightning image generation by default
- AI-first furnished architectural rendering
- Optional CAD linework compositing
- Final PNG output
- Extracted palette and material-style legend

## Small-Model Constraint

This project stays under the 32B-parameter hackathon constraint by using a small/medium image generation model. The default is `Lykon/dreamshaper-xl-lightning`, a fast SDXL-style model. FLUX.1-schnell can be used by setting `PLANPALETTE_BASE_MODEL=black-forest-labs/FLUX.1-schnell`, but that repo may require accepting gated model terms on Hugging Face.

The MVP uses:

- DreamShaper XL Lightning for fast text-to-image generation
- Prompt guidance derived from the reference image palette and CAD canvas shape
- OpenCV thresholding to prepare optional CAD line masks
- K-means color clustering through OpenCV for the reference palette
- Pillow and NumPy image handling
- Gradio for the interactive UI

A GPU or ZeroGPU Space is recommended. CPU inference is not practical for the AI mode.

## Codex Usage

Codex was used to scaffold the Hugging Face Space structure, implement the palette and linework preprocessing pipeline, add the text-to-image generation path, add custom Gradio CSS, and document setup and limitations.

Suggested future Codex tasks:

- Add example floor-plan assets
- Add model presets for fast/quality GPU tiers
- Add export metadata with palette hex codes
- Add optional room-type labels or manual prompt regions
- Add before/after comparison controls

## Hugging Face Space Setup

1. Create a new Hugging Face Space.
2. Select **Gradio** as the Space SDK.
3. Upload or commit these files:
   - `app.py`
   - `requirements.txt`
   - `README.md`
4. Let the Space build automatically.
5. Upload a colored reference floor plan and a black-and-white CAD floor plan.
6. Click **Generate Colorized Plan**.

Use a GPU or ZeroGPU Space for generation. The app raises a clear error if it starts on CPU-only hardware.

## Local Development

Install dependencies:

```powershell
python -m venv .venv
.\.venv\Scripts\python.exe -m pip install torch==2.8.0 --index-url https://download.pytorch.org/whl/cpu
.\.venv\Scripts\python.exe -m pip install -r requirements-local.txt
```

Run the app:

```powershell
$env:HF_HOME="$PWD\.cache\huggingface"
$env:TRANSFORMERS_CACHE="$PWD\.cache\huggingface\transformers"
$env:PLANPALETTE_ALLOW_CPU="1"
$env:PLANPALETTE_MAX_SIDE="640"
.\.venv\Scripts\python.exe app.py
```

Then open the local Gradio URL printed in the terminal.

Local CPU inference is supported for debugging, but it is very slow and downloads large image model weights. Use a CUDA GPU or Hugging Face GPU/ZeroGPU hardware for practical generation speed.

## Limitations

- Text-to-image models can hallucinate rooms, fills, textures, or plan styling, especially from dense CAD sheets.
- The generated render may not perfectly understand every room, label, or wall in a dense CAD sheet.
- CAD linework overlay is optional. Set it to 0 for a pure AI render, or increase it for readability.
- Dense text, hatch patterns, and low-contrast scans may weaken prompt and overlay quality.
- Material names are inferred from color families, not from semantic understanding.
- The colorization pass is presentation-oriented, not physically based rendering.
- The MVP preserves black CAD linework but does not reconstruct missing or damaged CAD geometry.