独立开发
智能家居
数字孪生
Three.js
前端开发
HomeAssistant

全屋智能数字孪生:纯前端的 2D/3D 智慧户型工具 HA3D,支持 1:1 底图描摹、第一人称漫游与 Home Assistant 实时灯光联动

阿瑞
2026-11-19
2371 阅读
热度 3711

一、为什么要做这个项目?

在家庭装修规划和智能家居(尤其是 Home Assistant)折腾过程中,我发现市面上的工具存在一个明显的断层:

  1. 传统家装软件太重 / 商业化绑定深:AutoCAD、SketchUp 对普通人门槛过高;商业云端装修工具虽然上手快,但往往存在生态封闭、导出模型或高清图纸收费、数据无法完全私有化的问题。
  2. 传统 HA 3D 平面图维护成本极高:在 Home Assistant 社区中,流行的 Floorplan 方案通常是先在 SweetHome3D 或 Blender 里建好模、把每种灯的亮灭状态渲染成多张 PNG,再通过 CSS 图层叠加实现开关灯。一旦家里换了个灯、挪了张沙发,或者想看不同色温/RGB 的光影效果,就得重新渲染整套图片,既不实时,也无法自由旋转视角。

因此,我打造了现在的 HA3D 智慧户型 —— 一个**纯前端运行、零后端依赖、同时服务于“装修平面规划”与“Home Assistant 3D 实时可视化”**的开源 Web 应用。

image.png


二、核心功能全景介绍

1. 精密高效的 2D 户型编辑器

在最新版中,我们将 2D 渲染引擎全面升级为基于 requestAnimationFrame 的 Canvas 2D 高帧率引擎,并引入了节点-墙体-洞口拓扑数据模型(TopoGraph),解决了传统独立矩形墙体容易脱节错位的问题:

  • 底图上传与比例尺标定:支持上传开发商户型图作为半透明底图,只需在图上两点标定并输入真实毫米长度(如门宽 900mm),即可自动缩放到 1:1 比例进行描摹。
  • 智能绘图与联动编辑:
    • 支持单段画墙、拆改墙体以及 B 键快速拉矩形房间(支持绘制时直接键盘输入 宽,深 回车精确成型)。
    • 拖动墙体平移或拖拽墙角端点时,相连垂直墙体与附着的门窗会自动跟随伸缩闭合,配合绿色中心线对齐参考线,绘图手感极佳。
    • 选中平开门时支持画布内一键「翻转」开门朝向与合页方向;门窗可直接在墙体间拖拽换墙。
  • 画布内“所见即所得”改数:无需频繁切换右侧属性面板,直接点击画布上的蓝色尺寸数字即可原地修改墙长、门窗宽度、门窗距墙角距离以及家具到四周墙体的离墙距离。
  • 家具库与自动算量:内置卧室、客厅、灯具、餐厨、卫浴、家电、书房·休闲 7 大类常用家具,支持 8 点拖拽缩放、贴墙自动吸附(按住 Alt 临时取消吸附)。系统会自动识别封闭房间、计算套内使用面积,并支持为每个房间切换地面材料(木地板、地砖、大理石、水磨石、地毯等),按 实际面积 + 5% 损耗 估算材料造价。

image.png

2. Three.js 3D 实时场景与第一人称漫游

按下 T 键即可从 2D 无缝切换至 Three.js(r160)构建的 3D 场景:

  • 纯代码程序化建模:家具模型(包含柜门分缝、金属拉手、软包床头、陶瓷与金属环境反射材质等)全部通过 TypeScript + Three.js 代码程序化生成,无需请求动辄数十 MB 的外部模型资源包,首屏加载极快。项目还内置了独立的 /models 模型展厅页面,方便开发者预览和调试各类扩展模型。
  • 双风格 3D 视图与昼夜光影:
    • 提供常规 3D 视图与 HA3D 毛玻璃薄墙视图(半透明磨砂墙体,更适合作为智能家居中控大屏底图)。
    • 支持全高墙 / 剖切墙切换、日照时间滑块(模拟全天候太阳角度与夜景灯光)、以及可选的“墙体灯光遮挡”开关。
  • 第一人称漫游(PC + 移动端适配):PC 端支持 WASD + 鼠标锁定漫游,移动端/平板支持屏幕虚拟摇杆;靠近门扇时可点击或按 E 键实时开关门。此外,在 3D 场景中也可以直接选中并拖动家具,改动实时回写 2D 方案。

image.png

3. Home Assistant 实时双向联动与环境看板

这是 HA3D 区别于普通户型工具的核心能力:

  • WebSocket 原生直连:直接在浏览器中通过 WebSocket 连接内网或公网的 Home Assistant(ws://<IP>:8123/api/websocket),使用 Long-Lived Access Token 鉴权,配置持久化在本地 localStorage 中。
  • 实体绑定与实时同步:将户型中的灯具与 HA 的 light.* 实体绑定后,支持 开/关状态、亮度(Brightness)、色温(Kelvin/Mired)与 RGB 色彩 的双向实时同步。无论是点击 3D 场景里的灯具,还是外部触发自动化,画面都会即时响应。
  • HA 环境感知看板:界面内置了精美的环境数据面板(包含时间/农历问候、室内温湿度、PM2.5、空调/新风/窗帘状态卡片与趋势折线图),配合 HA3D 夜景视图,非常适合直接全屏投放在家里的中控平板上。

image.png

4. 数据安全与多格式导出

  • 纯前端静态部署:项目基于 Next.js output: 'export' 配置,构建产物为纯静态 HTML/JS/CSS(out/ 目录),无需 Node.js 后端即可部署到 NAS(群晖/威联通/飞牛等)、Nginx、Vercel 或 GitHub Pages。
  • 开放的数据导入导出:支持一键导出高清 PNG 图像、JSON 完整方案备份与导入,还支持 直接导出标准 .glb 格式的 3D 场景模型,方便导入 Blender 等专业工具进行后续渲染。

三、技术栈与架构简析(面向开发者)

对于想二次开发或学习 Three.js / Canvas 编辑器架构的同学,本项目也是一个非常干净的工程参考:

  • 前端框架:Next.js 16(Pages Router + 静态导出)+ React 19 + TypeScript 5 + Tailwind CSS v4
  • 2D 引擎(lib/canvas2d.ts、lib/topo.ts、lib/rooms.ts):
    • 将原先的 SVG DOM 渲染重构为 Canvas 2D requestAnimationFrame 渲染管线,支持高 DPI 自适应与几何热区命中检测(hitTestCanvas)。
    • 通过 rectsToTopo / topoToRects 实现矩形墙体与拓扑图模型的双向同步,配合射线法/多边形环路搜索自动识别封闭房间。
  • 3D 引擎(lib/render3d.ts、lib/models/):
    • 采用动态导入按需初始化 Three.js,使用 OrbitControls、PointerLockControls、RoomEnvironment 与 GLTFExporter。
    • 家具模型按空间模块化拆分(bedroom.ts、living.ts、kitchenBath.ts、lights.ts、openings.ts、studyMisc.ts 等),结构清晰,易于扩展自定义家具。
  • HA 通信层(lib/ha.ts):
    • 封装了完整的 HA WebSocket 心跳、重连、状态订阅与服务调用(call_service),无任何中间代理服务器。

四、5 分钟本地运行与部署教程

本地开发与运行

# 1. 安装依赖
npm install

# 2. 启动开发服务器(访问 http://localhost:3000)
npm run dev

静态构建(部署到 NAS / Nginx / 静态托管)

npm run build

构建完成后,项目根目录下的 out/ 文件夹即为完整的纯静态网站,直接将其放入任意 Web 服务器的根目录即可访问。

关于 Home Assistant 跨域/混合内容提示:如果 HA3D 部署在 HTTPS 域名下,浏览器可能会拦截 ws:// 非加密连接,建议将 HA 配置为 wss://(通过反向代理开启 HTTPS),或在局域网内直接通过 HTTP 访问本地部署的 HA3D 站点。


演示与下载

付费资源

许可协议:知识共享声明

本站所有原创文章应用 CC BY-NC-SA 4.0 协议。转载请注明作者及出处,且不可用于商业目的。

免责声明

本站提供的所有资源仅供学习与学术研究参考。请于下载后 24 小时内自觉删除。如有侵权,请通过留言或反馈通道告知,我们将在收到通知后立即进行处理。

互动评论

登录后参与精彩讨论

演示与下载

付费资源
获取权限单次付费解锁
¥29.9/ 永久有效
浏览次数2371
最近售出67
近期推荐
暂无推荐
Admin

李瑞 (RUI)

SHUMOX FOUNDER

专注前端架构、React 生态与独立开发变现。分享最硬核的技术实战经验。

Gemini

Gemini

AI-Native
Powered byGoogle

基于 Google Gemini 模型深度协同构建,从全栈架构到交互细节,持续探索人机共创的高效开发新范式。

全栈架构人机协同持续演进
Gemini Co-Engineered · Powered by Google
Claude

Claude

Reasoning
Powered byAnthropic

由 Anthropic Claude 深度协同构建,以更强的推理与编码能力驱动站点持续迭代进化。

深度推理编码协作安全可控
Claude Co-Engineered · Powered by Anthropic

订阅周刊

每周一发布,分享最新的技术动态、设计灵感和独立开发经验。

© 2026 Shumox. All Rights Reserved.

苏ICP备2023001297号