API控制三维场景
约 1685 字大约 6 分钟
2025-12-08
一、可视化API场景控制调试
说明
- api 地址: http://onetwin.cn/api/v1/socket/pushMessage
- post 请求
注意
- ⚠️ 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 参数说明:
| 字段 | 类型 | 说明 |
|---|---|---|
| image | string | 贴图 URL(相对或绝对路径) |
| color | number | 基础色(十六进制转十进制,如 #ffffff → 16777215) |
| wrapMode | "repeat" | "clamp" | 纹理包裹模式 |
| metalness | number (0~1) | 金属度 |
| roughness | number (0~1) | 粗糙度 |
| textureQuality | "high" | "normal" | "pixel" | 渲染质量策略 |
提示:color 可留空,仅用贴图;image 可为空,仅用纯色。
2.🔄 恢复原始材质(restoreMesh)
{
"kanbanId": "68a6742ff6e8a11600de95dc",
"message": {
"type": "replaceMesh",
"payload": {
"type": "restoreMesh",
"targetName": ["车间外墙"]
}
}
}- 无需 options
- 自动还原模型加载时的原始材质
