数据标记

数据标记用于为 3D 模型的节点（Node）绑定业务数据（userData 键值对），典型场景：工业设备编号、楼层房间信息、电商 SKU、数字孪生传感器 ID 等。标记结果导出为独立 JSON 文件，导出的数据结构与 Three.js 的 userData 直接兼容，前端加载模型后按节点名挂接即可使用。

界面布局

数据标记页为三列布局：

区域	功能
左：节点树	展示模型完整节点层级，实时显示「已标记 / 总节点」数量
中：3D 视口	点选节点，选中节点高亮描边；与节点树双向联动
右：数据编辑器	为选中节点编辑键值对，支持多条目增删与 JSON 批量应用

基本流程

1. 拖入或选择模型文件（免费版 ≤ 20 MB，授权后 ≤ 500 MB）
2. 在节点树中浏览层级，或直接在 3D 视口中点选目标节点
3. 在右侧编辑器中添加键值对，如 设备编号 = PUMP-0231、类型 = 离心泵
4. 重复标记其他节点，完成后点击工具栏「导出 JSON」保存标记数据

工具栏

按钮	说明
导入	从 JSON 文件批量导入标记，按节点名匹配自动填充
预览	全局预览所有已标记节点的数据，支持统一编辑
矫正	扫描并清理孤立数据（节点已删除但标记残留）与冗余数据，保持标记与模型一致
清空	清除当前模型的全部标记
导出 JSON	导出全部标记为 JSON 文件，可归档或用于再次导入

JSON 编辑器说明

右侧数据编辑器与「预览」弹窗的 JSON 编辑区均基于 Ace 编辑器（vue3-ace-editor + ace-builds，JSON 语法高亮）。打包后（Tauri/Windows）若出现编辑器无高度、不滚动、行堆叠错乱，通常是 CSP 拦截了编辑器运行时写入的内联 style 属性所致——请确保 tauri.conf.json 的 security.csp 对象中包含 style-src-attr / style-src-elem 子指令并放行 'unsafe-inline'（Tauri 编译期会向主 style-src 注入 nonce，但仅污染主指令，子指令不受影响）。

键值预设与批量应用

• 常用键名（如 id、name、type）可通过预设快速插入，减少重复输入
• 编辑器支持 JSON 批量应用：粘贴一段 JSON 对象，一键写入当前节点的多条键值

导出格式

导出的 JSON 文件结构如下（默认文件名 {模型名}-userdata.json）：

{
  "meta": {
    "version": "1.0",
    "createdAt": "2026-08-02T10:00:00.000Z",
    "markedNodeCount": 2,
    "totalFieldCount": 3,
    "modelFileName": "factory"
  },
  "nodes": {
    "001": {
      "name": "Pump_0231",
      "data": { "设备编号": "PUMP-0231", "类型": "离心泵" }
    }
  }
}

其中每个节点的 data 字段就是普通键值对象，与 Three.js 的 object.userData 结构一致，可直接赋值使用。

使用建议

节点名是匹配依据

JSON 导入与数据矫正均以节点名作为匹配键。请确保建模阶段节点命名唯一且有业务含义，避免 Cube.001 这类自动命名。

常见问题

标记数据存在模型里还是独立文件里？

独立文件。导出的 JSON（默认文件名 {模型名}-userdata.json）与模型分离，模型本身不被修改；前端加载后按节点名把 data 写入 Three.js 的 object.userData。

前端怎么读取标记的数据？

导出 JSON 中每个节点的 data 字段与 Three.js object.userData 结构一致，按 nodes[节点名].data 取值赋给对应 object.userData 即可，无需额外解析。

节点太多，一个一个标太慢怎么办？

两种方式：用「导入」从 JSON 文件按节点名批量填充；或在编辑器中粘贴一段 JSON 对象批量写入当前节点的多条键值。常用键名（id、name、type）可从预设一键插入。

删除了模型里的节点，旧标记会怎样？

用工具栏「矫正」扫描即可清理：自动移除节点已删除的孤立数据和冗余数据，保持标记与模型一致。