README.md

metadata

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:

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:

$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.