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 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

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

// 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

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

// 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

// 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:

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().

// 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

• MultiSetLocalizationActivity