数字孪生Three组件使用

约 14230 字大约 47 分钟

2025-08-14

📢 近期更新

2026/08/23：BVH碰撞体构建优化，分帧构建策略避免主线程冻结 → 立即查看
2026/06/29：着色器系统大更新：57种内置着色器、分类标签页UI、模型选择器、Entity多模型支持 → 立即查看
2026/02/01：新增「场景编辑器」功能 → 立即查看
2026/01/25：新增「模型场景事件配置」功能 → 立即查看
2026/01/25：背景设置新增 HDR 支持 → 立即查看
2026/01/25：新增「着色器效果配置」功能 → 立即查看
2026/01/25：新增「环境效果预设」功能 → 立即查看

1-孪生组件拖出与移动

说明

必须按住【Alt】键才能对组件进行缩放和位移，否则鼠标的移动会触发孪生组件的相机视角变化，一般建议点击顶部快捷键【全屏铺满】

2-添加模型

说明

1.鼠标选中【数字孪生-three】组件
2.右侧属性面板中【模型组】点添加，选中模型，点击【确定】，仅支持 glb/gltf两种模型格式
3.命名不能与之前的模型名重复
4.模型维护路径：【资源广场】 - 【三维模型】，非管理员账号只能维护【我的资源】，不可维护【公共资源】
5.添加模型后如果看不见模型，有可能是模型太大了或者是太小了，或者中心点不对，请调整相机或者缩放

3-模型基本属性配置

说明

模型基本属性支持：隐藏显示模型，配置动画，位移，旋转，缩放
一般不建议调整模型大小，建模一般根据标准尺寸建模，可以调整相机位置，让整个场景看起来协调

4-配置相机属性

4-1-自由相机漫游（第一人称视角）

🎮 这是什么？

自由相机漫游让您像玩 FPS 游戏一样，用键盘和鼠标在三维场景中自由移动。适合近距离观察设备细节、沉浸式巡检等场景。

✅ 什么时候用？
需要走近查看某个设备的细节
想体验“身临其境”的巡检感觉
给客户做虚拟导览展示

快速上手

第一步：启用功能

选中数字孪生 Three 组件
在右侧【相机】模块中
勾选 "模型可点击"
勾选 "自由视角漫游"

第二步：设置观察焦点（可选）

按住 Shift 键 + 鼠标左键点击场景中的任意模型
相机会将该模型设为观察中心，后续移动将围绕它进行

第三步：开始漫游 使用以下键盘按键控制相机：

按键	功能
W 或 ↑	向前移动
S 或 ↓	向后移动
A 或 ←	向左移动
D 或 →	向右移动
Q	向上升起
E	向下降低
鼠标移动	环顾四周（360°）

调整移动参数

如果觉得移动太快或太慢，可以调整以下参数：

水平移动速度（1-50）

控制 W/S/A/D 的移动速度
建议值：小场景用 5-10，大场景用 15-25

垂直移动速度（1-50）

控制 Q/E 的升降速度
建议值：3-8（太快容易晕）

使用技巧

技巧1：快速定位到某个设备

先用鼠标点击选中目标设备
按 Shift + 点击该设备
相机会立即跳转到该位置并聚焦

技巧2：避免眩晕

初次使用时，建议将移动速度调低（5-10）

技巧3：配合其他功能

可以先用【摄像头动画轨迹】飞到某个区域
然后启用自由相机漫游，近距离观察
观察完后，点击【重置相机】回到初始位置

常见问题

Q1：为什么我按键盘没反应？

A：请检查：

是否在预览模式下（编辑模式下可能不生效）
是否已勾选“自由视角漫游”开关
浏览器窗口是否处于激活状态（点击一下页面）

Q2：移动时画面卡顿怎么办？

A：尝试：

降低移动速度
关闭其他不必要的特效（如雾效果、后处理）
检查电脑性能是否足够

注意

自由相机漫游仅在预览模式下完全生效
长时间使用可能导致眩晕，建议适时休息
如果场景非常大，建议先飞到目标区域再启用漫游

5-配置轨道控制器

说明

是否允许使用控制器(鼠标缩放、移动、旋转场景)，
缩放范围
自动旋转
键盘控制（如：按住【Alt】键鼠标变成拖拽模式）
阻尼（鼠标控制的敏感度以及松开鼠标后的惯性）

6-配置辅助工具

说明

辅助工具有：模型可点击、模型点击变色、显示帧数、视图辅助工具、坐标线、网格

7-灯光配置

说明

灯光：环境光、平行光、点光源、聚光灯
灯光辅助视图

8-背景设置

说明

使用自定义颜色作为背景
使用图片作为背景
背景支持全景模式
背景支持透明
背景支持HDR [新增功能（2026/01/25）]

新增功能（2026/01/25）

为了让场景更具真实感，我们现在支持HDR背景。HDR背景能够显著提升场景中的光影细节表现。

9-设计孪生组件-添加到孪生库

说明

后续设计孪生交互从孪生库中选择
孪生组件支持任意二维组件，也可以是AI生成的组件
如：孪生交互需要点击点位展示摄像头监控，则拖出iframe组件，链入监控地址，添加到孪生库，下一个教程二维孪生交互选中摄像头组件即可达到效果

10-二维孪生交互设计

说明

二维孪生交互设计通过css2d实现二维组件与三位场景的完美融合
点位标注支持动态配置，支持素材库图片作为标注点
点位支持鼠标取点
孪生组件从孪生库中选中
二维孪生组件始终面向摄像头

10-1-添加二维孪生交互点位

说明

二维孪生交互设计第一步得先建立点位
以下视频为：为左下角办公室区域建立一个点位

10-2-将点位快速定位到选中模型位置

注意

【使用点位】是应用到选中行，请不要选错行
快速应用点位之后可能位置有些偏差，需要微调
确定好点位之后，最好先关闭模型可点击，并将颜色恢复

10-3-更换标注类型

提示

不同类型的点位使用不同类型的标注可以更加清晰体现功能目的，以下为变压器添加一个变压器类型图标点位
图片标注可以从图片资源中选择，支持动态图片
无标住类通常用于直接展示css2d孪生组件,一般也不命名、不支持关闭，这样看起来就是一个永远存在的2D组件

10-4-点击展示CSS2D孪生组件

提示

点击展示孪生组件功能是实现二维组件和三维场景融合在一起的重要功能
孪生组件从孪生库中选择，孪生库添加方式见： 9-设计孪生组件-添加到孪生库
孪生组件可以配合AI生成更加丰富的组件
配合【点击后摄像头贴近】展示css2d孪生组件的同时，摄像头将贴近孪生组件，贴近值请调整到合适的角度

11-三维孪生交互设计

说明

三维孪生交互设计通过css3d实现，将二维组件当成三维实体，二维组件与三位场景的完美融合
点位标注支持动态配置
点位支持鼠标取点
孪生组件从孪生库中选中
三维孪生组件作为场景一部分位置固定，不会随摄像头改变而变更视角

12-摄像头动画轨迹(开场动画)

说明

功能介绍：摄像头动画轨迹是配置摄像头按固定轨迹定时切换，摄像头焦点也支持配置，切换过程带动画效果（类似于电影场景动态切换）
点位支持鼠标点击模型取点对焦摄像头
支持调试过程中 单调调试，即：单个摄像头场景预览调试
轨迹动态添加删除
常常配合 单按钮（ 15-7-单按钮-摄像头动画轨迹）、或者 按钮组 配合使用

配置入口：

配置详解：

过程总览：

13-配置模型动态移动

说明

功能介绍：模型动态移动是支持选中模型按配置的固定路线移动，移动过程中支持摄像头跟随、模型旋转、路径轨迹等，适用于场景中自动巡检、模拟导航
点位支持鼠标点击模型取点快速定位
支持调试过程中 单调调试，即：单个点位调试
移动点位动态添加删除
常常配合 单按钮（ 15-8-单按钮-模型动态移动）、或者 按钮组 配合使用
集成websocket驱动模型动态移动，只需要调用接口即可实现。参考：xxx

注意

单点预览必须从第二个点位开始，第一个点位不支持单点预览
当前点位的旋转角度作用于当前点位和下一个点位之间,所有当前点位调试时，会应用上一个点位的旋转角度
摄像头参数作用于当前点位

配置入口：

配置详解：

过程总览：

14-配置流动线条轨迹

说明

功能介绍：模型动态移动是支持选中模型按配置的固定路线移动，移动过程中支持摄像头跟随、模型旋转、路径轨迹等，适用于场景中路线指引、园区导航
点位支持鼠标点击模型取点快速定位
支持调试过程中 单调调试，即：单个点位调试
移动点位动态添加删除
常常配合 单按钮 、或者 按钮组 配合使用

配置入口：

配置详解：

过程总览：

15-单按钮配置

说明

配置入口：单按钮
单按钮目前支持：切换相机、自动旋转、重置相机、机器人巡检、模型拆分与还原、摄像头动画轨迹、模型动态移动、流动线条、音乐、模型隐藏/显示、播放/停止动画、材质替换/还原、环境效果预设、着色器效果、TTS语音播报等，持续拓展中...
按钮样式支持自定义
按钮位置支持自定义
按钮图标支持自定义
新增按钮的位置都是固定在 x:450 y:450的位置，假如该位置存在按钮，新增的按钮会重叠，请按设计移动到合适的位置

15-1-单按钮-自动旋转

说明

控制场景自动旋转与停止旋转

15-2-单按钮-切换相机

说明

快速切换相机位置和对焦点（适用于场景转换），支持调试预览
一般使用切换相机按钮，最好配合增加一个相机重置按钮

15-3-单按钮-重置相机

说明

重置场景相机到原始状态，常用与进行过多控制后一键恢复状态

15-4-单按钮-机器人巡检

说明

第一人称或者第三人称漫游与场景中
支持键盘与鼠标结合操作
编辑模式下无法使用鼠标进行视角切换，必须预览模式才可以，也可以将鼠标移出编辑器范围也可以转动视角

15-5-机器人巡检-碰撞检测、重力效果配置

说明

能像玩游戏一样的体验
碰撞检测、重力效果须先选中可碰撞体构建BVH
重力效果下才能使用space键进行跳跃
W A S D 键控制角色移动 SPACE跳跃 E R 控制角色升降 Q隐藏鼠标
B快速重置机器人到原始位置
BVH构建优化：采用分帧构建策略，每帧限时12ms构建BVH，期间显示loading动画，构建完成后碰撞检测性能与原始代码完全一致

15-6-单按钮-模型拆分与还原

说明

模型拆分还原支持【随机爆炸】模式与【自定义】模式
新增【模型拆分还原】按钮，属性位置点击【模型变换位置】右侧弹出配置窗口
在场景树中选择需要变换位置的实体，【随机爆炸】模式下会自定义向各个方向爆炸
自定义模型则需手动配置每个实体的位置变换值，支持：位移、旋转、缩放等变换

15-7-单按钮-摄像头动画轨迹

说明

通过按钮的形式主动触发摄像头动画轨迹
单按钮控制的方式不涉及开场动画，必须通过按钮触发，执行完成动画会自动重置摄像头到初始位置
配置摄像头动画属性同：12-摄像头动画轨迹(开场动画)

15-8-单按钮-模型动态移动

说明

通过按钮的形式主动触发模型动态移动
必须在：13-配置模型动态移动这个步骤先进行配置
单按钮控制模型动态移动不再需要进行配置，直接选择已配置好的模型动态移动列表，如下图：

15-9-单按钮-流动线条轨迹

说明

通过按钮的形式主动触发流动线条轨迹
必须在：14-配置流动线条轨迹这个步骤先进行配置
再次点击即可关闭流动线条轨迹
单按钮控制流动线条轨迹不再需要进行配置，直接选择已配置好的流动线条轨迹列表，如下图：

15-10-单按钮-音乐

说明

通过按钮的形式主动触发音乐播放
再次点击即可关闭音乐
音乐格式支持MP3、WAV、WMA
音乐文件地址请用网络地址，自行配置
首次配置需要预览生效

15-11-单按钮-模型隐藏/显示

说明

通过按钮的形式主动触发模型隐藏/显示

15-12-单按钮-播放停止动画

说明

通过按钮的形式主动触发播放停止动画

15-13-单按钮-材质替换/还原

说明

通过按钮的形式主动触发材质替换/还原
材质替换/还原功能需要先配置材质替换/还原列表，请查看：11-材质替换/还原

15-14-单按钮-环境效果

说明

通过按钮的形式主动切换不同环境效果，环境效果从环境预设中选择，必须先配置环境预设

15-15-单按钮-着色器效果

说明

通过按钮控制着色器效果的开启与关闭
需先在着色器效果配置中添加着色器实例，通过 key 标识关联
支持同时控制多个着色器实例

15-16-单按钮-TTS语音播报

说明

通过按钮触发 TTS（Text-to-Speech）语音播报
支持手动输入文字或通过 API 接口获取播报内容
可配置声音类型、语速、音量、音调、语言
使用浏览器内置 speechSynthesis API，无需额外依赖

16-按钮组配置

说明

配置入口：单按钮
展开【按钮组】【显示按钮组】调整按钮组位置，调整按钮组背景图片与选中图片
支持按钮组初始化位置为 x:200px; y:200px 请根据当前分辨率计算并调整到合适的位置
支持按钮组存进全局变量
每个tab支持配置多个事件类，选中事件类后，右侧会出现相应的事件配置按钮

图

16-1-按钮组基本属性配置

位置调整+新建按钮

背景更改-全局生效模式

背景更改-单按钮个性化

16-2-按钮组-显示隐藏CSS2D组

说明

需要先对【CSS2D】进行分组，分组之后会立即消失，需要切换相应的tab组才会显示，不分组的CSS2D一直显示

以下教程为：使【按钮组1】展示【变压器】css2d，【按钮组2】展示【办公室】css2d

CSS2D分组

按钮组配置显示隐藏CSS2D组

16-3-按钮组-显示隐藏组件

说明

用于切换二维组件的显示与隐藏
适用于切换不同场景的二维数据统计

以下教程为：使【按钮组1】展示：圆环图、漏斗图，【按钮组2】展示表格、柱形图，【按钮组3】全部都不显示

16-4-按钮组-切换相机

说明

选中tab类【切换相机】右侧出现配置按钮，配置方式同 15-3-单按钮-切换相机

16-5-按钮组-重置相机

说明

选中tab类【重置相机】右侧出现配置按钮，配置方式同 15-4-单按钮-重置相机

16-6-按钮组-机器人巡检

说明

选中tab类【机器人巡检】右侧出现配置按钮，配置方式同 15-4-单按钮-机器人巡检
碰撞检测见： 15-5-机器人巡检-碰撞检测、重力效果配置

16-7-按钮组-模型拆分与还原

说明

选中tab类【模型拆分与还原】右侧出现配置按钮，配置方式同 15-6-单按钮-模型拆分与还原

16-8-按钮组-摄像头动画轨迹

说明

选中tab类【摄像头动画轨迹】右侧出现配置按钮，配置方式同 15-7-单按钮-摄像头动画轨迹

16-9-按钮组-模型动态移动

说明

选中tab类【模型动态移动】右侧出现配置按钮，配置方式同 15-8-单按钮-模型动态移动

16-10-按钮组-流动线条轨迹

说明

选中tab类【流动线条轨迹】右侧出现配置按钮，配置方式同 15-9-单按钮-流动线条轨迹

16-11-按钮组-显示隐藏模型

说明

选中tab类【显示隐藏模型】右侧出现配置按钮，选中对应显示与隐藏模型名称
显示隐藏模型仅支持导入的整个模型，不支持局部

16-12-按钮组事件-播放/停止动画

说明

选中tab类【显示隐藏动画】右侧出现配置按钮，选中对应显示与隐藏模型动画

16-13-按钮组-材质替换/还原

说明

选中tab类【材质替换/还原】右侧出现配置按钮，配置方式同 15-13-单按钮-材质替换/还原

16-14-按钮组-环境效果

说明

选中tab类【环境效果】右侧出现配置按钮，配置方式同 15-14-单按钮-环境效果

16-15-按钮组-着色器效果

说明

选中tab类【着色器效果】右侧出现配置按钮，配置方式同 15-15-单按钮-着色器效果

16-16-按钮组-TTS语音播报

说明

选中tab类【TTS语音播报】右侧出现配置按钮，配置方式同 15-16-单按钮-TTS语音播报

17-材质替换

说明

改变选中材质，使用图片替换或者之间改变颜色，图片优先于颜色
支持金属度和光泽度
图片支持铺满和堆叠铺满
替换后立即生效

配置详解

演示

18-雾效果

说明

雾效果是提升三维场景氛围感的重要功能，支持多种预设雾效与自定义参数调节，适用于模拟真实环境（如晨雾、黄昏、战场烟雾等）或增强视觉层次。

启用雾效果后，场景远端将逐渐被雾气遮挡，营造空间深度。
支持多种雾类型：指数雾（FogExp2）、线性雾（Fog），可灵活配置颜色、密度和背景色同步。
提供常用环境预设，一键切换不同氛围。
雾效可配合“环境光”、“灯光”、“背景”等共同使用，打造沉浸式数字孪生体验。

18-1-雾效启用与关闭

在右侧属性面板中找到【雾效果】模块。
点击 “启用雾效果” 开关，开启后即可在画布中看到雾气渲染效果。
关闭开关则清除所有雾效。

✅ 提示：建议先启用再调整参数，避免误操作导致无法查看变化。

18-2-雾效预设

提供以下常用环境预设，点击即可应用：

预设名称	效果描述
默认	清晰无雾，用于对比或重置
晨雾	浅灰白色雾气，适合清晨场景
战场硝烟	灰褐色浓雾，模拟战斗烟尘
仙境	淡蓝色轻雾，营造梦幻氛围
黄昏	橙黄色雾气，配合夕阳光照

💡 使用建议：预设仅作为参考，实际项目中可根据需求微调参数。

18-3-自定义雾效参数

雾类型

下拉选择：
- 指数雾 (FogExp2)：雾气随距离呈指数衰减，适合远景模糊处理。
- 线性雾 (Fog)：雾气随距离线性变化，控制更精确。

雾颜色

点击颜色块可打开颜色选择器，设置雾的颜色。
常见搭配：
- 白色（#FFFFFF）：通用雾气
- 灰色（#888888）：阴天/工业区
- 橙色（#FFA500）：黄昏/火灾现场

密度

控制雾的浓淡程度，默认值为 0.001。
数值越大，雾越浓；数值越小，雾越淡。
推荐范围：0.0005 ～ 0.01

同步背景色

开启后，雾色会自动跟随当前背景色变化，保持画面协调。
关闭时可独立设置雾色，适用于特殊艺术效果。

18-4-注意事项

小贴士

雾效对性能有一定影响，复杂场景建议适当降低密度。
若模型边缘出现“穿帮”现象，可尝试调整相机远裁剪面（Far Clip）或增加模型细节。
雾效不支持透明材质的完全穿透，请确保关键元素处于近景或使用非透明材质。

注意

雾效仅作用于三维场景，不影响二维组件（如CSS2D标签、图表等）。
发布前请在不同分辨率下预览雾效表现，避免因比例失真导致视觉异常。

19-后处理（Post Processing）

说明

后处理是提升三维场景视觉表现力的核心功能，通过一系列图像滤镜和特效增强画面质感，实现电影级渲染效果。
后处理模块支持实时调整，可快速应用于城市夜景、工业监控、科幻风格等不同场景。

启用后处理后，整个场景将经过色彩校正、光影增强、艺术滤镜等多层处理。
支持多种预设风格，一键切换不同视觉主题。
所有参数均可动态调节，支持与灯光、雾效、背景联动使用。

✅ 提示：建议在最终发布前启用后处理，以获得最佳展示效果。

19-1-后处理启用与关闭

在右侧属性面板中找到【后处理】模块。
点击 “开启后处理” 开关，开启后即可看到画面整体风格变化。
关闭开关则恢复原始未处理画面。

💡 使用建议：首次进入项目时默认关闭，便于调试基础模型与布局。

19-2-风格预设

提供以下常用视觉风格预设，点击即可应用：

预设名称	效果描述
默认	无任何滤镜，保持原始画面
赛博朋克	高对比度蓝紫调，霓虹光晕，适合未来都市
冷调科技	冷色调为主，强调线条与结构，适合工业控制中心
怀旧电影	暖黄偏棕，模拟老式胶片感，适合历史回顾类场景
高级黑白	黑白灰阶强化，突出建筑轮廓，适合极简设计

📌 示例：选择“赛博朋克”可自动激活辉光、高对比度和轻微模糊，营造科幻氛围。

19-3-画面增强

辉光强度

控制发光物体（如灯光、屏幕）的光晕扩散程度。
数值越大，辉光越明显，适合夜间照明或炫酷特效。
推荐范围：0.5 ～ 2.0

晕影（暗角）

在画面四角添加渐变暗角，聚焦视觉中心。
数值越大，暗角越深，常用于突出主体建筑或重要区域。
建议配合“辉光强度”使用，增强层次感。

19-4-颜色校正

支持对画面整体色调进行精细调整：

色调叠加

添加统一色调覆盖全图，如蓝色冷调、橙色暖调。
可用于统一风格或弥补光照不足。
点击 × 可清除当前叠加。

亮度

调整整体画面明暗程度。
适用于光线过暗或过亮的场景。

对比度

增强或减弱画面明暗差异。
高对比度适合清晰展示结构，低对比度适合柔和氛围。

饱和度

控制颜色鲜艳程度。
高饱和适合广告宣传类大屏，低饱和适合专业监控系统。

19-5-艺术滤镜

为场景添加个性化艺术风格：

黑白度

控制画面黑白化程度，数值为 0 时完全彩色，1 时完全黑白。
可用于制作“监控录像”或“历史影像”效果。

怀旧感

模拟老照片或胶片感，带有轻微颗粒与失真。
适合用于回忆录、时间轴类展示。

不透明度

控制后处理整体透明度，数值为 0 时完全关闭，1 时完全生效。
可用于混合原图与处理图，实现过渡动画或动态切换。

19-6-注意事项

小贴士

后处理会增加 GPU 负载，复杂场景建议适当降低“辉光强度”或“对比度”。
若发现模型边缘出现“锯齿”或“重影”，可尝试调整“抗锯齿”设置或优化模型面数。
发布前请在目标分辨率下测试后处理效果，避免因缩放导致滤镜失真。

注意

后处理仅作用于渲染输出，不影响模型数据与交互逻辑。
多个后处理效果叠加可能导致性能下降，请根据实际需求合理组合使用。
部分浏览器可能不支持高级滤镜，请确保发布环境兼容 WebGL 2.0+。

20-着色器效果配置 [新增功能（2026/01/25）| 大更新（2026/06/29）]

更新说明

2026/01/25：新增「着色器效果」功能，支持火焰、海面等基础着色器。
2026/06/29：着色器系统大更新！内置着色器从 7 种扩展到 51 种，新增分类标签页UI、模型选择器、Entity多模型支持、材质叠加模式等。

说明

着色器效果是基于 WebGL 的高级图形渲染技术，可在不增加模型复杂度的情况下实现丰富动态效果。
系统提供 57 种内置着色器，分为两大类：
- 🎬 独立场景着色器（Standalone）：独立存在于场景中，通过位置坐标定位，如火焰、雨雪、海面等。
- 🧊 模型材质着色器（Entity）：绑定到指定模型上，修改模型材质实现特效，如全息投影、透视扫描、溶解等。
每个着色器可独立配置参数和唯一标识（key），便于后续通过按钮或事件控制。
Entity 着色器支持 多模型绑定（groupNames 数组），可同时将特效应用到多个模型。
Entity 着色器支持 材质叠加模式（isOverlay），在保留原材质基础上叠加特效，通过 baseOpacity 控制原材质透明度。
支持与灯光、雾效、后处理联动使用。

✅ 提示：建议先在简单模型上测试效果，再应用到复杂场景中。

20-1-配置入口

在底部工具栏点击 【配置着色器效果】 按钮。
弹出「着色器效果配置」面板，进入配置界面。

---

20-2-着色器选择器

着色器选择器采用 分类标签页 + 网格卡片 的暗色风格界面：

分类标签页

🎬 独立场景：展示所有 Standalone 类型着色器
🧊 模型材质：展示所有 Entity 类型着色器

网格卡片

每个着色器以卡片形式展示，包含名称和简短描述
点击卡片即可选中该着色器类型
新增着色器默认为 关闭状态（show: false），需手动开启

20-3-着色器标识与基本配置

着色器标识（key）

输入一个唯一的 key 名称，用于区分同类型多个着色器实例。
示例：fire_01, radar_main, snow_area1
必须唯一，否则可能覆盖或冲突。

添加着色器

点击 【+ 添加着色器】 按钮，将当前配置添加到已配置列表。
可重复添加多个相同或不同类型的着色器。

20-4-两种着色器模式详解

🎬 独立场景模式（Standalone）

独立场景着色器在场景中创建独立的3D对象，通过位置坐标定位：

位置 X/Y/Z：着色器在三维空间中的世界坐标，支持 +/- 微调或直接输入
全局缩放：控制着色器整体大小，范围 0.1 ～ 100
部分着色器支持 模型名称绑定（groupName），自动使用模型包围盒中心作为位置

✅ 推荐做法：优先使用模型名称绑定，确保效果始终贴合目标对象。

🧊 模型材质模式（Entity）

模型材质着色器绑定到指定模型的材质上，通过修改材质实现特效：

模型选择：使用 模型选择器（ModelSelector） 组件选择目标模型
- 支持多选/单选模式
- 树形结构展示场景中的所有模型
- 支持搜索过滤
- 点击「使用选中」按钮确认选择
多模型绑定：Entity 着色器通过 groupNames 数组支持同时绑定多个模型
材质叠加模式（isOverlay）：
- 开启后，在原材质基础上叠加着色器效果
- 通过 baseOpacity 控制原材质的透明度（默认 0.15）
- 关闭叠加模式时，着色器将完全替换原材质
位置：Entity 着色器无需手动设置位置，自动跟随目标模型

20-5-内置着色器一览

🎬 独立场景着色器（Standalone）— 共 28 种

序号	着色器名称	shaderName	说明
1	圆形波纹	circle	扩散波纹效果
2	能量光柱	cityScan	垂直光柱扫描
3	城市扫描光	cityScanLight	建筑/地面扫描光效
4	大坝泄洪	damDischarge	水流泄洪效果
5	电弧	electricArc	电弧闪烁效果
6	火焰	fire	火焰燃烧效果
7	科技网格地面	gridGround	科技感网格地面
8	熔岩地面	lavaGround	熔岩流动地面
9	魔法阵	magicCircle	旋转魔法阵
10	抛物线飞行	parabolaFlight	数据传输/抛物线轨迹
11	雷达扫描	radar	圆形雷达扫描
12	雨	rain	下雨粒子效果
13	海面	sea	水面波纹效果
14	选中光环	selectionRing	选中扩散光环
15	雪	snow	下雪粒子效果
16	围墙	wall	动态光墙/围栏
17	极光	aurora	极光飘带效果
18	量子隧道	quantumTunnel	旋转隧道效果
19	能量场	energyField	球形能量场
20	黑洞	blackHole	黑洞吸积盘效果
21	太阳耀斑	solarFlare	太阳表面耀斑喷发效果
22	引力井	gravityWell	引力场空间扭曲效果
23	生物荧光	bioLuminescence	深海生物荧光效果
24	彗星	comet	彗星拖尾效果
25	超立方体	tesseract	四维超立方体投影
26	沙暴	sandstorm	沙漠沙暴粒子效果
27	涟漪池塘	ripplePond	水面多源涟漪波纹
28	火山喷发	volcano	岩浆粒子喷射+烟雾

🧊 模型材质着色器（Entity）— 共 29 种

序号	着色器名称	shaderName	说明
1	管道流动	pipe	管道内流动效果
2	全息投影	hologram	全息扫描投影
3	透视扫描	xray	X光透视效果
4	边缘发光	glowEdge	菲涅尔边缘发光
5	能量护盾	shield	六边形能量护盾
6	星云	nebula	深空星云气体云效果
7	脉冲冲击波	shockwave	扩散冲击波
8	烟雾	smoke	烟雾粒子效果
9	漩涡/龙卷风	vortex	旋转漩涡
10	溶解	dissolve	模型溶解消失
11	热力图	heatMap	温度热力分布
12	晶体化	crystallize	水晶化效果
13	腐蚀	corrosion	金属腐蚀生锈
14	冰冻	frost	冰霜覆盖效果
15	电磁场	electricField	电弧电磁场
16	数据流	dataFlow	数据流动效果
17	警告闪烁	warning	警告灯光闪烁
18	隐身	cloak	光学隐身扭曲
19	生锈	rust	金属锈蚀效果
20	矩阵代码	matrix	矩阵数字雨
21	脉冲波	pulseWave	脉冲扩散波
22	幽灵	ghost	幽灵飘动效果
23	电路纹理	circuit	电路板走线
24	损伤裂纹	damage	裂纹损伤效果
25	油膜彩虹	oilSlick	油膜干涉色效果
26	像素化	pixelate	模型像素化/马赛克效果
27	热成像	thermalVision	热成像仪色温映射
28	全息网格	hologramGrid	模型表面科技网格线
29	苔藓生长	moss	苔藓/植被覆盖效果

📌 完整的 API 参数说明请参考：API控制三维场景 - 着色器效果控制

20-6-已配置着色器管理

已配置列表

显示所有已添加的着色器实例。
每个条目显示名称、类型、状态（开启/关闭）及操作按钮。

控制项

开关按钮：启停该着色器效果。
使用点位：若已设置点位，可自动对齐到指定位置。
删除按钮：移除该着色器配置。

位置与缩放（Standalone 着色器）

位置 X/Y/Z：调整着色器在三维空间中的坐标。
全局缩放：控制着色器整体大小，范围 0.1 ～ 100。

✅ 推荐做法：先在模型中心附近添加，再逐步调整至理想位置。

20-7-实际应用示例

📌 示例说明：本视频展示了在建筑顶部添加"火焰着色器"，并配合"雷达扫描"模拟火灾报警系统。通过按钮组可一键切换不同警报状态。

20-8-注意事项

小贴士

着色器效果对 GPU 资源消耗较高，建议避免在同一区域同时启用多个高负载着色器。
若发现画面卡顿或闪烁，请尝试降低"全局缩放"或减少着色器数量。
Entity 着色器使用材质叠加模式（isOverlay）时，可通过 baseOpacity 调整原材质透明度，实现半透特效。
Entity 着色器支持多模型绑定（groupNames），可同时将特效应用到多个模型。
支持与「单按钮」「按钮组」联动，实现动态触发与关闭。
完整的 API 调用方式请参考：API控制三维场景

注意

着色器效果需在 预览模式 下才能完整查看动画效果。
发布前请在目标设备上测试兼容性，部分低端设备可能不支持复杂 Shader。
Entity 着色器需要目标模型已加载到场景中，否则无法生效。
若模型未正确响应着色器，请检查模型选择器中是否已正确选择目标模型。

更新日志

2026/01/25：初始版本，支持 7 种基础着色器。
2026/06/29：着色器系统大更新，扩展至 57 种内置着色器，新增分类标签页UI、模型选择器组件、Entity多模型绑定、材质叠加模式等。

21-环境效果预设 [新增功能（2026/01/25）]

更新说明（2026/01/25）

为提升数字孪生场景的统一性与可复用性，新增「环境效果预设」功能。支持将背景、雾效、后处理、灯光、着色器等多维度视觉元素打包成一个“环境方案”，一键切换不同时间段或场景状态（如早晨、中午、夜晚、火灾预警等），极大简化复杂场景的配置流程。

✅ 示例：在园区大屏中，通过“环境预设”实现从“清晨”到“夜间”的自动过渡，无需逐项调整。

说明

环境预设是全局性配置，影响整个三维场景的视觉风格。
每个预设包含：背景、雾效果、后处理、灯光、着色器五大部分，可独立配置。
支持创建多个预设，并通过按钮组或单按钮快速切换。
预设支持实时调试与参数修改，发布前可随时优化。

💡 建议：先配置常用场景（如“白天”、“夜晚”、“雨天”），再根据需求扩展。

21-1-配置入口

在右侧属性面板中展开 【环境效果预设】 模块。
点击 【+ 添加新方案】 按钮，创建一个新的环境预设。
或点击 【重置系统配置】 恢复默认设置。

21-2-预设管理

预设列表

默认提供以下基础预设：
- 早晨
- 中午
- 傍晚
- 夜晚
每个预设显示状态：未激活 / 已激活
点击预设名称可展开详细配置项。

操作按钮

启用/禁用：控制该预设是否生效。
编辑：进入配置模式，修改各项参数。
删除：移除该预设（需确认）。

21-3-环境方案配置项

每个环境方案包含以下五个核心模块：

背景

可配置背景颜色、图片、全景图或 HDR 背景。
支持透明背景，适用于叠加视频或图表。

雾效果

启用/关闭雾效。
选择预设类型（晨雾、战场硝烟等）或自定义密度、颜色。

后处理

开启/关闭后处理。
选择风格预设（赛博朋克、冷调科技等）或手动调节辉光、对比度等。

灯光

配置环境光、平行光、点光源、聚光灯。
支持批量调整光照强度与颜色，模拟不同时段光线。

着色器效果

添加或移除已配置的着色器（火焰、雷达扫描等）。
控制其开关状态与位置缩放。

📌 注意：所有配置均基于当前场景的已有设置，仅保存“差异值”，不会覆盖原始模型数据。

21-4-实时调试与试预览

实时调试

点击 【实时调试预览】 按钮，开启“参数可实时预览”模式。
修改任何一项参数，画面立即更新，无需刷新。
适合精细调校光影与色彩平衡。

设为系统默认配置

点击 【设为系统默认配置】，将当前方案设为项目默认环境。
新建项目或重置时自动加载此配置。

21-5-实际应用示例

📌 示例说明：本视频展示了从“早晨”→“中午”→“夜晚”的环境切换过程，配合灯光渐变、雾效变化、后处理增强，实现完整的昼夜循环动画。

21-6-注意事项

小贴士

环境预设支持分层管理，建议按业务场景命名（如“消防应急”、“日常巡检”）。
若某预设未生效，请检查是否已“激活”且无其他冲突配置。
多个预设可共存，但同一时间只能有一个处于“激活”状态。
支持与「摄像头动画轨迹」「按钮组」联动，实现自动化场景切换。

注意

环境预设为全局配置，会影响所有模型和组件。
修改预设前建议先备份当前状态，避免误操作。
发布前请在目标分辨率下测试完整流程，确保各模块协同正常。

新增功能（2026/02/05）

本功能旨在解决复杂数字孪生项目中“多场景切换难、配置重复高”的痛点，通过“一键切换”实现高效可视化表达。

22-模型场景事件配置 [新增功能（2026/01/25）]

更新说明（2026/01/25）

为增强数字孪生场景的交互能力，新增「模型场景事件配置」功能。支持对三维模型进行点击触发或机器人靠近触发等事件绑定，实现模型与业务逻辑的深度联动，广泛应用于设备监控、巡检预警、产线状态展示等场景。

✅ 示例：当用户点击“产线2”模型时，自动弹出该产线的实时运行数据面板；当机器人巡检至“配电房”附近时，触发报警灯光闪烁。

说明

模型事件是基于模型实例的交互行为，每个模型可独立配置多个事件。
支持两种触发方式：
- 点击触发：用户在编辑器中点击模型即可触发。
- 靠近触发：机器人或角色接近指定距离时自动触发。
所有事件均支持与「按钮组」「单按钮」「CSS3D组件」「动画」「音乐」等联动使用。
配置入口位于右侧属性面板的【模型事件配置】模块。

💡 建议：先启用“模型可点击”功能，便于快速定位和测试事件。

22-1-配置入口

在右侧属性面板中展开 【模型事件配置】 模块。
点击左侧模型树中的任意一个模型节点（如“产线2”），右侧将显示该模型的事件配置项。
若未选中任何模型，则无法配置事件。

🔍 提示：可通过勾选“模型可点击”来开启点击响应，方便调试。

22-2-事件触发方式

触发方式选择

下拉菜单提供以下两种触发模式：
- 点击触发：用户点击模型时触发事件。
- 机器人靠近：当机器人巡检路径进入设定距离范围内时触发事件。

📌 注意：
“机器人靠近”需配合【机器人巡检】功能使用。
距离单位为米（m），默认值为 5m，可根据实际需求调整。

触发距离设置

可自定义触发距离范围（最小 0.1m，最大 100m）。
数值越小，触发越灵敏；数值越大，影响区域更广。

✅ 推荐做法：对于关键设备建议设为 2～3m，避免误触。

22-3-事件动作配置

点击 【触发事件】 下拉框，可选择多种预设动作：

动作类型	描述
✅ 触发CSS2D	显示指定CSS2D标签，常用于展示设备信息、参数面板等
✅ 触发CSS3D	显示指定CSS3D组件，适用于立体标注、动态图标等
🔄 模型拆分/还原	触发模型爆炸或还原动画，适用于故障排查、结构展示
▶️ 播放/停止动画	启动或暂停模型内置动画（如旋转、闪烁）
🎵 音乐	播放指定背景音乐或提示音，增强沉浸感
🌫️ 环境效果	切换环境预设（如火灾预警 → 红色警报氛围）
🎨 材质替换/还原	更改模型材质颜色或贴图，用于状态标识（如正常/异常）
👁️ 模型隐藏/显示	控制模型是否可见，适用于分层展示
🔊 TTS语音播报	文字转语音播报，支持 API 接口获取播报内容