Appearance
场景感知操作
本族是 5.0 为上层 AI 应用补上的场景观察能力。getRuntimeInfo 回答当前场景看得见什么，getSceneGraph 回答场景里有哪些对象；两者都只返回快照、不做研判，供 AI 编排、自动化巡检与状态看板读取三维场景的真实运行状态。
目录
1. 获取运行时信息
引入版本：5.0 起支持
功能描述
获取当前三维场景的运行时状态，返回场景、镜头、视口、图层、事件监听与资源六类信息。
调用方法
JavaScript
let jsonData = {
include: ['scene', 'camera', 'layers'],
};
appInstance.uniCall('getRuntimeInfo', jsonData, (result) => {
console.log(result);
});参数描述
| 属性 | 类型 | 说明 |
|---|---|---|
| include | Array<String> | 按模块裁剪返回内容，可选值：scene 场景、camera 镜头、layers 图层、events 事件监听、resources 资源；不传则返回全部五个模块 |
回调数据
JSON
{
"result": 1,
"message": "成功。",
"data": {
"timestamp": "2026-10-23T02:10:00.000Z"
}
}回调数据参数描述
| 属性 | 类型 | 说明 |
|---|---|---|
| result | Number | 1：代表成功；0：代表失败 |
| message | String | 成功或者失败原因 |
| data | Object | 运行时信息，七个顶层字段；完整结构见下方「返回结构」 |
5.0 端渲染支持的字段少于流渲染，未支持的字段计划于后续版本添加支持。
1. data 顶层
| 字段 | 类型 | 端渲染 | 流渲染 | 说明 |
|---|---|---|---|---|
| timestamp | String | 支持 | 支持 | 采集时刻，ISO 8601 |
| scene | Object | 支持 | 支持 | 场景信息，见 1.1 |
| camera | Object | 支持 | 支持 | 镜头信息，见 1.2 |
| viewport | Object | 支持 | 支持 | 视口信息，见 1.3 |
| layers | Object | 支持 | 支持 | 覆盖物图层信息，见 1.4 |
| eventListeners | Object | 支持 | 支持 | 事件监听状态，见 1.5 |
| resources | Object | 支持 | 支持 | 可用资源，见 1.6 |
1.1 scene 场景信息
| 字段 | 类型 | 端渲染 | 流渲染 | 说明 |
|---|---|---|---|---|
| name | String | 支持 | 支持 | 当前加载的场景名称 |
| mode | String | 支持 | 支持 | 场景模式：scene 端渲染、streaming 流渲染 |
| extent.origin.lon / lat / alt | Number | 支持 | 支持 | 场景基准点，米坐标系统原点对应的经度、纬度、海拔（米） |
| extent.boundsLLH.lonMinMax / latMinMax / altMinMax | Array<Number> | 不支持 | 支持 | 场景数据范围的经纬高包围盒 |
| extent.boundsENU.xMinMax / yMinMax / zMinMax | Array<Number> | 不支持 | 支持 | 场景数据范围的米坐标包围盒，ENU 东北天 |
| status.isInitialized | Boolean | 支持 | 支持 | 场景是否已初始化 |
| status.isLoading | Boolean | 不支持 | 支持 | 是否正在加载 |
| status.currentSceneName | String | 支持 | 支持 | 当前场景名；未加载时不返回该字段 |
| states[].name | String | 支持 | 支持 | 场景内置状态名称 |
| states[].isDefault | Boolean | 支持 | 支持 | 是否为默认状态，即场景加载时自动激活 |
| activeState | Object | 不支持 | 支持 | 当前激活状态的配置摘要，含镜头、天气、后期效果 |
| currentGeoLevel.level | Number | 支持 | 支持 | 当前视野地理层级数值，1–10 |
| currentGeoLevel.geoLevel | String | 支持 | 支持 | 层级名称：全球级、国家级、省级、市级、区县级、街道级、园区级、建筑级、楼层级、房间级 |
1.2 camera 镜头信息
| 字段 | 类型 | 端渲染 | 流渲染 | 说明 |
|---|---|---|---|---|
| position.coordLLA | Array<Number> | 支持 | 支持 | 镜头位置 [经度, 纬度, 海拔] |
| position.coordENU | Array<Number> | 支持 | 支持 | 镜头位置 [x, y, z]，ENU 东北天坐标系，单位米 |
| target.coordLLA | Array<Number> | 支持 | 支持 | 镜头朝向目标 [经度, 纬度, 海拔] |
| target.coordENU | Array<Number> | 支持 | 支持 | 镜头朝向目标 [x, y, z]，ENU 坐标系 |
| params.pitch | Number | 支持 | 支持 | 俯仰角，度 |
| params.heading | Number | 支持 | 支持 | 航向角，度 |
| params.distance | Number | 支持 | 支持 | 镜头到目标的距离，米 |
| params.fov | Number | 支持 | 支持 | 视场角，度 |
| isRestricted | Boolean | 支持 | 支持 | 镜头当前是否处于受限状态 |
| restrictedAreaLLA | Object | 不支持 | 支持 | 镜头受限范围，经纬高表示 |
| restrictedAreaENU | Object | 不支持 | 支持 | 镜头受限范围，ENU 米坐标表示 |
| restrictedDistance.min / max | Number | 不支持 | 支持 | 镜头受限距离范围，米 |
1.3 viewport 视口信息
| 字段 | 类型 | 端渲染 | 流渲染 | 说明 |
|---|---|---|---|---|
| widthPx | Number | 支持 | 支持 | 视口宽度，像素 |
| heightPx | Number | 支持 | 支持 | 视口高度，像素 |
| devicePixelRatio | Number | 支持 | 支持 | 设备像素比 |
| pixelArea | Number | 支持 | 支持 | 像素面积，等于 widthPx × heightPx |
1.4 layers 覆盖物图层信息
| 字段 | 类型 | 端渲染 | 流渲染 | 说明 |
|---|---|---|---|---|
| layerIds | Array<String> | 支持 | 支持 | 全部图层 id 列表，按图层叠放顺序排列 |
| results | Array<Object> | 支持 | 支持 | 每个图层的可见性结果，结构见 1.4.1 |
以下 1.4.1 至 1.4.5 为端渲染返回结构。
1.4.1 单个图层结果
| 字段 | 类型 | 说明 |
|---|---|---|
| id | String | 图层 id |
| type | String | 图层类型，如 3DColumnLayer、heatmapLayer |
| name | String | 图层名称 |
| isVisible | Boolean | 图层的显隐状态 |
| elementCount | Number | 该图层的渲染对象数量 |
| dataPointCount | Number | 实际数据点数量；仅优化渲染的图层返回 |
| renderingType | String | 渲染类型：mesh、instanced、shader、unknown |
| visibility.isInFrustum | Boolean | 是否至少有一个元素在视锥范围内 |
| visibility.isHidden | Boolean | 是否被设置为隐藏 |
| visibility.isFullyOccluded | Boolean | 是否所有元素都被遮挡 |
| visibility.isTooSmall | Boolean | 是否屏幕占比低于阈值 |
| visibility.summary | String | 可见性摘要：visible 可见、off_screen 屏外、occluded 被遮挡、hidden 隐藏、too_small 过小 |
| averageVisibility | Object | 各可见性分类的元素数量与可见率，见 1.4.2 |
| aggregatedScreenBounds | Object | 可见元素的屏幕包围盒并集，见 1.4.3 |
| aggregatedSpatialExtent | Object | 所有元素的空间范围，含 dataBoundsLLA 与 dataBoundsENU |
| averageElementMetrics | Object | 元素尺寸统计，见 1.4.4 |
| elementSamples | Array<Object> | 前 5 个元素的样本，结构见 1.4.5 |
| elements | Array<Object> | 参与计算的元素明细，最多 20 个，结构见 1.4.5 |
1.4.2 averageVisibility 可见性统计
| 字段 | 类型 | 说明 |
|---|---|---|
| visibleCount | Number | 可见元素数量，summary 为 visible |
| offScreenCount | Number | 屏外元素数量 |
| occludedCount | Number | 被遮挡元素数量 |
| hiddenCount | Number | 被隐藏元素数量 |
| tooSmallCount | Number | 尺寸过小元素数量 |
| visibilityRatio | Number | 可见率，等于 visibleCount / elementCount |
1.4.3 aggregatedScreenBounds 屏幕包围盒
| 字段 | 类型 | 说明 |
|---|---|---|
| minX / maxX / minY / maxY | Number | 包围盒四边，像素 |
| widthPx / heightPx | Number | 包围盒宽高，像素 |
| coverageRatio | Number | 总覆盖率，所有可见元素覆盖面积除以视口面积 |
1.4.4 averageElementMetrics 元素尺寸
| 字段 | 类型 | 说明 |
|---|---|---|
| avgWorldSizeENU | Array<Number> | 平均世界尺寸 [x, y, z]，ENU 坐标系 |
| minWorldSizeENU | Array<Number> | 最小元素的世界尺寸 |
| maxWorldSizeENU | Array<Number> | 最大元素的世界尺寸 |
| avgScreenSize | Array<Number> | 平均屏幕尺寸 [宽, 高] |
| minScreenSize | Array<Number> | 最小元素的屏幕尺寸 |
| maxScreenSize | Array<Number> | 最大元素的屏幕尺寸 |
1.4.5 elementSamples 与 elements 的元素结构
| 字段 | 类型 | 说明 |
|---|---|---|
| id | String | 元素标识 |
| screenCoord | Array<Number> | 元素在屏幕上的坐标 |
| screenSize | Array<Number> | 元素的屏幕尺寸 |
elementSamples 取前 5 个，elements 最多 20 个。
1.5 eventListeners 事件监听状态
| 字段 | 类型 | 端渲染 | 流渲染 | 说明 |
|---|---|---|---|---|
| global | Array<Object> | 不支持 | 支持 | 全局事件监听器，元素含 eventName、listenerCount |
| layers | Array<Object> | 不支持 | 支持 | 图层事件监听器，元素含 idLayer、overlayType、events[] |
1.6 resources 可用资源
| 字段 | 类型 | 端渲染 | 流渲染 | 说明 |
|---|---|---|---|---|
| icons.builtin | Array<String> | 不支持 | 支持 | 内置图标名称列表 |
| icons.custom | Array<String> | 不支持 | 支持 | 自定义图标名称列表 |
| models | Array<String> | 支持 | 支持 | 可用的模型类型列表 |
2. include 的裁剪范围
只查一部分内容时传 include，可减少一次调用里的查询项。viewport 不受 include 控制，任何情况下都返回。
2. 获取场景图信息（含地理信息节点）
引入版本：5.0 起支持
功能描述
获取场景对象树与地理信息节点树，用于按 POI 标识定位与聚焦。
调用方法
JavaScript
let jsonData = {
includeTypes: ['building', 'model'],
maxDepth: 2,
includeHidden: true,
};
appInstance.uniCall('getSceneGraph', jsonData, (result) => {
console.log(result);
});参数描述
| 属性 | 类型 | 说明 |
|---|---|---|
| includeTypes | Array<String> | 按节点类型过滤，可选值：building 建筑、model 模型、icon 图标、connection 连接线、paintlayer 画刷图层、city 城市、root 场景根节点；不传返回全部类型。其中 root 仅作返回类型出现，传入不产生额外查询 |
| includeHidden | Boolean | 是否包含隐藏节点，默认 true |
| maxDepth | Number | 最大层级深度，根节点为 0；0 表示只返回根节点，不传表示不限制 |
| rootId | String | 只返回该节点及其所有后代，不传返回整个场景图 |
回调数据
JSON
{
"result": 1,
"message": "成功。",
"data": {
"timestamp": "2026-10-23T02:10:00.000Z",
"stats": {
"totalNodes": 128,
"nodesByType": {},
"maxDepth": 4
}
}
}回调数据参数描述
| 属性 | 类型 | 说明 |
|---|---|---|
| result | Number | 1：代表成功；0：代表失败 |
| message | String | 成功或者失败原因 |
| data | Object | 场景图数据，含 timestamp、geoData 地理层级树、nodes 节点列表、stats 统计信息；完整结构见下方「返回结构」 |
5.0 端渲染支持的字段少于流渲染，未支持的字段计划于后续版本添加支持。
1. data 顶层
| 字段 | 类型 | 端渲染 | 流渲染 | 说明 |
|---|---|---|---|---|
| timestamp | String | 支持 | 支持 | 生成时刻，ISO 8601 |
| geoData | Object | 不支持 | 支持 | 地理层级树，见第 3 节 |
| nodes | Array<Object> | 支持 | 不支持 | 场景对象节点列表，见第 2 节 |
| stats | Object | 支持 | 不支持 | 节点统计信息，见第 4 节 |
2. nodes 节点列表
| 字段 | 类型 | 说明 |
|---|---|---|
| id | String | 节点唯一标识。取原始数据的 id、idLayer 或 name |
| name | String | 显示名称 |
| type | String | 节点类型：building、model、icon、connection、paintlayer、city、root |
| parentId | String | 父节点 id；根节点为 null |
| order | Number | 同类型节点中的排序序号 |
| visible | Boolean | 是否可见 |
| transform.position | Array<Number> | 位置 [x, y, z] |
| transform.rotation | Array<Number> | 旋转 [x, y, z]，欧拉角，度 |
| transform.scale | Array<Number> | 缩放 [x, y, z] |
| properties | Object | 原始对象的全部属性，按数据源原样透传，字段随图层类型变化 |
节点排序按类型分组：city、paintlayer、building、model、icon、connection，组内按 order。
3. geoData 地理层级树
| 字段 | 类型 | 说明 |
|---|---|---|
| geoLevels | Array<Object> | 顶层地理节点数组，结构与 3.1 的节点相同 |
3.1 单个地理节点
| 字段 | 类型 | 说明 |
|---|---|---|
| geoLevel | Number | 层级数值，1 全球级到 10 房间级 |
| geoLevelText | String | 层级名称：全球级、国家级、省级、市级、区县级、街道级、园区级、建筑级、楼层级、房间级 |
| administrativeName | String | 行政区域或建筑区域名称 |
| precisionGrade | String | 建模精度分级：L1、L2、L3、L4；非必返 |
| defaultPOI | Object | 该层级的默认推荐视角，可为 null；结构见 3.2 |
| availablePOIs | Array<Object> | 该层级可用视角列表，结构同 3.2；按约定不重复包含 defaultPOI |
| children | Array<Object> | 子节点数组，结构与本节相同，递归嵌套 |
3.2 视角对象
| 字段 | 类型 | 说明 |
|---|---|---|
| poiId | String | 视角唯一标识，聚焦指令用它寻址 |
| name | String | 视角名称 |
| targetRef | Object | 聚焦目标引用，结构见 3.3 |
| cameraParams.target.lon / lat / alt | Number | 镜头朝向目标 |
| cameraParams.distance | Number | 镜头到目标距离，米 |
| cameraParams.pitch | Number | 俯仰角，度 |
| cameraParams.heading | Number | 航向角，度 |
| cameraParams.fov | Number | 视场角，度 |
| localBaseCenter.x / y / z | String | 本地基准中心，字符串形式保存。x 经度、y 纬度、z 高度 |
| timeZone | Number | 时区，由基准中心经度推算的整数 |
| description | String | 描述。场景生成时为空，可在场景编辑器中补充 |
cameraParams 可能带 position 等附加字段，按原样透传。
3.3 targetRef 目标引用
| 字段 | 类型 | 说明 |
|---|---|---|
| type | String | 目标类型：state 状态、model 模型、building 建筑、floor 楼层、room 房间、location 地点、icon 图标 |
| sceneName | String | 目标所属场景 |
| buildingId | String | 目标所属建筑；type 为 building、floor、room 时需要 |
| floorId | String | 目标所属楼层；type 为 floor、room 时需要 |
| roomId | String | 目标房间；type 为 room 时需要 |
| identifier | String | 目标标识；type 为 state、model、icon 时使用 |
| highlightMode | String | 高亮方式，可选 |
4. stats 统计信息
| 字段 | 类型 | 说明 |
|---|---|---|
| totalNodes | Number | 过滤后的节点总数 |
| nodesByType | Object | 按类型分组的计数，键为 nodes 里出现的 type 值 |
| maxDepth | Number | 实际最大层级深度，不受 maxDepth 参数影响 |
5. 参数与返回的关系
按 rootId 过滤时，该 id 不存在则返回 result 为 1、message 为找不到根节点的提示、nodes 为空数组、stats.totalNodes 为 0。
maxDepth 与 rootId 可同时使用，先按深度过滤再按子树过滤。
6. 与地理聚焦指令的关系
geoData 里的 poiId 是地理聚焦系列指令的寻址依据：focusGeoLevel 按层级与名称定位节点，focusUpperGeoLevel 与 focusLowerGeoLevel 在当前节点上下移动，focusPlace 按 poiId 直接定位。
5.0 端渲染不返回 geoData，这组指令在端渲染下返回 result 为 0；端渲染支持计划于后续版本添加。