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; asset tracking data does not include geographic coordinates.

Prerequisites​

This guide assumes that you have already completed:

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 a device 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 yet. The code above handles this case: TryGetDeviceGeolocation reports it as Vps2TrackingState.Unavailable.
  • coarse — An approximate global geoposition from GPS, sensor fusion, and universal localization. Good for large-scale alignment, but not for precise placement.
  • precise — A high-accuracy geoposition, typically reached after localizing to a Site's VPS map. Wait for this state 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 latitude, longitude, altitude, and heading. Do not derive them from a VPS map asset: asset tracking data supplies a map-relative AR pose, not an absolute geographic position.