Using WayspotAnchorService

WayspotAnchorService provides a high-level interface for working with Wayspot Anchors. WayspotAnchorService simplifies the process of creating and managing anchors by maintaining a cache of anchors and handling many of the low-level VPS events for you.

For an example of using WayspotAnchorService, see the WayspotAnchors sample in ARDK-examples. Many of the following code examples are from WayspotAnchorExampleManager in that sample.

If you need more control over how Wayspot Anchors are created and cached, use WayspotAnchorController instead of WayspotAnchorService. See Using WayspotAnchorController for more details on working with WayspotAnchorConroller.

Creating a Wayspot Anchor

Use the following steps to create a Wayspot Anchor:

  1. Create a new anchor at a specific position in your local coordinate space.

    In your session where you’ve started VPS, call WayspotAnchorService.CreateWayspotAnchors() with your anchor position and orientation in your local coordinate space. WayspotAnchorService will verify the current localization state is LocalizationState.Localized when you create any anchors.

    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() returns immediately with a list of IWayspotAnchors, or an empty list if there was an issue with call to CreateWayspotAnchors() (for example, the localization state was not Localized).

    Each returned IWayspotAnchor will have an anchor ID that VPS assigns, that you’ll use to identify anchors during status or tracking events. The anchors will initially have a IWayspotAnchor.Status of WayspotAnchorStatusCode.Pending, indicating that VPS is in the process of creating the anchors.

  2. Create GameObjects associated with your anchor.

    Create GameObjects in your scene for virtual objects associated with your anchor. The following example instantiates a GameObject from a _anchorPrefab and associates the GameObject with an anchor using WayspotAnchorTracker.

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

    If anchors and associated virtual objects are being created and placed by your users, you may want to create and activate your GameObjects even if the anchor is still in Pending status. This ensures your users don’t encounter a delay from when they place the anchor to when VPS successfully creates and positions the anchor. If VPS can’t create the anchor you’ll need to remove the associated GameObject.

  3. Track the creation status for each anchor.

    Track the created anchor status by registering a handler for each anchor’s IWayspotAnchor.StatusCodeUpdated event. If the status changes from Pending to Success, VPS successfully created the anchor.

    If the status changes to Failed, the anchor could not be created and you won’t be able to use the anchor for placing game objects or tracking anchor position changes. To map StatusCodeUpdated events to IWayspotAnchors, either use the WayspotAnchorStatusUpdate.ID passed to the event handler, or create a class similar to WayspotAnchorTracker that gets associated with a IWayspotAnchor and adds its own StatusCodeUpdated event handler.

  4. Save the anchor payload.

    Each successfully created IWayspotAnchor will have a Payload, a binary blob that you should save to use when you want to restore previously created anchors, or to share the anchor with other users. The payload is created by VPS and is only available once the IWayspotAnchor.Status is Success or Limited. See Persisting and Sharing Wayspot Anchors for how to serialize and deserialize anchor payloads.

  5. Track anchor position updates.

    Once a Wayspot Anchor has been successfully created, subscribe to the anchor’s TransformUpdated event to get corrections from VPS for the anchor’s position and orientation as the user moves. See Handle Anchor Tracking Updates for how to do this.

Restoring a Wayspot Anchor

Use the following steps to restore a previously created Wayspot Anchor:

  1. Restore the anchor using the anchor payload.

    To restore a Wayspot Anchor created in a prior VPS session, use WayspotAnchorService.RestoreWayspotAnchors(). Provide a list of anchor payloads that contain all the information needed to restore the anchors relative to the VPS-activated Wayspot where they were placed.

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

    If you need to load previously persisted Wayspot Anchor payloads see Persisting and Sharing Wayspot Anchors for how to serialize and deserialize Wayspot Anchors.

    RestoreWayspotAnchors() returns an array of IWayspotAnchors similar to what CreateWayspotAnchors() returns.

  2. Create GameObjects associated with anchors.

    Create GameObjects in your scene for virtual objects associated with your anchors. See Creating a Wayspot Anchor for an example that instantiates a prefab and associates it with an anchor using WayspotAnchorTracker.

  3. Track the restore status for each anchor.

    Track the restored anchor status by registering a handler for each anchor’s IWayspotAnchor.StatusCodeUpdated event. If the status changes from Pending to Success, VPS successfully restored the anchor.

    If the status changes to Failed, the anchor could not be restored and you won’t be able to use the anchor for placing game objects or tracking anchor position changes. To map StatusCodeUpdated events to IWayspotAnchors, either use the WayspotAnchorStatusUpdate.ID passed to the event handler, or create a class similar to WayspotAnchorTracker that gets associated with a IWayspotAnchor and adds its own StatusCodeUpdated event handler.

  4. Track anchor position updates.

    Just like when creating new anchors, you’ll need to subscribe to the anchor’s TransformUpdated event to get corrections from VPS for the anchor’s position and orientation as the user moves. See Handle Anchor Tracking Updates for how to do this.

    Note

    Restored anchors may not be fully resolved when RestoreWayspotAnchors() returns. If you’re not using WayspotAnchorTracker you should listen for TransformUpdated events for an anchor before assuming the anchor has been correctly placed in the world.

Deleting a Wayspot Anchor

WayspotAnchorService manages a cache of Wayspot Anchors for you. If you no longer need to track one or more Wayspot Anchors, you can delete the Anchors from the cache using WayspotAnchorService.DestroyWayspotAnchors(), providing either a list of IWayspotAnchors or a list of anchor IDs.

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

Restarting a VPS Session

If your app needs to restart the VPS session from scratch, you can use WayspotAnchorService.Restart(). See “Understanding Localization Flow” in Localizing with VPS for examples of when you might need to restart VPS. Also, see “Restarting VPS” in Localizing with VPS for additional details on what happens when you restart a VPS session.