数据驱动

SceneV 3D 的数据驱动能力用于把实时业务数据映射到三维对象上，让模型状态、颜色、标签、告警和信息面板随数据变化而变化。

1. 数据来源

SceneV 3D 可参考 SceneV 大屏的数据接入方式，接入常见物联网和业务系统数据。

数据源	适用场景
HTTP/HTTPS	拉取设备列表、指标快照、业务统计
WebSocket	订阅实时状态、告警和推送消息
MQTT	接收设备遥测和物联网消息
ThingsBoard	获取遥测、属性、实体关系和告警数据

2. 数据接入流程

数据源 -> 原始数据 -> 过滤器 -> 标准数据 -> 绑定对象 -> 场景表现

步骤	说明
数据源	配置接口地址、认证信息、请求方式、订阅主题
原始数据	接收平台返回的 JSON、数组、遥测对象或消息体
过滤器	使用脚本整理字段、过滤无效数据、补充业务含义
标准数据	输出稳定结构，供模型、标签、面板和事件绑定
绑定对象	将数据字段绑定到模型、标签、材质或交互条件
场景表现	颜色变化、数值刷新、告警闪烁、相机定位等

3. 数据绑定对象

数据可以绑定到不同类型的 3D 对象：

对象	绑定内容
模型	颜色、显隐、动画、材质、告警状态
标签	设备名称、实时值、单位、状态文本
面板	详情字段、图表、告警列表
视角	根据状态跳转到指定位置
交互	根据数据控制按钮、弹框或业务动作

4. 数据格式建议

建议将设备数据整理为稳定结构，便于绑定和复用：

{
  "id": "pump-01",
  "name": "1号水泵",
  "status": "running",
  "metrics": {
    "temperature": 36.8,
    "pressure": 0.42,
    "flow": 18.6
  },
  "alarm": {
    "level": 0,
    "message": ""
  }
}

多设备数据示例

[
  {
    "id": "pump-01",
    "status": "running",
    "temperature": 36.8,
    "alarmLevel": 0
  },
  {
    "id": "pump-02",
    "status": "alarm",
    "temperature": 82.4,
    "alarmLevel": 2
  }
]

建议每条数据都包含唯一 id，并让这个 id 与模型编码一致。

5. 状态映射

常见状态映射方式：

数据条件	映射效果
status = running	模型显示运行色，播放轻量动画
status = offline	模型降低亮度或显示离线标签
alarm.level > 0	模型红色高亮并显示告警面板
temperature > 60	温度标签变色，触发风险提示

状态色建议

状态	颜色建议	说明
正常	蓝色或绿色	保持稳定，不要强闪烁
运行中	青色、绿色或流动效果	用于表达设备正在工作
离线	灰色或低透明度	表达不可用或无数据
预警	黄色或橙色	表达需要关注但未严重故障
告警	红色、闪烁、边框高亮	表达需要立即处理

6. 数据刷新

根据数据类型选择刷新方式：

• 低频数据：设备名称、位置、类型等基础信息，可通过 HTTP 初始化加载。
• 中频数据：统计指标、运行参数，可通过定时 HTTP 或 WebSocket 更新。
• 高频数据：实时遥测、告警推送，适合 WebSocket 或 MQTT。

WARNING

不要把所有数据都设置为高频刷新。高频刷新应只用于真正需要实时变化的关键字段。

7. 数据异常处理

现场数据经常会出现接口失败、字段缺失、设备离线等情况。建议提前设计兜底状态：

异常	处理方式
接口请求失败	保留上一次有效数据，并显示数据异常提示
字段缺失	使用默认值，避免脚本报错
设备离线	模型置灰，标签显示离线
数据延迟	显示最后更新时间
告警恢复	清除告警高亮，恢复正常状态

8. 过滤器示例

const list = Array.isArray(e) ? e : [e];

return list.map((item) => ({
  id: item.deviceId,
  label: item.deviceName || item.deviceId,
  value: {
    status: item.online ? "running" : "offline",
    temperature: Number(item.temperature || 0),
    alarmLevel: Number(item.alarmLevel || 0),
    updateTime: item.ts
  }
}));

过滤器要保证返回结构稳定，避免某次数据异常导致绑定对象无法刷新。

9. 与 ThingsBoard 集成

在 ThingsBoard 场景中，可以将实体、设备、遥测和告警映射到 3D 模型：

1. 使用设备 ID 或业务编码关联模型。
2. 订阅设备遥测作为模型状态来源。
3. 将告警等级映射为颜色、闪烁和面板提示。
4. 在点击模型时打开设备详情或 ThingsBoard 业务页面。

更多通用数据接入规则可参考 SceneV 数据接入。