Geolocate with VPS2

Use VPS2 geolocation data to read the device's current geographic position and heading or an anchor's fixed geographic position and orientation. This guide explains which source to use, how to evaluate device geolocation accuracy, and how to read anchor orientation correctly on each platform.

Prerequisites

This guide assumes that you have already completed:

• Get started with VPS2

Device geolocation

Retrieve the device's current geographic coordinates independently of any anchor. The heading mode parameter controls how heading is computed:

• Camera Direction: Heading from the camera's forward axis. Best when the device is held upright in portrait or landscape orientation.
• Device Top: Heading from the top edge of the screen. Best when the device is face-up or for compass-style widgets.

if (vps2Manager.TryGetDeviceGeolocation(out var geolocation, HeadingMode.CameraDirection) &&
    geolocation.TrackingState != Vps2TrackingState.Unavailable) {
    var latitude = geolocation.Geolocation.Latitude;
    var longitude = geolocation.Geolocation.Longitude;
    var altitude = geolocation.Geolocation.Altitude;
    var heading = geolocation.Geolocation.Heading;
    var horizontalAccuracy = geolocation.HorizontalAccuracy;
    var verticalAccuracy = geolocation.VerticalAccuracy;
    var headingAccuracy = geolocation.HeadingAccuracy;
}

Accuracy

The geolocation object contains a VPS2 tracking state that can be unavailable, coarse, or precise. These are broad categories describing the quality of VPS2's georeference estimate. Applications should rely on reported accuracy values rather than assuming centimeter-level global alignment.

Each estimate also includes accuracy values that represent margin-of-error estimates. Accuracy may vary across conversions performed with the same localization when using different input poses or locations.

• Horizontal accuracy (meters)
• Vertical accuracy (meters)
• Heading / rotation accuracy (degrees)

Anchor geolocation

VPS2 anchor updates include geolocation data when it is available. Reading geolocation data directly from anchor updates is the most direct way to position anchors on a map.

Anchor geolocation becomes available after a brief initialization period when the anchor tracking state is limited or tracked. Once available, the anchor's geographic coordinates and orientation remain fixed. The anchor's pose in local AR space can still change as coarse localization improves or the device localizes to the VPS map.

The guide for placing virtual content with VPS2 provides detailed steps for using VPS2 anchors. The following examples focus on the APIs for getting geolocation.

Anchor and device geolocations expose orientation differently, even though both include a heading field. The following table identifies the orientation field to use for each geolocation source and explains what happens if an application reads the wrong field.

Read anchor orientation from the East-Down-North (EDN) quaternion, not the heading value

Using an anchor's heading to rotate a map or other content leaves that content unrotated. This limitation does not apply to device geolocation.

Geolocation source	Orientation field to use	Behavior
Anchor	EDN orientation quaternion	The heading field on an anchor's geolocation is never filled in and always reads 0, even when the anchor's orientation is known. Use the anchor's EDN orientation quaternion instead, and work out a heading from it if you need one. If you rotate a map or other content using an anchor's heading, that content will not be rotated at all.
Device	heading	This limitation applies only to anchor geolocations. The device geolocation heading works normally, because it is calculated from the heading mode you request.

Each frame, read the anchor's geolocation when the anchor tracking state is limited or tracked:

if (anchor.trackingState != TrackingState.None) {
    var geo = anchor.geolocation;
    if (geo.HasValue) {
        // Position: Latitude, Longitude, Altitude
        var latitude = geo.Value.Latitude;
        var longitude = geo.Value.Longitude;
        var altitude = geo.Value.Altitude;

        // Orientation: use OrientationEdn, NOT geo.Value.Heading (see previous warning)
        var forwardEdn = geo.Value.OrientationEdn * Vector3.forward;
        var headingDegrees = Mathf.Atan2(forwardEdn.x, forwardEdn.z) * Mathf.Rad2Deg;
        headingDegrees = (headingDegrees % 360f + 360f) % 360f;
    }
}

Accuracy

The accuracy of an anchor's geolocation depends on multiple factors, including the quality of GPS readings when the map was created and the algorithm used to align the map. Manually adjusting the map with the Georeference tool in Scaniverse Web can improve its global alignment. See Geo-alignment and accuracy for factors that affect anchor geolocation accuracy.