# Getting Started with VPS

Source: https://www.nianticspatial.com/docs/nsdk/how-to/vps/adding_vps/

### Platform: unity

When using Unity, the Niantic Spatial Development Kit (NSDK)s package provides a configurable component to help you create and manage your VPS enabled AR experience.

## The AR Location Manager

The AR Location Manager allows you to easily persist content at Public Locations.

(image: AR Location Manager Component)

- **Default Anchor GameObject:** This will take a gameObject prefab and instantiate it at the ARLocation's default anchor position once localized as an easy way to visualize the process.
- **VPS Usage Mode:** Preset configurations for the VPS Manager.

Drift Mitigation Options:

- **Continuous Localization:** Continue to send localization requests after localization. This mitigates drift but consumes more bandwidth. If enabled then you can also use:
  - **Interpolation Enabled:** Interpolates anchors positions instead of snapping them in place.
  - **Temporal Fusion Enabled:** Average/fused multiple localization results to provide a more stable localization.

Performance:

- **JPEG compression Quality:** (Default: 50) 0-100 value, determines the quality of the JPEG image sent to the servers for cloud localization. The lower quality can save more network bandwidth usage. We have benchmarked that 50-90 quality for jpeg compression does not significantly impact the accuracy of the localization results.
- **Initial Service Request Interval Seconds:** Number of seconds between server requests.
- **GPS Correction for Continuous Localization:**
  If checked, VPS localization will use estimated GPS location from previously localized information instead of device GPS read. Intended for large and poor GPS area localization.

Debugging Options:

- **Diagnostics Enabled:** If checked, VPS localization will run image classification which outputs the probability of each "failure cause" category, for example: image too dark, moving too fast or looking at ground. This feature is GPU intensive and Android devices often struggle and slow down rendering performance.
- **VPS Debugger Enabled:** If checked, NSDK will create a log file with detailed events related to VPS localization. This can be helpful to investigate issues in VPS localization.

VPS Startup Behavior:

- **Auto Track:** If checked, the location manager will automatically try to localize to the AR Location selected.
- **AR Location:** AR Locations available in the scene.
- **Add AR Location:** This will create an AR Location GameObject in the hierarchy which will then show up on the AR Location list. Note that this will not be valid until you assign a location manifest or Payload to it.

## AR Location

The AR Location game object is a representation of a real-life location.
In the hierarchy the game object holding this component must be a child of XR Origin, and child objects of the AR Location will be connected to the location and appear relative to it when localization succeeds.

(image: AR Location Component)

- **Include Mesh in Build:** if enabled and an AR Location Manifest is assigned, you'll be able to see the mesh of the location on Editor.
- **AR Location Manifest:** allows you to assign a location mesh (available on the GeoSpatial Browser).
- **Payload:** string blob representing the location.

> **Warning:**
>
> **Legacy Geospatial Browser workflow**
>
> The Geospatial Browser is no longer available. These instructions are retained for developers
> maintaining older `ARLocation` projects. For current projects, manage Sites in
> [Scaniverse Web](https://scaniverse.nianticspatial.com/) and use [VPS2](https://www.nianticspatial.com/docs/nsdk/how-to/vps2/adding_vps2/).

### Platform: swift

This guide assumes that you've already gone through:

- Importing the NSDK for Swift.
- How to set up a basic AR session guide.

# Adding VPS to your projects

The `NsdkVpsSession` provides capabilities for precise localization using visual features. VPS can determine device position and orientation relative to a pre-mapped environment, enabling persistent AR experiences that maintain accuracy across sessions and devices.

### Setting Up and Configuring VpsSession

The `NsdkVpsSession` manages the VPS feature lifecycle -- configuration, activation, and retrieval of the latest anchors data.
It is created from an existing `NsdkSession` instance and works independently of other AR features.

```swift
let vpsSession = nsdkSession.createVpsSession()

let config = NsdkVpsSession.Configuration(
    continuousLocalizationEnabled: true,
    temporalFusionEnabled: true,
    gpsCorrectionForContinuousLocalization: true
)

do {
    try vpsSession.configure(with: config)
} catch {
    print("Configuration failed: \(error)")
}
```

The available config settings:

- **Continuous Localization:** (Default: off) Continue to send localization requests after localization. This mitigates drift but consumes more bandwidth. If enabled then you can also use:
  - **Interpolation Enabled:** (Default: off) Interpolates anchors positions instead of snapping them in place.
  - **Temporal Fusion Enabled:** (Default: off) Average/fused multiple localization results to provide a more stable localization.
  - **Cloud Localizer Continuous Requests per Second:** (Default: 0.2) Number of seconds between server requests after the first successful localization. The default of 0.2 translates to one request every 5 seconds.

- **JPEG compression Quality:** (Default: 70) 0-100 value, determines the quality of the JPEG image sent to the servers for cloud localization. We have benchmarked that 50-90 quality for jpeg compression does not significantly impact the accuracy of the localization results.

- **Cloud Localizer Initial Requests per Second:** (Default: 1.0) Number of seconds between server requests, prior to the first successful localization.

- **GPS Correction for Continuous Localization:** (Default: off) If checked, VPS localization will use estimated GPS location from previously localized information instead of device GPS read. Intended for large and poor GPS area localization.

- **Device Map Localization Enabled:** (Default: off) Whether to enable localization for locally-created Device Maps.

### Starting and Stopping Vps

Start the VPS session to begin collecting sensor data needed for localization:

```swift
vpsSession.start()
```

Once started, VPS begins collecting local device sensor data. Refer to the [How to Use Location AR with Code](https://www.nianticspatial.com/docs/nsdk/how-to/vps/location_ar_code/) guide to learn how to localize against maps.

To stop the VPS session, simply call:

```swift
vpsSession.stop()
```

After stopping, you can reconfigure and restart the session. All anchor tracking will be paused when stopped.

> **Caution:**
>
> **Attention!**
>
> Be sure to stop the `VpsSession` before calling start again!

### Platform: kotlin

This guide assumes that you've already gone through:

- Importing the NSDK for Kotlin.
- Gone through our How To set up a basic AR session guide.

# Adding VPS to your projects

The `VPSSession` provides capabilities for precise localization using visual features. VPS can determine device position and orientation relative to a pre-mapped environment, enabling persistent AR experiences that maintain accuracy across sessions and devices.

### Setting Up and Configuring VPSSession

The `VPSSession` manages the VPS feature lifecycle -- configuration, activation, and tracking of anchors.
It is created from an existing `NSDKSession` instance and works independently of other AR features.

```kotlin
val nsdkSession = NSDKSession(accessToken = "YOUR_ACCESS_TOKEN", refreshToken = "YOUR_REFRESH_TOKEN")
val vpsSession = nsdkSession.vps.acquire()

// Example config, see documentation for all possible config options
val config = VPSConfig(
    enableContinuousLocalization = true,
    enableTemporalFusion = true,
    enableGpsCorrectionForContinuousLocalization = true,
)

try {
    vpsSession.configure(config)
} catch (e: NsdkStatusException) {
    Log.e("VPS", "Configuration failed: ${e.message}")
}
```

The available config settings:

- **Continuous Localization:** (Default: off) Continue to send localization requests after localization. This mitigates drift but consumes more bandwidth. If enabled then you can also use:
  - **Interpolation Enabled:** (Default: off) Interpolates anchors positions instead of snapping them in place.
  - **Temporal Fusion Enabled:** (Default: off) Average/fused multiple localization results to provide a more stable localization.
  - **Cloud Localizer Continuous Requests per Second:** (Default: 0.2) Number of seconds between server requests after the first successful localization. The default of 0.2 translates to one request every 5 seconds.

- **JPEG compression Quality:** (Default: 70) 0-100 value, determines the quality of the JPEG image sent to the servers for cloud localization. We have benchmarked that 50-90 quality for jpeg compression does not significantly impact the accuracy of the localization results.

- **Cloud Localizer Initial Requests per Second:** (Default: 1.0) Number of seconds between server requests, prior to the first successful localization.

- **GPS Correction for Continuous Localization:** (Default: off) If checked, VPS localization will use estimated GPS location from previously localized information instead of device GPS read. Intended for large and poor GPS area localization.

- **VPS Debugger Enabled:** (Default: off) If enabled, NSDK will create a log file with detailed events related to VPS localization. This can be helpful to investigate issues in VPS localization.

- **Device Map Localization Enabled:** (Default: off) Whether to enable localization for locally-created Device Maps.

### Starting VPS

Start the VPS session to begin collecting sensor data needed for localization:

```kotlin
vpsSession.start()
```

Once started, VPS begins collecting local device sensor data. Refer to the [How to Use Location AR with Code](https://www.nianticspatial.com/docs/nsdk/how-to/vps/location_ar_code/) guide to learn how to localize against maps.

### Stopping VPS

Stop the VPS session:

```kotlin
vpsSession.stop()
```

After stopping, you can reconfigure and restart the session. All anchor tracking will be paused when stopped.

> **Caution:**
>
> **Attention!**
>
> Be sure to stop the `VpsSession` before calling start again!