Getting Started with Lightship VPS

With the Lightship Visual Positioning System (VPS) developers now have the power to determine a user’s position and orientation with centimeter-level accuracy - in seconds. You can use Lightship VPS in your Unity project to create location-based AR experiences that connect the real world with the digital one. Virtual objects can be anchored to locations, enabling virtual objects to interact realistically with the space they are in. This makes the augmented reality experience feel more personal, more meaningful, more real, and gives users new reasons to explore the world around them.

The following sections will cover the prerequisites for using VPS, information on VPS features, and how to get started using VPS:

Lightship VPS Setup Prerequisites

To develop an AR experience that uses Lightship VPS, you’ll need a Unity project that you’ve set up with the Lightship ARDK, as described in Getting Started with ARDK.

Note

Lightship VPS uses the device camera and location service, so you will need to make sure your app has permissions to access those services. ARDK provides convenience classes for handing permission requests: see Permissions for more information.

Browse VPS-Activated Wayspots

Lightship VPS uses VPS-Activated Wayspots. VPS-Activated Wayspots are real-world locations that are unique or notable, and publicly accessible, that you can localize in your app using Lightship VPS.

Use the Geospatial Browser on lightship.dev to search and find VPS-Activated Wayspots across the globe. Select the Wayspots you want to use for your project and download the associated 3D mesh assets.

See the Geospatial Browser (Beta) topic to learn how to search Wayspots and download their meshes.

Use the Niantic Wayfarer App

The Niantic Wayferer app is the companion app for developers who are using Lightship VPS. Install the app to:

  • View VPS-Activated Wayspots

  • Create Private Scans for testing

  • Test localization with VPS-Activated Wayspots or Private Scans

  • Scan locations to create new VPS-Activated Wayspots

See Using the Niantic Wayfarer App for more information.

Create Private Scans for Testing VPS

For development and testing, you can create private VPS locations in your surrounding area to test with using the Niantic Wayfarer App. Scans of that location provide you a single mesh to use in development, restricted to your developer account, for testing VPS experiences. You do not need to be at the location to test a private scan, so you can even test at your desk. While private scans are a great solution for developing and testing VPS experiences while a public Wayspot is being nominated or activated, private scans are not authorized for use in published projects.

You can download private scans under the Private Scans tab in the Geospatial Browser, once the scan has been processed.

See Managing Private Scans for more information.

Create New VPS-Activated Wayspots

We are continually growing our global coverage of VPS-activated Wayspots, but you may have a specific location in mind that is not yet VPS-activated. If the location you’d like to use in your project is not available as a Wayspot, you can submit Wayspot locations to Niantic through the Create New Wayspot function in the Geospatial Browser.

For more information on Wayspot creation and requirements, see Creating New VPS-Activated Wayspots. See also Generating Scans for VPS for how to scan and submit information for a VPS-activated Wayspot or Private VPS location to Niantic.

Place Content with Wayspot Anchors

Use VPS Wayspot Anchors to place virtual objects that maintain a consistent, stable pose in an AR environment. Wayspot Anchors allow you to precisely locate your AR content in the real world relative to a VPS-activated Wayspot or Private VPS Location. To learn more about how the VPS Wayspot Anchor system works, see Using VPS Wayspot Anchors.

There are two main methods for setting up and managing anchors: using the VPS Authoring Assistant, and using the WayspotAnchor APIs. The VPS Authoring Assistant works quickly and can be done at any time. Using the WayspotAnchor APIs must be done at runtime in your app.

The VPS Authoring Assistant (Beta) provides Unity tooling for creating Wayspot Anchors and saving them to file or project, so that you can easily create experiences for VPS end-to-end, without needing to leave your home or office. See Authoring Wayspot Anchors in Unity for more information.

The WayspotAnchor APIs provide high and low level interfaces for working with Wayspot Anchors. See Using the VPS Coverage API for more information.

Build your VPS-based App

Once you have set up anchors and placed content, ARDK provides tooling for managing locations and Wayspot Anchor resolution at runtime, as well as for simulating your experience in Unity.

See the Building & Testing Apps with VPS documentation for more information.

Localize with VPS-activated Wayspots

Once your user is physically near a VPS-activated Wayspot, you can have them localize (determine their location) with that Wayspot. To localize with a VPS-activated Wayspot, your app needs to provide user location data and camera data of the user’s view of the VPS-activated Wayspot to Lightship VPS. Lightship VPS can then determine the user’s position and orientation relative to the VPS-activated Wayspot.

See Localizing with VPS for details on how to localize with VPS Activated Wayspots.

Discover Wayspots Programmitically with VPS Coverage API

If your app features the ability to discover VPS-activated Wayspots, or navigate to nearby VPS-activated Wayspots, you’ll need to use the VPS Coverage API. The VPS Coverage API lets your end users discover VPS coverage areas and understand how best to localize with VPS localization targets. Coverage areas describe the geographic region where a user can successfully localize using a localization target. Localization targets describe what the user should be aiming their device at when they want to localize with a VPS-activated Wayspot.

See Using the VPS Coverage API for more information.

Create and Set User IDs For Your App Users

Use of features such as VPS localization, the VPS Wayspot Anchors API, and the VPS Coverage API involves the collection of personal information from your end user. For more information, see the Lightship ARDK Data Privacy FAQ.

API requests for the VPS Coverage API and the VPS Wayspot Anchors API use a User ID to uniquely identify individual users of your app. You’ll need to generate this User ID and set it in the current ARDK configuration whenever the user of your app changes. If you can’t provide a User ID, VPS will use a Client ID. See Using ARDK User IDs for more information on User IDs and Client IDs.