🏢 Building Sunlight Simulator

建筑采光模拟工具 · 轻量级楼盘日照分析解决方案

👉 点击查看在线演示 (Live Demo) 👈

注：在线演示仅展示默认数据，如需自定义规划图请参考下文“本地使用”。

效果预览

📋 项目简介

Building Sunlight Simulator 是一套基于 Web 技术的楼盘规划与采光模拟工具。

它允许用户直接在浏览器中通过规划图（JPG/PNG）绘制建筑轮廓，生成 3D 场景，并结合地理纬度和太阳轨迹算法，对目标建筑进行精确的日照遮挡分析。项目纯前端实现，无后端依赖，支持离线使用。

✨ 核心特性

| 模块 | 功能描述 | |------|----------| | 部署 | 纯静态 HTML/CSS/JS，下载即用，无需安装环境 | | 编辑 | 2D 平面图转 3D 模型，支持楼栋轮廓绘制、层高设置、比例尺标定 | | 计算 | 基于球面三角学计算太阳轨迹，内置 50+ 城市纬度数据 | | 可视 | 4096px 高精度阴影贴图，支持冬至/夏至/春秋分及自定义日期，06:00-18:00 实时调节，配备专业罗盘指南针 | | 量化 | 每户日照时长计算与热力图展示（淡黄到深橙色阶），支持单户详情交互查询，行业标准8小时上限 | | 交互 | 支持 PC 端及移动端触控，可过滤非本小区建筑 | | 多语言 | 支持中英文切换，界面右上角可自由切换语言 |

📊 日照时长量化分析

采光检测点计算：对每栋本小区建筑（isThisCommunity: true），根据楼层数和户数，在南面墙体上生成每户的采光检测点。检测点位于每户南窗中心位置（楼层中间偏上1.2米处）。
日照时长计算：从 6:00 到 18:00，按 6 分钟间隔进行射线检测。如果该时刻太阳方向的射线未被任何建筑物遮挡，则累计该时间段的日照。
热力图显示：计算完成后可开启热力图模式，在每户南窗位置显示彩色方块。采用温暖色系，从淡黄色（0小时）渐变到深橙色（8小时及以上），符合行业标准。
交互功能：开启热力图后点击任意户型方块，可查看该户的详细信息（楼层、户号、日照时长、日照状态）。

🧭 专业罗盘指南针

地面配备专业3D罗盘，清晰标注东南西北方位，北方用红色突出显示，替代传统简单箭头，提供更专业的方位指示。

🚀 快速开始

本项目包含两个核心文件：editor.html（数据生产）和 index.html（数据消费）。

1. 获取项目

git clone https://github.com/seanwong17/building-sunlight-simulator.git
或者直接下载 ZIP 解压

2. 运行方式

本项目不依赖构建工具，选择以下任一方式打开：

直接打开：双击文件夹中的 editor.html 或 index.html 即可在浏览器运行。
本地服务（可选）：如果需要热更新或解决跨域限制，可使用 live-server 或 python -m http.server。

📖 使用流程

流程：规划图配置 (Editor) ➜ 导出 JSON ➜ 采光分析 (Viewer)

Step 1: 制作数据 (editor.html)

打开 editor.html，将平面的规划图转化为 3D 模拟所需的 JSON 数据。

上传底图：支持 JPG/PNG 格式的规划图或总平图。
标定比例：在图上选取已知距离的两点（如标尺），输入实际距离（米）。
绘制楼栋：左键点击描点，双击闭合生成轮廓。
设置属性：选中楼栋，设置层数、层高、地理位置等参数。
导出配置：点击保存，生成配置文件（默认为 data.json）。

📌 编辑器快捷键

| 操作 | 快捷键 | |------|--------| | 缩放视图 | 鼠标滚轮 | | 拖拽画布 | 鼠标中键 / 空格+左键 | | 撤销绘制 | 鼠标右键 | | 完成闭合 | 双击左键 |

编辑器界面

Step 2: 模拟分析 (index.html)

打开 index.html，进行 3D 可视化分析。

导入数据：点击按钮加载上一步导出的 JSON 文件（或使用仓库内的 examples/sample.json 进行测试）。
调整环境：选择预设城市或手动输入纬度，切换日期（冬至/夏至/春秋分/自定义日期）。
观察阴影：拖动时间滑块，观察目标楼层的日照遮挡情况。地面罗盘指示方位。
量化分析：点击"计算日照时长"，查看热力图（淡黄到深橙色阶）及具体户型数据。点击热力图方块可查看单户详情。

📐 数据协议

项目通过 JSON 格式传递建筑数据。examples/sample.json 提供了完整的示例数据。

点击查看 JSON 结构说明

{
  "version": 1.7,                  // 数据版本
  "latitude": 36.65,               // 项目纬度（影响太阳高度角）
  "scaleRatio": 0.483,             // 比例尺：1像素 = N米
  "origin": { "x": 306, "y": 336 },// 坐标系原点（像素）
  "buildings": [
    {
      "name": "1号楼",
      "floors": 18,                // 层数
      "floorHeight": 3,            // 层高（米）
      "totalHeight": 54,           // 总高度（可选，默认自动计算）
      "isThisCommunity": true,     // 是否为目标小区（用于高亮/过滤）
      "shape": [                   // 轮廓顶点坐标（相对于 origin 的米数）
        { "x": -19.18, "y": -107.28 },
        { "x": -19.18, "y": -115.55 },
        { "x": 2.51, "y": -115.31 }
      ],
      "center": { "x": -8.36, "y": -111.45 }
    }
  ]
}

🛠️ 技术实现

渲染引擎: Three.js (WebGL)
阴影方案: PCFSoftShadowMap
太阳算法:

* 太阳高度角: $\sin(h) = \sin(\phi)\sin(\delta) + \cos(\phi)\cos(\delta)\cos(\omega)$ * 太阳方位角: $\cos(A) = (\sin(h)\sin(\phi) - \sin(\delta)) / (\cos(h)\cos(\phi))$

项目结构

building-sunlight-simulator/
├── css/                    # 样式文件
├── js/
│   ├── config.js          # 全局配置
│   ├── utils.js           # 工具函数
│   ├── i18n.js            # 国际化
│   ├── cities.js          # 城市数据
│   ├── editor.js          # 编辑器逻辑
│   └── viewer.js          # 查看器逻辑
├── examples/              # 示例数据
├── editor.html            # 编辑器页面
└── index.html             # 查看器页面