Skip to main content
Version: 21 Aug 2024

MLSpace

NameSpace: MagicLeap

Inherits from:
MLAutoAPISingleton< MLSpace >,
MLLazySingleton< T >

Public Fields

OnLocalizationEvent

This callback will be invoked whenever there is an update to the localization status. Localization events can occur when the application requests for localization via RequestLocalization(ref SpaceInfo) or due to other events outside the control of the app such as head tracking failure, localization loss.


public static OnLocalizationDelegate OnLocalizationEvent { get; set; }


Public Methods

MLResult.Code ExportSpace

Export an on device Magic Leap Space. Permissions: com.magicleap.permission.SPACE_IMPORT_EXPORT (protection level:dangerous).

public static MLResult.Code ExportSpace(
in SpaceInfo info,
out SpaceData data
)

Parameters

TypeNameDescription
in SpaceInfoinfoInformation needed to export the space
out SpaceDatadataExported space data

Returns: MLResult.Code will be MLResult.Code.Ok if space was exported successfully. MLResult.Code will be MLResult.Code.InvalidParam if 1 or more input parameters are not valid. MLResult.Code will be MLResult.Code.PermissionDenied if necessary permission is missing. MLResult.Code will be MLResult.UnspecifiedFailure if failed for unknown reason. MLResult.Code will be MLResult.Code.UnavailableSpace if failed due to unavailable space.


MLResult.Code GetLocalizationResult

Get the localization results. Returns the results of the most recent localization request. Permissions: None.

public static MLResult.Code GetLocalizationResult(
out LocalizationResult result
)

Parameters

TypeNameDescription
out LocalizationResultresultContains the result of the localization request

Returns: MLResult.Code will be MLResult.Code.Ok if the result was retrieved successfully. MLResult.Code will be MLResult.Code.InvalidParam if input parameter is not valid. MLResult.Code will be MLResult.Code.Unauthenticated if authentication credentials invalid for this operation. MLResult.Code will be MLResult.UnspecifiedFailure if failed for unknown reason.


MLResult.Code GetSpaceList

Get the list of available spaces. The list of spaces returned will depend on the current device mapping mode. Only the Spaces associated with the current mapping mode will be returned by this call.Device mapping mode can be changed via the system application(s). Permissions: None.

public static MLResult.Code GetSpaceList(
out Space [] spaceList
)

Parameters

TypeNameDescription
out Space []spaceListList of spaces currently available to the device

Returns: MLResult.Code will be MLResult.Code.Ok if the list of spaces was retrieved successfully. MLResult.Code will be MLResult.Code.InvalidParam if input parameter is not valid. MLResult.Code will be MLResult.Code.Unauthenticated if authentication credentials invalid for this operation. MLResult.Code will be MLResult.UnspecifiedFailure if failed for unknown reason. MLResult.Code will be MLResult.Code.SpacesServerError if operation failed due to server-side error. MLResult.Code will be MLResult.Code.SpacesServiceUnavailable if operation failed due to service not being ready.


MLResult.Code ImportSpace

Import a Magic Leap Space. Permissions: com.magicleap.permission.SPACE_IMPORT_EXPORT (protection level:dangerous).

public static MLResult.Code ImportSpace(
in SpaceData data,
out SpaceInfo id
)

Parameters

TypeNameDescription
in SpaceDatadataInformation needed to import the space
out SpaceInfoidSpace data returned on successful import

Returns: MLResult.Code will be MLResult.Code.Ok if space was imported successfully. MLResult.Code will be MLResult.Code.InvalidParam if 1 or more input parameters are not valid. MLResult.Code will be MLResult.Code.PermissionDenied if necessary permission is missing. MLResult.Code will be MLResult.UnspecifiedFailure if failed for unknown reason. MLResult.Code will be MLResult.Code.IncompatibleSpace if operation failed due to incompatible space. MLResult.Code will be MLResult.Code.SpaceAlreadyExists if space being imported already exists.


void LocalizationChanged

public static void LocalizationChanged(
ref SpaceLocalizationResult result,
IntPtr data
)

Parameters

TypeNameDescription
ref SpaceLocalizationResultresultA structure containing information about the device's localization state. This structure must be initialized by calling #MLSpaceLocalizationResultInit before usebefore use.
IntPtrdata

delegate void MLSpaceDelegate

public delegate void MLSpaceDelegate(
ref SpaceLocalizationResult result,
IntPtr data
)

Parameters

TypeNameDescription
ref SpaceLocalizationResultresultA structure containing information about the device's localization state. This structure must be initialized by calling #MLSpaceLocalizationResultInit before usebefore use.
IntPtrdata

delegate void OnLocalizationDelegate

public delegate void OnLocalizationDelegate(
LocalizationResult result
)

Parameters

TypeNameDescription
LocalizationResultresultA structure containing information about the device's localization state.

MLResult.Code RequestLocalization

Send a request to localize to a given Magic Leap Space. This is an asynchronous request. Use GetLocalizationResult to get the results of the localization, or add a listener to OnLocalizationEvent . Permissions: None.

public static MLResult.Code RequestLocalization(
ref SpaceInfo info
)

Parameters

TypeNameDescription
ref SpaceInfoinfoInformation about Space to localize into

Returns: MLResult.Code will be MLResult.Code.Ok if the request was submitted successfully. MLResult.Code will be MLResult.Code.InvalidParam if input parameter is not valid. MLResult.Code will be MLResult.Code.Unauthenticated if authentication credentials invalid for this operation. MLResult.Code will be MLResult.UnspecifiedFailure if failed for unknown reason. MLResult.Code will be MLResult.Code.SpacesServerError if operation failed due to server-side error. MLResult.Code will be MLResult.Code.SpacesServiceUnavailable if operation failed due to service not being ready.


Protected Methods

StartAPI

Start the API. Permissions: com.magicleap.permission.SPACE_MANAGER (protection level: normal)

protected virtual override MLResult.Code StartAPI()

Reimplements: StartAPI


StopAPI

Stop the API.

protected virtual override MLResult.Code StopAPI()

Reimplements: StopAPI


Public Attributes

MaxSpaceNameLength

Maximum size for the name of a Magic Leap Space.


public const uint MaxSpaceNameLength = 64;


Public Enums

LocalizationConfidence

The confidence of the current localization.

EnumeratorValueDescription
PoorLocalization confidence is very poor and should be reattempted.
FairThe confidence is low, current environmental conditions may adversely affect localization.
GoodThe confidence is high, persistent content should be stable.
ExcellentThis is a very high-confidence localization, persistent content will be very stable.

LocalizationErrorFlag

A set of possible reasons that a localization attempt may be unsuccessful.

EnumeratorValueDescription
None0No error, localization was successful.
Unknown1 << 0Localization failed for an unknown reason.
OutOfMappedArea1 << 1Localization failed becuase the user is outside of the mapped area.
LowFeatureCount1 << 2There are not enough features in the environment to successfully localize.
ExcessiveMotion1 << 3Localization failed due to excessive motion.
LowLight1 << 4Localization failed because the lighting levels are too low in the environment.
HeadposeFailure1 << 5A headpose failure caused localization to be unsuccessful.
AlgorithmFailure1 << 6There was an internal algorithm failure that prevented localization.

Status

The current localization status.

EnumeratorValueDescription
NotLocalizedThe device is currently not localized.
LocalizedThe device has localized successfully.
LocalizationPendingLocalization attempt is currently in progress.
SleepingBeforeRetryThe device will attempt to localize after sleep duration is complete.

Type

Indicates the type of the Space.

EnumeratorValueDescription
OnDeviceOn device space.
ARCloudAR Cloud based space.