MapLocalizationManager
Map Localization Manager
The MapLocalizationManager is the core component for handling Visual Positioning System (VPS) localization in the MultiSet Quest SDK. It captures a sequence of frames from the Quest passthrough camera, sends them to the MultiSet backend for pose estimation, and aligns the digital content (mapSpace) with the real world on a successful localization.
Description
This manager localizes the headset against a pre-existing Map or MapSet. It can start localization automatically after authentication, run periodically in the background to keep the pose fresh, and retry the first request silently until it succeeds. Camera frames are supplied by a frame capture provider, which must be set via Initialize() before localization can run on the device. In the Unity Editor, where the passthrough camera is not available, the manager falls back to simulation data for testing.
A set of UnityEvent callbacks lets other scripts react to each stage of the localization process, and a C# event provides the full localization response.
Properties
This section details the publicly accessible fields of the MapLocalizationManager that can be configured in the Unity Editor or via script.
mapSpace
GameObject
Assigned in the Inspector. The GameObject that holds your digital content. Its pose is updated to align with the real world after a successful localization.
localizationType
LocalizationType
An enum to specify the type of localization. This can be either Map (for a single map) or MapSet (for a collection of maps).
mapOrMapsetCode
string
The unique identifier for the Map or MapSet you want to localize against. This code is obtained from the MultiSet developer portal.
autoLocalize
bool
If set to true, the manager will automatically attempt to localize as soon as the SDK is authenticated.
backgroundLocalization
bool
When enabled, the manager will periodically send localization requests in the background to maintain or improve the headset's pose over time.
bgLocalizationDuration
float
The time interval in seconds between background localization attempts. The value is clamped between 15 and 180 seconds (default: 60).
numberOfFrames
int
The number of camera frames to capture for a single localization request. A higher number can improve accuracy but increases processing time. The value is clamped between 4 and 6.
frameCaptureInterval
float
The time delay in seconds between capturing each frame for a localization request. The value is clamped between 0.4 and 0.8 seconds.
confidenceCheck
bool
When enabled, a localization result is accepted only if its confidence score is above _confidenceThreshold.
_confidenceThreshold
float
The minimum confidence score required for a localization result to be considered valid when confidenceCheck is enabled. The value is clamped between 0.2 and 0.8 (default: 0.3).
firstLocalizationUntilSuccess
bool
If enabled, the first localization request retries silently until it succeeds, without showing failure messages.
geoCoordinatesInResponse
bool
If set to true, the localization response will include the geo-coordinates corresponding to the headset's estimated pose.
hintRadius
int
Search radius in meters for spatial filtering (default: 25m). The value is clamped between 1 and 100. Only applies when hintPosition is provided.
use2DFiltering
bool
When true, skip altitude (Y-axis) in spatial filtering. Uses only horizontal distance (X and Z axes).
hintMapCodes
List<string>
Script-only. Used when localizationType is MapSet. Populate this list with specific map codes to restrict the search to those maps, potentially speeding up localization.
hintPosition
string
Script-only. An "X,Y,Z" position string used to provide a spatial hint for the localization query.
hintFloorHeight
string
Script-only. A "floor,ceiling" height range string (e.g. "0,5") used to restrict the search to a vertical slice of the map.
LocalizationInit
UnityEvent
Invoked when the localization process is initiated by calling LocalizeFrame().
LocalizationRequested
UnityEvent
Invoked just before the captured frames are sent to the MultiSet API.
LocalizationSuccess
UnityEvent
Invoked when the headset has been successfully localized and the pose has been applied to the mapSpace.
LocalizationFailure
UnityEvent
Invoked when the localization process fails for any reason (e.g., no pose found, network error).
OnLocalizationWithResponse
event Action<LocalizationResponseMultiFrame>
C# event that provides the detailed localization response. Subscribe to this from script to access the full response data.
Methods
This section describes the publicly accessible methods of the MapLocalizationManager.
Initialize(IFrameCaptureProvider frameCaptureProvider)
Sets the frame capture provider used to grab passthrough camera frames.
Declaration
Description The manager needs a frame capture provider before it can capture images on the device. Call this once during scene setup, passing the provider that wraps the Quest passthrough camera. The sample scenes show this wiring.
LocalizeFrame()
Manually starts the localization process.
Declaration
Description Calling this method begins the sequence of capturing the specified numberOfFrames from the passthrough camera, waiting frameCaptureInterval seconds between captures. Once all frames are collected, they are sent to the MultiSet backend to request localization. This is the primary method to call if you have autoLocalize disabled and want to trigger localization based on user input or another event. If a localization is already in progress, the call is ignored.
Last updated
Was this helpful?