デバイスの現在地での VPS の提供状況を確認する

Geospatial API は、VPS と GPS データを組み合わせて使用し、高精度の地理空間のポーズを生成します。API は、デバイスが位置を判断できる場所であれば、どこでも使用できます。

• 屋内や密集した都市環境など、GPS 精度の低い地域では、API は VPS カバレッジに基づいて高精度のポーズを生成します。
• オーバーヘッドの障害物がほとんどまたはまったくない屋外環境では、Geospatial API は利用可能な GPS 位置情報データを使用して、地理空間のポーズを高い精度で生成できます。

AR セッションを開始する前に、特定の水平位置での VPS の可用性を判断し、それを使用して、より具体的なエクスペリエンス（たとえば「AR を入力」を提示する）を作成できます。ボタンは、VPS が使用可能な場合にのみ使用できます。

ARCore API を有効にする

VPS の利用可否を確認するには、アプリで ARCore API を有効にする必要があります。

ARCore API が有効になると、以下を行わずに VPS の可用性を確認できるようになります。

• 現在実行中の Session（Session.resume() を呼び出す前）。
• GeospatialMode の設定。

アプリで VPS が利用可能かどうか確認する

Geospatial API は、デバイスが自身の位置情報を特定できる場所であれば、どこでも使用できます。AR エクスペリエンスが VPS のカバレッジに依存している場合は、Session.checkVpsAvailabilityAsync() を使用して VpsAvailabilityFuture を取得できます。これは、特定の水平位置で VPS の可用性を確認する非同期タスクです。 VpsAvailabilityFuture を取得したら、ポーリングまたはコールバックを通じて結果を取得できます。

結果をポーリングする

Future.getState() を使用して Future の状態を取得します。ステータスには次の 3 つがあります。

• PENDING: オペレーションはまだ完了していないため、結果は不明です。
• CANCELLED: オペレーションは Future.cancel() によってキャンセルされました。登録済みのコールバックが呼び出されることはありません。
• DONE: オペレーションは完了しています。VpsAvailabilityFuture.getResult() を使用して結果を取得します。

タスクが完了するまで、引き続き Future.getState() をチェックできます。

Java

// 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, ...
  }
}

Kotlin

// 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 を指定します。この callback は、Future の状態が DONE になった直後にメインスレッドで呼び出されます。

Java

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.
      }
    });

Kotlin

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 で高精度のポーズを生成できます。

次のステップ

• デバイスカメラの地理空間ポーズを取得して、現実世界におけるユーザーのデバイスの正確な位置を特定します。