WayspotAnchorServiceを使用する

WayspotAnchorService には、Wayspot Anchorsを使用するための高レベルのインターフェイスが用意されています。また、 WayspotAnchorService では、アンカーのキャッシュを維持し、低レベルのVPSイベントを多数処理することで、アンカーの作成と管理のプロセスを簡略化しています。

WayspotAnchorService の使用例については、 ARDK使用例 のWayspotAnchorsの例をご参照ください。以下のコード例の多くは、そのサンプルの中の WayspotAnchorExampleManager から引用したものです。

Wayspot Anchorsの作成やキャッシュを詳細に制御したい場合は、 WayspotAnchorService ではなく、 WayspotAnchorController を使用します。 WayspotAnchorConroller の詳細な使用方法については、 WayspotAnchorControllerを使用する をご参照ください。

Wayspot Anchorを作成する

Wayspot Anchorを作成するには、以下の手順で行います。

1. ローカル座標空間内の特定の位置に新しいアンカーを作成します。

   VPSを起動したセッションで、ローカル座標空間でのアンカーの位置と向きを指定して WayspotAnchorService.CreateWayspotAnchors() を呼び出します。アンカーを作成すると、 WayspotAnchorService によって、現在のローカライゼーションのステータスが LocalizationState.Localized であることが確認されます。

   using Niantic.ARDK.AR.WayspotAnchors;
   
   WayspotAnchorService _wayspotAnchorService;
   
   private void PlaceAnchor(Matrix4x4 localPose)
   {
       var anchors = _wayspotAnchorService.CreateWayspotAnchors(localPose);
       if (anchors.Length == 0)
           return; // error raised in CreateWayspotAnchors
   }
   

   WayspotAnchorService.CreateWayspotAnchors() より、すぐに IWayspotAnchors のリストが返り、CreateWayspotAnchors() の呼び出しに問題があった場合には空のリストが返ります（たとえば、ローカライズのステータスが Localized でない場合など）。

   返された IWayspotAnchor には、それぞれVPSで割り当てられるアンカーIDが含まれます。このIDは、ステータスやトラッキングイベント中にアンカーを識別する際に使用します。アンカーの最初の IWayspotAnchor.Status は WayspotAnchorStatusCode.Pending です。これは、VPSでアンカーが作成中であることを示します。

2. アンカーに関連付けるGameObjectを作成します。

   アンカーに関連付けられている仮想オブジェクトのGameObjectをシーンに作成します。次の例では、 _anchorPrefab のGameObjectをインスタンス化し、 WayspotAnchorTracker を使用してGameObjectをアンカーと関連付けています。

   using Niantic.ARDK.Extensions;
   
   private GameObject CreateWayspotAnchorGameObject
   (
       IWayspotAnchor anchor,
       Vector3 position,
       Quaternion rotation,
       bool startActive
   )
   {
       var go = Instantiate(_anchorPrefab, position, rotation);
   
       var tracker = go.GetComponent<WayspotAnchorTracker>();
       if (tracker == null)
       {
           tracker = go.AddComponent<WayspotAnchorTracker>();
       }
   
       tracker.gameObject.SetActive(startActive);
       tracker.AttachAnchor(anchor);
   
       return go;
   }
   

   アンカーと、関連付けられている仮想オブジェクトがユーザーによって作成され、配置されている場合に、アンカーのステータスがまだ Pending であっても、GameObjectの作成や有効化が必要になる場合があります。これにより、ユーザーがアンカーを設置してから、VPSでアンカーが正常に作成され、配置されるまでの間に遅延が発生しないようにします。VPSがアンカーを作成できない場合は、関連付けられているGameObjectを削除する必要があります。

3. アンカーごとに作成ステータスを追跡します。

   各アンカーの IWayspotAnchor.StatusCodeUpdated イベントにハンドラを登録し、作成されたアンカーのステータスを追跡します。ステータスが Pending から Success に変更された場合は、VPSでアンカーが正常に作成されたことを意味します。

   ステータスが Failed に変わると、アンカーを作成できなかったことを意味します。この場合、ゲームオブジェクトを配置したり、アンカーの位置の変化を追跡したりできなくなります。 StatusCodeUpdated イベントを IWayspotAnchors にマッピングするには、イベントハンドラに渡される WayspotAnchorStatusUpdate.ID を使用するか、 WayspotAnchorTracker のようなクラスを作成して IWayspotAnchor と関連付け、独自の StatusCodeUpdated イベントハンドラを追加します。

4. アンカーペイロードを保存します。

   作成された IWayspotAnchor には Payload が含まれます。このバイナリブロブは、以前に作成したアンカーを復元する場合や、他のユーザーとアンカーを共有する場合のために保存しておく必要があります。このペイロードは、VPSで作成され、 IWayspotAnchor.Status が Success または Limited の場合のみ使用することができます。アンカーペイロードのシリアライズやデシリアライズを行う方法については、 Wayspot Anchorsの永続化と共有 をご参照ください。

5. アンカーの位置更新を追跡します。

   Wayspot Anchorが正常に作成されたら、アンカーの TransformUpdated イベントをサブスクライブして、ユーザーの動きに合わせてアンカーの位置や向きをVPSから修正してください。これを行う方法については アンカートラッキングの更新を処理する をご参照ください。

Wayspot Anchorを復元する

以前に作成したWayspot Anchorを復元するには、次の手順で行います。

1. アンカーを復元するには、アンカーペイロードを使用します。

   以前のVPSセッションで作成されたWayspot Anchorを復元するには、 WayspotAnchorService.RestoreWayspotAnchors() を使用します。アンカーが配置されているVPSが起動したWayspotに対してアンカーを復元するために必要な情報をすべて含むアンカーのペイロードのリストを指定してください。

   using Niantic.ARDK.AR.WayspotAnchors;
   
   // Deserialize/load saved payloads, using WayspotAnchorPayload.Deserialize() as needed
   // var payloads = ...load payloads...
   if (payloads.Length > 0)
   {
       var wayspotAnchors = _wayspotAnchorService.RestoreWayspotAnchors(payloads);
   }
   

   以前のWayspot Anchorペイロードをロードする必要がある場合は、 Wayspot Anchorsの永続化と共有 を参照の上、Wayspot Anchorsのシリアライズとデシリアライズの方法をご覧ください。

   RestoreWayspotAnchors() は、CreateWayspotAnchors() によって返る内容と同様の IWayspotAnchors の配列を返します。

2. GameObjectsを作成し、アンカーに関連付けます。

   アンカーに関連付けられている仮想オブジェクトのGameObjectをシーンに作成します。プレハブをインスタンス化し、 WayspotAnchorTracker を使用してアンカーを関連付けるサンプルは、 Wayspot Anchorを作成する をご参照ください。

3. アンカーごとに復元ステータスを追跡します。

   アンカーごとの IWayspotAnchor.StatusCodeUpdated イベントにハンドラを登録し、作成されたアンカーのステータスをトラッキングします。ステータスが Pending から Success に変更された場合は、VPSでアンカーが正常に作成されたことを意味します。

   ステータスが Failed に変わると、アンカーを復元できなかったことを意味します。この場合、ゲームオブジェクトを配置したり、アンカーの位置の変化を追跡したりできなくなります。 StatusCodeUpdated イベントを IWayspotAnchors にマッピングするには、イベントハンドラに渡される WayspotAnchorStatusUpdate.ID を使用するか、 WayspotAnchorTracker のようなクラスを作成して IWayspotAnchor と関連付け、独自の StatusCodeUpdated イベントハンドラを追加します。

4. アンカーの位置更新を追跡します。

   新しいアンカーを作成する場合と同様に、ユーザーの動きに合わせてアンカーの位置や向きをVPSから修正するために、アンカーの TransformUpdated イベントをサブスクライブする必要があります。これを行う方法については アンカートラッキングの更新を処理する をご参照ください。

   注釈

   復元されたアンカーは、 RestoreWayspotAnchors() が戻ったときに完全に解決されていない可能性があります。 WayspotAnchorTracker を使用していない場合には、アンカーが世界に正しく配置されたと仮定する前に、アンカーの TransformUpdated イベントをリッスンする必要があります。

Wayspot Anchorsを削除する

WayspotAnchorService は、Wayspot Anchorsのキャッシュを管理します。アンカーをトラッキングする必要がなくなると、 WayspotAnchorService.DestroyWayspotAnchors() を使ってキャッシュからアンカーを削除できます。その際、 IWayspotAnchors のリストまたはアンカーIDのリストを指定します。

using Niantic.ARDK.AR.WayspotAnchors;

Guid[] ids;

// ...populate ID array with Anchor IDs you want to remove...

// Delete anchors from cache using Anchor IDs
_wayspotAnchorService.DestroyWayspotAnchors(ids);

VPSセッションを再起動する

アプリでVPSセッションをゼロから再起動する必要がある場合は、 WayspotAnchorService.Restart() を使用することができます。VPSを再起動する必要がある場合の例については、 VPSでのローカライズ　の「ローカライゼーションフローを理解する」を参照してください。また、VPS セッションを再起動する際の詳細については、 VPSを使ってローカライズする の「VPSを再起動する」をご参照ください。