统一开发 API

Appearance

第二章 统一接口调试器 ​

目录 ​

在本章教程中，我们主要讲解图观统一开发 API 的辅助调试工具图观统一接口调试器。本章内容分为五个小节，会为大家手把手讲解操作，使用图观统一接口调试器创建一个新项目，完成快速测试基本接口，并且进行场景内的绘制和模拟代码生成，最后将全部的自定代码保存成综合测试代码的的操作方法。

第一节 接口调试器优势 ​

图观统一接口调试器主要有以下功能优势：

  • 图观统一接口调试器内置了一套最新的图观统一开发 API，全部的代码可以脱离接口调试器，在 TGAPI SDK 中单独运行。
  • 可以帮助开发者省去使用程序开发 IDE 搭建环境、运行程序的繁琐步骤，在线轻松的测试图观已经发布的场景。
  • 内置大量的 TGAPI 标准功能测试代码，可以在您的场景中默认执行。其代码片段亦可作为您的开发手册进行查阅，并复制到您的工程代码中。
  • 提供绘制功能，可以在加载的图观场景中标绘点、线、面数据，获得基于场景真实坐标，并且导出数据。
  • 提供生成模拟代码功能，可以根据您的标绘点线面数据，生成模拟的图观统一开发 API 中的图层数据，生成代码。解决您在没有真实数据时，开发项目需要生成模拟数据的苦恼。
  • 综合测试功能可以保存您的测试代码，或者生成的模拟代码，以备后续调用。

返回本章目录

第二节 创建调试场景 ​

1. 预先条件 ​

如果您准备使用图观统一接口调试器加载练习场景，需要具备以下硬件和软件的条件。

硬件 ​

  • 8G 内存，有独立显卡，NVIDIA GTX 960 及以上的笔记本或者台式机。

软件 ​

  • 操作系统：Windows，MacOS，Linux 均可
  • 推荐使用Google Chrome 浏览器，版本 88 及以上（2021 年 1 月之后版本），或者 Microsoft Edge 版本 88 及以上、360 浏览器版本 13 及以上
  • 如需查看自己的 Google Chrome 浏览器版本，您可以在浏览器地址栏中输入 chrome://settings/help，或者点击菜单 -> 设置 -> 关于 Chrome

查看浏览器版本

2. 登录图观打开接口调试器 ​

  1. 打开谷歌浏览器，输入图观网址https://www.tuguan.net并访问，我们就进到了图观的官网
  2. 点击官网导航栏右侧的 登录 按钮，看到了登录界面，输入已开通好的账号和密码后点击 登录
  3. 进到了图观业务管理界面，在“我的业务”中有“租户服务”、“端渲染场景服务”、“接口调试器服务”、“应用编辑器服务”4 种服务，我们选择“接口调试器服务”点击 前往 按钮

用户后台

  1. 进入接口调试器首页

3. 接口调试器首页介绍 ​

进入到接口调试器的首页页面， 页面左侧是 场景管理列表，在这里我们可以对我们所有场景进行分类整理，便于我们后续查找。中间 Tab 栏切换 工作台 和 案例库，工作台 可新建场景并展示所有已创建场景；案例库 中的案例可以进行预览到导入到自己的工作台。页面右上显示公告，帮助及用户设置。

接口调试器首页

4. 创景场景“智慧社区” ​

  1. 点击“新建场景”，将会弹出“新建场景”对话框。
  2. 场景类别选择默认“端渲染”，场景名称中输入中文名称“智慧社区”，场景链接输入https://www.tuguan.net/api/sceneEditor/v1/scenes/ed402a51-a00a-48f2-8b60-f51963440e82/loadAVWS，点击“确定”按钮即可完成项目的创建。

新建场景

  1. 鼠标悬停在场景面板上可以唤醒隐藏的功能菜单，我们可以对该场景进行“重命名”、“移动”、“复制”、“删除”。现在我们点击 编辑 按钮，打开该场景。

编辑场景

5. 场景首页介绍 ​

进入场景首页后，可以看到：

场景首页

  1. 界面上方是“单体测试”和“综合测试”切换按钮。
  2. 右侧是“场景信息”，点击后会在场景前方通过悬浮面板展现端渲染的实时的帧率、三角面数、定点数和绘制调用，这些信息在做场景性能分析，排查性能问题时比较有用。
  3. “保存”按钮，如果在综合测试、绘制、生成模拟代码功能中有修改内容，“保存”按钮会一直闪烁，直到重新保存，大家在做的时候一定要记得随时点击这个按钮保存我们的页面。
  4. “设置”按钮，点击“设置”按钮，里面可以修改当前场景地址，并且设置场景绘制功能的样式，在后续课程中还会详细讲解该功能。

返回本章目录

第三节 单体测试功能介绍 ​

1. 单体测试介绍 ​

单体测试介绍

  1. 在单体测试中，界面主要位置显示的是需要调试的三维场景，场景上叠加有工具栏，工具栏的功能后续会有相应介绍。
  2. 在场景右侧分辨是“场景对象”、“场景对象”和“全局对象”，这里已经按照三大分类，罗列了可以调试执行的图观统一开发 API 全部接口。“场景对象”界面上半部分还列举出了场景内置状态，和场景中模型和建筑对象列表。这个功能比较有用，您可以零代码的完成切换场景状态、控制模型显隐的操作。
  3. “场景对象”下部分的“模型”、“建筑”、“特殊”分类，及“场景对象”相同级别的“图层对象”、“全局对象”列表中的功能点击后，都将出现在右上方的代码面板中，通过点击代码面板右上方的“执行”按钮可以运行代码。如果修改代码，可以再次点击“执行”查看修改完的效果。如果想保存修改的代码，可以点击“添加到综合测试”。
  4. 执行代码的运行结果会出现在右下方的“事件日志“面板中。

2. 使用场景对象 ​

在场景对象中，如果您选中了一个模型节点，将会在“模型”代码执行的时候使用这个模型 ID。

使用场景对象

  1. 从场景对象列表中选中“小区底座”。
  2. 在“模型”分类面板中，选中“获取模型关节数据”。
  3. 右上角代码模版中有相应的图观 API 指令，并且id对应了选中的小区底座。
  4. 点击“执行”按钮，看到下方“事件日志”中小区底座对应的关节数据。

3. 使用图层对象 ​

如果场景已经设置好了基准点，对应了场景和经纬度信息，在图层对象中的所有图层测试数据都会自动围绕着这个场景中心点的经纬度来模拟生成。

  1. 在全局对象中选中“其他控制”，点击“获取当前基准位置”，并执行代码，可以在下方看到本场景已经设置了经纬度基准点，如果所示。

获取当前基准位置

JavaScript
{
  "result": 1,
  "message": "成功。",
  "originLon": 116.348586,
  "originLat": 40.084065,
  "originHeight": 0
}
  1. 在图层对象中选中“地标点”，点击“添加地标点”，在右上方代码中可以看到，接口调试器中单体测试图层代码要多一些，每个图层的添加都是由clearOverlayType、addLandmark和focusById组成的。这样可以避免重复添加造成的 id 重复问题，并且在添加后，还可以自动聚焦到新添加的对象上。所以在接口调试器，并没有单独的“聚焦”测试代码，这些代码都是放到了添加图层的代码里。

添加地标点

  1. 可以看到右上方代码面板中，coord信息是在本场景中心点附近，我们可以在微调一下代码，把coordZ修改为 4，把coord修改为[116.35046,40.08441]，然后点击执行。

返回本章目录

第四节 绘制和模拟生成代码 ​

在二次开发场景过程中，会经常遇上在场景内获得点位、镜头信息甚至是生成模拟数据的需求，这些在接口调试器中都有对应的功能。

1. 获取场景点位和镜头信息 ​

如果只是获取单个点位和镜头信息，最快速的方法是使用工具栏的【获取经纬度】和【获取当前视角参数】功能。

获取经纬度

  1. 点击工具栏上 获取经纬度 按钮。
  2. 在您需要拾取经纬度信息的位置单击。
  3. 弹出返回获取结果对话框。结果通过两种格式返回，分别是经纬度信息和 JSON 信息。这些信息都可以通过旁边的复制按钮快速复制。JSON 格式的接口的数据又有两种coordType，为 0 的类型是经纬度信息，为 1 的是相对于场景中心点的直角坐标系 XYZ 偏移，单位是米。
JavaScript
{
  "data": [
    {
      // 经纬度和高度信息
      "coord": [116.35038100181625, 40.08387589472818],
      "coordZ": 56.36066447595689,
      "coordType": 0
    }, {
      // 相对于场景中心点的直角坐标系XYZ偏移，单位是米
      "coord": [80.83362013402173, 11.130423168949338],
      "coordZ": 22.799852132791344,
      "coordType": 1
    }
  ]
}
  1. 点击 获取当前视角参数 按钮，将会弹出返回对话框，其中的数据可以快速复出出来，并且应用到 TGAPI 其他接口当中。

获取当前视角参数

返回本章目录

2. 绘制 ​

工具栏上的第三个和第四个按钮，是非常重要的功能，这里先介绍第三个 绘制 按钮。

进入到绘制功能之前，请先使用 设置 功能，进入 标绘设置 确认路线和区域的设置，特别是路线宽度和围栏高度，这个数值的单位都是米。在不同大小的场景下，请确保这个数值不会过大或者过小造成看不到的问题。

请按照如图所示设置数值，并点击 确定。

标绘设置

点绘制 ​

添加点

添加点

  1. 点击 绘制 按钮，弹出 绘制对话框。
  2. 绘制对话框 共有三个页签功能，分别是“点”、“路径”、”区域“。
  3. 在“点”功能下，点击 绘制 按钮，你可以在界面中通过单击，添加一个点。添加的点会出现在列表中，通过列表右侧的编辑按钮修改点名称。

编辑点

  1. 在列表中，选中一个不同点，可以在左侧三维对应的点上出现 平移交互轴。点击 编辑 按钮可以修改点名称。

编辑点

  1. 使用 平移交互轴 可以修改点的位置。这个 平移交互轴 有 7 个不同的平移方向组合。
    • 单向移动：拖拽这个轴，只会沿着 x、y、z 其中某一个方向移动。
    • 平面移动：拖拽这个面，只会沿着 xy 平面、yz 平面、xz 平面其中某一个平面移动。
    • 自由移动：拽转这个点，坐标点会随意移动，基于当前视角状态的透视关系移动，请谨慎使用。

平移交互轴

  1. 再点击 绘制 按钮，退出绘制和编辑状态。

导出、删除数据和其他

  1. 点击 全选 选中全部点，单击 导出 并选择一种希望的格式，可以导出数据。如果想直接生成图观 API 代码数据，请看后面的 生成模拟代码 功能。
  2. 选择的点，您可以通过使用工具栏上的 删除 按钮进行删除。
  3. 如果绘制的点比较多，可以通过工具栏上的 新建文件夹 组合和管理点。另外还可以通过列表最右侧的图标控制图层、或者单点的显隐。
  4. 在后续的“路径”、“区域”功能中，选择、导出、删除、新建文件夹和显隐控制功能是一样的，就不再另行介绍了。

路径绘制 ​

添加

添加路径

  1. 在绘制对话框里，选择“路径”Tab 页签，点击 绘制 按钮。
  2. 在三维场景中您希望绘制开始的地方单击，添加第一个点。
  3. 然后继续在场景中单击，添加第二个点，这时，在第二个点和之后的每一个最后点的旁边，会有 确定 和 取消 两个按钮。您可以沿着小区入口主路，标绘一条路径。在标绘过程中，鼠标右键拖拽仍然可以旋转场景，中键滚轮缩放场景，中键点击拖拽平移场景。
  4. 标绘完成后，点击 确定 按钮，添加的路径会出现在列表中，通过列表右侧的编辑按钮修改路径名称。
  5. 再次点击 绘制 按钮，退出添加状态。

编辑

编辑路径

  1. 在三维场景中，单击一条已经绘制好的路径，可以进入到编辑路径的状态。
  2. 通过 平移交互轴 调整整个路径位置
  3. 使用加号图标在路径上添加一个新的关键点。

编辑路径关键点

  1. 单击关键点可以进入关键点编辑状态，这个时候，可以通过 平移交互轴 调整单个点的位置，路径的每个点可以位于不同的高度。
  2. 使用关键点右侧的删除图标，删除单个点。如果路径上只有两个点，不会有单个点的删除按钮，这时删除路径需要通过路径列表中，选中路径，再单击 删除 按钮。
  3. 单击场景的其他位置，可以退出关键点编辑状态，返回路径编辑状态。
  4. 再次单击场景的其他位置，退出路径编辑状态。

区域绘制 ​

添加

添加区域

  1. 在绘制对话框里，选择“区域”功能
  2. 点击 绘制 按钮，进入绘制状态。
  3. 在界面中通过单击，添加第一个点，然后继续在场景中单击，添加第二个点和第三个点。您可以沿着小区道路，标绘一栋建筑区域。在绘制过程中，鼠标右键拖拽仍然可以旋转场景，中键滚轮缩放场景，中键点击拖拽平移场景。
  4. 在第三个点和之后的每一个最后点的旁边，会有 确定 和 取消 两个按钮。标绘完成后，点击“确定“按钮.
  5. 再次点击 绘制 按钮，退出添加状态。

编辑

  1. 在三维场景中或者区域列表中，单击一个已经绘制好的区域，可以进入到编辑状态。这时，您可以通过 平移交互轴 调整整个区域位置。通过加号图标在区域上添加一个新的关键点。
  2. 单击关键点可以进入关键点编辑状态，这个时候，可以通过 平移交互轴 调整单个点的位置，如果修改了单个点的高度，整个区域的高度也会发生变化。
  3. 点击关键点右侧的删除图标，可以删除单个点。如果区域上只有三个点，不会有单个点的删除按钮，这时删除区域需要通过区域列表中，选中区域，再单击 删除 按钮。
  4. 单击场景的其他位置，可以退出关键点编辑状态，返回区域编辑状态。
  5. 再次单击场景的其他位置，退出区域编辑状态。

返回本章目录

3. 生成模拟代码 ​

工具栏上的第四个按钮，是非常重要的 生成模拟代码 功能。点击这个按钮，会弹出 生成模拟代码 对话框。

生成模拟代码

对话框分为三个 Tab 页签，分别是“图层”， “模型/特效”和“视点”。每个 Tab 页签下方可以选择更加具体的代码类型，点击右侧的“加号”按钮，可以生成对应类型的模拟代码。

添加三维柱图 ​

通过这个演示，可以在刚才每栋楼上点击标绘点的位置，生成相应的三维柱图图层。

  1. 选中 图层 Tab 页签，在图层类型中选择 三维柱图，然后点击“+“按钮。

添加三维柱图

  1. 弹出 生成模拟代码 - 三位柱图对话框，左侧是对于图层代码的设置，每个选项都对应 TGAPI 的指令参数，中间是列举在 绘制 面板中的点数据。这里的数据类型是根据生成 TGAPI 代码所需要的数据类型加载的。例如三维柱图只能关联中心点坐标，所以只能看到 图层数据 - 点。在这里，我们选择 默认图层，图层的全部子节点都会被选中。右侧面板比较特殊，并不是所有的图层都有的，只有 TGAPI 参数需要 value 的图层，才会有这个区域。因为柱图在关联点的位置后，还需要一个 value 决定柱子的高度。所以这里可以有数据的最小值下限、最大值上限，另外还提供了多种分布方式可以选择，对于 value 的随机结果，可以通过 生成预览 查看。

添加三维柱图对话框

  1. 点击 确定 按钮，完成生成三维柱图的模拟代码，柱图出现在每栋楼的楼顶，并且在图层列表中多了一个 3DCloumn 图层。

完成添加三维柱图

  1. 鼠标悬浮在图层上，可以激活图层操作按钮，如图所示，功能分辨是“修改”，“添加到综合测试”、“定位”和“隐藏”

编辑三维柱图

  1. 这里点击 添加到综合测试，弹出新的对话框，点击 创建空白测试项，然后点击 添加。
  2. 点击 综合测试 并且将列表滚动到最下方，点击最后一项，可以在右上方的代码区域看到刚才生成好的 TGAPI 指令和测试数据。您可以在代码区域继续编辑代码，编辑完成后别忘记保存。

返回本章目录

第五节 使用综合测试 ​

综合测试

  1. 在上面最后的步骤中，我们已经来到了 综合测试 页面。
  2. 在综合测试列表中，选中一行可以在右侧看到测试代码，还可以在列表中修改名称或者删除。
  3. 修改代码后，使用 保存 按钮进行保存。
  4. 在列表的最下方，可以点击 + 添加综合测试项 添加一个新的空白测试项。

返回本章目录

第六节 使用案例库 ​

在接口调试器中，为您提供了案例库功能。使用案例库，您可以快速浏览接口调试器的场景中的代码执行，并且将您感兴趣的案例导入到自己的工作台中，继续进行参考、编辑。

案例库

  1. 在接口调试器首页点击案例库。
  2. 找到 开发教程卡通版。
  3. 点击 预览 按钮，这是打开了接口调试器预览页面。

案例库预览

  1. 在新开的浏览器标签页里，左侧综合测试列出来当前场景的接口调试器内置测试代码。
  2. 鼠标悬浮在列表项上，可以激活 查看代码 按钮。
  3. 点击 查看代码 按钮，在右侧代码面板可以查看测试用例的详细内容。
  4. 单击列表项可以执行代码。

案例库导入

  1. 返回到之前的案例库页面，找到 开发教程卡通版，鼠标点击 导出 按钮。
  2. 在弹出的导出对话框了，选择一个希望导入工作台的节点。一版选择 根节点 也可以。
  3. 点击 确定 按钮。
  4. 这样案例库的示例工程就会出现在 工作台 对应的节点目录下。打开后，跳转到 综合测试 可以看到示例代码功能。

在本教程后面的章节中，全部的示例代码片段都存在于这个 开发教程卡通版 的案例工程里。所以请您在进行后面课程之前，导入到自己的工作台中。

返回本章目录