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.
hintRadius	Int	25	Search radius in meters for spatial filtering. Only applies when geoHint or hintPosition is provided. Valid range: 1 - 100 meters.
use2DFiltering	Bool	false	When true, skip altitude (Y-axis) in geoHint spatial filtering. Uses only horizontal distance (X and Z axes). Only applies when geoHint is provided.

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.

Object Tracking Settings

Property	Type	Default	Description
objectCodes	[String]	[]	Array of object codes to track. Obtain from the MultiSet dashboard. Maximum 10 codes.
autoObjectTracking	Bool	true	Whether to automatically start object tracking when the AR session is ready.
backgroundObjectTracking	Bool	true	Whether to re-send tracking requests at regular intervals after first success.
bgObjectTrackingDurationSeconds	Float	15.0	Interval in seconds between background object tracking requests. Valid range: 5 - 30 seconds.
restartObjectTracking	Bool	true	Whether to re-track when AR tracking state is lost or paused.
objectTrackingCaptureDelay	Float	1.0	Delay in seconds before capturing the frame after tracking is triggered. Gives users time to aim. Valid range: 0.5 - 3.0 seconds.
firstObjectTrackingUntilSuccess	Bool	true	If true, failed tracking attempts will silently retry until one succeeds, without triggering onObjectTrackingFailure.

---

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.
hasObjectTrackingConfiguration	Bool	Returns true if objectCodes is non-empty.
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.2 - 0.8
hintRadius	1 - 100
imageQuality	50 - 100
objectCodes	Truncated to 10 entries
bgObjectTrackingDurationSeconds	5 - 30
objectTrackingCaptureDelay	0.5 - 3.0

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

• ARObjectTrackingView