# Localization

### What is Localization?

Localization is the process of determining a device's precise position and orientation (6-DoF pose) within a pre-scanned map. When a query image is sent to the VPS API, the system searches the map's database of reference frames for visually similar candidates, then computes an exact pose using feature matching and geometry.

By default the search covers the entire map. In large maps or multi-floor buildings this can be slow and prone to confusion between visually similar areas. **Localization parameters** let you provide prior knowledge — floor level, known position, GPS coordinates, map scope — to narrow the search before it begins, improving both speed and accuracy.

### Localization Parameters

<figure><img src="https://3163433004-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FokTDI7QVY04Zvb1pQ8Ry%2Fuploads%2FdMh5dJnlUwdgr0ozAwDC%2FScreenshot%202026-04-07%20at%206.26.41%E2%80%AFPM.png?alt=media&#x26;token=1cc3cdf1-1df9-4a3c-a57a-1f2afaf5c870" alt=""><figcaption></figcaption></figure>

#### hintPosition

A 3D coordinate `[x, y, z]` in map-local space (left-handed / Unity convention) that tells the server approximately where the device is. The search is limited to frames within a radius of that point (default 25 m, configurable via `hintRadius`).

| Format                          | Example                             |
| ------------------------------- | ----------------------------------- |
| Array of 3 numbers (JSON body)  | `"hintPosition": [2.5, 0.1, 8.0]`   |
| JSON-encoded string (form-data) | `"hintPosition": "[2.5, 0.1, 8.0]"` |

Coordinates use the same LHS coordinate system as the localization response (when `isRightHanded: false`, the default). You can pass a previous localization result's `position` directly as the hint for the next query.

Use when you have approximate position from BLE, UWB, WiFi fingerprinting, or a previous localization result. For GPS-georeferenced maps, use `geoHint` instead.

#### hintMapCodes *(MapSet only)*

A list of map codes that limits the search to specific maps within a MapSet. Useful in multi-floor buildings where floor-level context is already known (e.g. from a floor selector, QR code scan, or BLE beacon).

| Format                          | Example                                                    |
| ------------------------------- | ---------------------------------------------------------- |
| Array of strings (JSON body)    | `"hintMapCodes": ["MAP_RJFKKWQ1787J", "MAP_XPQR3456ABCD"]` |
| JSON-encoded string (form-data) | `"hintMapCodes": "[\"MAP_RJFKKWQ1787J\"]"`                 |

Only valid when querying against a `mapSetCode`. Ignored for single-map queries.

#### hintFloorHeight

A vertical band `[y_min, y_max]` in map-local Y coordinates. Only frames whose camera position falls within this Y range are considered. Useful for floor-level filtering in multi-floor spaces without needing per-floor map codes.

| Format                          | Example                           |
| ------------------------------- | --------------------------------- |
| Array of 2 numbers (JSON body)  | `"hintFloorHeight": [3.0, 6.0]`   |
| JSON-encoded string (form-data) | `"hintFloorHeight": "[3.0, 6.0]"` |

Order does not matter — `[-3, -1]` and `[-1, -3]` both select y ∈ \[-3, -1]. See [HintFloorHeight](https://docs.multiset.ai/basics/localization/hint-floor-height) for full details.

#### geoHint

The device's GPS coordinates `[latitude, longitude, altitude]` passed as a comma-separated string. For georeferenced maps, the server converts these to map-local coordinates and applies the same spatial radius filtering as `hintPosition`. Requires the map to be georeferenced in the MultiSet Developer Portal.

| Format                 | Example                                 |
| ---------------------- | --------------------------------------- |
| Comma-separated string | `"geoHint": "37.4219983,-122.084,10.5"` |

Works for both single Maps and MapSets. Combine with `convertToGeoCoordinates: "true"` to receive the pose result back in GPS coordinates. See [GeoHint in Localization](https://docs.multiset.ai/basics/localization/geohint-in-localization) for full details.

#### hintRadius

Controls the search radius around `hintPosition` or `geoHint`. Default is 25 m. Smaller values are faster but require a more accurate prior; larger values are more forgiving.

| Format                     | Range   | Default |
| -------------------------- | ------- | ------- |
| Number (JSON body)         | 1–100 m | 25 m    |
| Numeric string (form-data) | `"25"`  | 25 m    |

Only applies when `hintPosition` or `geoHint` is provided. Has no effect otherwise.

#### use2DFiltering

When `true`, the spatial radius filter ignores the Y-axis (altitude) and uses only horizontal distance (X and Z). Useful for tall buildings or outdoor environments where GPS altitude is unreliable.

| Format                                  | Default   |
| --------------------------------------- | --------- |
| Boolean (JSON body)                     | `false`   |
| String `"true"` / `"false"` (form-data) | `"false"` |

Only applies when `geoHint` is provided. Works for both Maps and MapSets. Has no effect with `hintPosition` alone.

### How Parameters Combine

Parameters are applied in sequence — each one narrows the candidate set further:

```
All map frames
  → hintMapCodes      (keep only frames from these maps)
  → hintPosition / geoHint + hintRadius  (keep frames within radius)
  → use2DFiltering    (if set, ignore Y in radius check)
  → hintFloorHeight   (keep frames within vertical band)
  → visual matching   (rank remaining candidates by image similarity)
```

Using more hints together reduces the search space more aggressively and is particularly effective in large, multi-floor MapSets.

***

### Quick Reference

| Parameter         | Type             | Applies to   | Purpose                                  |
| ----------------- | ---------------- | ------------ | ---------------------------------------- |
| `hintPosition`    | `[x, y, z]`      | Map / MapSet | Spatial radius filter from a known point |
| `hintMapCodes`    | `[string, ...]`  | MapSet only  | Limit search to specific maps            |
| `hintFloorHeight` | `[y_min, y_max]` | Map / MapSet | Vertical band filter                     |
| `geoHint`         | `"lat,lon,alt"`  | Map / MapSet | GPS-based spatial filter                 |
| `hintRadius`      | number (1–100)   | Map / MapSet | Radius for hintPosition / geoHint        |
| `use2DFiltering`  | boolean          | Map / MapSet | Ignore Y-axis in geoHint radius check    |


---

# Agent Instructions: 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:

```
GET https://docs.multiset.ai/basics/localization.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.