MultiSetConfig

SDK Configuration

The MultiSetConfig struct provides centralized configuration for the MultiSet SDK localization behavior. It controls how the AR views perform localization, including timing, quality, and feature settings.

Description

This configuration struct allows you to customize the localization behavior when initializing the SDK. Settings include auto-localization triggers, background localization intervals, frame capture parameters, confidence thresholds, GPS integration, and UI feedback options. All settings are passed during SDK initialization and can be validated using the validated() method.

---

Properties

This section details the publicly accessible properties of the MultiSetConfig that can be configured.

Authentication

Property	Type	Default	Description
clientId	String	Required	Your MultiSet client identifier. Obtain from developer.multiset.ai/credentials.
clientSecret	String	Required	Your MultiSet client secret key. Obtain from developer.multiset.ai/credentials.

Map Configuration

Property	Type	Default	Description
mapCode	String	""	Single map identifier for localization. Use either this or mapSetCode.
mapSetCode	String	""	Map set identifier for localizing against multiple maps. Use either this or mapCode.

Localization Mode

Property	Type	Default	Description
localizationMode	LocalizationMode	.multiFrame	The capture strategy: .singleFrame for quick single-image capture, or .multiFrame for multi-image capture with better accuracy.

Localization Behavior

Property	Type	Default	Description
autoLocalize	Bool	true	Whether to automatically start localization when the AR session begins. If false, the user must manually tap the capture/localize button.
backgroundLocalization	Bool	true	Whether to continue localization in the background after the first success. Helps maintain accurate positioning over time.
bgLocalizationDurationSeconds	Float	30.0	The time interval in seconds between background localization attempts. Only used when backgroundLocalization is true. Valid range: 15 - 180 seconds.
relocalization	Bool	true	Whether to enable relocalization when AR tracking is lost. Automatically triggers localization when the AR tracking state changes to paused or stopped.
firstLocalizationUntilSuccess	Bool	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	Int	500	The interval between frame captures in milliseconds. Allows user movement between frames for better coverage. Valid range: 300 - 800 ms.

Confidence Settings

Property	Type	Default	Description
confidenceCheck	Bool	false	Whether to check confidence threshold before accepting localization. If true, localizations with confidence below the threshold will be rejected.
confidenceThreshold	Float	0.3	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
passGeoPose	Bool	false	Whether to send GPS coordinates as a hint to improve localization. Requires location permission. Useful for outdoor or large-scale maps.
geoCoordinatesInResponse	Bool	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	Bool	true	Whether to show UI alerts (toasts) for localization status. Shows success/failure messages to the user.
meshVisualization	Bool	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.

---

Computed Properties

Property	Type	Description
activeMapType	MapType	Returns .map or .mapSet based on which code is configured.
activeMapCode	String	Returns the active map code (either mapCode or mapSetCode).
hasCredentials	Bool	Returns true if both clientId and clientSecret are configured.
hasMapConfiguration	Bool	Returns true if either mapCode or mapSetCode is configured.
frameCaptureIntervalSeconds	TimeInterval	Returns frameCaptureIntervalMs converted to seconds.
bgLocalizationDuration	TimeInterval	Returns bgLocalizationDurationSeconds as TimeInterval.

---

Factory Methods

default(clientId:clientSecret:mapCode:)

Creates a default configuration for localization.

let config = MultiSetConfig.default(
    clientId: "your_client_id",
    clientSecret: "your_client_secret",
    mapCode: "your_map_code"
)

---

Methods

validated()

Returns a new configuration with all numeric settings clamped to their valid ranges.

Declaration

func validated() -> MultiSetConfig

Description

Calling this method returns a new configuration with all values clamped to acceptable bounds. This ensures that all configuration values are within acceptable ranges before they are used by the SDK.

Validation Rules:

Property	Valid Range
bgLocalizationDurationSeconds	15 - 180
numberOfFrames	4 - 6
frameCaptureIntervalMs	300 - 800
confidenceThreshold	0.0 - 1.0
imageQuality	50 - 100

Example

var config = MultiSetConfig(
    clientId: "id",
    clientSecret: "secret",
    mapCode: "map",
    numberOfFrames: 10  // Outside valid range
)

// validated() will clamp numberOfFrames to 6
config = config.validated()

---

Usage Examples

Basic Configuration

// Configure for quick, automatic localization
let config = MultiSetConfig(
    clientId: clientId,
    clientSecret: clientSecret,
    mapCode: mapCode,
    autoLocalize: true,
    backgroundLocalization: true,
    showAlerts: true
)

MultiSet.shared.initialize(config: config, callback: delegate)

---

Configuration Flow

1. Create MultiSetConfig with desired properties
         |
2. Optionally call config.validated()
         |
3. Call MultiSet.shared.initialize(config:callback:)
         |
4. SDK reads configuration during initialization
         |
5. Localization behavior follows configuration

---

Best Practices

1. Always validate configuration by calling validated() after modifying settings to ensure values are within valid ranges.

2. Disable firstLocalizationUntilSuccess when using passGeoPose and geoCoordinatesInResponse together, as geo-based failures should be reported to the user.

3. Increase numberOfFrames for environments with sparse or repetitive features.

4. Enable backgroundLocalization for applications that need to maintain accurate positioning over time.

5. Use higher imageQuality for complex environments but be mindful of network bandwidth.

---

Related

• LandingView

• ARLocalizationView