> For the complete documentation index, see [llms.txt](https://docs.multiset.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.multiset.ai/webxr-sdk/localization-options.md).

# Localization Options

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:

```typescript
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:

```typescript
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 (1 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:

```typescript
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.

```typescript
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:

```typescript
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):

```typescript
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):

```typescript
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.

```typescript
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:

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

### Combining Options

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

```typescript
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,
});
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.multiset.ai/webxr-sdk/localization-options.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.