Geospatial API 会结合使用 VPS 和 GPS 数据来生成高精度地理空间姿势。此 API 可在设备能够确定其位置的任何位置使用:
- 在 GPS 精度较低的区域(例如室内空间和密集的城市环境)中,该 API 将依赖于 VPS 覆盖范围来生成高精度姿势。
- 在几乎或没有高空遮挡物的户外环境中,Geospatial API 或许能够使用可用的 GPS 位置数据来生成高度准确的地理空间姿势。
您可以在 AR 会话开始之前确定 VPS 在给定水平位置的可用性,并使用它来打造更具体的体验,例如呈现“进入 AR”按钮。
启用 ARCore API
您的应用必须启用 ARCore API 才能检查 VPS 是否可用。
启用 ARCore API 后,您无需执行以下操作即可检查 VPS 可用性:
- 当前正在运行的
Session
(在调用Session.resume()
之前)。 - 设置
GeospatialMode
。
检查应用中的 VPS 可用性
Geospatial API 可在设备能够确定其位置的任何位置使用。如果您的 AR 体验取决于 VPS 覆盖率,您可以使用 Session.checkVpsAvailabilityAsync()
获取 VpsAvailabilityFuture
,这是一个异步任务,用于检查给定水平位置的 VPS 可用性。
获取 VpsAvailabilityFuture
后,您可以通过轮询或回调来获取其结果。
轮询结果
使用 Future.getState()
获取 Future
的状态。有三种不同的状态:
PENDING
:操作尚未完成,因此无法得知结果。CANCELLED
:操作已被Future.cancel()
取消。绝不会调用任何注册的回调。DONE
:操作已完成。使用VpsAvailabilityFuture.getResult()
获取结果。
您可以继续查看 Future.getState()
,直到任务完成为止。
// Obtain a VpsAvailabilityFuture and store it somewhere.
VpsAvailabilityFuture future = session.checkVpsAvailabilityAsync(latitude, longitude, null);
// Poll VpsAvailabilityFuture later, for example, in a render loop.
if (future.getState() == FutureState.DONE) {
switch (future.getResult()) {
case AVAILABLE:
// VPS is available at this location.
break;
case UNAVAILABLE:
// VPS is unavailable at this location.
break;
case ERROR_NETWORK_CONNECTION:
// The external service could not be reached due to a network connection error.
break;
// Handle other error states, e.g. ERROR_RESOURCE_EXHAUSTED, ERROR_INTERNAL, ...
}
}
// Obtain a VpsAvailabilityFuture and store it somewhere.
val future = session.checkVpsAvailabilityAsync(latitude, longitude, null)
// Poll VpsAvailabilityFuture later, for example, in a render loop.
if (future.state == FutureState.DONE) {
when (future.result) {
VpsAvailability.AVAILABLE -> {
// VPS is available at this location.
}
VpsAvailability.UNAVAILABLE -> {
// VPS is unavailable at this location.
}
VpsAvailability.ERROR_NETWORK_CONNECTION -> {
// The external service could not be reached due to a network connection error.
}
else -> {
TODO("Handle other error states, e.g. ERROR_RESOURCE_EXHAUSTED, ERROR_INTERNAL, ...")
}
}
}
通过回调获取结果
您还可以通过回调获取 Future
的结果。使用 Session.checkVpsAvailabilityAsync()
并提供 callback
。在 Future
的状态变为 DONE
后,主线程很快就会调用此 callback
。
session.checkVpsAvailabilityAsync(
latitude,
longitude,
result -> {
// Callback is called on the Main thread.
switch (result) {
// Handle the VpsAvailability result as shown above.
// For example, show UI that enables your AR view.
}
});
session.checkVpsAvailabilityAsync(latitude, longitude) { result ->
// Callback is called on the Main thread.
// Handle the VpsAvailability result as shown above.
// For example, show UI that enables your AR view.
TODO("Handle VpsAvailability " + result)
}
取消Future
使用 Future.cancel()
尝试取消 Future
。由于线程并行性,您的取消尝试可能实际上并未成功。
如果尝试成功,Future.cancel()
返回 true
,否则返回 false
。
在没有 VPS 覆盖的情况下使用 Geospatial API
Geospatial API 还可在未覆盖 VPS 的区域使用。在顶部障碍很少或没有障碍物的户外环境中,GPS 可能足以生成高精度姿势。
后续步骤
- 获取设备相机的地理空间姿态,以确定用户设备在现实世界中的确切位置。