Geospatial API 总览与核心能力

Geospatial API 是什么

ARCore Geospatial API（地理空间 API）是 Google 在 ARCore 体系中推出的"把 AR 内容锚定到真实世界坐标"的能力。与普通 Anchor（锚定到 SLAM 检测到的平面/特征点）不同，Geospatial Anchor 直接锚定到经纬度（WGS84 坐标）和海拔高度——你可以在 Google Street View 覆盖的任何位置放置 AR 内容，用户走到这个位置就能看到。

核心优势：不需要预先建图。传统 AR 共享（如 Cloud Anchors）需要用户先走到某个位置"建立锚点"，其他设备再去"解析"。Geospatial API 借助 Google 街景的全球覆盖，让开发者直接把内容关联到任意经纬度，路过的人只需要打开应用就能看到——不需要任何人先做本地扫描。

Geospatial API 的三层架构

设备侧（手机）          云端（Google）          真实世界
─────────────────────────────────────────────────────────
GPS + IMU + 摄像头  →  VPS 匹配  →  经纬度 + 海拔
                              ↓
                       Geospatial Anchor（你的 AR 内容）

核心能力清单

覆盖范围与限制

已覆盖国家/地区

Geospatial API 覆盖 Google Street View 已经拍摄过的区域——这意味着全球超过 100 个国家和地区的主要城市和道路都能用。但以下情况有例外：

• 室内：VPS 无法定位（街景不进室内）
• 偏远地区/乡村：街景覆盖稀疏，VPS 定位可能不准或失败
• 极偏远地区：完全没有街景数据，VPS 无法工作
• 地下/地铁/隧道：GPS 和 VPS 都失效

精度对比

设备要求

Geospatial API 支持大部分 ARCore 支持的 Android 设备和 iOS 12+。少数老设备或某些低端机型不支持——可以用代码检测：

val geospatialSupported = session.isGeospatialModeSupported(
    Session.Config.GeospatialMode.ENABLED
)

网络要求

Geospatial API 必须有网络连接——VPS 定位需要把摄像头画面发送到 Google 云端匹配街景数据。没有网络时 Geospatial API 会完全无法工作，需要降级到本地 SLAM + 普通 Anchor。

Session 配置启用 Geospatial

val session = Session(context)

// 检查设备支持
if (session.isGeospatialModeSupported(Session.Config.GeospatialMode.ENABLED)) {
    session.configure(
        Session.Config(context).apply {
            setGeospatialMode(Session.Config.GeospatialMode.ENABLED)
        }
    )
}

// 在 iOS 上还需要配置 API Key 和隐私声明

iOS 上的额外配置

iOS 上使用 Geospatial API（或任何需要上传数据到 Google 云端的 API）需要在 Info.plist 中声明：

• NSLocationWhenInUseUsageDescription（使用地理位置）
• NSCameraUsageDescription（使用摄像头）
• NSMicrophoneUsageDescription（某些场景可能需要）

开发入口

Google 提供了所有主流开发环境的 Geospatial API 支持：

典型应用场景