Skip to content

三维地形

本指南：开启三维地形渲染，呈现丘陵、山谷等地形起伏。

功能介绍

三维地形通过高程数据使地表呈现 起伏与阴影，便于理解山区、丘陵等场景下的道路走向与相对高度。该能力通过 FeaturesController.terrain() 在运行时开关，无需额外的 SDK 初始化参数。

terrain() 与 satelliteMap() 可以同时启用，两个 Feature 互不排斥，按业务需要分别或一并 setEnabled() / setDisabled() 即可。单独开启地形时，效果叠加在矢量底图上；同时开启卫星图时，须先完成卫星图 SDK 初始化，详见 卫星图。

能力 说明
运行时开关 terrain().setEnabled() / setDisabled()
与 satelliteMap 可与 satelliteMap() 同时启用，两个 Feature 可并存
地形数据 支持 在线（Streaming）下载 高程数据；不强制 预装本地地图包
默认状态 关闭
视角配合 建议在 三维显示模式 下适当 倾斜相机，更易观察地形起伏（见 显示模式与视角）

效果示意：

三维地形

获取入口：

1
val features = mapView.getFeaturesController() ?: return

核心接口一览

阶段 接口 说明
运行时 features.terrain().setEnabled() 开启三维地形
运行时 features.terrain().setDisabled() 关闭三维地形，恢复平坦矢量底图

对应 SDK 声明：

1
2
3
4
5
/**
 * Get [Feature] object to control the terrain
 * @return the terrain Feature
 */
fun terrain(): Feature

接口详细说明

terrain — 运行时开关

在 MapView.onReady 之后通过 FeaturesController 控制三维地形显隐。与通用 Feature 一致，使用 setEnabled() / setDisabled()。

接口方法 说明
features.terrain().setEnabled() 开启三维地形渲染
features.terrain().setDisabled() 关闭三维地形

示例代码（主屏）：

1
2
3
4
mapView.setOnReadyListener {
    val features = mapView.getFeaturesController() ?: return@setOnReadyListener
    features.terrain().setEnabled()
}

示例代码（Cluster 副屏）：

1
clusterMapView.featuresController().terrain().setEnabled()

与 satelliteMap 同时启用：

1
2
3
val features = mapView.getFeaturesController() ?: return
features.terrain().setEnabled()
features.satelliteMap().setEnabled()

完整集成示例

1
2
3
4
5
6
7
8
9
// 地图就绪后开启三维地形
mapView.setOnReadyListener {
    mapView.getFeaturesController()?.terrain()?.setEnabled()
}

// 用户关闭三维地形
fun disableTerrain() {
    mapView.getFeaturesController()?.terrain()?.setDisabled()
}

注意事项

  • terrain() 与 satelliteMap() 可同时启用，互不排斥；若同时开启卫星图，须配置 API Key 与缓存，并评估 渲染与网络 开销。
  • 地形表现与 缩放级别、相机倾角 相关；过低缩放或纯俯视时起伏可能不明显，可配合相机控制调整视野。

相关指南