Get started with VPS2
This guide shows how to add VPS2 to your project, configure its localization options, and manage its lifecycle. For an explanation of universal and VPS map localization, assets, and tracking states, see Visual Positioning System 2.
Prerequisites
This guide assumes that you have already completed:
If you are upgrading an existing ARDK 3.x application, see Migrate from VPS to VPS2.
Add and configure VPS2
The Niantic Spatial Unity SDK (NSDK) uses AR Foundation as the interface for exposing its features. Adding VPS2 is therefore similar to adding other AR Foundation components.
ARVps2Manager
ARVps2Manager is the entry point to VPS2: configuration, localization, geolocation, anchors, and asset tracking. It owns the VPS2 feature's lifecycle. Tracked assets and anchors are served as trackables by the ARVps2AssetManager and ARVps2AnchorManager components it requires next to it; Unity adds both automatically when you add ARVps2Manager to a GameObject.
The manager can also convert between local AR poses and global geopositions (and vice versa).
Configuration Fields
| Field | Default | What it controls |
|---|---|---|
| Universal Localization Enabled | Disabled | When active, the VPS2 session sends AR sensor data and camera imagery to the server to localize against global-scale maps. This method can improve geoposition accuracy beyond local sensor fusion but requires a network connection. If disabled, the system relies exclusively on local sensor fusion. |
| Universal Localization Requests per Second | 1 | Frequency of network requests sent for universal localization. |
| VPS Map Localization Enabled | Enabled | When active, the VPS2 session sends AR sensor data and camera imagery to the server to localize against VPS maps. |
| Initial Requests per Second | 1.0 | Server request frequency prior to the first successful VPS map localization. For example, 1.0 is one request per second. |
| Continuous Requests per Second | 0.2 | Server request frequency after the initial VPS map localization. For example, 0.2 is one request every five seconds. |
| Geolocation Smoothing Enabled | — | Enables interpolation between localization updates. This minimizes “snapping” or visual jumps during abrupt GPS or compass recalibrations, for a more stable AR experience. |
| Blur Detection Enabled | Disabled | Enables an advisory image blur check on the frames VPS2 sends for VPS map localization. A frame whose sharpness score falls below the threshold produces a FrameFlagged localization request record with error ImageTooBlurry, but is still sent for localization, never rejected. Use the signal to coach the user, for example "hold the device steady". See Prompt users through blurry frames. |
| Min Sharpness Score | 0 | Sharpness threshold below which a frame is flagged as too blurry. The default of 0 flags nothing. Higher scores mean sharper images. There is no universal "sharp" value; 1000 is a good starting point and is the value the VPS2 samples use. |
Universal and VPS map localization are configured independently. VPS map localization is enabled by default; universal localization is disabled by default, so turn it on explicitly if you want cloud geopositioning.
ARVps2Manager enables VPS Map Localization but not Universal Localization, so a scene that uses the component runs VPS map localization only. Tick Universal Localization Enabled on the inspector component to run both together.
Start and stop VPS2
VPS2 starts and stops according to the Unity component lifecycle. When started, universal localization, if enabled, begins collecting the sensor data required for localization, and coarse positioning estimates are typically available within a few seconds after the AR session begins running. VPS map localization does not start until you call TryLocalize:
- To localize to a specific Site, call
TryLocalize(siteId)with its Site ID. Get a Site ID by querying Sites, or by navigating to the Site in the Scaniverse portal and copying its ID from the URL. - To localize to all nearby Sites, call
TryLocalize(latitude, longitude, radiusMeters)with a coordinate and radius.
A Site must have a processed VPS map tagged for production to be eligible for map-relative localization. Localize requests are additive, and the submitted Sites stay in the localization set until the manager stops. TryLocalize returns false until the manager has been enabled for the first time. After that, you can call it while the manager is disabled; the request is submitted when the manager is enabled again.
To check whether the Site has localized, call TryGetAssetTrackingData; it returns data once the Site's asset is localized and tracked. Do not use the session's Vps2TrackingState for that check. For the difference between those two states, see Tracking states.
When stopped, all localization and anchor state is reset.
Configuration changes to ARVps2Manager are applied only when the component starts and cannot be modified while it is running. The blur detection fields are the exception: they are applied live while the component is running.
To restart VPS2 with a different configuration, disable the ARVps2Manager component, change the configuration, then re-enable it. Because configuration is read at start, changing a field on a running manager has no effect until the next start.
Next Steps
| Goal | Guide |
|---|---|
| Complete an end-to-end Site localization | First localization with NSDK |
| Retrieve global position, heading, and accuracy | Geolocate with VPS2 |
| Localize to a Site and attach AR content | Place virtual content with VPS2 |
| Retrieve Sites and assets at runtime | Getting Started with Sites |
| Guide users to a successful localization | Guide users during localization |
| Explore complete implementations | NSDK sample projects |