Building Sunlight Simulator

项目背景

这个项目最初来自一个很具体的个人需求：我在买房后，希望更直观地判断小区不同楼栋、不同楼层在不同季节和时段下的采光情况。传统的楼盘日照信息往往停留在二维规划图、口头说明或静态效果图上，很难让普通购房者理解楼栋之间的真实遮挡关系。

因此我尝试把小区总平图转化成可交互的 3D 场景，并结合太阳轨迹和建筑遮挡关系做可视化分析。项目后续开源后，很多网友也提出了功能建议和使用反馈，我根据这些反馈持续迭代了编辑器、三维展示、日照热力图和交互体验。最后几次更新中，我也参考了社区 Fork 中的一些二次开发思路，对分户采样、热力图贴附和交互查询等能力进行了吸收和完善。

项目成果

• GitHub 开源项目，当前获得 400+ Stars，在建筑采光模拟这一细分方向中具备较高关注度。
• 被阮一峰《科技爱好者周刊》第 382 期推荐，带来了更多真实用户反馈和二次传播。
• 提供在线 Demo，用户无需安装环境即可查看示例数据；本地使用时可以导入自己的楼盘规划图并生成配置文件。
• 项目采用 MIT License 开源，支持社区 Fork、二次开发和问题反馈。

核心功能

• 规划图编辑器：支持上传 JPG / PNG 总平图，标定比例尺，手动绘制楼栋轮廓，并配置层数、层高、户数等参数。
• 3D 可视化分析：基于 Three.js 将二维轮廓转换为楼栋模型，支持相机旋转、缩放、楼栋标签、阴影和方位罗盘。
• 太阳轨迹计算：结合城市纬度、日期和时间计算太阳高度角与方位角，支持冬至、夏至、春秋分和自定义日期。
• 日照时长量化：按时间步长进行遮挡检测，估算每户日照时长，并通过热力图展示不同楼层和户型的采光差异。
• 纯前端部署：项目不依赖后端服务，HTML / CSS / JavaScript 静态文件即可运行，便于 GitHub Pages 部署和离线使用。

我的工作

• 从真实购房决策场景出发，设计了“规划图配置 -> JSON 数据 -> 3D 日照分析”的完整工具流程。
• 实现楼栋编辑器，将平面图中的建筑轮廓、比例尺和楼栋属性转化为结构化数据。
• 使用 Three.js 构建三维场景，完成楼栋建模、阴影渲染、相机控制、方位罗盘和交互面板。
• 实现太阳轨迹计算和日照遮挡分析，将几何遮挡关系转化为可理解的时间变化和热力图结果。
• 根据开源社区反馈持续优化功能体验，并在后续版本中吸收社区二次开发中的合理思路，完善分户采样和交互查询能力。

技术实现

项目没有引入复杂后端，而是将编辑、数据协议、三维渲染和分析能力都收敛在浏览器端完成。这样做的好处是部署成本低、使用门槛低，也更适合开源传播。

技术上主要包含三部分：

• 数据生产：在编辑器中完成底图加载、比例尺标定、楼栋多边形绘制和属性配置，导出统一 JSON。
• 场景渲染：将楼栋轮廓转换为三维几何体，使用 WebGL 阴影贴图表达遮挡关系。
• 日照分析：根据纬度、日期和时间计算太阳方向，结合建筑几何关系估算不同户型的日照时长。

复盘

这个项目从买房时的一个实际困惑开始，经过自用、开源、用户反馈和社区二次开发，慢慢变成了一个别人也能用的工具。技术栈不复杂，但因为解决的问题足够具体，在这个细分方向上获得了不少关注。

后续如果继续维护，主要想改进数据录入效率、移动端交互和面向普通用户的使用引导。