PCFPG is a graph-conditioned floor-plan generation system. Give it a building boundary, a set of rooms, room-to-room connections, and optional room-size preferences. It generates multiple candidate layouts, ranks them, and produces a labelled 2D plan together with an interactive 3D view.
The project combines a Streamlit-based floor-plan studio, two neural-network stages, and a geometric reconstruction pipeline.
Project repository: github.com/nerfelitewar/PCFPG
Dataset: ResPlan — 17,000 residential floor plans
- What PCFPG does
- How the model works
- Repository structure
- Getting started
- Download and prepare the dataset
- Run the application
- Generate from JSON using the CLI
- Input JSON format
- Application walkthrough
- Train the models
- Evaluation
- Generated files and exports
- Configuration and compatibility
- Troubleshooting
- Dataset attribution and references
PCFPG converts a building footprint and a room-connectivity graph into a complete floor-plan proposal.
| Capability | What it does |
|---|---|
| Boundary conditioning | Uses the building outline and entrance location as spatial constraints. |
| Room-graph conditioning | Uses room types and room-to-room relationships to guide the layout. |
| Room-size conditioning | Optional relative room-size preferences influence the generated proportions. |
| Multiple candidates | Generates several layout hypotheses and ranks them to select a strong candidate. |
| Geometric reconstruction | Converts predicted room regions into clean, axis-aligned room polygons. |
| Architectural elements | Builds walls, places doors from room connections, adds windows, and places the entrance. |
| 2D and 3D output | Displays a labelled 2D plan and an interactive browser-based 3D model. |
| Diagnostics and export | Shows layout-quality metrics and lets you download the specification, plan, 3D viewer, and metrics. |
The application is designed so that you can work visually in the browser. You do not need to manually write the JSON input, although the application can show the JSON specification it creates.
PCFPG separates learned layout prediction from deterministic geometric reconstruction.
flowchart TD
A[Input specification] --> B[Boundary + entrance]
A --> C[Room types + connections + optional sizes]
B --> D[Conditioned generation]
C --> D
D --> E[Stage 1: BoxNet]
E --> F[K candidate room-box layouts]
F --> G[Stage 2: RefineNet]
G --> H[Per-room refined segmentation]
H --> I[Stage 3: Geometric reconstruction]
I --> J[Room polygons and walls]
J --> K[Doors, windows, entrance, labels]
K --> L[Candidate scoring and ranking]
L --> M[2D plan + JSON + interactive 3D]
- A graph Transformer processes room types and room connections.
- Adaptive Layer Normalization (AdaLN) incorporates optional room-size conditioning.
- The network proposes multiple room-box arrangements from different noise hypotheses.
- Winner-takes-all supervision encourages the model to produce diverse plausible layouts.
- A U-Net refines the room boxes into a per-room segmentation map.
- Edge-weighted cross-entropy encourages accurate room boundaries.
- An anisotropic total-variation term encourages cleaner, straighter borders.
- Optional test-time augmentation averages predictions from flipped and rotated inputs.
This stage is deterministic post-processing; it is not a neural network.
- Restores rooms that may have been dropped during prediction.
- Converts room regions into Manhattan-style polygons with right-angle corners.
- Constructs walls and places doors using the requested room connections.
- Repairs connectivity when needed, then adds windows, the entrance, and labels.
generate.py evaluates the generated candidates and selects the highest-scoring layout. The scorer can use hand-designed weights or calibrated weights produced by calibrate_score.py.
The main files and folders are:
PCFPG/
├── app.py # Streamlit floor-plan studio
├── boundary_editor/ # Interactive building-boundary editor
├── room_graph/ # Interactive room-connection graph editor
├── static/ # Static browser assets and visualizer
├── assets/ # README screenshots
├── checkpoints/ # BoxNet and RefineNet model weights
├── data/ # Preprocessed training and evaluation caches
├── docs/ # Project documentation
├── logs/ # Training, calibration, and evaluation logs
├── outputs/ # Generated output files
├── paper/ # Research-paper material
├── samples/ # Example input JSON files
├── common.py # Shared configuration and utilities
├── graphdata.py # Dataset-to-graph/sample conversion
├── prepare_data.py # Dataset preprocessing
├── models.py # BoxNet and RefineNet definitions
├── train_box.py # Stage 1 training
├── train_refine.py # Stage 2 training and fine-tuning
├── layout.py # Geometry, walls, doors, windows, and exports
├── generate.py # Inference, candidate generation, and scoring
├── calibrate_score.py # Candidate-score calibration
├── evaluate.py # Test-set evaluation
├── metrics.py # Layout metrics
├── requirements.txt # Core Python dependencies
├── viewer_template.html # Interactive 3D viewer template
└── colab_kaggle_train.ipynb # Hosted training notebook
These instructions use Windows 10/11 and PowerShell. A CUDA-capable NVIDIA GPU is recommended for training and faster inference. CPU execution may also be possible, but can be significantly slower.
Install:
- Git
- Python 3.10 or newer
- A compatible NVIDIA driver if you plan to use CUDA
git clone https://github.com/nerfelitewar/PCFPG.git floorplan_gen
cd floorplan_genpython -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install --upgrade pipIf PowerShell blocks environment activation, run this in the same terminal and activate again:
Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass
.\.venv\Scripts\Activate.ps1For an NVIDIA RTX 50-series GPU, the development setup used the CUDA 12.8 PyTorch wheels:
pip install torch torchvision --index-url https://download.pytorch.org/whl/cu128
pip install -r requirements.txt
pip install streamlit plotly pandasThe last command installs the additional packages used by the Streamlit interface. For a different GPU, CUDA version, or CPU-only setup, select the matching PyTorch build from the official PyTorch installation selector.
Check CUDA availability:
python -c "import torch; print('CUDA available:', torch.cuda.is_available()); print('GPU:', torch.cuda.get_device_name(0) if torch.cuda.is_available() else 'CPU mode')"PCFPG uses ResPlan, a dataset containing 17,000 residential floor plans.
- Dataset archive: Direct download:
ResPlan.zip· view the official file page (approximately 95.5 MB). - Canonical train/validation/test splits:
split.json. - Official dataset repository: m-agour/ResPlan.
- Research paper: ResPlan paper — arXiv:2508.14006.
Use the upstream repository above rather than an unverified mirror. The ResPlan.zip archive contains the dataset pickle; split.json is a separate file and must also be available to the preprocessing script.
The project looks for the dataset in a sibling folder named ResPlan by default (ROOT.parent / "ResPlan"). Your workspace should look like this:
workspace/
├── floorplan_gen/ # this repository
│ ├── app.py
│ ├── prepare_data.py
│ └── ...
└── ResPlan/
├── ResPlan.pkl
└── split.json
Run these commands from the project root (named floorplan_gen in the example above). The first command moves to the parent workspace directory so that floorplan_gen and ResPlan become sibling folders.
cd ..
git clone https://github.com/m-agour/ResPlan.git ResPlan-source
New-Item -ItemType Directory -Force ResPlan | Out-Null
Expand-Archive -Path .\ResPlan-source\ResPlan.zip -DestinationPath .\ResPlan -Force
Copy-Item .\ResPlan-source\split.json .\ResPlan\split.json -ForceVerify the required files:
Test-Path .\ResPlan\ResPlan.pkl
Test-Path .\ResPlan\split.jsonBoth commands should return True. If extraction creates an extra nested folder, move ResPlan.pkl into the top-level ResPlan folder.
Return to the project directory before running the next commands:
cd .\floorplan_genIf you keep the dataset somewhere else, pass its path explicitly when preprocessing:
python prepare_data.py --data-dir "D:\path\to\ResPlan"Make sure the dataset is in place and that the compatible model checkpoints are available.
The inference application expects these two model files:
checkpoints/
├── box_best.pt
└── refine_best.pt
If the files are stored elsewhere, use the Stage 1 weights and Stage 2 weights fields in the application sidebar to provide their paths.
Start the Streamlit application from the project root:
streamlit run app.pyThen open the local address printed in the terminal (normally http://localhost:8501).
- Boundary: draw or select the building outline and position the entrance.
- Rooms & connections: add rooms, choose their relative sizes, and define door or adjacency relationships.
- Review & generate: check the validation list and model-weight status, then choose how many candidates to generate.
- Inspect results: review the selected plan, switch to the 3D view, compare candidates, and inspect metrics.
- Export: download the input specification, 2D plan, 3D HTML viewer, and metrics CSV.
The application loads trained checkpoints for inference. It does not train the networks each time you press Generate.
You can also call the generation pipeline without using the Streamlit interface.
Generate three candidates for a sample input:
python generate.py --input samples/rect_2bhk.json --n-samples 3Generate plans for all JSON samples in the sample directory:
python generate.py --samples-dir samplesCheck the command options supported by your local version:
python generate.py --helpA generation request describes the building boundary, rooms, room connections, and optionally the front-door position, entrance room, and relative room sizes.
{
"name": "my_flat",
"boundary": [[0, 0], [12, 0], [12, 9], [0, 9]],
"front_door": [6, 0],
"rooms": [
{"id": "living", "type": "living"},
{"id": "kitchen", "type": "kitchen"},
{"id": "bed1", "type": "bedroom"},
{"id": "bath1", "type": "bathroom"},
{"id": "balcony", "type": "balcony"}
],
"connections": [
["living", "kitchen"],
["living", "bed1"],
["bed1", "bath1"],
["living", "balcony"]
],
"entrance": "living"
}This section follows the same order as a normal run of the application: define the boundary, create the room graph, validate the input, generate layouts, and inspect the results.
The screenshots below are stored in the repository's
assets/folder. Keep the filenames unchanged, or update the corresponding image paths in this README.
Start by drawing the outer footprint of the building. You can choose a basic shape, edit its corner coordinates, and place the front entrance on an exterior wall.
Create the rooms that should appear in the floor plan and connect them to describe how they relate to one another. The graph represents which rooms should connect, not their final physical positions.
- A solid connection requests a door between two rooms.
- A dashed adjacency connection requests a shared wall without a door.
- Room-size controls provide relative size preferences when size conditioning is enabled.
Before generation, PCFPG checks the boundary, room graph, and model-weight paths. Resolve any failed checklist items, then start generation. The JSON expander shows the specification that will be passed to the generator.
After generation, the application reports the selected layout and the number of candidate layouts that were evaluated. The result view provides the generated plan and its quality summary.
The following screenshot continues the generated-results walkthrough.
Open the 3D view tab to inspect the generated floor plan as a 3D model.
- Drag: rotate the model.
- Mouse wheel: zoom in or out.
- Shift + drag: pan the view.
- Labels control: show or hide room names.
The 3D viewer may need an internet connection the first time it loads its 3D library.
PCFPG does not have to settle for the first layout it generates. It can create K candidates, score them, and display them in ranked order. Use the leaderboard to compare alternatives and open a candidate for inspection.
The details view exposes the information behind a selected candidate, including room placement, room areas, requested connections, and generation-stage diagnostics.
The metrics view helps assess the generated result beyond its visual appearance. Depending on the selected view, the application reports signals such as connectivity, room completeness, wall straightness, room-size deviation, candidate diversity, and model evaluation scores.
The Model & training view explains how the dataset is prepared, how the two networks are trained, and what happens to a user-provided layout during inference.
| Field | Required | Description |
|---|---|---|
name |
No | Name used when creating output files. |
boundary |
Yes | Polygon coordinates describing the building footprint. Use coordinates in metres when working through the Streamlit interface. |
rooms |
Yes | Room IDs and semantic room types. |
connections |
No | Room-to-room relationships. If omitted, the generator creates a typical default graph. |
front_door |
No | Point on or near the exterior boundary; it is snapped to the nearest wall. |
entrance |
No | Room connected to the building entrance; defaults to the living room when available. |
use_area |
No | Set to false to disable relative room-size conditioning. |
The current model supports these seven room types:
living, bedroom, bathroom, kitchen, balcony, storage, and stair.
The current model input limit is 16 rooms per plan.
The optional area value is a relative weight, not a strict room-area constraint. A larger value encourages the generator to allocate more space to that room. Rooms without an area value use typical room-size defaults.
{"id": "bed1", "type": "bedroom", "area": 16}To disable size conditioning:
{"use_area": false}A two-item connection requests a door between the two rooms:
["living", "kitchen"]A three-item connection with adjacent requests a shared wall without a door:
["living", "kitchen", "adjacent"]You can use room counts instead of listing every room object. The generator expands the counts into individual room IDs:
{
"rooms": {
"living": 1,
"bedroom": 3,
"bathroom": 2,
"kitchen": 1
}
}A list of room type names can also be used. If connections is omitted, PCFPG creates a typical graph with the living room acting as a hub and bathrooms generally attached to bedrooms.
Training is only required when compatible checkpoints are unavailable or when you want to retrain or fine-tune the networks.
Run preprocessing once after placing ResPlan.pkl and split.json in the expected dataset directory:
python prepare_data.pyThis creates the processed cache files used by training. To limit the number of plans for a quick pipeline check:
python prepare_data.py --limit 500python train_box.py --epochs 200 --d 256 --heads 8 --layers 6The v3.2 architecture includes AdaLN conditioning. An older BoxNet checkpoint from before this architecture is not compatible; retrain Stage 1 when upgrading to v3.2.
With a compatible BoxNet checkpoint available:
python train_refine.py --epochs 15 --lr 5e-4 --init checkpoints\refine_best.pt --boxnet checkpoints\box_best.ptTo train RefineNet from scratch instead:
python train_refine.py --epochs 40python calibrate_score.py --n 300Calibration compares candidate-selection strategies and learns weights for ranking generated layouts.
python evaluate.pyEvaluation results are written to logs/eval_test.json.
python generate.py --samples-dir samplesAdd --resume to a supported training command. For example:
python train_box.py --epochs 200 --d 256 --heads 8 --layers 6 --resumeCheck each script's --help output for the arguments supported by your local version.
A short smoke test can help verify that preprocessing and both training scripts run before starting a full experiment:
python prepare_data.py --limit 500
python train_box.py --epochs 3
python train_refine.py --epochs 1 --base 16This is a pipeline check, not a meaningful training run or model evaluation.
The colab_kaggle_train.ipynb notebook can be used for hosted training. After training, copy compatible box_best.pt and refine_best.pt files into the local checkpoints/ directory.
Run the evaluator with:
python evaluate.pyThe results are written to logs/eval_test.json. The evaluator reports metrics including:
| Metric | Meaning |
|---|---|
box_iou_true / box_iou_true_sizes |
Room-box overlap when the requested room sizes are used. |
box_iou_default |
Room-box overlap using default room-size settings. |
box_iou_no_sizes |
Room-box overlap without size conditioning. |
box_iou_oracle_best_of_8 |
Best candidate IoU under an oracle selection upper bound, when available. |
sample_diversity_L1 |
Diversity between noise-generated samples. |
room_iou_gt_box |
Refined room overlap when ground-truth boxes are supplied. |
room_iou_e2e |
End-to-end room overlap after both networks. |
doors_placed |
Fraction or count of requested doors successfully placed, as reported by the evaluator. |
all_rooms_connected |
Whether all rooms are reachable in the generated layout. |
plans_with_all_rooms |
Whether all requested rooms are present. |
straightness |
How closely room boundaries follow straight, axis-aligned edges. |
rectangularity |
How closely room polygons resemble rectangles. |
The Streamlit application can also display test-set scores, training curves, candidate-selection comparisons, and per-candidate diagnostics when the corresponding log files are present.
Do not interpret a training or validation score as a test-set result. The real-plan reference values for straightness and rectangularity in the development notes are dataset statistics, not guaranteed PCFPG generation scores.
The Export tab provides downloads for:
| Download | Description |
|---|---|
| Spec (JSON) | The input specification used for the generation run. |
| Plan (PNG) | The selected labelled 2D floor plan. |
| 3D viewer (HTML) | A standalone interactive 3D floor-plan viewer. |
| Metrics (CSV) | Candidate-level metrics in a spreadsheet-friendly format. |
The application also saves the run's files in the output directory shown in the interface.
The command-line pipeline writes generated results under outputs/:
| Output | Description |
|---|---|
<name>.png |
Labelled 2D floor plan. |
<name>.json |
Generated plan data. |
<name>_3d.html |
Interactive 3D floor-plan viewer. |
The 3D view supports drag-to-rotate, mouse-wheel zoom, and Shift + drag to pan.
A CLI status line may look like this:
rooms 7/7 doors 6/6 (+1 auto) windows 8 connected True best of 8
This example indicates that all seven requested rooms were placed, all six requested doors were placed, one additional door was added to repair connectivity, eight windows were generated, and the selected plan was the best-scoring candidate among eight generated layouts.
The following settings were used during development:
| Component | Setting | Purpose |
|---|---|---|
| Stage 1 | --d 256 --heads 8 --layers 6 --epochs 200 |
BoxNet capacity and training duration. |
| Stage 1 | --adj 12 |
Adjacency-related loss weighting in the training script. |
| Stage 2 | --base 48 --epochs 60 |
RefineNet capacity and training duration. |
| Generation | --k 16 |
Number of candidate hypotheses to generate. |
Compatibility notes:
- The current v3.2 pipeline uses AdaLN layers in BoxNet.
- A pre-v3.2
box_best.ptcheckpoint is not compatible with the v3.2 BoxNet architecture. Retrain Stage 1 before using the current pipeline with such a checkpoint. - The
refine_best.ptcheckpoint anddata/cache4_*.npzcache format are retained from v3.1 according to the project development notes. - Checkpoint files must match the model architecture expected by the code being run.
Check that the NVIDIA driver is installed and working. Reinstall the PyTorch build that matches your CUDA setup using the official PyTorch installation selector, then rerun the CUDA verification command.
Confirm that both ResPlan.pkl and split.json exist in the dataset directory. By default, the project expects a sibling ResPlan/ folder next to the project directory. Otherwise, pass the dataset path using --data-dir when running prepare_data.py.
Inference requires compatible BoxNet and RefineNet checkpoint files. Set their paths in the application sidebar or train the models using the instructions above. A checkpoints/ directory by itself does not mean that the required weight files are present.
The current v3.2 BoxNet architecture includes AdaLN layers. Retrain Stage 1 and use the resulting compatible checkpoints/box_best.pt file.
Open the generated HTML viewer in a modern browser. The viewer may need an internet connection once to load its 3D library. Also confirm that generation completed and the HTML export exists.
Run the following in the current PowerShell session, then activate the environment again:
Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass
.\.venv\Scripts\Activate.ps1PCFPG uses ResPlan: A Large-Scale Vector-Graph Dataset of 17,000 Residential Floor Plans.
- Dataset and source code: m-agour/ResPlan.
- Dataset archive:
ResPlan.zip. - Research paper: arXiv:2508.14006.
- Dataset licence: The upstream repository identifies the released data files as Creative Commons Attribution 4.0 International (CC BY 4.0). The upstream repository separately licenses its code under MIT; consult its LICENSE for the exact scope.
- Takedown policy: See the upstream
TAKEDOWN.md.
The dataset is maintained by its original authors. PCFPG is a separate project that uses the dataset. Attribute ResPlan to its authors and review the upstream licence before redistributing dataset files.
- Hu, R. et al. Graph2Plan: Learning Floorplan Generation from Layout Graphs. ACM Transactions on Graphics, 2020.
- Ronneberger, O., Fischer, P., and Brox, T. U-Net: Convolutional Networks for Biomedical Image Segmentation. MICCAI, 2015.
- Vaswani, A. et al. Attention Is All You Need. NeurIPS, 2017.
- Peebles, W. and Xie, S. Scalable Diffusion Models with Transformers. ICCV, 2023.
- Rezatofighi, H. et al. Generalized Intersection over Union. CVPR, 2019.
- Nauata, N. et al. House-GAN: Relational Generative Adversarial Networks for Graph-Constrained House Layout Generation. ECCV, 2020.









