SingleFrameLocalizationManager

Single Frame Localization Manager

The SingleFrameLocalizationManager performs VPS localization using a single passthrough camera frame per request. This approach is useful when you prefer quick, lightweight localization attempts over the multi-frame approach used by the MapLocalizationManager.

Description

This manager captures one frame from the Quest passthrough camera, sends it to the MultiSet backend for pose estimation, and aligns the mapSpace GameObject with the real world on success. It supports automatic localization after authentication, periodic background localization, silent retry of the first request, and confidence-based validation of results. 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, 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 SingleFrameLocalizationManager that can be configured in the Unity Editor or via script.

Property	Type	Description
m_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 specifying whether to localize against a single Map or a MapSet.
mapOrMapsetCode	string	The unique code for the Map or MapSet that the headset will attempt to localize against. This is a required field.
autoLocalize	bool	If true, the manager will automatically start the localization process after the SDK has successfully 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).
confidenceCheck	bool	When enabled, the manager will only consider a localization successful if its confidence score, returned by the API, is above the _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 enabled, 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 at the beginning of the localization process when LocalizeFrame() is called.
LocalizationRequested	UnityEvent	Invoked just before the captured frame is sent to the MultiSet API.
LocalizationSuccess	UnityEvent	Invoked after a successful localization attempt that meets the confidence criteria (if enabled), once the mapSpace pose has been updated.
LocalizationFailure	UnityEvent	Invoked if the localization attempt fails to produce a valid pose or the result does not meet the confidence threshold.
OnLocalizationWithResponse	event Action<LocalizationSuccessResponse>	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 SingleFrameLocalizationManager.

Initialize(IFrameCaptureProvider frameCaptureProvider)

Sets the frame capture provider used to grab passthrough camera frames.

Declaration

public void Initialize(IFrameCaptureProvider frameCaptureProvider)

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 initiates the single-frame localization process.

Declaration

public void LocalizeFrame()

Description Calling this method captures a single frame from the passthrough camera and sends it to the MultiSet API for pose estimation. This is the main method to use for triggering localization on demand when autoLocalize is disabled. If a localization is already in progress, the call is ignored.