YOKE System 数字孪生系统 API

Changelog

[1.6.1] - 2024-12-10

1. Fixed: 修改 Camera.moveTo()的部分参数限制(参数不符合限制仍可继续将消息发送给 ue)

[1.6.0] - 2024-12-09

1. Feature: 新增相机运镜功能 Camera.startLerp([CameraView])。支持传入一组相机参数(CameraView)做镜头运镜动画

[1.5.3] - 2024-10-18

1. Fixed: getl 工具获取相机的 location 参数自动复制到粘贴板错误

[1.5.2] - 2024-09-14

1. 新增 CDN 方式使用 sdk
2. 新增获取 getBoundary 参数的简易方法

介绍

YOKE System 数字孪生系统 API。此 sdk 提供了各种数字孪生系统相关的功能接口，包括：

1. 天气系统
2. 相机相关操作
3. 虚拟物体
4. 视角点
5. 建筑
6. 视觉风格
7. 物体高亮
8. 系统渲染相关
9. 建筑分层
10. ... 后续若有添加

以上各类相关系统与 ue 的事件收发机制进行了集成，使得开发者可以快速的集成到自己的项目中。

安装&使用

NPM 安装

// npm
npm i @dgene_ai/yoke-apis

// yarn
yarn add @dgene_ai/yoke-apis

// pnpm
pnpm i @dgene_ai/yoke-apis

NPM 方式通过 ESM 模块化在代码中引入使用（此方式支持按需加载），如：

import { DimoCore } from '@dgene_ai/sys-apis';

Dimo.weather.time(2);

通过 CDN

<script src="https://cdn.jsdelivr.net/npm/@dgene_ai/yoke-apis/lib/@dgene-yoke-api.min.js"></script>

CDN 方式 sdk 通过 Dgene.Dimo 使用，如：

Dgene.Dimo.weather.time(2);

如果你是使用 typescript 编写项目，为了避免代码错误提示，你需要在你的定义文件.d.ts 中定义一下 module, 如 declare const Dgene: any;

通常不建议通过 CDN 使用，因为 CDN 会引入全量代码，这样会增加项目包体积和影响页面加载速度。

代码结构

DimoCore // 核心代码(初始化，收发事件等)，所有操作均通过此类进行
Interfaces // 通用接口定义
Constants // 常量定义。例如各种系统使用到的参数枚举等
EventsDefine // 各系统的事件定义
sys // 各系统的具体实现
    ├── Weather
    ├── Camera
    ├── VirtualObject
    ├── SmartBuilding
    ├── Viewpoint
    ├── BuildingBlock
    ├── HighlightObject
    ├── VisualStyle
    ├── Projector
    ├── System
    └── ...  // 后续待添加的其他系统
interfaces // 各系统使用的接口定义
    ├── CameraInterfaces
    ├── VirtualObjectInterfaces
    ├── ViewPointInterfaces
    ├── BuildBlockInterfaces
    └── ...  // 后续待添加的其他系统

快速开始

1. 引入 sdk, 调用 init 方法初始化，传入 ue 的地址，加载 ue 底座。具体传参见 init 方法。

一定要先初始化，否则后续的操作都是无效的

通过 NPM 引入

import { DimoCore } from '@dgene_ai/sys-apis';

Dimo.init('https://your-ue-url',loadedCallback, 'ue-wrapper-element-id');

使用 CDN 的方式（无需写 import）

Dgene.Dimo.init('https://your-ue-url',loadedCallback, 'ue-wrapper-element-id');

后续的示例代码如无特殊均以 ESM 的方式展示

2. 调用相关系统的接口进行操作。 每个系统都有对应的接口事件定义，调用后会以 Promise 的形式返回结果。（注意： Durian 版本 UE 未对 weather event 做返回处理，故 weather 系统的接口没有 Promise 的返回） 具体见各系统的接口定义。

调用时以 Dimo 作为前缀(CDN 方式为 Dgene.Dimo)，加上各系统名称，再加上具体的事件名称， 例如： Dimo.virtualOb.visible('image_billboard1', false)。（sdk 以 TypeScript 编写，若是 ts 编写的项目，可以看到代码提示）

Tips：如果项目中有特殊自定义事件（或任何事件），也可以通过Dimo.send(eventname, payload, callback)来实现与 ue 的通信。 方法里的 callback 不传，则会自动通过 Promise 返回结果。

以下为几个简单示例：

import { WeatherOfPreset, VirtualObjectType } from './Constants';

// 设置预设天气
Dimo.weather.preset(WeatherOfPreset.CLEAR_SKIES);

// 设置虚拟物体的属性
Dimo.virtualOb
        .setPropsByClass(VirtualObjectType.CLICK_BOX, [], {
            color: { r: 0.35, g: 0.5688, b: 0.062883, a: 1 },
            rest_opacity: 0.8,
            camera_distance: 89,
            use_round: false,
            click_to_focus: false,
        })
        .then((data) => {
            console.log('virtualObject setPropsByClass successed :', data.object_class);
        });

// 移动相机到指定位置
Dimo.camera.moveTo({
        target_location: {
            x: 171351.79163681276,
            y: -322161.37598760426,
            z: 674.3435217706625,
        },
        camera_rotation: { pitch: -5.000286102294922, yaw: -49.487884521484375, roll: 0 },
        zoom_length: 6314.67333984375,
        fov: 90,
        move_speed: 5,
        interpolation: true,
    });
    .then((bool) => {
        console.log('camera moveTo successed :', bool);
    });

3. UE 事件监听

• 3.1 UE 对象的点击/hover 事件监听。 设置 Dimo 的 onClick 或 onHover 回调方法，即可监听 UE 对象的 click/hover 事件。

  // 监听ue点击事件
  Dimo.onClick((payload)=>{
      console.log('onClick: ', payload);
  })
  // 监听ue的hover事件
  Dimo.onHover((payload)=>{
      console.log('onHover: ', payload);
  })

  该回调只能最后一次设置的地方才生效，因此最好是在项目中某个地方集中做统一的事件监听。另外也可通过 window.addEventLisenter('ue_object_on_click', callback)或 window.addEventLisenter('ue_object_on_hover', callback)方式来监听。

• 3.2 UE 推送的其他事件（包含自定义事件）监听 设置 Dimo 的 onReceive 回调方法，可监听除去 ue 对象的 click 或 hover 的其他事件，包含各自项目中定制的其他事件。当然最好也是在项目中某个地方集中做统一的事件监听处理。

    // 监听ue推送的事件（或者某些虚拟物体的点击事件）
    Dimo.onReceive((payload)=>{
        console.log('onReceive: ', payload);
    })

同样可以通过window.addEventLisenter('ue_event_call_back', callback)方式来监听。

Tips：sdk 里有简易的封装 window 自定义事件，则监听也可写成：

import { triggerEvent } from '@dgene_ai/yoke-apis';

triggerEvent('ue_event_call_back', (e: CustomEvent) => {
    console.log('ue_event_call_back :', e.detail);
})

CDN 方式:

Dgene.triggerEvent('ue_event_call_back', (e: CustomEvent) => {
    console.log('ue_event_call_back :', e.detail);
})

• 发送事件： dispatchEvent(evnetName, data)

• 监听事件： triggerEvent(evnetName, callback)

• 移除监听： disposeEvent(evnetName, callback)

• 3.3 打开所有与 UE 交互的事件 log 调用Dimo.openOriginEventLog(true)可以在 console 控制台中显示 ue 发送过来未经过 sdk 解析的所有事件

4. 获取 camera 当前视角/位置/边界 参数的简易方法 在项目中可能需要用到 camera 的视角/位置/边界等参数，为此 sdk 提供了一个快捷的获取当前视角参数的方法。主要根据不同的类型输入特定的内容，即可将获得的参数自动复制到粘贴板上，方便使用。

• 获取当前 camera 视角参数 (getCamera) 在项目网页中敲击键盘的 getc按键并回车(Enter)，即可获取当前相机视角参数。 如 Dimo.camera.moveTo({})的参数就可以使用此方法获取

• 获取当前相机位置参数(getLocation)

  在项目网页中敲击键盘的 getl按键并回车(Enter)。

• 获取当前边界参数(getBoundary)

  在项目网页中敲击键盘的 getb按键并回车(Enter)。

注意： 保证每次按键的时间间隔不要超过 3 秒，否则按键的内容会重置，那么需要重新来一次。为了清楚输入的内容，会在控制台打印出按键的内容（需要设置 enableLog 为 true（默认为 true），若关闭了 log 可调用 Dimo.enableLog(true)打开 log）。

5. 获取控制权(Elderberry 版本 已不再需要) Dimo.takeControl()

详细系统介绍文档

YOKE System 产品说明书