README.md

# Parametric Floorplan Generator for Indian Residential Construction

A fine-tuned LLM that generates 2D construction floor plans from parametric input matching a `ProjectCreate` schema — including plot dimensions, setbacks, road side, number of bedrooms/toilets, optional rooms (pooja, study, balcony, parking, basement, stilt), and Vastu preferences.

## What It Does

Given parameters like:
```
Plot: 15m x 12m rectangular
Setbacks: front=1.5m, rear=1.0m, left=1.0m, right=1.0m
Road side: North
Bedrooms: 3, Toilets: 3
Parking required, Pooja room, Balcony
2 floors (G+1)
City: Delhi
```

The model outputs a complete JSON floorplan with:
- **Plot boundary** polygon (supports rectangular, L-shaped, trapezoid)
- **Buildable boundary** (plot minus setbacks)
- **Rooms** as polygons with dimensions, area, and center position
- **Doors** (main entrance + internal doors between adjacent rooms)
- **Windows** on external walls
- **Area summaries** by floor (GF, FF, SF, stilt, basement)

## Model

| Component | Value |
|-----------|-------|
| Base Model | `Qwen/Qwen2.5-1.5B-Instruct` |
| Fine-tuning | LoRA (r=16, alpha=32, dropout=0.05) |
| Target Modules | q_proj, k_proj, v_proj, o_proj, gate_proj, up_proj, down_proj |
| Epochs | 5 |
| Batch Size | 4 (accumulation=4) |
| Learning Rate | 1e-4 |
| Max Sequence Length | 4096 |
| Precision | bf16 |

## Dataset

The dataset is **synthetically generated** to match your `ProjectCreate` schema.

### Input Schema (ProjectCreate)

```json
{
  "name": "MyHouse",
  "plot_length": 15.0,
  "plot_width": 12.0,
  "setback_front": 1.5,
  "setback_rear": 1.0,
  "setback_left": 1.0,
  "setback_right": 1.0,
  "road_side": "N",
  "north_direction": "N",
  "num_bedrooms": 3,
  "toilets": 3,
  "parking": true,
  "city": "Delhi",
  "vastu_enabled": false,
  "road_width_m": 9.0,
  "has_pooja": true,
  "has_study": false,
  "has_balcony": true,
  "plot_shape": "rectangular",
  "num_floors": 2,
  "has_stilt": false,
  "has_basement": false,
  "municipality": "MCD",
  "custom_room_config": null
}
```

### Output Schema

```json
{
  "project_name": "MyHouse",
  "plot": {
    "shape": "rectangular",
    "outer_boundary": [[0,0],[15,0],[15,12],[0,12]],
    "setbacks": {"front":1.5,"rear":1.0,"left":1.0,"right":1.0},
    "buildable_boundary": [[1.5,1.5],[13.5,1.5],[13.5,11],[1.5,11]],
    "road_side": "N",
    "north_direction": "N",
    "plot_length": 15.0,
    "plot_width": 12.0
  },
  "rooms": [
    {
      "id": "living_1",
      "type": "living",
      "name": "Living Room",
      "floor": "gf",
      "polygon": [[1.5,1.5],[8.5,1.5],[8.5,5.5],[1.5,5.5]],
      "area_sqm": 24.0,
      "dimensions": {"width":7.0,"depth":4.0},
      "position": {"x":5.0,"y":3.5}
    },
    ...
  ],
  "doors": [
    {"id":"door_main","type":"main_entrance","width":0.9,"from":"outside","to":"living_1","position":[7.5,11.0],"orientation":"horizontal"},
    ...
  ],
  "windows": [
    {"id":"win_living_1","room":"living_1","width":1.2,"height":1.5,"position":[8.5,3.5],"orientation":"vertical"},
    ...
  ],
  "dimensions": {
    "total_built_up_area_sqm": 145.2,
    "total_carpet_area_sqm": 128.0,
    "ground_floor_area_sqm": 128.0,
    "first_floor_area_sqm": 0.0,
    "second_floor_area_sqm": 0.0,
    "stilt_area_sqm": 0.0,
    "basement_area_sqm": 0.0
  },
  "meta": {
    "num_floors": 2,
    "has_stilt": false,
    "has_basement": false,
    "vastu_enabled": false,
    "city": "Delhi",
    "municipality": "MCD"
  }
}
```

## Repository Structure

| File | Purpose |
|------|---------|
| `train.py` | Fine-tuning script using TRL SFTTrainer + LoRA |
| `generate.py` | Inference script — pass parametric input, get JSON floorplan |
| `generate_synthetic_dataset.py` | Generates the training dataset from the ProjectCreate schema |
| `README.md` | This file |

## Quick Start

### 1. Generate Dataset

```bash
pip install datasets
python generate_synthetic_dataset.py
```

This creates `floorplan_synthetic_dataset/` with 5,000 train, 500 val, 500 test examples.

### 2. Train

```bash
pip install transformers trl torch datasets peft accelerate trackio
export HF_TRAINER_HUB_MODEL_ID="Karthik8nitt/parametric-floorplan-generator"
python train.py
```

Requires ~16GB VRAM (T4, RTX 3090, A10G). Runtime: 2-4 hours.

### 3. Generate Floorplan

```bash
python generate.py \
  --plot_length 15 --plot_width 12 \
  --setback_front 1.5 --setback_rear 1.0 \
  --setback_left 1.0 --setback_right 1.0 \
  --road_side N --num_bedrooms 3 --toilets 3 \
  --parking --has_pooja --has_balcony \
  --num_floors 2 --city Delhi
```

## Advanced: Custom Rooms

Use `custom_room_config` to add non-standard rooms:

```json
[
  {"type": "gym", "name": "Home Gym", "min_area_sqm": 15, "floor_preference": "ff", "mandatory": true},
  {"type": "home_theater", "name": "Theater", "min_area_sqm": 20, "floor_preference": "basement", "mandatory": true}
]
```

## Supported Plot Shapes

- `rectangular`
- `l_shaped` (with `cutout_corner`, `cutout_width`, `cutout_height`)
- `trapezoid` (with `plot_front_width`, `plot_rear_width`, `plot_side_offset`)

## References

- DStruct2Design paper: [arXiv:2407.15723](https://arxiv.org/abs/2407.15723)
- Base model: [Qwen/Qwen2.5-1.5B-Instruct](https://huggingface.co/Qwen/Qwen2.5-1.5B-Instruct)