# Location Drift Mitigation

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

### Platform: unity

# Location Drift Mitigation

The `ARLocationManager` class provides experimental features for drift mitigation.

To access these features:

1. Open the **Player Settings** menu:
   1. In the **File** top menu, choose **Build Settings**.
   2. Click the button labeled **Player Settings** in the bottom-left corner of the **Build Settings** window.
2. Add the experimental feature flag:
   1. Scroll down to **Script Compilation** in the **Player Settings** menu.
   2. Under **Scripting Define Symbols**, click the **+ button** to add another line, then add `NIANTICSPATIAL_NSDK_EXPERIMENTAL_FEATURES` to enable them.

## Feature Overview

The experimental drift mitigation features are:

- **Temporal Fusion**
  - By default, averages the last five good localization results to provide a more stable localization. Continuous Localization must be enabled for Temporal Fusion to work.
- **TransformUpdateSmoothingEnabled:**
  - Smoothens anchor updates for cleaner transforms. Continuous Localization must be enabled for update smoothing.
- **InitialServiceRequestIntervalSeconds:**
  - Defines the time between network requests when initially attempting tracking. Longer intervals between requests will reduce network bandwidth consumption, but may take longer to gain tracking. By default, this is set to one request per second.
- **ContinuousServiceRequestIntervalSeconds:**
  - Defines the time between network requests when continuously localizing. Continuous Localization must be enabled to use this feature. Longer intervals between requests will reduce network bandwidth consumption, but may take longer to refine tracking. By default, this is set to one request every five seconds.
- **CloudLocalizationTemporalFusionWindowSize:**
  - Defines the number of anchor update entries that are considered in temporal fusion. By default, this is set to five entries, so it will fuse 25 seconds of entries (five entries multiplied by the default five seconds per localization). It is recommended to set this to a value that will fuse 5 to 25 seconds worth of localizations. Larger window sizes will cause refining to happen more slowly, but be more stable. Requires **Continuous Localization** and **Temporal Fusion** enabled.
- **DiagnosticsEnabled:**
  - Enabling diagnostics will enable an additional `frameDiagnosticsArray` entry in the **XRPersistentAnchorSubsystem's** `debugInfoProvided` event. These diagnostics provide guidance for the localizability of the user's camera feed (too dark, blurry, etc). This feature runs a neural network under the hood, so it is rather expensive.

### Platform: swift

# Location Drift Mitigation

`NsdkVpsSession.Configuration` allows you to customize VPS (Visual Positioning System) behavior including localization frequency, quality settings, and advanced features like temporal fusion. Use this class to optimize VPS performance for your specific use case.

## Important Notes

1. **Configuration Timing**: Configuration must be applied when the VPS session isn't running.

2. **System Defaults**: Setting numeric values to `0` uses system defaults, which are optimized for most use cases. Only override these if you have specific requirements.

3. **Feature Dependencies**: Some options work best together:
   - `temporalFusionEnabled` is most effective with `continuousLocalizationEnabled`
   - `interpolationEnabled` works best with `temporalFusionEnabled`
   - `gpsCorrectionForContinuousLocalization` requires `continuousLocalizationEnabled`

4. **Performance Trade-offs**: Higher request rates and compression quality improve accuracy but increase bandwidth usage and API quota consumption.

5. **GPS Requirements**: When `gpsCorrectionForContinuousLocalization` is `true`, ensure GPS location data is included in frames sent to NSDK.

## Configuration Properties

- `continuousLocalizationEnabled` Enables continuous localization updates after initial anchor tracking. When enabled, VPS will continue to refine the device's position even after an anchor has been successfully localized.

- `temporalFusionEnabled` Enables temporal fusion to smooth localization results over time. This provides more stable and accurate tracking by fusing results across multiple frames.

- `interpolationEnabled` Enables interpolation between localization updates. This provides smoother motion between discrete localization results.

- `gpsCorrectionForContinuousLocalization` Enables GPS correction for continuous localization. This is required when using `devicePoseAsGeolocation()` to convert VPS poses to GPS coordinates. ***Note:** When set to `true`, ensure GPS location data is included in frames sent to NSDK*

- `deviceMapLocalizationEnabled` Enables device-side map localization. This allows localization using maps stored on the device rather than requiring cloud connectivity.

- `cloudLocalizerInitialRequestsPerSecond` Controls the rate of cloud localization requests during the initial tracking phase (when first localizing an anchor). Higher values provide faster initial localization but consume more bandwidth and API quota.

- `cloudLocalizerContinuousRequestsPerSecond` Controls the rate of cloud localization requests during continuous tracking (after initial localization). Lower values are typically used to maintain localization while reducing bandwidth.

- `cloudTemporalFusionWindowSize` Size of the temporal fusion window in number of frames. This determines how many previous localization results are used when fusing results over time.

- `jpegCompressionQuality` JPEG compression quality for images sent to the cloud for localization. Higher values provide better image quality but larger file sizes and more bandwidth usage.

## Complete Configuration Example

Here's an example with all configuration options set to recommended values:

```swift
var config = NsdkVpsSession.Configuration(
    continuousLocalizationEnabled: true,
    temporalFusionEnabled: true,
    interpolationEnabled: true,
    cloudLocalizerInitialRequestsPerSecond: 2.0,
    cloudLocalizerContinuousRequestsPerSecond: 0.5,
    cloudTemporalFusionWindowSize: 5,
    jpegCompressionQuality: 85,
    gpsCorrectionForContinuousLocalization: true,
    deviceMapLocalizationEnabled: false
)

do {
    try vpsSession.configure(with: config)
    vpsSession.start()
} catch {
    print("Failed to configure VPS: \(error)")
}
```

### Platform: kotlin

# Location Drift Mitigation

The `VPSConfig` class allows you to customize VPS (Visual Positioning System) behavior including localization frequency, quality settings, and advanced features like temporal fusion. Use this class to optimize VPS performance for your specific use case.

## Parameter Dependencies

Some parameters have dependencies on others:

1. **`cloudContinuousRequestsPerSecond`, `enableTemporalFusion` and `enableInterpolation`** require `enableContinuousLocalization`
2. **`enableDeviceMapLocalization`** requires a local map to be created via the mapping feature

## Configuration Parameters

- `enableContinuousLocalization` Enables continuous localization to mitigate AR tracking drift. When enabled, VPS will periodically send localization requests even after the first successful localization. This helps correct accumulated tracking drift but increases bandwidth usage.

- `cloudInitialRequestsPerSecond` Number of localization requests per second before first successful localization. Controls how frequently VPS attempts initial localization. Higher values provide faster initial localization but use more bandwidth.

- `cloudContinuousRequestsPerSecond` Number of localization requests per second after successful localization. Controls continuous localization frequency when `enableContinuousLocalization` is enabled. Lower values reduce bandwidth while still providing drift correction.

- `enableTemporalFusion` Enables temporal fusion for more stable localization results. Temporal fusion combines multiple localization results over time to provide smoother, more stable positioning. This reduces jitter but requires continuous localization to be enabled.

- `enableInterpolation` Enables smooth interpolation of anchor position updates. When enabled, anchor transforms are interpolated rather than snapped to new positions, providing smoother visual transitions when positions are refined.

- `jpegCompressionQuality` JPEG compression quality for images sent to VPS server. Controls the quality-bandwidth tradeoff for localization images. Higher values improve localization success rate but increase bandwidth usage.

- `enableDeviceMapLocalization` Enables localization against device-created maps. When enabled, VPS will attempt to localize against maps created locally by the mapping feature in addition to Niantic Spatial's cloud maps. This enables localization in areas without cloud VPS coverage. ***Note:** A local map must be created using `DeviceMappingSession.createMapping` and The device must have access to the local map data*

- `enableVPSDebugger` Enable VPS Debugger. When enabled, more detailed internal VPS related events are logged into a file as well as accessible through the getter API.

- `enableGpsCorrectionForContinuousLocalization` Enable GPS correction for continuous localization. When enabled, allows the cloud localizer to use available VPS information to refine future VPS localizations. This improves localization rates on large maps (>20 nodes).

## Complete Configuration Example

Here's an example with configuration options set for High-Performance:

```kotlin
val highPerfConfig = VPSConfig(
    enableContinuousLocalization = true,
    cloudInitialRequestsPerSecond = 2.0f,
    cloudContinuousRequestsPerSecond = 0.5f,
    enableTemporalFusion = true,
    enableInterpolation = true,
    jpegCompressionQuality = 90,
    enableGpsCorrectionForContinuousLocalization = true
)
```