VPSを使ってローカライズする

Wayspot AnchorsなどのLightship VPSの機能を使用するには、ユーザーはまず、VPSが有効なWayspotまたはプライベートVPSロケーションでローカライズ（ロケーションを特定）する必要があります。VPSが有効なWayspotにローカライズするには、アプリがユーザーの位置情報データや、Wayspotに向けたユーザー視点のカメラデータをLightship VPSに送信する必要があります。Lightship VPSによって、Wayspotに対するユーザーの位置と向きが判断されます。

注釈

VPS有効なWayspotがローカライズ可能かどうかを確認する場合は、 Niantic Wayfarerアプリを使ってローカライゼーションテストを行います。

VPS有効なWayspotを検出し、そのWayspotに向かってローカライズする

VPS有効なWayspotに向かってローカライズする前に、ユーザーは、Wayspotのロケーションを探し、物理的に移動する必要があります。VPS Coverage APIを使用して、ユーザーに周辺のVPSカバレッジエリアとローカライゼーションターゲットを表示することで、VPS有効なWayspotに誘導し、ローカライズの対象を理解できるようになります。Coverage APIには、VPS有効なWayspotの「ヒント画像」も含まれており、これを使用して、ローカライゼーション中にデバイスを向ける場所をユーザーに指示することができます。詳細については、 VPS Coverage APIを使用するを参照してください。

プライベートVPSのロケーションを使ってローカライズする

開発目的かテスト目的に限り、 Niantic Wayfarerアプリを使用して作成したプライベートVPSロケーションを使ってローカライズを行うことができます。プライベートVPSロケーションのローカライズの手順は、VPSのWayspotのローカライズと同様です。プライベートVPSロケーションを使用したローカライズを行う場合は、以下の点にご注意ください。

プライベートVPSロケーションを作成したときにNiantic Wayfarerアプリで使用したのと同一のlightship.devアカウントで作成されたAPIキーで設定する必要があります。Lightship VPSでは、アプリのAPIキーと、lightship.devの開発者アカウントを照合します。
VPS Coverage APIからプライベートVPSロケーションを使用することはできません。

Wayspot Anchor APIを使ってローカライズする

Wayspot Anchor APIは、VPSを初期化するときに、 WayspotAnchorService インスタンスを新規に作成するか、 WayspotAnchorController.StartVps() を使って、VPSが有効なWayspotでローカライズを試みます。 WayspotAnchorService には、Wayspot Anchorsを作成して管理するためのシンプルな「高レベル」API、 WayspotAnchorController には、よりきめ細かい制御が必要な場合に使用できる「低レベル」APIが付属しています。

位置情報とカメラ権限を有効にする

VPS Wayspot Anchors APIではデバイスのカメラや位置情報を使用するため、ユーザーがデバイスでカメラと位置情報の権限を有効にしていることを確認する必要があります。デバイス権限のリクエストに関する詳細については、権限を参照してください。

注釈

VPSローカライゼーションや、VPS Wayspot Anchors APIなどの機能を使用するには、エンドユーザーから個人情報を収集する必要があります。詳細については、 Lightship ARDKのデータプライバシーに関するよくある質問を参照してください。

WayspotAnchorServiceを使用する

WayspotAnchorService を作成して、 ARSession、 LocationService 、 WayspotAnchorsConfiguration を取得します。 LocationService を起動する際は、正確な結果が得られるように、精度を0.01m、更新距離を0.01mに指定することをお勧めします。

using Niantic.ARDK.AR.WayspotAnchors;
using Niantic.ARDK.LocationService;

IARSession _arSession;
WayspotAnchorService wayspotAnchorService;

// ...

var wayspotAnchorsConfiguration = WayspotAnchorsConfigurationFactory.Create();
var locationService = LocationServiceFactory.Create(_arSession.RuntimeEnvironment);
// For LocationService, we recommend using a desiredAccuracyInMeters of 0.01f
// and an updateDistanceInMeters of 0.01f for best results
locationService.Start(desiredAccuracyInMeters, updateDistanceInMeters);
WayspotAnchorService _wayspotAnchorService = new WayspotAnchorService(_arSession, locationService, wayspotAnchorsConfiguration);

// Set wayspotAnchorService.LocalizationStateUpdated event handler if we want to track localization state
wayspotAnchorService.LocalizationStateUpdated += LocalizationStateUpdated;

// VPS WayspotAnchorService begins localizing, provide instructions for your user on how to localize, etc

デバイスのカメラをVPSが有効なWayspotに向け、ローカライズを開始するようユーザーに指示します（ローカライズにおけるユーザーのベストプラクティスを参照）。ローカライズの進行状況を確認するには、 WayspotAnchorService.LocalizationStateUpdated のイベントハンドラを追加します。ステータスが LocalizationState.Localized になると、セッションはVPSが作有効なWayspotにローカライズされたことを意味します。そのため、 VPS Wayspot Anchorの配置を開始できるようになります。セッションのローカライズが行われる前に復元されたWayspot Anchorは、セッションがローカライズされると位置情報の解決を開始します。

private void LocalizationStateUpdated(LocalizationStateUpdatedArgs args)
{
    // Handle any changes in localization state as needed. For example,
    // if state is Localized with a FailureReason of None, you app can
    // start creating or restoring anchors
    // ...
}

セッションがローカライズされていても、VPSで断続的なネットワーク接続が発生している可能性があることが検出されると、 LocalizationStateUpdated イベントが発生します。ステータスは Localized のままですが、 FailureReason は CannotConnectToServer に設定されます。このシナリオについて検討し、ネットワーク環境に不具合が検出されたことをアプリのユーザーに通知する必要があります。

WayspotAnchorControllerを使用する

ARSession と LocationService を指定して、 WayspotAnchorController を作成します。 LocationService を起動する際は、最良の結果が得られるように、精度を0.01メートル、交信距離を0.01メートルに指定することをお勧めします。

using Niantic.ARDK.AR.WayspotAnchors;
using Niantic.ARDK.LocationService;

WayspotAnchorController _wayspotAnchorController;

// ...

var locationService = LocationServiceFactory.Create(_arSession.RuntimeEnvironment);
// For LocationService, we recommend using a desiredAccuracyInMeters of 0.01f
// and an updateDistanceInMeters of 0.01f for best results
locationService.Start(desiredAccuracyInMeters, updateDistanceInMeters);
_wayspotAnchorController = new WayspotAnchorController(_arSession, locationService);

コントローラーの LocalizationStateUpdated イベント向けにイベントハンドラを次のように設定します。

_wayspotAnchorController.LocalizationStateUpdated += HandleLocalizationStateUpdated;

WayspotAnchorsConfiguration を作成して設定し、設定した内容で WayspotAnchorController.StartVps() を呼び出すと、ローカライズプロセスが開始されます。

var wayspotAnchorsConfiguration = WayspotAnchorsConfigurationFactory.Create();

_wayspotAnchorController.StartVps(wayspotAnchorsConfiguration);

デバイスのカメラをVPSが作動したWayspotに向け、ローカライズを開始するようユーザーに指示します（下記のローカライズにおけるユーザーのベストプラクティスを参照）。 LocalizationStateUpdated イベントハンドラでローカライゼーションのステータスを監視し、ローカライズが成功したかどうかを LocalizationState で確認します。

private void HandleLocalizationStateUpdated(LocalizationStateUpdatedArgs anyLocalizationStateUpdatedArgs)
{
    if (anyLocalizationStateUpdatedArgs.State == LocalizationState.Localized) {
        // Client successfully localized with wayspot
    }
    if (anyLocalizationStateUpdatedArgs.State == LocalizationState.Failed) {
        // Localization failed, see anyLocalizationStateUpdatedArgs.FailureReason for reason
    }
}

ステータスが LocalizationState.Localized の場合は、VPSが作動したWayspotにセッションがローカライズされたことを意味します。そのため、 VPS Wayspot Anchorsの配置を開始できます。セッションがローカライズされる前に復元されたWayspot Anchorでは、セッションがローカライズされると位置の解決を開始します。

ステータスが LocalizationState.Failed の場合は、失敗したローカライゼーションの詳細を LocalizationStateUpdatedArgs.FailureReason から取得します。失敗した条件の処理については、ローカライゼーションの失敗と修復手順をご参照ください。

セッションがローカライズされていても、VPSで断続的なネットワーク接続が発生している可能性があることが検出されると、 LocalizationStateUpdated イベントが発生します。ステータスは Localized のままですが、 FailureReason は CannotConnectToServer に設定されます。このシナリオについて検討し、ネットワーク環境に不具合が検出されたことをアプリのユーザーに通知する必要があります。

ローカライゼーションプロセスを設定する

ローカライゼーションの機能を制御するには、使用する WayspotAnchorsConfiguration インスタンスのデフォルト設定を変更します。ほとんどのシナリオでは、デフォルトの設定のままで十分です。ただし、ローカライゼーションに時間がかかったり、失敗する場合は、ローカライゼーションのタイムアウト調整が必要になる場合があります。調整する WayspotAnchorsConfiguration プロパティは次のとおりです。

LocalizationTimeout : すべてのローカライズに対するタイムアウトを秒単位で指定します。デフォルトでは30秒に設定されています。
RequestTimeLimit : 全体的なローカライズの試行中に行われる個々のリクエストのタイムアウトを秒単位で指定します。デフォルトでは10秒に設定されています。
GoodTrackingWait : VPSのローカライズのステータスが良好になってから、Wayspot Anchorのトラッキングを実施するまでに必要な時間（秒）です。デフォルトでは3秒に設定されています。この設定は、ローカルセッションが安定してからローカライゼーションを行うことを目的としており、ローカライゼーション後のドリフトを防ぐのに役に立ちます。
ContinuousLocalizationEnabled : 連続してローカライゼーションを行うかどうかを設定します（詳細は連続ローカライゼーションを行うを参照）。デフォルトではFalseに設定されています。

ローカライゼーションフローを理解する

以下の情報をもとに、Wayspot Anchors APIでローカライズする方法とローカライズが失敗した場合の対処方法について説明します。

ローカライズ前

VPS有効なWayspotを検出し、そのWayspotに向かってローカライズするに記載されているように、VPSが動作したWayspotをユーザーに見つけてもらうか、そこに移動するようにユーザーを誘導する必要があります。ユーザーがVPS作動のWayspotのカバレッジエリア内にいる場合は、VPSのローカライゼーションプロセスを開始することができます。

VPSはローカライゼーションプロセスにおいて、さまざまな「ステータス」に移行します。VPSを作動すると、ユーザーの近辺にあるVPSが有効なWayspotのローカライゼーションが開始されます。VPSのステータスは、 Localizing（ローカライズ中） に移行します。カメラフレームとGPS情報がVPSのバックエンドサービスに送信され、VPSが有効なWayspotへのローカライズを行います。このステータスでは、次のようなアクションが行われます。

VPS有効なWayspotでVPSのローカライズに成功する。VPSのローカライズステータスは Localized に移行します。
VPSで断続的なネットワーク接続の問題が発生している可能性があることを検出しました。ステータスは Localizing のままですが、 LocalizationStateUpdated``イベントは ``LocalizationFailureReason が CannotConnectToServer でトリガーされます。VPSではその後もローカライズが試行されます。
さまざまな理由でVPS有効なWayspotでローカライズに失敗する場合があります。考えられる理由と修復手順はローカライゼーションの失敗と修復手順を参照してください。ステータスは Failed（失敗） に移行します。
VPSによって、ARSessionの追跡状態が不安定になったことが検出されます。VPSはトラッキング状態が安定するのを待ってから、引き続きローカライズを行います。ステータスは、Localizing（ローカライズ中） のまま変わりません。 ARSessionトラッキングが不安定な場合の対処法をご参照ください。
アプリでローカライズプロセスをキャンセルすることができます。この操作は、ユーザーがVPSを使用するアプリの一部が終了した場合に行うことができます。ステータスは、 Failed（失敗） に移行します。ローカライズプロセスは再開できます。 VPSを再起動するをご参照ください。

ローカライズ中

VPSが正常にローカライズされると、VPSのステータスは Localized（ローカライズ済み） に移行し、Wayspot Anchorsの配置と解決を開始することができます。VPSはこのステータスを維持しますが、次のような状況では再ローカライズが行われるか、Failureステータスに移行する場合があります。

VPSで断続的なネットワーク接続の問題が発生している可能性があることを検出しました。ステータスは Localized のままですが、 LocalizationStateUpdated``イベントは ``LocalizationFailureReason が CannotConnectToServer でトリガーされます。アンカーは引き続き設置可能です。
VPSでエラー状態が検出された（考えられるエラー条件および修復手順は、ローカライゼーションの失敗と修復手順をご参照ください）。ステータスは Failed（失敗） に移行します。
VPSによって、ARSessionの追跡状態が不安定になったことを検出した。ステータスは、Localizing（ローカライズ中） に移行します。ARトラッキング状態が再び安定したことを検知すると、VPSは自動的にローカライズを行います。 ARSessionトラッキングが不安定な場合の対処法をご参照ください。

注釈

セッションが正常にローカライズされると、ローカライズ前にペイロードから復元されたWayspot Anchorがある場合は、アンカーの位置や向きの解決が開始されます。復元されたアンカーは、セッションがローカライズされるとすぐに解決されるわけではありません。アンカーの位置や向きの変化を追跡する方法については、アンカートラッキングの更新を処理するをご参照ください。

ローカライゼーションの失敗と修復手順

VPSの失敗

ローカライゼーションは、さまざまな理由で失敗することがあります。アプリを使用して、 WayspotAnchorService.LocalizationStateUpdated または WayspotAnchorController.LocalizationStateUpdated のイベントハンドラでローカライズのステータスの更新をトラッキングして、ステータスと LocalizationFailureReason をご確認ください。

ローカライズに失敗する原因としては、以下のようなものが考えられます。

LocalizationFailureReason が タイムアウト : VPSが有効なWayspotで WayspotAnchorsConfiguration.LocalizationTimeout 秒以内にローカライズできなかった。この失敗の原因としては、ユーザーがVPSが有効なWayspotをうまくスキャンできなかったことが考えられます。VPS Coverage APIのローカライゼーションターゲット「ヒント画像」を使用して、デバイスを向ける方向を明確に指示し、ユーザーに再試行するように指示します。また、ユーザーがネットワークの帯域幅が狭い環境にいる場合は、 WayspotAnchorsConfiguration.LocalizationTimeout を増やすこともできます。
LocalizationFailureReason が CannotConnectToServer : ユーザーのデバイスのネットワーク接続が失われたか、VPSバックエンドへのVPSリクエストが WayspotAnchorsConfiguration.RequestTimeLimit 秒以内に応答しないか、アプリがVPSリクエストレートの制限を超過している（ VPSのローカライゼーションに関する制限事項を参照）。ユーザーのデバイスでネットワークが無効になっていないかを確認し、ネットワーク接続を再度有効にするようユーザーに求めることができます。また、ユーザーが、ネットワークの帯域幅が狭い環境にいる場合は、 WayspotAnchorsConfiguration.RequestTimeLimit を増やすこともできます。
LocalizationFailureReason が LocationDataNotAvailable : VPSがユーザーのGPS位置情報にアクセスできない。ユーザーのデバイスでGPS位置情報の権限が無効になっていないか、VPSの初期化に使用したLocationServiceが予期したとおりに動作しているかを確認してください。
LocalizationFailureReason が InvalidApiKey : 無効なARDKライセンスキーでアプリケーションが設定されている。アプリのArdkAuthConfigに有効なキーを設定し、再設定してください。
LocalizationFailureReason が Canceled（キャンセル済み） : アプリでローカライズプロセスがキャンセルされた。

VPSの修復

VPSの失敗を修復するには、VPSを再起動してローカライズ処理を再度行います。方法については、 VPSを再起動するをご参照ください。ARセッションを再起動する必要はありません。状況によっては（ネットワーク接続が切れた場合など）、Wayspot Anchorsに関連する仮想オブジェクトのレンダリングを引き続き行い、ARDKでローカルARトラッキングを使用して仮想オブジェクトを配置することができます。この場合、若干のドリフトの問題が発生する可能性があります。

ARSessionトラッキングが不安定な場合の対処法

アプリがローカライズされ、VPSでARSessionのトラッキングステータスが不安定になった（ARカメラのフレームデータが無効または破損している）ことが検出されると、VPSは自動的に再ローカライズを行い、ステータスは Localized から Localizing に移行されます。この場合、VPSが再ローカライズしてステータスが Localized に戻ったら、配置した Wayspot Anchorsの復元と、仮想コンテンツのレンダリングが再度必要になる場合があります。

ARCamera.TrackingStateReason を検査してトラッキング状態が不安定になる原因を特定し、この情報を使って再ローカライズプロセス中にユーザーを誘導できます。たとえば、 ARCamera.TrackingStateReason が ExcessiveMotion の場合は、ユーザーに移動速度を下げてスキャンするように求めることができます。

また、デバイスのパフォーマンスの監視が必要になる場合もあります。デバイスのメモリやCPUが不足している場合、トラッキングシステムはシステムリソースの不足により、正常に動かなくなります。このシナリオでは、トラッキングのパフォーマンスが著しく低下する恐れがあります。

連続ローカライゼーションを行う

Lightship VPSは、VPS 起動時に WayspotAnchorsConfiguration.ContinuousLocalizationEnabled をTrueに設定することで、連続ローカライゼーションを行うように設定できます。連続ローカライゼーションを有効にすると、VPSは最初にローカライズを行った後、ユーザーの現在の環境に合わせて連続ローカライズを行います。

連続ローカライゼーションは、長時間（10分以上）のVPSセッションでのドリフトを回避するのに役立ちます。アプリで連続ローカライゼーションが行われると、ローカライゼーション情報が更新されるため、Wayspot Anchorのドリフトを修正するのに効果的です。

また、同一のVPSセッション中にユーザーがVPSのWayspotに移動することが予想される場合、連続ローカライゼーションを行うことでユーザーエクスペリエンスが向上します。VPSは、ユーザーが移動した新しいWayspotで自動的にローカライズを行います。ユーザーが新しいWayspotに正常にローカライズしたと判断したら、新しいVPSでWayspot Anchorsの配置を開始できます。

ドリフトに対処する

シナリオによっては、Wayspot Anchorトラッキングの更新により、アンカー位置が少しずつずれる「ドリフト」が発生することがあります。ローカライゼーションの誤差は50cm以内であるため、その分Wayspot Anchorsがずれたように見えることがあります。この現象は、ARトラッキングが不安定になったときや、連続ローカライゼーションが有効で、VPSの再ローカライズが行われたときに発生することがあります。

この問題を回避するには、以下の方法を行います。

Wayspot Anchorの位置更新が通知されたとき、位置更新が現在の位置から1m以内の場合は、子ゲームオブジェクトの再配置をスキップすることで、わずかな乱れを回避します。
Wayspot Anchorの位置更新が通知されると、元の位置と必要な位置の間をスムーズに補間できます。
Wayspot Anchorと関連するゲームオブジェクトがユーザーの現在の視界外にある場合にのみ、小さな位置更新を適用するように選択することができます。

VPSを再起動する

アプリでVPSセッションをゼロから再起動する必要がある場合は、 WayspotAnchorService.Restart() を使用できます。この操作は、アプリがデバイスの位置情報サービスやネットワーク接続に問題が発生した場合（ユーザーが機内モードを有効または無効にした場合など）に必要になることがあります。これにより、進行中のWayspot Anchorの作成またはトラッキングはキャンセルされ、VPSのローカライゼーションが再度開始されます。アプリの再ローカライズが完了すると、 WayspotAnchorService.Restart() も自動的にWayspot Anchorsのトラッキングを再開します。

VPSを再起動した場合、ARセッションを再起動する必要はありません。状況によっては（ネットワーク接続が切れたことによる再起動など）、Wayspot Anchorに関連する仮想オブジェクトのレンダリングを引き続き行い、ARDKがローカルARトラッキングを使用して仮想オブジェクトを配置することができます。この場合、アンカーに関連付けられた仮想オブジェクトがわずかにドリフトする場合があります。

注釈

WayspotAnchorController を使用しており、 StopVps() や StartVps() 経由でVPSを再起動する場合、配置したアンカーの追跡は StartVps() で自動的に再開されないため、再ローカライズしてから、配置したアンカーで ResumeTracking() を呼び出す必要があります。

ローカライズにおけるユーザーのベストプラクティス

VPSが有効なWayspotでユーザーがデバイスを使用してローカライズする場合は、次のように指示する必要があります。

環境条件が良好（かつ安全）であることを確認する。たとえば、次のような内容です。
- 昼間の時間帯にローカライズする
- 天候の良い時にローカライズする（暴風雨、降雪、霧の時はローカライズしない）。
- 比較的変化の少ない環境をローカライズする。カメラ視野内に歩行者や車が多い環境ではローカライズを行わないでください。
VPSが有効なWayspotから、3～5メートル（10～15フィート）ほど離れてください。
デバイスのカメラは、真正面からVPSが有効なWayspotに向け、高い位置や低い位置から向けないようにしてください。また、地面に向けないでください。3Dシーンの情報をできるだけ詳細に収集する必要があるため、広くて平らな面や平面はあまり役に立ちません。
プロセスが完了するまで、VPSが有効なWayspotの周囲にカメラを向け続けます。この作業には約5秒かかりますが、環境の複雑さやお使いのデバイスのネットワーク帯域幅によっては、最大で30秒かかる場合もあります。
最初のローカライズに失敗しても、ローカライズは続けて試行されます。続けてローカライズを行う場合は、VPSのWayspotにカメラを向けたまま、VPSのWayspotの周りをゆっくり1周して、ローカライズを行う視点を追加してください。

Coverage APIを使ってユーザーをWayspotに誘導する場合、Coverage APIが提供するローカライズターゲット情報には、VPS作動のWayspotのローカライズターゲットの「ヒント画像」が含まれます。この画像を使用することで、ユーザーは、VPSのWayspotを発見し、ローカライズ時にデバイスのカメラを向けるべきターゲットを理解できます。

モッキングローカライゼーション

Unityエディターでモックモードを実行すると、VPSでモックのローカライズが行われ、300ミリ秒後に自動的に Localized ステータスに移行して、ローカライゼーションプロセスをシミュレートします。その後、モックモードでWayspot Anchorsを配置できるようになります。

モックモードで実行する方法の詳細については、モックモードでのプレイを参照してください。モックモードでのWayspot Anchorsの配置と復元に関する詳細については、 VPS Wayspot Anchorを使用するの「Wayspot Anchorとモックモード」を参照してください。

VPSのローカライゼーションに関する制限事項

VPS有効なWayspotにローカライズを行う場合は、以下の点に注意してください。

現時点で、VPSのローカライゼーションは、環境のローカライズやマーカーベースのローカライズと併用することはできません。
現在ARDKでは、ローカライズの際に、1～3秒ごとに約300KのデータをNiantic ARバックエンドに送信しています。帯域幅が制限された状況でAR体験を使用する場合は、この点に留意してください。
また、現在VPSのローカライゼーションリクエストは、APIライセンスキーごとに1秒あたり30クエリー（QPS）に制限されています。Niantic は、使用状況とトラフィック分析に基づき、将来的にこの制限を調整する可能性があります。ユースケースで制限値の引き上げが必要な場合は、サポートチームに連絡の上、制限値の引き上げをリクエストしてください。

VPSのローカライゼーションに関するベストプラクティス

VPSセッションごとに1つのVPSのWayspotのみをローカライズすることをお勧めします。ユーザーが別のVPSのWayspotに移動する必要がある場合は、VPSを再起動して新しいWayspotにローカライズすることを推奨しています。

ユーザーがローカライズされたVPSのWayspotから10m以内にいる場合のみ、Wayspot Anchorを配置することをお勧めします。

VPSサポート

VPSのローカライゼーションの問題に対処する方法については、開発者フォーラム https://community.lightship.dev/ をご覧ください。Niantic で詳細に問題を調査できるように、可能な場合は以下の情報をお知らせください。

問題が発生しているセッションのARセッションID。 IARSession.StageIdentifier を使用してログ記録を残す必要がある場合があります。ローカライゼーションリクエストを特定できるように、可能であればこの情報をお知らせいただくことを強くお勧めします。
ローカライゼーションを行ったGPS座標。
ローカライズ中のVPS有効なWayspotの LocalizationTarget.Identifier の情報（VPS Coverage APIを使用している場合）。
LocalizationStateとLocalizationFailureReason（該当する場合）。
ローカライゼーションを行った日時。