# Get started with VPS2 Source: https://www.nianticspatial.com/docs/nsdk/how-to/vps2/adding_vps2/?platform=kotlin 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](https://www.nianticspatial.com/docs/nsdk/features/vps2/). ## Prerequisites This guide assumes that you have already completed: - [Set up the NSDK in Kotlin](https://www.nianticspatial.com/docs/nsdk/setup/#set-up-the-nsdk-in-kotlin) * [Authorization](https://www.nianticspatial.com/docs/nsdk/auth_getting_started/) If you are upgrading an existing ARDK 3.x application, see [Migrate from VPS to VPS2](https://www.nianticspatial.com/docs/nsdk/features/vps2_migration/). ## Construct and Configure VPS2 [`Vps2Session`](https://www.nianticspatial.com/docs/api/kotlin/com.nianticspatial.nsdk.vps2.Vps2Session) manages the VPS2 lifecycle: configuration, activation, and retrieval of geographic positioning data. It is created from an existing [`NSDKSession`](https://www.nianticspatial.com/docs/api/kotlin/com.nianticspatial.nsdk.NSDKSession) and operates independently of other AR features. ```kotlin import com.nianticspatial.nsdk.Vps2Config val vps2Session = nsdkSession.vps2.acquire() // Example config, see documentation for all possible config options val config = Vps2Config( enableUniversalLocalization = true, enableVpsMapLocalization = true, ) try { vps2Session.configure(config) } catch (e: NsdkStatusException) { Log.e("VPS", "Configuration failed: ${e.message}") } ``` > **Note:** > > **`configure()` is optional** > > If you don't call `configure()`, VPS2 runs with the defaults in the following table, including VPS map localization on and universal localization off. Call it only to change those defaults. #### Configuration Fields | Field | Default | What it controls | |---|---:|---| | **Universal Localization Enabled** | Disabled | When active, the VPS2 session sends camera imagery and the device's GPS position to the cloud for geopositioning, without needing a VPS map. This can improve geoposition accuracy beyond local sensor fusion but requires a network connection. If disabled, the device's geoposition away from VPS maps comes from local sensor fusion alone, which always runs. Either way, the VPS2 tracking state reaches at most `coarse` until it localizes to a VPS map. | | **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. This only allows VPS map localization: no requests are sent until you call `localize` (Unity: `TryLocalize`) for a Site or a nearby coordinate. | | **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. | | **Temporal Fusion Enabled** | Enabled | Fuses successive VPS map localizations against the same map into one estimate, instead of using only the newest. Localizations that agree raise the asset's tracking confidence and steady its pose, at the cost of reacting more slowly to a genuine pose change. Unrelated to local sensor fusion of GPS and compass. | | **Geolocation Smoothing Enabled** | 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](https://www.nianticspatial.com/docs/nsdk/how-to/vps2/guide_users_during_localization/#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. Local sensor fusion is not configurable and runs in both cases. ## Start VPS2 > **Caution:** > > **Configure before starting** > > If you call `configure()`, call it before VPS2 starts -- that is, before `start()` or before the first `localize(...)` call, whichever comes first, because `localize(...)` starts the session too. To change configuration after starting, `stop()` the session, reconfigure, then `start()` again. > **Note:** > > **`start()` is optional** > > `localize(siteId)` and `localize(latitude, longitude, radiusMeters)` start the session themselves, so a flow that localizes to a Site does not have to call `start()` first. Call `start()` explicitly to begin collecting sensor data -- and to run universal localization, if it is enabled -- before you know which Site to localize to, or to resume after `stop()`. Calling `start()` while the session is already running has no effect. > > Tracking an anchor payload does **not** start the session. If your app only calls `trackAnchor(payload)`, e.g. when using a device map, call `start()` first. Start the session to begin collecting sensor data: ```kotlin vps2Session.start() ``` Calling [`start()`](https://www.nianticspatial.com/docs/api/kotlin/com.nianticspatial.nsdk.vps2.Vps2Session.start) begins local sensor fusion, which provides the device's approximate global position and heading typically within a few seconds of calling `NSDKSession.update()`, and starts universal localization if it is enabled. VPS map localization does not start automatically; request it with one of the `localize` calls below, each of which starts the session if it is not already running. - To localize to a specific Site, call [`localize(siteId)`](https://www.nianticspatial.com/docs/api/kotlin/com.nianticspatial.nsdk.vps2.Vps2Session.localize) with its Site ID. Get a Site ID by [querying Sites](https://www.nianticspatial.com/docs/nsdk/how-to/sites/getting_started/#3-query-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 [`localize(latitude, longitude, radiusMeters)`](https://www.nianticspatial.com/docs/api/kotlin/com.nianticspatial.nsdk.vps2.Vps2Session.localize) 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: calling `localize` again does not disturb a request already in flight, and the Sites accumulate. To check whether the Site has localized, call [`getAssetTrackingData()`](https://www.nianticspatial.com/docs/api/kotlin/com.nianticspatial.nsdk.vps2.Vps2Session.getAssetTrackingData) with the Site's asset ID, which you can get from the [Sites API](https://www.nianticspatial.com/docs/nsdk/how-to/sites/getting_started/) or from the localized asset in the latest localization; it returns data while that asset is tracked. Without an asset ID, it reports the asset the device most recently localized to, which may belong to a different Site when you localize to several. Do not use the session's [`Vps2TrackingState`](https://www.nianticspatial.com/docs/api/kotlin/com.nianticspatial.nsdk.vps2.Vps2TrackingState) for that check: it describes the device's geoposition, not whether the asset is tracked. For the difference between those two states, see [Tracking states](https://www.nianticspatial.com/docs/nsdk/features/vps2/#tracking-states). ### Restarting a session To restart VPS2 within a running app, reuse the session you already acquired: ```kotlin vps2Session.stop() vps2Session.configure(newConfig) vps2Session.start() ``` Acquire the VPS2 session **once** and keep it for the lifetime of the app. Releasing it and acquiring a new one is not a supported restart path, and a session rebuilt that way can end up tracking anchors without ever attaching geolocations -- anchor tracking appears to work while the map frame never becomes available. ### Verifying that configuration succeeded `configure()` validates its arguments synchronously, but configuration can still fail **after** it returns -- most commonly because the session was not stopped first. A successful return therefore does not prove the feature is running. Use `featureStatus()` as the authoritative readiness check shortly after starting: ```kotlin vps2Session.configure(config) vps2Session.start() // Poll featureStatus() after start; a fault here means the feature is not running, // even though configure() returned without throwing. val status = vps2Session.featureStatus() ``` Without this check, a failed configuration is easy to miss and can lead to unexpected behavior. ### How updates are delivered VPS2's `Flow` properties are **not** driven by your frame loop. Each one polls in the background on its own schedule, and only while something is collecting it: | Flow | Poll interval | |---|---| | `localizationUpdates` | ~30 Hz | | `localizationRequestRecords` | ~30 Hz | | `debuggerEvents` | ~30 Hz | Design around these delivery behaviors: | Behavior | Application guidance | |---|---| | **Localization updates describe the current VPS2 result, not a particular camera frame.** | Read the localized asset ID from the latest localization, then query that asset's tracking data when rendering map-relative content. | | **Updates are not tied to a particular frame.** | An update does not necessarily match the AR frame currently on screen, so do not try to pair it with frame-specific state based on timing. Use the data inside the update instead. | | **Updates arrive on a background thread.** | Switch to the main dispatcher before updating UI, as shown in the following example. | ```kotlin vps2Session.localizationUpdates .flowOn(Dispatchers.Default) .onEach { update -> /* ... */ } .flowOn(Dispatchers.Main) .launchIn(lifecycleScope) ``` These intervals are fixed by the SDK and cannot be changed through `Vps2Config`. ## Get Updates VPS2 only advances when your app calls [`NSDKSession.update()`](https://www.nianticspatial.com/docs/api/kotlin/com.nianticspatial.nsdk.NSDKSession.update), which pulls sensor samples from the data source and submits a frame for native processing. Call it once per ARCore session update (see [Update the session](https://www.nianticspatial.com/docs/nsdk/setup/#update-the-session)). ## Stop VPS2 To stop the VPS2 session, simply call: ```kotlin vps2Session.stop() ``` After stopping, you may reconfigure and restart the session. All localization and anchor state is reset when stopped. Calling `stop()` while the session is already stopped has no effect. ## Next Steps | Goal | Guide | | --- | --- | | Complete an end-to-end Site localization | [First localization with NSDK](https://www.nianticspatial.com/docs/nsdk/first_localization/) | | Retrieve global position, heading, and accuracy | [Geolocate with VPS2](https://www.nianticspatial.com/docs/nsdk/how-to/vps2/getting_vps2_geoposition/) | | Localize to a Site and attach AR content | [Place virtual content with VPS2](https://www.nianticspatial.com/docs/nsdk/how-to/vps2/placing_virtual_content/) | | Retrieve Sites and assets at runtime | [Getting Started with Sites](https://www.nianticspatial.com/docs/nsdk/how-to/sites/getting_started/) | | Guide users to a successful localization | [Guide users during localization](https://www.nianticspatial.com/docs/nsdk/how-to/vps2/guide_users_during_localization/) | | Explore complete implementations | [NSDK sample projects](https://www.nianticspatial.com/docs/nsdk/sample_projects/) |