Skip to main content

Geolocate with VPS2

Use VPS2 device geolocation to read the device's current geographic position and heading. For map-relative AR placement, localize to a Site or nearby coordinate and use the localized asset's tracking data, which gives the pose of the asset's origin in AR space (and, for georeferenced assets, the geolocation of that origin).

Prerequisites​

This guide assumes that you have already completed:

Get a precise geolocation​

Starting VPS2 on its own gives only a coarse geolocation, from local sensor fusion and, if enabled, universal localization. VPS2 never localizes to a VPS map by itself: VPS Map Localization Enabled only allows VPS map requests. For a precise, more accurate geolocation, also localize to nearby Sites with the device's current position, or to a specific Site by its ID:

if (vps2Manager.TryGetDeviceGeolocation(out var geolocation, HeadingMode.CameraDirection) &&
    geolocation.TrackingState != Vps2TrackingState.Unavailable) {
    // Localize to every Site within the default radius (100 m) of the device.
    vps2Manager.TryLocalize(geolocation.Geolocation.Latitude, geolocation.Geolocation.Longitude);
}

Once the device localizes to a Site's VPS map, the VPS2 tracking state becomes precise and the same geolocation calls return the improved position. Away from mapped Sites, the geolocation stays coarse. See Tracking state below, and Get started with VPS2 for both localize calls.

Device geolocation​

Retrieve the device's current geographic coordinates independently of any localized asset. 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;
}

Tracking state​

VPS2 reports the VPS2 tracking state — a broad quality category for how well the device knows where it is in the world — with three values:

  • unavailable — VPS2 has no usable geoposition, either not yet or no longer, for example after losing GPS with no VPS map correction. The code above handles this case: TryGetDeviceGeolocation reports it as Vps2TrackingState.Unavailable.
  • coarse — An approximate global geoposition from local sensor fusion of GPS, AR tracking, and the compass when available, improved by universal localization when it is enabled. Good for large-scale alignment, but not for precise placement. This is the highest state available away from mapped Sites.
  • precise — A high-accuracy geoposition, reached only after localizing to a Site's VPS map, and only as accurate as that map's georeference. Universal localization alone never reaches this state. The state falls back to coarse or unavailable if the device loses its connection to that map, for example when AR tracking resets, so keep checking it. Wait for it when your content needs accurate placement from geographic coordinates.

The state is a broad category, not a measurement — use the accuracy values for numeric margins of error. Also, it describes the device's geoposition, which is separate from whether a localized asset is tracked for content placement; for that distinction and the full reference, see Tracking states.

Accuracy​

Each estimate includes accuracy values that represent margin-of-error estimates. Rely on these rather than assuming centimeter-level global alignment. 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)

Use a localized asset for AR placement​

Calling localize starts a request; it does not itself provide a pose. After VPS2 reports a localized asset, read that asset's tracking data and render content only while the data is available. See Place virtual content with VPS2 for the platform-specific placement pattern.

note

Use device geolocation for the device's latitude, longitude, altitude, and heading. Asset tracking data describes the asset's origin, not the device: its pose places the asset's origin in AR space, and its geolocation (present only for georeferenced assets) is the geographic position of that origin.