HackSimBuild 2026 — IBPSA SimBuild Hackathon
PrestoGeometry converts walk-around photos of a building exterior into a representative floor plan geometry file for building energy modelling.
Current output: a Floorspace.js
.json file — a schema-validated starting point that can be refined in the
Floorspace.js web editor and exported to EnergyPlus, OpenStudio, or HPXML
formats.
Walk-around photos
│
▼
[Annotate] ── trace the edges of each building face in the photos
│ mark shared corners so the tool learns face order
▼
[Assemble] ── review photo-estimated face widths
adjust corner angles, solve for a closed floor plan
save a Floorspace.js geometry file
The photo annotation and assembly steps are both interactive graphical tools launched from a single launcher window.
- Windows 10 / 11 (the
.batlaunchers are Windows-only; the Python tools themselves are cross-platform) - Python 3.10 or newer — either via Miniconda/Anaconda or a standalone Python installer
- Internet connection (to download packages on first install)
git clone https://github.com/GFlechas/PrestoGeometry.git
cd PrestoGeometry
Double-click install.bat (or run it from a command prompt).
The installer will ask which environment type you prefer:
Which environment type would you like to use?
[1] Conda (recommended — Miniconda or Anaconda)
[2] Python venv (uses your system Python + pip)
The installer automatically searches for a Miniconda or Anaconda installation in the most common Windows locations. If it finds one it will ask you to confirm; otherwise it will prompt for the path.
It then:
- Creates a new conda environment named
presto_geometry(customisable) usingenvironment.yml - Installs all required packages
- Writes
_env.bat— a small config file that records the path to the environment'spython.exe
Tip: if the environment already exists the installer asks whether to reuse it (and update packages) or recreate it from scratch.
The installer automatically detects your system Python (requires 3.10+) and:
- Creates a
.venvvirtual environment at the repo root - Runs
pip install -e .to install the package and all dependencies - Writes
_env.bat
_env.bat is a one-line machine-specific config file generated by the
installer. It records the full path to python.exe for your environment so
that launch.bat, annotate.bat, and assemble.bat all use the correct
Python without any hardcoded paths. It is git-ignored and must be
regenerated if you move the repository or change environments.
Once installation is complete, double-click launch.bat to open the
graphical launcher.
PrestoGeometry | building photos → energy model geometry
────────────────────────────────────────────────────────
1 Select a Photos Folder
2 Annotate Building Faces ● No annotations yet
3 Assemble & Save Geometry ● No geometry saved yet
4 Use the Output
The launcher guides you through all four steps. Status indicators (● / ✔) update automatically as you complete each step.
Click Browse… and select the folder containing your walk-around photos.
Tips for good photos:
- Walk a full loop around the building so every exterior face appears in at least one photo
- Capture the full height of each face (roof line to ground)
- Overlap between consecutive photos helps establish corner relationships
- Photos taken more nearly perpendicular to a face give better width estimates than heavily oblique shots
The Building name field auto-fills from the folder name; edit it if needed. This name is used for all annotation and output files.
Set the number of faces to annotate (2–8), then click Open Annotation Tool.
The annotation window opens with the first photo. A sidebar on the left contains face selector buttons (F0–F7) and tool controls.
| Key / action | What it does |
|---|---|
| 1–8 | Select the active face (F0–F7) |
| Left-click | Place a point. Subsequent clicks chain into segments. |
| Right-click / Esc | Break the current chain |
| Scroll wheel | Zoom in / out centred on cursor |
| Middle-mouse drag | Pan the view |
| R | Reset zoom to fit the full image |
| N | Toggle CLAHE contrast enhancement (display only) |
| U | Undo the last segment on the active face |
| C | Clear all annotations on the current image |
| Space / → | Save and advance to the next image |
| ← / B | Go back to the previous image |
| H | Toggle the full control reference overlay |
| Q | Quit and save everything |
- Press a number key to select the face you are tracing (e.g. 1 for F0).
- Trace all four edges of each visible face (top, bottom, left side, right side). Click to start, click again to extend the segment chain.
- At building corners — when two faces share an edge, snap the endpoint of one face's segment onto an endpoint of the adjacent face. A yellow ring appears when your cursor is within snapping distance. This shared corner tells the assembler which faces are neighbours and in what order.
- Press Space to move to the next image when you are done with the current one.
- You do not need to annotate every photo. Focus on the images that show each face most clearly. Faces photographed more head-on give better dimension estimates.
Annotations are saved automatically after every segment to
data/annotations/<building>/<building>.json.
Click Open Assembly Tool. Face widths are estimated automatically from the photo annotations.
The assembly window shows a floor plan on the left and a 3-D view on the right. Face widths are estimated from the photo annotations.
| Button | What it does |
|---|---|
| Solve | Find corner angles that close the polygon |
| Reset 90° | Restore all corners to 90° and clear free/mode settings |
| Save PNG | Write a floor-plan + 3-D image to data/outputs/geometry/ |
| Save Geometry | Write a Floorspace.js .json file to data/outputs/geometry/ |
| Convex: OFF/ON | Toggle the convexity constraint (∑ corner angles = 360°) |
Each face has:
- A width text box — pre-populated from the photo estimate. Type a known value (e.g. from Google Earth) and press Enter to override it.
- A Free / Fixed toggle — when Fixed (green), the solver will not change that face's width.
- A [flex] label on one face — the flex face is allowed to stretch ± tolerance to help the solver close the polygon. Click F# (click to cycle) to change which face is the flex face.
- A Tolerance ± m field — how far the flex face can stretch (default 10 m).
Click any corner circle on the floor plan to cycle through four modes:
| Colour | Mode | Meaning |
|---|---|---|
| Green | Fixed | Held at exactly 90° — not changed by the solver |
| Yellow | Free | Solver picks the best angle (2°–178°) |
| Orange | Acute | Solver constrains angle to < 90° |
| Blue | Obtuse | Solver constrains angle to > 90° |
- Review the width estimates. These are derived from the photo aspect ratios. Long faces photographed at steep oblique angles are often underestimated. If you know any face widths (Google Earth, blueprints, laser measure), type them into the text boxes and mark them Fixed.
- Mark non-rectangular corners as Free. For a rectangular building all corners can stay Fixed. For an L-shape or angled corner, click the relevant corners to make them Free (yellow).
- Enable Convex if the building is convex (no re-entrant corners). This
adds
∑ angles = 360°as an extra solver constraint, preventing the solver from producing a concave shape. - Click Solve. The solver finds corner angles that close the polygon while minimising deviation from 90° (or from the acute/obtuse bounds). The flex face absorbs any residual mismatch.
- Inspect the result. The floor plan updates immediately. The status bar shows closure error and whether the solution is valid. If the shape looks wrong, try setting different corners as Acute / Obtuse, or toggle Convex on/off.
- Click Save Geometry when satisfied.
Click Open Output Folder to open data/outputs/geometry/<building>/ in
Windows Explorer. The folder contains:
| File | Contents |
|---|---|
<building>.json |
Floorspace.js geometry (schema v0.7.0) |
<building>_geometry.png |
Floor plan + 3-D view image (if saved) |
- Open https://nrel.github.io/floorspace.js/
- In the menu bar choose File → Import
- Select the
.jsonfile - The floor plan loads and can be refined (add windows, doors, spaces, thermal zones) before export
The Floorspace.js Web Editor ↗ button in the launcher opens the web editor directly in your browser.
Each tool can also be launched from the command line after running the installer once.
annotate.bat [building_name] [--photos-dir PATH] [--faces N]
| Argument | Default | Description |
|---|---|---|
building_name |
UnivStThomas_1loop |
Name used for annotation files |
--photos-dir PATH |
photos/<building> |
Path to a folder of photos |
--faces N |
4 |
Number of faces available in the sidebar |
Examples:
annotate.bat
annotate.bat MyBuilding --photos-dir "C:\Photos\MyBuilding" --faces 5
annotate.bat UnivStThomas_1loopassemble.bat [building_name] [--widths F0=W,...]
| Argument | Default | Description |
|---|---|---|
building_name |
UnivStThomas_1loop |
Must match the annotation file name |
--widths F0=13,... |
(estimated from photos) | Comma-separated width overrides in metres |
Examples:
assemble.bat
assemble.bat MyBuilding
assemble.bat MyBuilding --widths F0=13,F1=47,F2=15,F3=40,F4=10tools/
launcher.py ← graphical launcher (step-by-step guide)
annotate_building.py ← annotation tool
assemble_geometry.py ← assembly + interactive editor
photos/
UnivStThomas_1loop/ ← included test dataset (University of St. Thomas)
UnivStThomas/
LoringPark/
data/
annotations/ ← saved annotation JSON files (auto-created)
outputs/geometry/ ← saved PNGs and Floorspace.js files (gitignored)
presto_geometry/
models/building.py ← Floorspace.js-aligned data model
exporters/floorspace.py ← schema-validated JSON serialiser
schemas/ ← vendored Floorspace.js v0.7.0 JSON Schema
reconstruction/ ← DUSt3R photogrammetry pipeline (in development)
web/ ← Flask API + React editor (in development)
install.bat ← installer (run this first)
launch.bat ← opens the graphical launcher
annotate.bat ← opens the annotation tool directly
assemble.bat ← opens the assembly tool directly
_env.bat ← gitignored, generated by install.bat
environment.yml ← conda environment spec
requirements.txt ← pip dependencies
pyproject.toml ← package metadata
The saved .json file conforms to the
Floorspace.js geometry schema v0.7.0.
It is validated against the schema before being written — if validation fails
an error is shown in the assembly tool's status bar.
The file contains a single-story building where floor_to_ceiling_height is
set to the total building height (floors × floor height). This is intentional:
the file is a starting point, not a finished model. Multi-story refinement
can be added in the Floorspace.js editor.
The following features are planned or in active development:
- IDF / OSM / HPXML export — converting the Floorspace.js file into EnergyPlus, OpenStudio, and HPXML simulation inputs
- DUSt3R photogrammetry pipeline — automatic 3-D reconstruction from photos without manual annotation (requires a GPU and additional DUSt3R installation)
- Multi-story floor plan refinement — propagating the ground-floor plan to upper floors with per-floor overrides
MIT — see LICENSE.