素材与 3D 户型图

素材管理和 3D 户型图工作室是两个入口：工作室绘制、布置灯光并导出图片，编辑器负责选取并叠加图片。完成绘制后，也可以使用户型图自动导图在主页面生成图片和效果控件。

图片素材的两个来源

图片选择器只有两个来源：

• 我的图片：用户上传的图片，以及 3D 户型图工作室导出的文件；
• 栖光素材：随「栖光」UI 方案提供的内置素材。

3D 导出文件归入「我的图片」的导出文件夹，不是第三个来源。

上传、搜索和删除

支持 PNG、JPG、JPEG、WebP 和 SVG；SVG 最大 5 MB，位图最多 10,000,000 像素且单边不超过 8192。素材过大可能拖慢加载。

素材管理支持按文件夹筛选、按名称搜索、预览和删除。被仪表盘或户型图引用的图片需先移除引用。

打开户型图工作室

在编辑器左侧顶部点击「户型图绘制」。工作室独立于仪表盘，结果可被多个仪表盘使用。流程为：导入底图 → 标定比例 → 描绘户型 → 摆放物件 → 放置灯光 → 保存图片。

1. 导入底图并标定比例

1. 导入户型平面图作为底图。
2. 选择「参考线」，在底图上画已知长度的线。
3. 填写真实长度并确认比例。
4. 多楼层时，每个楼层都要分别完成比例校准。

没有真实长度无法计算墙体和家具尺寸；先完成比例校准再画墙。底图只是参考，不会自动变成墙体。

2. 描绘户型

工具栏包含选择、参考线、墙体、窗户、门、栏杆、铭牌、删除、旋转画布和适应画布。可开启吸附，并选择端点、交点、墙线、垂直优先、15° 角度、网格和吸附距离。

1. 使用「墙体」沿底图描绘外墙和隔墙。
2. 需要地面的房间必须闭合墙线；未闭合的线不会生成地面。
3. 将门、窗或栏杆靠近墙体放置，使其吸附到墙线。
4. 用「选择」调整对象，用「删除」移除误画内容。

多楼层时分别完成比例和墙体，再用「对齐楼层」指定参照点。

3. 摆放物件和铭牌

物件按家居、电器、灯光分类。拖入场景后可修改：

• 位置；
• 宽、深、高；
• 离地高度；
• 旋转角度。

户型铭牌支持修改中英文标题、字间距和底线长度。摆放后在 3D 预览检查穿墙、悬空和遮挡。

4. 放置灯光

灯具是具体的光源对象，灯组用于把多个灯具归在一起统一控制；导图完成后，导出的户型图和灯光图层会自动出现在素材库「我的图片」的对应导出文件夹中。

灯具可设置所属灯组、色温、亮度、照射范围和光束角。灯组支持开关、重命名、复制、删除和排序；多选灯具可批量应用属性。

生成多灯光缓存时相机可能暂时只能缩放，等待完成后再调整视角。

5. 3D 预览与视角

预览支持当前层或全楼；视角有「自由」和「顶视」，投影有「正交」和「透视」。焦段仅在透视模式生效，可保存和恢复楼层及全楼视角。

• 当前层使用「保存视角」「恢复视角」；全楼使用「保存总览」「恢复总览」。
• 全楼模式提供「层间距」，用来调整各层在预览构图中的展示间隔。
• 左键旋转、右键平移、滚轮缩放；「重置视角」用于重新居中。

本轮待发布的预览调整

以下调整属于 v0.4.5 之后的待发布更新，本文编写时正式版仍为 v0.4.5：

• 工具栏保持两行操作区，收紧全楼模式下层间距控件的占用；「进阶设置」移到滚轮缩放提示后方，用于打开基础光调节。
• 「重置视角」按墙体、地面、门窗等户型结构计算中心，外围家具、电器、汽车、灯具和铭牌不再拉偏旋转中心，也不会因此被隐藏或删除。
• 旧的已存视角仍恢复原构图；想采用新的居中方式时，先重置再保存视角。右键平移后的旋转中心仍随平移改变。
• 工作室会在浏览器空闲时提前准备灯光渲染，减轻首次开灯停顿，无需手动开启，也不会改变灯组开关状态。刚进入页面或性能较弱的设备仍可能短暂停顿。

上图使用本地双层住宅演示数据。右上角「进阶设置」位于鼠标操作提示后方；正式版升级前的工具栏位置可能不同。

按“墙体和地面 → 门窗 → 家具电器 → 灯光阴影 → 当前层/全楼”检查。预览正常后仍需保存图片导出。

6. 保存图片并导出

1. 点击预览工具栏的「导图」，进入导出工作区并填写文件夹名。
2. 设置输出宽高（默认约 1852 × 1293），需要保持比例时锁定比例。
3. 选择当前楼层或全楼、视角、投影、焦段和已保存视角。
4. 选择导出内容，点击「保存导图」并等待完成。

建议输出宽高与目标仪表盘画布一致，至少保持相同比例。这样导入后叠加底图、户型图和灯光层时更容易对齐；使用其他尺寸时，需要在编辑器中重新检查位置和缩放。

输出为 WebP / sRGB，保存到 HA Bridge 的 data/exports。常见文件包括：

• 00底图.webp；
• 00底图带户型.webp；
• 00电视-开.webp、00汽车-充电中.webp 等状态图层；
• 00户型图.webp；
• 各灯组的透明光效层；
• lights.json 和 scene.json 场景数据。

所有导出层使用同一视角，可在仪表盘中作为多个图片控件叠加。回到编辑器后，在「我的图片」中按导出文件夹查找。

确认覆盖同名导图时，原文件夹会整体替换，本次未勾选的旧文件也会删除；其他页面引用该文件夹的图片也会受影响。希望保留多套构图或各楼层成品时，请使用不同文件夹名。

7. 导出后制作仪表盘

3D 户型图工作室和仪表盘编辑器是两个独立入口。可选择自动导图流程，也可以按下面的手动叠图流程把导出图片接入仪表盘：

1. 先按栖光模板或空白仪表盘创建项目，打开目标仪表盘，确认设备方向和画布比例；
2. 在目标主页面进入编辑模式，从「我的图片」添加导出的底图、户型图和灯光层；

3. 按“底图 → 户型图 → 灯光效果”的顺序排列图层，并把各图片控件调整到相同位置和尺寸；
4. 在户型图中对应的设备位置添加设备按钮、开关或其他控件，绑定 Home Assistant 实体；

5. 为控件设置点按、双击、长按或弹窗动作，保存后切换到「仪表盘」模式验证；
6. 确认画面位置、灯光效果和设备状态都正常，再复制到其他页面或中控设备。

手动导出的图片和灯光层只负责显示，需要在同一页面上另加控件并绑定实体。自动导图流程会生成效果按钮，但仍要检查关联实体和动作。户型图通常属于某个房间的主页面，不建议放入会跨页面显示的侧边栏。

图片控件的具体设置见认识控件及实体配置；完整的页面、控件和交互编辑流程见编辑器与基本操作。

常见问题

• 没有地面：检查墙线是否闭合；
• 家具尺寸不对：检查当前楼层是否完成比例标定；
• 门窗不贴墙：重新拖近墙线并确认吸附已开启；
• 楼层错位：使用「对齐楼层」重新指定参照点；
• 导出的图片找不到：确认导出完成，并在「我的图片」按文件夹搜索；
• 图片不能删除：先在仪表盘和户型图中移除所有引用。

通过域名访问时模型一直加载、重置视角后中心不符合预期，或首次开灯持续卡顿，可继续查看更新与使用问题排查。

在仪表盘中交互使用户型

户型保存后，可以添加3D 交互控件，配置楼层视角、灯光、设备与摄像头，让手机和平板直接在 3D 户型里操作。