外观

API控制三维场景

约 1685 字大约 6 分钟

2025-12-08

一、可视化API场景控制调试

说明

注意

  • ⚠️ 1. 必须是已发布或者保存待发布的看板ID
  • ⚠️ 2. 使用了【数字孪生threeD】组件
  • ⚠️ 3.【数字孪生threeD】组件内开启了【远程遥控】模式

可视化界面调试

二、API场景控制

1.控制模型移动

说明

  • kanbanId：看板唯一标识，用于路由到指定场景。
  • message.type：固定为 "modelMove"，表示模型移动指令。
  • payload.groupArray：要控制的模型组名称列表（如 ["坦克"]）。
  • payload.customPath：路径点数组，每个点包含位置、旋转、缩放等。
  • payload.loop：是否循环执行路径（仅 fullPath 模式有效）。
  • payload.cameraFollowing：是否启用相机跟随。
  • payload.css2DFollow：CSS2D 标签跟随配置，follow 开关，nameList 是标签类名或 ID 列表。
  • rotationAtOnce / scaleAtOnce：是否立即应用旋转/缩放（不插值）。
  • cameraOffset：相机相对于模型的偏移量（x, y, z）。
{
  "kanbanId": "68a6742ff6e8a11600de95dc",
  "message": {
    "type": "modelMove",
    "payload": {
      "groupArray": [
        {
          "name": "坦克"
        }
      ],
      "customPath": [
        {
          "position": {
            "x": 0,
            "y": 0,
            "z": 0
          },
          "rotation": {
            "x": 0,
            "y": 0,
            "z": 0
          },
          "scale": {
            "x": 1,
            "y": 1,
            "z": 1
          },
          "animationTime": 2000,
          "rotationAtOnce": true,
          "scaleAtOnce": true
        }
      ],
      "loop": false,
      "animationTime": 2000,
      "cameraFollowing": false,
      "css2DFollow": {
        "follow": false,
        "nameList": [
          "坦克"
        ]
      }
    }
  }
}

2.控制按钮组切换

{
        kanbanId: "6878e76c6f55c70fa8c15482",
        message: {
          type: "tabsBtnChange",
          payload: {
            tabName: "流动线条轨迹2"
          }
        }
      }

3.控制单按钮点击

{
        kanbanId: "6878e76c6f55c70fa8c15482",
        message: {
          type: "bottonClick",
          payload: {
            bottonName: "坦克巡逻"
          }
        }
      }

4.控制CSS2D点击

{
        kanbanId: "6878e76c6f55c70fa8c15482",
        message: {
          type: "css2dClick",
          payload: {
            css2dName: "标注示例"
          }
        }
      }

5.控制CSS2D关闭

{
        kanbanId: "6878e76c6f55c70fa8c15482",
        message: {
          type: "css2dClose",
          payload: {
            css2dName: "标注示例"
          }
        }
      }

三、API着色器效果控制

说明

着色器用于在场景中叠加动态视觉特效，如火焰、水面、雷达扫描等。所有着色器指令通过 type: "createShader" 或 type: "removeShader" 触发

🎯 关于位置设置：两种模式详解

在使用着色器时，您可选择以下两种方式确定效果位置

✅ 模式一：绑定模型名称（推荐）

  • 勾选 "使用模型名称" 开关

  • 输入有效的 模型名称（groupName），如 "车间1"、"Tank_01"。

  • 系统将自动计算该模型的 视觉中心（包围盒中心） 作为着色器位置：

  • 优势：无需手动输入坐标，避免因模型移动或缩放导致位置错误。

  • 适用场景：火焰、雷达等需要附着在具体模型上的效果

✍️ 模式二：手动输入位置

  • 关闭 "使用模型名称" 开关
  • 手动填写 position.x/y/z（单位：米）。
  • 风险：若坐标错误，效果可能出现在空中、地下或远离目标区域。
  • 适用场景：海面、大型围墙等覆盖固定地理区域的效果。

注意

💡 最佳实践：优先使用 模型名称绑定，确保效果始终贴合目标对象。

1.触发火焰着色器（模拟火灾）效果

说明

  • shaderName: 固定为 "fire"。
  • key: 必填，用于唯一标识该火焰实例（关闭时需相同 key）。
  • position: 火焰中心的世界坐标（单位：米）。
  • ✅ 强烈建议使用模型名称绑定（见上文）自动获取视觉中心位置，避免手动输入错误。
  • globalScale: 火焰整体缩放（默认 10.0，范围 0.1 ~ 50）。
  • options: 当前版本暂无自定义参数，保留空对象 {}。
  • 若同时传入 groupName，系统会自动将 position 覆盖为该模型的包围盒视觉中心（即 Box3().- getCenter()），此时 position 字段仅作偏移参考（当前未启用偏移，实际以模型中心为准）。
{
  "kanbanId": "68a6742ff6e8a11600de95dc",
  "message": {
    "type": "createShader",
    "payload": {
      "shaderName": "fire",
      "shaderOptions": {
        "key": "fire_001",
        "position": { "x": -127.184, "y": 18.624, "z": 206.200 },
        "globalScale": 10.0,
        "options": {}
      }
    }
  }
}

2.触发海面着色器（水面效果）

说明

  • shaderName: 固定为 "sea"。
  • key: 必填，用于后续关闭或更新。
  • globalScale: 对海面整体缩放（通常保持 1.0）。
  • options 参数详解：
  • width / height: 水面平面尺寸（单位：米，默认 5000×5000）。
  • waterColor: 水体颜色（支持 HEX 或 RGBA 字符串）。
  • yPosition: 水面在 Y 轴的高度（例如地面为 0，则水面设为 10 表示高于地面 10 米）。
  • xPosition / zPosition: 水面中心在 X/Z 轴的偏移（默认居中于场景原点）。
  • ⚠️ 海面不支持 groupName 绑定（因其覆盖大面积区域，通常独立存在）。
{
  "kanbanId": "68a6742ff6e8a11600de95dc",
  "message": {
    "type": "createShader",
    "payload": {
      "shaderName": "sea",
      "shaderOptions": {
        "key": "ocean_main",
        "globalScale": 1.0,
        "options": {
          "width": 5000,
          "height": 5000,
          "waterColor": "#4AA0C5",
          "distortionScale": 3.7,
          "yPosition": 10,
          "xPosition": 0,
          "zPosition": 0
        }
      }
    }
  }
}

3.触发围墙着色器（动态光墙/围栏）

说明

  • shaderName: 固定为 "wall"。
  • key: 必填。
  • globalScale: 通常保持 1.0。
  • options 参数详解：
  • width / length / height: 围墙尺寸（宽 × 长 × 高，单位：米）。
  • position: 围墙中心的世界坐标（X/Y/Z）。
  • baseColor: 围墙主色（HEX 格式）。
  • amplitude: 波纹振幅（0.1 ~ 5）。
  • frequency: 波纹密度（1 ~ 20）。
  • speed: 动画速度（10 ~ 200）。
{
  "kanbanId": "68a6742ff6e8a11600de95dc",
  "message": {
    "type": "createShader",
    "payload": {
      "shaderName": "wall",
      "shaderOptions": {
        "key": "perimeter_wall",
        "globalScale": 1.0,
        "options": {
          "width": 20,
          "length": 40,
          "height": 4,
          "baseColor": "#00ff80",
          "amplitude": 1.0,
          "frequency": 10.0,
          "speed": 130.0,
          "position": { "x": 0, "y": 0, "z": 0 }
        }
      }
    }
  }
}

4.触发雷达扫描着色器（圆形扫描光效）

说明

  • shaderName: 固定为 "radar"。
  • key: 必填。
  • position: 扫描中心点（世界坐标）。
  • globalScale: 扫描半径缩放（默认 10.0，值越大范围越广）。
  • options.color: 扫描光颜色（HEX 格式）。
  • ✅ 支持 groupName 绑定：若提供 groupName，系统将自动使用该模型的视觉中心作为position，忽略手动传入的位置值。
{
  "kanbanId": "68a6742ff6e8a11600de95dc",
  "message": {
    "type": "createShader",
    "payload": {
      "shaderName": "radar",
      "shaderOptions": {
        "key": "radar_01",
        "position": { "x": -127.184, "y": 18.624, "z": 206.200 },
        "globalScale": 10.0,
        "options": {
          "color": "#BCF2FE"
        }
      }
    }
  }
}

5.关闭任意着色器效果

说明

  • type: 固定为 "removeShader"。
  • 必须提供与创建时完全相同的 key。
{
  "kanbanId": "68a6742ff6e8a11600de95dc",
  "message": {
    "type": "removeShader",
    "payload": {
      "shaderName": "fire",
      "shaderOptions": {
        "key": "fire_001",
      }
    }
  }
}

四、API按名称替换或恢复材质

提示

✨ 全新能力：无需修改模型文件，通过 API 动态替换任意模型或材质的外观。

🔍 匹配逻辑

提示

  • 若 targetName 匹配 Object3D.name（如 "水泵A"）→ 替换该对象下所有子 mesh 的材质
  • 若 targetName 匹配 Material.name（如 "墙面_砖"）→ 仅替换使用该材质的所有 mesh
  • 支持批量操作：输入多个名称，用英文逗号 ,、分号 ; 或换行分隔。

1.📦 替换材质（replaceMesh）

{
  "kanbanId": "68a6742ff6e8a11600de95dc",
  "message": {
    "type": "replaceMesh",
    "payload": {
      "type": "replaceMesh",
      "targetName": ["车间外墙", "屋顶"],
      "options": {
        "image": "/textures/metal_rust.jpg",
        "color": 16777215,
        "wrapMode": "repeat",
        "metalness": 0.3,
        "roughness": 0.7,
        "textureQuality": "high"
      }
    }
  }
}

options 参数说明：

字段类型说明
imagestring贴图 URL（相对或绝对路径）
colornumber基础色（十六进制转十进制，如 #ffffff → 16777215）
wrapMode"repeat" | "clamp"纹理包裹模式
metalnessnumber (0~1)金属度
roughnessnumber (0~1)粗糙度
textureQuality"high" | "normal" | "pixel"渲染质量策略

提示：color 可留空，仅用贴图；image 可为空，仅用纯色。

2.🔄 恢复原始材质（restoreMesh）

{
 "kanbanId": "68a6742ff6e8a11600de95dc",
 "message": {
   "type": "replaceMesh",
   "payload": {
     "type": "restoreMesh",
     "targetName": ["车间外墙"]
   }
 }
}
  • 无需 options
  • 自动还原模型加载时的原始材质

Powered by onetwin

桂ICP备2021002639号-4