统一开发 API

Appearance

第一章 图观统一开发 API 概述 ​

目录 ​

第一节 TGAPI 接口概览 ​

图观统一开发 API 是一套基于 JavaScript 语言开发的二次编程接口，用于在现代浏览器中加载、显示图观引擎提供的流渲染或端渲染三维场景，并且为开发者提供在场景中绘制业务数据、触发场景交互、控制场景逻辑的功能。图观统一开发 API 兼容当前主流的 JavaScript 前端框架，例如 Vue.js 或者 React，前端开发人员可快速便捷的进行二次开发。

通过使用图观统一开发 API，开发人员可以完全释放图观场景的二次开发能力，开发出从手机端的轻量化应用，到具有复杂功能和交互的大屏应用。统一开发 API 已经针对典型三维数字孪生应用的场景开发，对三维开发接口进行了良好封装。并且对于底层渲染核心，无论是端渲染还是流渲染都做好了适配。相比传统的三维引擎的二次开发，开发者只需要了解 JavaScript 就可以快速上手，接口调用和消息结构也相对简单，熟悉一种渲染核心的开发后，可以快速上手另外一种渲染核心的开发。甚至在场景资源具备的情况下，开发好一种渲染核心的应用，可以无缝迁移到另外的渲染核心。充分满足显示效果，和高并发的要求。

1. 双渲染技术架构 ​

图观 ™ 的渲染核心有流渲染和端渲染两种。对于 TGAPI 的二次开发接口是一致的。这里简单介绍两种渲染核心的技术架构。

流渲染 ​

图观 ™ 流渲染开发架构，是基于实时云渲染（ GPU 云化）、视频串流等技术，整合推出可视化数字孪生流渲染解决方案技术支撑体系，涵盖：流渲染服务平台、流渲染二次开发等技术产品，为大规模场景渲染在轻量化终端上的呈现提供技术保障。

流渲染系统架构如下图所示:

系统架构图

端渲染 ​

图观 ™ 端渲染开发架构，是基于 HTML5 和 WebGL 技术，整合推出的数字孪生端渲染技术支撑体系，涵盖端渲染场景编辑器、端渲染服务平台、端渲染二次开发等技术产品，覆盖数字孪生应用开发的全生命周期，提供简便、快捷、强大的数字孪生应用运行和开发平台。

端渲染系统架构如下图所示:

系统架构图

2. 图观引擎场景和二次开发效果速览 ​

流渲染效果速览 ​

端渲染效果速览 ​

返回本章目录

第二节 TGAPI 接口体系 ​

1. 接口总数 ​

TGAPI 3.3 正式发布的版本，共有接口总数 500 多个，其中方法数量 200 多个、事件数量 300 多个。

2. 接口功能分类 ​

根据三维数字孪生场景开发中的常见功能，图观统一开发 API 将全部功能接口分为以下几大类：

  • 全局接口：应用生命周期管理，服务调度，场景调度，状态调度，镜头操作，时间天气和其他辅助功能。
  • 图层接口：各种可视化图层的添加、删除、更新数据、更新样式功能。图层包括单对象图层、多对象图层和 GIS 图层。
  • 模型接口：添加和控制模型等等，包括普通模型和建筑模型。普通具有关节和动画控制能力。建筑模型具有楼层、房间的控制能力。另外还可以试用模型轨迹图和特效图层。
  • 事件：监听各种方法执行的结果或用户交互行为。

返回本章目录

第三节 TGAPI 方法指令范式 ​

引入版本：3.0 起支持

TGAPI 除了构造应用使用的new TGApp.app()和初始化服务appInstance.initService()两个接口以外，都是使用appInstance.uniCall(action, parameter, callback)方法来调用的，第一个参数为指令名称，第二个参数为指令参数，第三个参数为回调函数。

例如：

JavaScript
// 设置摄像机状态
appInstance.uniCall('setCamera', {}, (result) => {});

// 添加事件监听回调
appInstance.uniCall('addEventListener', {
    eventName: 'onResolutionChange',
    callback: function (event) { },
  },  (result) => {}
);

// 销毁应用
appInstance.uniCall('destroy', {}, (result) => {});

返回本章目录

第四节 TGAPI 指令回调结果 ​

引入版本：3.2 起支持

每个uniCall的指令调用，在第三个参数都包括一个callback回调函数。回调函数的结果，通过一个 Object 类型的对象返回。对象的基本结构如下：

JavaScript
{
  "result": 1,        // 指令的执行结果，1 代表成功，0 代表失败；
  "message": "成功。"  // 指令执行成功或者失败的具体消息。
  // 如果指令返回结果中有其他内容，会通过这里其他的属性返回。
}

例如，一个端渲染场景，调用获取应用状态信息的指令：

JavaScript
appInstance.uniCall('getAppInfo', {}, (result) => {
  console.log(result);
})

控制台中，result 结果内容如下：

JavaScript
{
  "result": 1,
  "message": "成功。",
  "tgApiSdkVer": "3.3",
  "tgApiDocUrl": "https://www.tuguan.net/doc/tg-api/",
  "sceneSdkVer": "3.3",
  "clientWidth": 1111,
  "clientHeight": 969
}

可以看到，getAppInfo的 callback 中除了包括调用是否成功的基础信息，还包括了 TGAPI 的版本信息，客户端控件大小信息等，为调试程序提供有了用的帮助。

返回本章目录

第五节 TGAPI 事件订阅 ​

引入版本：3.1 起支持

如上方提到的，TGAPI 的事件订阅指令为addEventListener, 参数对象中包括了eventName和一个回调函数callback，其中eventName是需要监听的事件，callback为事件触发时执行的方法。同一个事件，可以监听多次，执行不同的方法。

对应的，取消事件订阅指令为removeEventListener，可以移除指定事件和回调函数的对应关系。

例如：

JavaScript
// 在服务初始化完成后，需要执行的方法
function onServiceInitCallback(result) {
    console.log(result)
}

// 添加事件监听
appInstance.uniCall('addEventListener', {
    eventName: 'onServiceInit',        // 事件名称
    callback: onServiceInitCallback
  },  (result) => {}
);

// 移除事件监听
appInstance.uniCall('removeEventListener', {
    eventName: 'onServiceInit',        // 事件名称
    callback: onServiceInitCallback
  },  (result) => {}
);

事件回调函数的result对象，每个事件接口的并不相同，具体需要参考API 手册的事件部分。例如，onCameraMove事件订阅后，会收到如下回调消息：

JavaScript
{
    coordType: 0,	// XY 轴坐标类别，0：X 经度，Y 纬度；1：X 米，Y米，相对世界00点
    coordTypeZ: 0,	// Z 轴坐标类别，0：相对 3D 世界 0 海拔；1：相对 3D 世界地表；2：相对 3D 模型表面（单位：米）
    centerCoord: [103.956291,1.406699],	// 中心点的坐标 lng,lat
    coordZ: 150,	// Z 轴高度（单位：米）
    distance: 1000,	// 镜头距中心点距离(单位:米)
    pitch: 30,	// 镜头俯仰角(5~89)
    heading: 0	// 镜头偏航角(0正北, 0~359)
}

在图观统一开发 API 中，事件的总数量甚至是比接口指令的数量都要多。掌握好事件监听，能够接收和处理事件的回调消息，对于二次开发好一个应用具有特别重要的意义。特别是对于需要和场景进行交互，感知场景状态，获得场景中无接口调用信息，通过场景触发或者用户交互触发的消息的功能开发。在后面还会详细说到一些事件的具体用法。

返回本章目录