# GeoHint in Localization

Release **v1.7.0** adds two major features to the MultiSet VPS for improved localization in large georeferenced maps.

1. **GeoHint in Localization Requests**
   * **Purpose:** Pass the device's GPS coordinates (latitude, longitude, altitude) in localization requests after georeferencing your map.
   * **Benefits:**
     * Significantly reduces localization time in large outdoor environments.
     * Mitigates issues of visual aliasing.
     * Improves overall localization performance and accuracy.
2. **GeoCoordinates in Localization Responses**
   * **Purpose:** Get localization results directly in global GPS coordinates (latitude, longitude, altitude).
   * **Benefits:**
     * Enables seamless integration with other applications or services that rely on GPS coordinates.
     * Directly connects localization results to real-world locations.

***

### How to Use These Features

#### In Unity (MultiSet SDK Manager)

The following GPS-related options are available in the MultiSet SDK Manager component in Unity:

* **passGeoPose:** Enables sending device GPS as a GeoHint in requests.
* **geoCoordinatesInResponse:** Enables receiving localization results in global GPS coordinates.
* **hintRadius:** Search radius in meters for spatial filtering (default: 25m, range: 1–100). Only applies when geoHint or hintPosition is provided.
* **use2DFiltering:** When enabled, skips altitude (Y-axis) in geoHint spatial filtering and uses only horizontal distance (X and Z axes). Only applies when geoHint is provided.

**Setup Steps:**

1. **Update Map GeoCoordinates:**\
   Before enabling these features, update the geo-coordinates of your map in the MultiSet Developer Portal.
2. **Enable Options in Unity:**
   * Open your scene and select the MultiSet SDK Manager (or Single Frame Localization Manager).
   * Check the box for `Pass GeoPose` to send device GPS as a hint.
   * Check the box for `GeoCoordinates In Response` to receive results in global GPS coordinates.
   * Adjust `Hint Radius` to control the spatial filtering search radius (default: 25 meters).
   * Enable `Use 2D Filtering` if you want to ignore altitude differences during spatial filtering.

## GeoHint for MapSet

To enable GeoHint in MapSet, start by georeferencing the primary map. Afterward, merge all the maps to enable georeferencing for the entire MapSet.

***

#### Using MultiSet Localization API Directly

If you are integrating via the API (outside Unity), you can enable these features by including the following fields in your localization request:

**Request Parameters**

| Field                     | Type   | Description                                                                                                     |
| ------------------------- | ------ | --------------------------------------------------------------------------------------------------------------- |
| `geoHint`                 | string | Comma-separated string, e.g. `"latitude,longitude,altitude"`. Pass the device's GPS as a hint for localization. |
| `convertToGeoCoordinates` | string | Pass `"true"` to receive localization response in global coordinates.                                           |

**Example Request Body and Response:**

JSON

<pre><code>{
  "mapId": "your-map-id",
  "geoHint": "37.4219983,-122.084,10.5",
  "convertToGeoCoordinates": "true",
  "isRightHanded": "false",
  ..... /other parameters
<strong>}
</strong></code></pre>

```
{
    "poseFound": true,
    "position": {
        "x": -0.12362211813361121,
        "y": 1.563005737034826,
        "z": 6.99455530632896
    },
    "rotation": {
        "x": 0.0054829774148128785,
        "y": -0.575302195022844,
        "z": -0.009251237126862318,
        "w": 0.8178702439703922
    },
    "mapIds": [
        "68c8fe2ff8f229955c39eb02"
    ],
    "GeoPose": {
        "frame_spec": {
            "model": "WGS-84",
            "frame": "Y-Up-ENU"
        },
        "pose": {
            "position": {
                "lat": 12.952603117267845,
                "lon": 77.61615745357129,
                "h": 912.923009573482
            },
            "quaternion": {
                "x": 0.01041866301787597,
                "y": -0.985121678974319,
                "z": -0.002664561995662227,
                "w": 0.1715215123100019
            }
        }
    }
}
```

### Feature Details

#### 1. Passing GeoHint in Localization

* **How:**\
  When `passGeoPose` is enabled, the SDK will automatically attach the device's current GPS coordinates to your localization request.
* **Why:**\
  This narrows down the search area in large outdoor georeferenced maps, speeding up localization and reducing errors.

#### 2. Receiving GeoCoordinates in Response

* **How:**\
  When `geoCoordinatesInResponse` is enabled (or when `convertToGeoCoordinates: "true"` is included in API requests), the SDK converts the localization result into global GPS coordinates.
* **Why:**\
  This is useful for interoperability with external systems or for mapping localization results to real-world positions.

***

### Important Notes

* **Map Preparation:**\
  Ensure your map is properly geo-referenced and updated in the MultiSet Developer Portal before using these options.
* **Platform Support:**\
  GPS functionality requires device location permissions; the SDK will prompt the user accordingly.
* **Unity Integration:**\
  No additional scripting is needed—just enable the options in the SDK Manager.

***