统一开发 API

Appearance

统一开发 API 简介 ​

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

5.0 起，这套接口在原有的控制能力之外补齐了观察侧：可以读取场景的真实运行状态、按标识寻址聚焦，再决定下一步动作，便于上层 AI 应用编排。具体内容见文末「面向 AI 的开发特性」。

目录 ​

双渲染技术架构 ​

流渲染 ​

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

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

系统架构图

端渲染 ​

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

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

系统架构图

返回本章目录

流渲染视频速览 ​

返回本章目录

端渲染视频速览 ​

返回本章目录

面向 AI 的开发特性 ​

引入版本：5.0 起支持

观察与寻址 ​

在此之前，统一开发 API 是一组单向控制接口：能下发指令，但读不到场景的实际状态。上层要判断当前画面里有什么，没有查询接口可用。

5.0 补上了两件 AI 应用必需的能力。一是场景感知，把场景的运行状态与对象结构作为结构化数据返回；二是地理层级聚焦族，把「去哪里看」从一组手填的镜头参数变成按标识寻址的指令。两者配合，AI 应用才能形成「观察 → 决策 → 执行 → 复核」的闭环，而不是只跑一次的固定脚本。

返回本章目录

场景感知 ​

场景感知包含两条接口，都只返回快照、不做研判，判断交给上层应用。

接口回答的问题主要内容
getRuntimeInfo当前看得见什么场景、镜头、视口、图层可见性、事件监听、可用资源
getSceneGraph场景里有哪些对象节点树（建筑、模型、图标、关系线、画刷图层、城市）与地理层级树

getRuntimeInfo 用 include 按模块裁剪返回内容，可选 scene、camera、layers、events、resources；不传则返回全部。viewport 不受 include 控制，任何情况下都会返回。

其中图层一部分对 AI 最有用：它不是只给一个「显示/隐藏」，而是逐层给出是否在视锥内、是否被设置为隐藏、是否被其他物体遮挡、屏幕占比是否低于阈值，并汇总成 visible、off_screen、occluded、hidden、too_small 五种摘要，同时给出可见元素数量与可见率。这样上层可以区分「图层关了」和「图层开着但当前角度看不见」，避免把屏外当成数据缺失。

getSceneGraph 支持四个过滤条件：includeTypes 按节点类型过滤（building、model、icon、connection、paintlayer、city、root，其中 root 仅作返回类型出现，传入不产生额外查询），includeHidden 控制是否包含隐藏节点，maxDepth 限制层级深度，rootId 只看某棵子树。返回的每个节点带 id、name、type、parentId、visible、transform 与 properties，其中 properties 是原始对象的属性，按数据源原样透传。

返回本章目录

地理层级聚焦族 ​

镜头控制在一级指令之外，5.0 新增了四条按地理层级定位的聚焦指令。

指令作用关键参数
focusGeoLevel按地理层级或节点名称定位geoLevel 取 1–10（全球级到房间级）、name 按行政区名精确匹配，两者至少给一个
focusUpperGeoLevel从当前节点向上卷一级无
focusLowerGeoLevel从当前节点向下钻一级name 指定下级节点；不传时下钻到第一个子节点
focusPlace按 POI 标识直接聚焦到地点类目标id 取自 getSceneGraph 返回的节点 id，不能为空

这组指令的关键在寻址方式。getSceneGraph 的地理层级树里，每个节点带默认视角 defaultPOI 与可用视角 availablePOIs，视角对象用 poiId 唯一标识，并附带目标引用与镜头参数。AI 只要先读出 poiId，就能交给 focusPlace 直接定位，不必自己推算经纬度、俯仰角和距离。

配套还有行政边界图层相关的 addBoundaryLayer、updateBoundaryLayerStyle、updateBoundaryNameStyle、updateBoundaryLayerLOD、updateBoundaryLayerFilter、setBoundaryDisplayScope，以及 highlightCity、setCityNameVisible，可按行政层级绘制边界并逐级控制样式、名称与显示范围。

两点边界情况需要按预期处理，而不是当成故障重试：

  • 已经处于最高可聚焦层级（全球级）时继续上卷，引擎返回 result 为 0 并给出层级边界说明。
  • model 与 icon 类目标不属于「地点」，用 focusPlace 寻址不到，应改用 focusModel、focusById 等既有聚焦指令。

返回本章目录

典型编排闭环 ​

下面是一段最小闭环：先看现状，再取候选视角，按标识聚焦，最后复核。

JavaScript
// 1. 观察：当前场景、镜头与图层可见性
appInstance.uniCall('getRuntimeInfo', { include: ['scene', 'camera', 'layers'] }, (view) => {
  // 2. 取址：从地理层级树里读 availablePOIs[].poiId
  appInstance.uniCall('getSceneGraph', {}, (graph) => {
    const poiId = 'poi-entrance';
    // 3. 寻址：按 poiId 直接聚焦
    appInstance.uniCall('focusPlace', { id: poiId }, (focused) => {
      // 4. 复核：再看一次镜头与图层，确认目标已进入视野
      appInstance.uniCall('getRuntimeInfo', { include: ['camera', 'layers'] }, (after) => {
        console.log(view, graph, focused, after);
      });
    });
  });
});

三步的分工是：观察负责回答「现在是什么状态」，取址负责回答「可以去哪里」，聚焦负责「去」。复核这一步不能省，因为镜头到位不等于目标可见——被前置建筑遮挡时，图层状态仍会显示为已加载。

返回本章目录

支持范围与限制 ​

  • 端渲染与流渲染的支持程度并不齐平。5.0 中行政边界与城市高亮、地理层级聚焦、场景图的地理信息部分（geoData）目前仅流渲染支持；端渲染调用这些接口返回 result 为 0，计划于后续版本添加支持。
  • getRuntimeInfo 的部分字段也只在流渲染下返回，包括事件监听状态、内置与自定义图标列表、场景数据范围的包围盒、当前激活状态摘要等；端渲染可用的字段见各接口页面的「端渲染 / 流渲染」列。
  • 两条感知接口返回的都是采集时刻的快照，不含历史与趋势。需要对比时由上层按需多次采样。
  • 坐标与单位统一：位置同时以 [经度, 纬度, 海拔] 和 ENU 东北天坐标 [x, y, z] 两套给出，前者单位为度、海拔为米，后者单位为米。

返回本章目录