> For the complete documentation index, see [llms.txt](https://multiset.gitbook.io/multiset/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://multiset.gitbook.io/multiset/native-support/android-native/api-reference/localizationconfig.md).

# LocalizationConfig

#### Localization Configuration

The `LocalizationConfig` is a singleton object that provides centralized configuration for the MultiSet SDK localization behavior. It controls how the AR activities perform localization, including timing, quality, and feature settings.

#### **Description**

This configuration object allows you to customize the localization behavior **before a query request is made**. Settings include auto-localization triggers, background localization intervals, frame capture parameters, confidence thresholds, GPS integration, **localization hints** (to narrow the search for Map and MapSet localization), and UI feedback options. All settings can be modified at runtime and validated using the `validate()` method.

The AR activities read these values when localization starts, so any change you make to `LocalizationConfig` takes effect on the next query. The sample app also exposes an in-app [**Settings dialog**](#runtime-settings-dialog) that edits these same properties at runtime and persists them across launches.

***

## **Properties**

This section details the publicly accessible fields of the `LocalizationConfig` that can be configured via script.

### Localization Behavior

| Property                                | Type      | Default | Description                                                                                                                                                  |
| --------------------------------------- | --------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `autoLocalize`                          | `Boolean` | `true`  | Whether to automatically start localization when the AR session begins. If `false`, the user must manually tap the capture/localize button.                  |
| `backgroundLocalization`                | `Boolean` | `true`  | Whether to continue localization in the background after the first success. Helps maintain accurate positioning over time.                                   |
| `backgroundLocalizationIntervalSeconds` | `Float`   | `30f`   | The time interval in seconds between background localization attempts. Only used when `backgroundLocalization` is `true`. Valid range: **15 - 180 seconds**. |
| `relocalization`                        | `Boolean` | `true`  | Whether to enable relocalization when AR tracking is lost. Automatically triggers localization when the AR tracking state changes to PAUSED or STOPPED.      |
| `firstLocalizationUntilSuccess`         | `Boolean` | `true`  | Keep trying until the first localization succeeds. If `true`, failed localizations will silently retry until one succeeds.                                   |

### Multi-Frame Capture Settings

| Property                 | Type   | Default | Description                                                                                                                                         |
| ------------------------ | ------ | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| `numberOfFrames`         | `Int`  | `4`     | The number of frames to capture for multi-frame localization. More frames = better accuracy but longer capture time. Valid range: **4 - 6 frames**. |
| `frameCaptureIntervalMs` | `Long` | `500L`  | The interval between frame captures in milliseconds. Allows user movement between frames for better coverage. Valid range: **100 - 1000 ms**.       |

### Confidence Settings

| Property              | Type      | Default | Description                                                                                                                                               |
| --------------------- | --------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `confidenceCheck`     | `Boolean` | `true`  | Whether to check confidence threshold before accepting localization. If `true`, localizations with confidence below the threshold will be rejected.       |
| `confidenceThreshold` | `Float`   | `0.3f`  | Minimum confidence score to accept a localization result. Only used when `confidenceCheck` is `true`. Valid range: **0.2 - 0.8** (matches the Unity SDK). |

### GPS Settings

| Property                          | Type      | Default | Description                                                                                                                              |
| --------------------------------- | --------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| `enableGeoHint`                   | `Boolean` | `false` | Whether to send GPS coordinates as a hint to improve localization. Requires location permission. Useful for outdoor or large-scale maps. |
| `includeGeoCoordinatesInResponse` | `Boolean` | `false` | Whether to include geo-coordinates in the localization response. Useful if you need the world position of localized objects.             |

### Localization Hints

Localization hints let you constrain the search space *before* sending a query, which speeds up matching and reduces false positives in large maps or mapSets. All hints are optional — leave them empty/default to disable them.

| Property          | Type           | Default       | Description                                                                                                                                                                                    |
| ----------------- | -------------- | ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `hintMapCodes`    | `List<String>` | `emptyList()` | Subset of map codes within a **mapSet** to restrict localization to. Sent as repeated `hintMapCodes` fields. Only applies to **mapSet** localization; ignored for single **map** localization. |
| `hintPosition`    | `String`       | `""`          | Approximate position hint in `"x,y,z"` format to narrow the search around a known location. Leave empty to disable.                                                                            |
| `hintFloorHeight` | `String`       | `""`          | Floor/ceiling height constraint in `"floor,ceiling"` format, e.g. `"0,5"`. Leave empty to disable.                                                                                             |
| `hintRadius`      | `Int`          | `25`          | Search radius in meters for spatial filtering. Applied **only** when a geo hint (`enableGeoHint`) or `hintPosition` is present. Valid range: **1 - 100**.                                      |
| `use2DFiltering`  | `Boolean`      | `false`       | When spatial filtering is active, skip altitude (Y-axis) and filter on horizontal distance (X/Z) only.                                                                                         |

> **Note:** `hintRadius` and `use2DFiltering` are spatial filters that are only meaningful relative to a geo hint or a position hint. They are sent **only** when `enableGeoHint` (with a valid GPS fix) or `hintPosition` is set — otherwise the server would filter out every candidate and report "Pose not found".

### UI Settings

| Property                  | Type      | Default | Description                                                                                                     |
| ------------------------- | --------- | ------- | --------------------------------------------------------------------------------------------------------------- |
| `showAlerts`              | `Boolean` | `true`  | Whether to show UI alerts (toasts) for localization status. Shows success/failure messages to the user.         |
| `enableMeshVisualization` | `Boolean` | `true`  | Whether to show 3D mesh overlay after successful localization. The mesh helps visualize the mapped environment. |

### Image Quality Settings

| Property       | Type  | Default | Description                                                                                                                                        |
| -------------- | ----- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| `imageQuality` | `Int` | `90`    | JPEG quality for captured images sent to the localization API. Higher quality = better accuracy but larger upload size. Valid range: **50 - 100**. |

***

## Methods

This section describes the publicly accessible methods of the `LocalizationConfig`.

### resetToDefaults()

Resets all settings to their default values.

**Declaration**

```kotlin
fun resetToDefaults()
```

**Description**

Calling this method will reset all configuration properties to their factory default values. This is useful when you want to ensure a clean configuration state before customizing specific settings.

**Example**

```kotlin
// Reset all settings before customizing
LocalizationConfig.resetToDefaults()

// Now customize specific settings
LocalizationConfig.autoLocalize = false
LocalizationConfig.numberOfFrames = 6
```

***

### validate()

Applies validated bounds to all settings.

**Declaration**

```kotlin
fun validate()
```

**Description**

Calling this method will clamp all numeric settings to their valid ranges. This ensures that all configuration values are within acceptable bounds before they are used by the AR activities. It is recommended to call this method after modifying any settings.

**Validation Rules:**

| Property                                | Valid Range |
| --------------------------------------- | ----------- |
| `backgroundLocalizationIntervalSeconds` | 15 - 180    |
| `numberOfFrames`                        | 4 - 6       |
| `frameCaptureIntervalMs`                | 100 - 1000  |
| `confidenceThreshold`                   | 0.2 - 0.8   |
| `hintRadius`                            | 1 - 100     |
| `imageQuality`                          | 50 - 100    |

**Example**

```kotlin
// Set a value outside the valid range
LocalizationConfig.numberOfFrames = 10

// Validate will clamp it to the maximum (6)
LocalizationConfig.validate()

// numberOfFrames is now 6
```

***

## Usage Examples

### Basic Configuration

```kotlin
// Configure for quick, automatic localization
LocalizationConfig.autoLocalize = true
LocalizationConfig.backgroundLocalization = true
LocalizationConfig.showAlerts = true
LocalizationConfig.validate()

// Launch AR activity
val intent = Intent(this, MultiSetLocalizationActivity::class.java)
intent.putExtra(
    MultiSetLocalizationActivity.EXTRA_LOCALIZATION_MODE,
    LocalizationMode.MULTI_FRAME.name
)
startActivity(intent)
```

### MapSet Localization with Hints

When localizing against a **mapSet**, you can narrow the search to a subset of maps and a known area before the query is sent:

```kotlin
LocalizationConfig.resetToDefaults()

// Restrict matching to specific maps inside the mapSet
LocalizationConfig.hintMapCodes = listOf("MAP_LOBBY", "MAP_FLOOR_1")

// Bias the search around a known position and floor band
LocalizationConfig.hintPosition = "12.5,0.0,-3.2"   // "x,y,z"
LocalizationConfig.hintFloorHeight = "0,5"          // "floor,ceiling"

// Spatial filtering (only applied because hintPosition is set)
LocalizationConfig.hintRadius = 20                  // meters
LocalizationConfig.use2DFiltering = true            // ignore altitude

LocalizationConfig.validate()
// hintMapCodes is ignored automatically when localizing a single map.
```

***

## Configuration Flow

```
1. Modify LocalizationConfig properties
         ↓
2. Call LocalizationConfig.validate()
         ↓
3. Launch MultiSetLocalizationActivity with desired mode
         ↓
4. AR Activity reads configuration in onCreate()
         ↓
5. Localization behavior follows configuration
```

***

## Runtime Settings Dialog

The sample app lets you change the localization configuration **at runtime, before starting a query** — no rebuild required. Tap the **settings gear** on the landing screen (`MainActivity`) to open a full-screen `SettingsDialogFragment` that edits every `LocalizationConfig` (and `ObjectTrackingConfig`) property described above, including the localization hints.

* Changes are written straight back to the `LocalizationConfig` singleton, so the next localization query uses the updated values.
* Settings are persisted with `ConfigStore` (backed by `SharedPreferences`) and restored on the next app launch via `ConfigStore.load(this)` in `MainActivity.onCreate()`.
* Credentials and map / mapSet / object codes are **not** persisted — they always come from `multiset.properties` (`BuildConfig`).
* **Save** applies and stores the values; **Reset** restores defaults via `resetToDefaults()`.

```kotlin
// MainActivity restores any saved configuration before the AR activities read it
override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(savedInstanceState)
    // ...
    ConfigStore.load(this)   // applies persisted LocalizationConfig / ObjectTrackingConfig
    // ...
}

// Opening the settings dialog from the gear button
binding.settingsButton.setOnClickListener {
    SettingsDialogFragment
        .newInstance(selectedMode == LocalizationMode.MULTI_FRAME)
        .show(supportFragmentManager, SettingsDialogFragment.TAG)
}
```

> You can achieve the same result programmatically by setting `LocalizationConfig` properties directly and calling `validate()` before launching `MultiSetLocalizationActivity` — the Settings dialog is simply a UI over those same properties.

***

## Best Practices

1. **Always call `validate()`** after modifying settings to ensure values are within valid ranges.
2. **Call `resetToDefaults()`** before configuring if you want to start from a known state.
3. **Disable `firstLocalizationUntilSuccess`** when using `enableGeoHint` and `includeGeoCoordinatesInResponse` together, as geo-based failures should be reported to the user.
4. **Increase `numberOfFrames`** for environments with sparse or repetitive features.
5. **Enable `backgroundLocalization`** for applications that need to maintain accurate positioning over time.
6. **Use higher `imageQuality`** for complex environments but be mindful of network bandwidth.
7. **Use `hintMapCodes`** to restrict large mapSets to the maps the user is likely in — this speeds up matching and avoids cross-map false positives.
8. **Pair `hintRadius` / `use2DFiltering` with a hint** (either `enableGeoHint` with a GPS fix or `hintPosition`). On their own they have no reference point and the server will reject every candidate.

***

## Related

* [MainActivity](/multiset/native-support/android-native/sample-activities/mainactivity.md)
* [MultiSetLocalizationActivity](/multiset/native-support/android-native/sample-activities/multisetlocalizationactivity.md)


---

# 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://multiset.gitbook.io/multiset/native-support/android-native/api-reference/localizationconfig.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.