---
## đ Introduction
**Building Sunlight Simulator** is a web-based tool for architectural planning and sunlight simulation.
It lets users draw building outlines over a JPG/PNG plan, generate a 3D scene, and estimate sunlight occlusion using the project location and solar trajectory. The project is entirely frontend-based; all runtime dependencies ship in the repository, so it needs neither a backend nor a network connection.
---
## ⨠Core Features
| Module | Description |
|--------|-------------|
| **Deployment** | Pure static HTML/CSS/JS. Download and run, no environment installation required. |
| **Editor** | Converts 2D plans to 3D models with JSON/image drag-and-drop, building selection and movement, edit undo, and visual apartment splits. |
| **Calculation** | Uses spherical trigonometry for solar paths. Built-in coordinates and IANA time zones for 50+ major cities. |
| **Visuals** | High-precision 4096px shadow maps. Hemisphere-aware solstice/equinox labels and custom dates with local-civil-time adjustment (06:00-18:00). Professional compass for orientation. |
| **Quantification** | Estimates cumulative sunlight per apartment with a heatmap, apartment details, configurable reference duration, and reusable analysis results. |
| **Interaction** | Supports desktop and mobile controls plus file drag-and-drop. Filtering non-target buildings preserves the current camera view. |
| **Multi-language** | Supports Chinese/English switching. Language toggle available in the top-right corner. |
### đ Quantified Sunlight Analysis
* **Detection Point Generation**: For target buildings (`isThisCommunity: true`), every exterior-wall segment is mapped to an apartment along the configured split axis, with a detection point placed at window height on each floor. An apartment may span several facade segments; its reported duration is the maximum among those segments.
* **Duration Calculation**: Performs midpoint raycasting over 6-minute intervals from 06:00 to 18:00 local civil time. Longitude, IANA time zone, and the equation of time convert civil time to apparent solar time before each direction is calculated.
* **Heatmap Visualization**: Displays color-coded tiles on the sampled exterior-wall segments. It uses a warm color scheme from light yellow (0h) to deep orange (8h+).
* **Interaction**: Click a heatmap tile to inspect its floor, unit number, cumulative sunlight, and reference status. The reference duration is configurable and defaults to 2 hours.
> **Scope**: This is a planning visualization estimate based on cumulative 6-minute intervals and the maximum among an apartment's exterior-facade samples. It is not a universal regulatory compliance result. Formal assessment must apply local rules for dates, test points, and continuous-duration requirements.
### đ§ Professional Compass
* Professional 3D compass on the ground clearly marks cardinal directions (N/S/E/W), with north highlighted in red, replacing traditional simple arrows for better orientation guidance.
---
## đ Quick Start
The project consists of two core files: `editor.html` (Data Producer) and `index.html` (Data Consumer/Viewer).
### 1. Get the Project
```bash
git clone [https://github.com/seanwong17/building-sunlight-simulator.git](https://github.com/seanwong17/building-sunlight-simulator.git)
# Or download the ZIP directly
```
### 2. How to Run
No build tools are required. Choose one of the following methods:
* **Direct Open**: Double-click `editor.html` or `index.html` in your file explorer to run in the browser.
* **Local Server (Recommended)**: For hot-reloading or to avoid local file CORS restrictions, use `live-server` or `python -m http.server`.
---
## đ Usage Workflow
Flow: **Plan Configuration (Editor)** â **Export JSON** â **Sunlight Analysis (Viewer)**
### Step 1: Create Data (editor.html)
Open `editor.html` to convert your 2D floor plan into the JSON data required for 3D simulation.
1. **Import a Project**: Click or drop a JPG/PNG plan to start a project, or import a previously exported JSON file to continue editing.
2. **Calibrate Scale**: Pick two points on the map with a known distance (e.g., a scale bar) and input the actual distance in meters.
3. **Draw and Adjust Buildings**: Left-click to plot points, then use Finish Outline or double-click to close the shape. Outside drawing mode, select and drag buildings; Undo Edit restores create, move, delete, and property changes.
4. **Set Properties**: Configure floors, floor height, units per floor, and location. Use Visual Editor to adjust the split axis and apartment width ratios per floor or across all floors. Imported floor-specific unit counts are preserved; adding or removing floors extends ratios from the last floor or trims extra rows. Visual editing keeps every unit at 1% or more and dynamically caps the maximum ratio.
5. **Export Config**: Click save to generate the configuration file (defaults to `data.json`).
### Step 2: Simulate (index.html)
Open `index.html` for 3D visualization and analysis.
1. **Import Data**: Click the button or drop a JSON file onto the page to load an exported project (or use `examples/sample.json` for testing).
2. **Adjust Environment**: Select a preset city or manually enter latitude, longitude, and an IANA time zone; switch dates (Winter/Summer Solstice/Spring Equinox/Autumn Equinox/Custom Date).
3. **Observe Shadows**: Drag the time slider to observe sunlight occlusion on the target floors throughout the day. Ground compass indicates orientation.
4. **Quantified Analysis**: Set a reference duration, then click "Calculate Sunlight Duration" to view the heatmap and apartment data. Click heatmap tiles to inspect individual units.
5. **Reuse Results**: After calculation, export Project and Results. On re-import, the Viewer restores the saved season preset or exact custom date and loads the result when geometry, location, north angle, and sampling parameters still match. Changing only the reference duration reuses the computed hours and rebuilds the statistics.
---
## đ Data Protocol
The project uses JSON to transfer building data. `examples/sample.json` provides a complete example.
