卫星图

本指南：配置卫星图能力，并在运行时切换卫星底图。

功能介绍

卫星图允许用户在标准矢量地图与卫星影像之间切换：

初始化阶段：配置 HERE API Key 与本地缓存空间上限。
运行时：通过 FeaturesController.satelliteMap() 开启或关闭卫星底图。

能力	说明
运行时切换	`satelliteMap().setEnabled()` / `setDisabled()`
缓存空间限制	`setSatelliteDataSpaceLimit` 控制本地影像缓存上限（最小 32 MB，推荐 200 MB，满额自动淘汰旧数据）
回退矢量地图	`setDisabled()` 恢复标准矢量底图

效果示意：

卫星底图

核心接口一览

阶段	接口	说明
SDK 初始化	`NavSDKOptions.setSatelliteHereApiKey(apiKey)`	HERE 卫星图 API Key
SDK 初始化	`NavSDKOptions.setSatelliteDataSpaceLimit(size)`	本地缓存上限（字节）；最小 32 MB，推荐 200 MB
运行时	`features.satelliteMap().setEnabled()`	切换为卫星底图
运行时	`features.satelliteMap().setDisabled()`	恢复矢量底图

接口详细说明

1. setSatelliteHereApiKey — 配置 API Key（初始化）

在 SDK 初始化之前 配置卫星图访问凭证。

fun setSatelliteHereApiKey(
    apiKey: String
)

参数	类型	说明
`apiKey`	`String`	HERE 卫星图服务 API Key；发布前确认域名、包名等限制

示例代码：

val navSDKOptions = NavSDKOptions.builder(options, vehicleInfoConfig)
    .setSatelliteHereApiKey(SATELLITE_HERE_API_KEY)
    .build()

SDK.getInstance().initialize(context, navSDKOptions)

2. setSatelliteDataSpaceLimit — 配置卫星影像本地缓存上限（初始化）

设置卫星瓦片在设备本地的 最大存储空间（字节）。浏览地图、缩放或平移时，SDK 会按需下载并缓存卫星影像；达到上限后，自动删除较早的缓存数据 以腾出空间给新区域使用。

接口方法	参数	类型	说明
`setSatelliteDataSpaceLimit(size)`	`size`	`Long`	卫星数据缓存空间上限，单位为字节（bytes）

取值说明：

项	值	说明
最小值	`32 MB`（`1024 × 1024 × 32`）	传入值小于该值时，SDK 在 `build()` 时自动抬升到最小值
推荐值	`200 MB`（`1024 × 1024 × 200`）	官方推荐配置，兼顾常用导航区域缓存与磁盘占用
合法性	`> 0`	若 `≤ 0`，初始化校验会抛出异常（`MESSAGE_SATELLITE_STREAMING_LIMIT_INVALID`）

工作机制：

卫星瓦片下载后写入本地缓存目录，占用空间累计计算。
当已缓存数据总大小达到 size 上限时，引擎会 删除较早的卫星缓存 以释放空间，保证新浏览区域仍可继续加载。
关闭卫星图（satelliteMap().setDisabled()）时，会清理卫星图形缓存（clearGraphicCache），与本地空间上限配置相互独立。

何时调整 size：

场景	建议
城市导航、偶发开启卫星图	使用推荐值 `200 MB` 即可
频繁切换卫星图、跨城长途	可适当增大（如 `300 MB`），减少重复下载
存储空间紧张的嵌入式设备	可设为最小值 `32 MB`，但缓存命中率会下降

该配置为可选项；未调用时，MapContent 侧默认按 200 MB 处理。须在 SDK.getInstance().initialize(...) 之前通过 NavSDKOptions.Builder 设置。

fun setSatelliteDataSpaceLimit(size: Long)

示例代码：

// 推荐：200 MB
private const val SATELLITE_CACHE_RECOMMENDED = 1024L * 1024L * 200L  // 200 MB

// 最小：32 MB（小于此值会被 SDK 自动修正为 32 MB）
private const val SATELLITE_CACHE_MINIMUM = 1024L * 1024L * 32L   // 32 MB

val navSDKOptions = NavSDKOptions.builder(options, vehicleInfoConfig)
    .setSatelliteHereApiKey(SATELLITE_HERE_API_KEY)
    .setSatelliteDataSpaceLimit(SATELLITE_CACHE_RECOMMENDED)
    .build()

SDK.getInstance().initialize(context, navSDKOptions)

3. satelliteMap — 运行时开关

在 MapView.onReady 之后通过 FeaturesController 控制卫星底图显隐。该特性 默认关闭。

接口方法	说明
`features.satelliteMap().setEnabled()`	切换为卫星影像底图
`features.satelliteMap().setDisabled()`	恢复矢量底图

示例代码（主屏）：

val features = mapView.getFeaturesController() ?: return

features.satelliteMap().setEnabled()   // 开启卫星图
features.satelliteMap().setDisabled()  // 关闭，回到矢量地图

示例代码（Cluster 副屏）：

clusterMapView.featuresController().satelliteMap().setEnabled()

完整集成示例

// 1) SDK 初始化（Application.onCreate 或启动前）
val navSDKOptions = NavSDKOptions.builder(options, vehicleInfoConfig)
    .setSatelliteHereApiKey(BuildConfig.SATELLITE_HERE_API_KEY)
    .setSatelliteDataSpaceLimit(200L * 1024L * 1024L)
    .build()
SDK.getInstance().initialize(context, navSDKOptions)

// 2) 地图就绪后切换
mapView.setOnReadyListener {
    mapView.getFeaturesController()?.satelliteMap()?.setEnabled()
}

// 3) 用户关闭卫星图
fun disableSatellite() {
    mapView.getFeaturesController()?.satelliteMap()?.setDisabled()
}

注意事项

不要同时开启 satelliteMap() 与 terrain()；切换时先关闭另一方。详见地图特性。
卫星瓦片依赖在线影像，需评估网络流量；setSatelliteDataSpaceLimit 过小会导致旧区域瓦片被频繁淘汰、重复下载。
缓存上限仅在 SDK 初始化时生效，运行中无法动态修改；调整需重新初始化 SDK。
不再需要卫星图时及时 setDisabled()，降低渲染与数据压力。
发布前确认 API Key 与域名 / 包名限制配置正确。

卫星图