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 launching AR activities. Settings include auto-localization triggers, background localization intervals, frame capture parameters, confidence thresholds, GPS integration, and UI feedback options. All settings can be modified at runtime and validated using the validate() method.

---

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	false	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.0 - 1.0.

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.

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.0 - 1.0
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, SingleFrameARActivity::class.java)
startActivity(intent)

---

Configuration Flow

1. Modify LocalizationConfig properties
         ↓
2. Call LocalizationConfig.validate()
         ↓
3. Launch SingleFrameARActivity or MultiFrameARActivity
         ↓
4. AR Activity reads configuration in onCreate()
         ↓
5. Localization behavior follows configuration

---

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.

---

Related

• MainActivity

• SingleFrameARActivity

• MultiFrameARActivity