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

Settings are supplied during SDK initialization via MultiSet.shared.initialize(config:callback:). You can also change them at runtime and apply the updated configuration with MultiSet.shared.updateConfig(_:) — the new values take effect on the next localization / tracking query, without re-initializing or re-authenticating. All numeric settings can be clamped to their valid ranges 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	""	MapSet 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.2 - 0.8.

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 a geo hint or hintPosition is provided; sent when greater than 0. Valid range: 1 - 100.
use2DFiltering	Bool	false	When true, skips altitude (Y-axis) in spatial filtering, using only horizontal distance (X and Z). Only applies when a geo hint is provided.

Localization Hints

These hints narrow the search space for Map and MapSet localization, improving speed and accuracy in large or visually repetitive environments. They are most useful to set (or adjust) at runtime, right before a query — see Updating Configuration at Runtime.

Property	Type	Default	Description
hintMapCodes	[String]	[]	Map codes that narrow the candidate maps during MapSet localization. Only sent when localizing a MapSet; each code is sent as a separate hintMapCodes field.
hintPosition	String	""	Positional hint to seed localization, in "X,Y,Z" format. Sent when non-empty.
hintFloorHeight	String	""	Floor/ceiling height hint, in "floor,ceiling" format (e.g. "0,5"). Sent when non-empty.

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

Each factory method returns a MultiSetConfig preset for a common localization strategy.

singleFrame(clientId:clientSecret:mapCode:)

Single-image localization: captures one frame, with auto and background localization disabled.

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

multiFrame(clientId:clientSecret:mapCode:)

Multi-image localization for higher accuracy.

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

continuous(clientId:clientSecret:mapCode:)

Aggressive re-localization, re-localizing at 15-second intervals.

let config = MultiSetConfig.continuous(
    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()

---

Updating Configuration at Runtime

Configuration is supplied once at initialization, but you can change the Map / MapSet localization settings on the fly and apply them before the next query request using MultiSet.shared.updateConfig(_:). This is the recommended way to adjust behavior — auto-localize, confidence thresholds, background intervals, localization hints, object-tracking behavior — between queries without tearing down the SDK.

updateConfig(_:)

Declaration

func updateConfig(_ config: MultiSetConfig)

Description

Applies an updated configuration to an already-initialized SDK without re-authenticating. The new behavioral settings take effect on the next localization / tracking query; a run that is already in flight is unaffected. Credentials and authentication state are preserved — to change credentials, call release() followed by initialize(config:callback:) instead. The call is a no-op if the SDK has not been initialized yet.

Example

// Start from the current configuration, adjust MapSet hints, then apply before querying
var config = MultiSet.shared.config ?? SDKConfig.buildConfig()

config.passGeoPose = true
config.hintRadius = 40
config.hintMapCodes = ["MAP_A", "MAP_B"]   // narrow MapSet candidates
config.confidenceThreshold = 0.5

MultiSet.shared.updateConfig(config)        // takes effect on the next query
MultiSet.shared.localize()

The updated values take effect on the next localize() / object-tracking query — there is no need to re-initialize or re-authenticate the SDK.

In-App Settings Screen

The sample app exposes a Configuration screen (the gear icon on the LandingView) that edits these same properties at runtime. It is backed by a ConfigStore that persists values across launches via UserDefaults, and it calls updateConfig(_:) on Save / Reset — so changes apply to the running SDK immediately, before your next localization or object-tracking query.

---

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
         |
6. (Optional) Change properties and call MultiSet.shared.updateConfig(_:)
   to apply the new settings before the next query

---

Best Practices

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

2. Apply runtime changes with updateConfig(_:) rather than re-initializing — it updates the live SDK before the next query without a re-authentication round-trip.

3. Set localization hints (hintMapCodes, hintPosition, hintRadius) before a MapSet query to narrow the candidate maps in large or repetitive spaces.

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

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

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

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

---

Related

• LandingView

• ARLocalizationView

• ARObjectTrackingView