Localization Options

Tune localization accuracy with confidence filtering, hints, and background localization

All options below are passed to XRSessionManager (or MultisetClient for client-side options) during initialization. They are also available as Inspector fields on the MultisetVPS Needle Engine component.

Confidence Filtering

Every localization response includes a confidence value from 0 to 1. By default the SDK accepts any result regardless of confidence. Enable confidence filtering to reject low-quality poses:

const session = new XRSessionManager(gl, {
  client,
  autoLocalize: true,
  confidenceCheck: true,
  confidenceThreshold: 0.6,  // only accept results >= 0.6
});

Results below the threshold trigger onLocalizationFailure rather than onLocalizationResult. Typical ranges:

Use case	Recommended threshold
General AR overlay	0.4 to 0.5
Precision BIM / sub-5 cm accuracy	0.7 to 0.8
Object anchoring	0.5 to 0.6

Hint Position

Narrow the retrieval search to a sphere around a known location. Supply the position in map-local coordinates:

const client = new MultisetClient({
  clientId: '...',
  clientSecret: '...',
  mapType: 'map',
  code: 'MAP_XXXXXXXXXX',
  hintPosition: '2.5,0,-4.0',  // "x,y,z" as a string
  hintRadius: 10,               // search radius in metres (5 to 100)
});

Use this when you know the device's approximate location from a floor plan, a QR code scan, or a previous localization result.

Hint MapCodes (MapSet Only)

Restrict the search to a subset of maps within a MapSet. Useful in large multi-floor buildings where floor is already known:

const client = new MultisetClient({
  clientId: '...',
  clientSecret: '...',
  mapType: 'map-set',
  code: 'MAPSET_XXXXXXXXXX',
  hintMapCodes: ['MAP_FLOOR1', 'MAP_FLOOR2'],
});

GeoHint (Geo-Fencing)

Send the device's GPS coordinates as a hint. The map must be georeferenced in the Multiset portal first.

const client = new MultisetClient({
  clientId: '...',
  clientSecret: '...',
  mapType: 'map',
  code: 'MAP_XXXXXXXXXX',
  passGeoPose: true,       // send Geolocation API data with each request
  use2DFiltering: true,    // ignore altitude — useful in multi-story buildings
});

passGeoPose prompts the browser for location permission on first localization. Combine with use2DFiltering in buildings where GPS altitude is unreliable.

Background Localization

Re-localize on an interval during an active session to reduce drift. The pose is updated silently without user interaction:

const session = new XRSessionManager(gl, {
  client,
  autoLocalize: true,
  backgroundLocalization: true,
  bgLocalizationInterval: 30,  // seconds between attempts (10 to 180)
});

The default interval is 30 seconds for VPS and 10 seconds for object tracking when not specified.

Relocalization on Tracking Loss

Re-run localization automatically when the device recovers from AR tracking loss (for example, after the camera is covered or the device sleeps):

const session = new XRSessionManager(gl, {
  client,
  autoLocalize: true,
  relocalization: true,
});

Geo Coordinates in Response

Request latitude, longitude, and altitude in the localization response (requires the map to be georeferenced):

const client = new MultisetClient({
  clientId: '...',
  clientSecret: '...',
  mapType: 'map',
  code: 'MAP_XXXXXXXXXX',
  convertToGeoCoordinates: true,
});

Framebuffer Scale

Control rendering resolution during the AR session. A value below 1 reduces GPU load; a value above 1 supersamples.

const session = new XRSessionManager(gl, {
  client,
  framebufferScaleFactor: 0.75,  // render at 75% resolution
});

Reference Space

The default reference space is 'local', which is supported on all ARCore devices. Use 'local-floor' on devices that support floor-relative tracking:

const session = new XRSessionManager(gl, {
  client,
  referenceSpaceType: 'local-floor',
});

Combining Options

Options compose freely. A typical production setup with all quality features enabled:

const client = new MultisetClient({
  clientId: '...',
  clientSecret: '...',
  mapType: 'map-set',
  code: 'MAPSET_XXXXXXXXXX',
  hintMapCodes: ['MAP_FLOOR3'],
  passGeoPose: true,
  use2DFiltering: true,
});

const session = new XRSessionManager(gl, {
  client,
  autoLocalize: true,
  confidenceCheck: true,
  confidenceThreshold: 0.55,
  relocalization: true,
  backgroundLocalization: true,
  bgLocalizationInterval: 45,
  framebufferScaleFactor: 0.85,
});