Version: 20 Mar 2024

Spatial Anchor

APIs for managing Spatial Anchors. More...

Classes

	Name
struct	MLSpatialAnchorLocalizationInfo A structure containing information about the device's localization state.
struct	MLSpatialAnchor A structure representing a user-defined Spatial Anchor.
struct	MLSpatialAnchorCreateInfo A structure used to populate anchor creation info when creating a new Spatial Anchor.
struct	MLSpatialAnchorQueryFilter A collection of filters for Spatial Anchor queries.

Types

	Name
typedef struct MLSpatialAnchorLocalizationInfo	MLSpatialAnchorLocalizationInfo A structure containing information about the device's localization state.
typedef struct MLSpatialAnchor	MLSpatialAnchor A structure representing a user-defined Spatial Anchor.
typedef struct MLSpatialAnchorCreateInfo	MLSpatialAnchorCreateInfo A structure used to populate anchor creation info when creating a new Spatial Anchor.
typedef struct MLSpatialAnchorQueryFilter	MLSpatialAnchorQueryFilter A collection of filters for Spatial Anchor queries.

Enums

	Name
enum	Anonymous Enum 29 { MLResultAPIPrefix_SpatialAnchor = ( 0x439 << 16), MLSpatialAnchor_MaxSpaceNameLength = 64 }
enum	MLSpatialAnchorResult { MLSpatialAnchorResult_MaxAnchorLimitReached = MLResultAPIPrefix_SpatialAnchor, MLSpatialAnchorResult_MinDistanceThresholdExceeded, MLSpatialAnchorResult_InsufficientMapping, MLSpatialAnchorResult_InvalidId, MLSpatialAnchorResult_InvalidExpirationTimestamp, MLSpatialAnchorResult_NotLocalized, MLSpatialAnchorResult_ServerError, MLSpatialAnchorResult_ServiceUnavailable, MLSpatialAnchorResult_Ensure32Bits = 0x7FFFFFFF } SpatialAnchor-specific return codes.
enum	MLSpatialAnchorLocalizationStatus { MLSpatialAnchorLocalizationStatus_NotLocalized, MLSpatialAnchorLocalizationStatus_Localized, MLSpatialAnchorLocalizationStatus_LocalizationPending, MLSpatialAnchorLocalizationStatus_Ensure32Bits = 0x7FFFFFFF } The current localization status.
enum	MLSpatialAnchorMappingMode { MLSpatialAnchorMappingMode_OnDevice, MLSpatialAnchorMappingMode_ARCloud, MLSpatialAnchorMappingMode_Ensure32Bits = 0x7FFFFFFF } Mapping mode.
enum	MLSpatialAnchorQuality { MLSpatialAnchorQuality_Low, MLSpatialAnchorQuality_Medium, MLSpatialAnchorQuality_High, MLSpatialAnchorQuality_Ensure32Bits = 0x7FFFFFFF } The quality of the local space around the anchor.

Functions

	Name
void	MLSpatialAnchorLocalizationInfoInit(MLSpatialAnchorLocalizationInfo * inout_info) Initialize default values for MLSpatialAnchorLocalizationInfo.
void	MLSpatialAnchorInit(MLSpatialAnchor * inout_anchor) Initialize default values for a MLSpatialAnchor structure.
void	MLSpatialAnchorCreateInfoInit(MLSpatialAnchorCreateInfo * inout_info) Initialize default values for a MLSpatialAnchorCreateInfo structure.
void	MLSpatialAnchorQueryFilterInit(MLSpatialAnchorQueryFilter * inout_query_filter) Initializes the default values for a query filter.
MLResult	MLSpatialAnchorTrackerCreate(MLHandle * out_handle) Create a Spatial Anchor tracker.
MLResult	MLSpatialAnchorTrackerDestroy(MLHandle handle) Destroy a previously created Spatial Anchor tracker.
MLResult	MLSpatialAnchorCreate(MLHandle handle, const MLSpatialAnchorCreateInfo create_info, MLSpatialAnchor out_anchor) Create a new local Spatial Anchor at the desired location.
MLResult	MLSpatialAnchorPublish(MLHandle handle, MLUUID anchor_id) Publish an existing local Spatial Anchor to the persistent backend.
MLResult	MLSpatialAnchorDelete(MLHandle handle, MLUUID anchor_id) Delete an existing Spatial Anchor.
MLResult	MLSpatialAnchorUpdate(MLHandle handle, const MLSpatialAnchor * anchor) Update a Spatial Anchor's properties.
MLResult	MLSpatialAnchorQueryCreate(MLHandle handle, const MLSpatialAnchorQueryFilter query_filter, MLHandle out_query_handle, uint32_t * out_results_count) Create a new query for Spatial Anchors in the current space.
MLResult	MLSpatialAnchorQueryDestroy(MLHandle handle, MLHandle query_handle) Destroy a previously created query handle and release its associated resources.
MLResult	MLSpatialAnchorQueryGetResult(MLHandle handle, MLHandle query_handle, uint32_t first_index, uint32_t last_index, MLSpatialAnchor * out_results) Get the result of a previous Spatial Anchor query.
const char *	MLSpatialAnchorGetResultString(MLResult result) Returns an ASCII string for MLSpatialAnchorResult and MLResult codes.
MLResult	MLSpatialAnchorGetLocalizationInfo(MLHandle handle, MLSpatialAnchorLocalizationInfo * out_localization_info) Get the current localization status of the device.

Detailed Description

APIs for managing Spatial Anchors.

Spatial Anchor management is closely tied to the selected mapping mode on the device. The modes are mutually exclusive and affect the functionality of these APIs. The available mapping modes are:

On-Device Mode - A persistent mode in which anchors are persisted locally and will be available in multiple sessions when localized to the same space in which they were published.

AR Cloud Mode - A persistent mode in which anchors are persisted in the cloud environment and will be available in multiple sessions to devices that are localized to the same space in which they were published.

Shared Object:

perception.magicleap*

Enums Documentation

Anonymous Enum 29

Enumerator	Value	Description
MLResultAPIPrefix_SpatialAnchor	( 0x439 << 16)	Defines the prefix for MLSpatialAnchorResult codes.
MLSpatialAnchor_MaxSpaceNameLength	64	Maximum size for the name of the space in the MLSpatialAnchorLocalizationInfo structure.

MLSpatialAnchorResult

Enumerator	Value	Description
MLSpatialAnchorResult_MaxAnchorLimitReached	MLResultAPIPrefix_SpatialAnchor	The maximum number of anchors for the current space has been reached.
MLSpatialAnchorResult_MinDistanceThresholdExceeded		The minimum distance between anchors was not met.
MLSpatialAnchorResult_InsufficientMapping		The space has not been sufficiently mapped to allow this operation.
MLSpatialAnchorResult_InvalidId		The provided anchor Id was not valid.
MLSpatialAnchorResult_InvalidExpirationTimestamp		The provided expiration suggestion was not valid.
MLSpatialAnchorResult_NotLocalized		The operation cannot be completed because the device has not yet localized.
MLSpatialAnchorResult_ServerError		There was an error communicating with the server.
MLSpatialAnchorResult_ServiceUnavailable		The operation failed because the underlying service is not yet available, retry later.
MLSpatialAnchorResult_Ensure32Bits	0x7FFFFFFF	Ensure enum is represented as 32 bits.

SpatialAnchor-specific return codes.

API Level:

MLSpatialAnchorLocalizationStatus

Enumerator	Value	Description
MLSpatialAnchorLocalizationStatus_NotLocalized		The device is not currently localized.
MLSpatialAnchorLocalizationStatus_Localized		The device has localized successfully.
MLSpatialAnchorLocalizationStatus_LocalizationPending		A localization attempt is currently in progress.
MLSpatialAnchorLocalizationStatus_Ensure32Bits	0x7FFFFFFF	Ensure enum is represented as 32 bits.

The current localization status.

Deprecated

Deprecated since 1.3.0. Scheduled for removal. Replaced by MLSpaceLocalizationStatus.

API Level:

MLSpatialAnchorMappingMode

Enumerator	Value	Description
MLSpatialAnchorMappingMode_OnDevice		Using on-device mapping.
MLSpatialAnchorMappingMode_ARCloud		Using cloud-based mapping.
MLSpatialAnchorMappingMode_Ensure32Bits	0x7FFFFFFF	Ensure enum is represented as 32 bits.

Mapping mode.

Deprecated

Deprecated since 1.3.0. Scheduled for removal.

API Level:

MLSpatialAnchorQuality

Enumerator	Value	Description
MLSpatialAnchorQuality_Low		Low quality, this anchor can be expected to move significantly.
MLSpatialAnchorQuality_Medium		Medium quality, this anchor may move slightly.
MLSpatialAnchorQuality_High		High quality, this anchor is stable and suitable for digital content attachment.
MLSpatialAnchorQuality_Ensure32Bits	0x7FFFFFFF	Ensure enum is represented as 32 bits.

The quality of the local space around the anchor.

This can change over time as the user continues to scan the space.

API Level:

Types Documentation

MLSpatialAnchorLocalizationInfo

typedef struct MLSpatialAnchorLocalizationInfo MLSpatialAnchorLocalizationInfo;

A structure containing information about the device's localization state.

More Info

Deprecated

Deprecated since 1.3.0. Scheduled for removal. Replaced by MLSpaceLocalizationResult.

API Level:

MLSpatialAnchor

typedef struct MLSpatialAnchor MLSpatialAnchor;

A structure representing a user-defined Spatial Anchor.

More Info

API Level:

MLSpatialAnchorCreateInfo

typedef struct MLSpatialAnchorCreateInfo MLSpatialAnchorCreateInfo;

A structure used to populate anchor creation info when creating a new Spatial Anchor.

More Info

API Level:

MLSpatialAnchorQueryFilter

typedef struct MLSpatialAnchorQueryFilter MLSpatialAnchorQueryFilter;

A collection of filters for Spatial Anchor queries.

Filters that have been set will be combined via logical conjunction. E.g. results must match the ids filter AND fall within the radius constraint when both have been set.

This struct must be initialized by calling MLSpatialAnchorQueryFilterInit before use.

More Info

API Level:

Functions Documentation

MLSpatialAnchorLocalizationInfoInit

static inline void MLSpatialAnchorLocalizationInfoInit(
    MLSpatialAnchorLocalizationInfo * inout_info
)

Initialize default values for MLSpatialAnchorLocalizationInfo.

Parameters


MLSpatialAnchorLocalizationInfo *	inout_info	The localization info to initialize.

Required Permissions:

None

Deprecated

Deprecated since 1.3.0. Scheduled for removal. Replaced by MLSpaceLocalizationResultInit.

API Level:

MLSpatialAnchorInit

static inline void MLSpatialAnchorInit(
    MLSpatialAnchor * inout_anchor
)

Initialize default values for a MLSpatialAnchor structure.

Parameters


MLSpatialAnchor *	inout_anchor	The anchor to initialize.

Required Permissions:

None

API Level:

MLSpatialAnchorCreateInfoInit

static inline void MLSpatialAnchorCreateInfoInit(
    MLSpatialAnchorCreateInfo * inout_info
)

Initialize default values for a MLSpatialAnchorCreateInfo structure.

Parameters


MLSpatialAnchorCreateInfo *	inout_info	The info struct to initialize.

Required Permissions:

None

API Level:

MLSpatialAnchorQueryFilterInit

static inline void MLSpatialAnchorQueryFilterInit(
    MLSpatialAnchorQueryFilter * inout_query_filter
)

Initializes the default values for a query filter.

Parameters


MLSpatialAnchorQueryFilter *	inout_query_filter	The filter to initialize.

Required Permissions:

None

API Level:

MLSpatialAnchorTrackerCreate

MLResult MLSpatialAnchorTrackerCreate(
    MLHandle * out_handle
)

Create a Spatial Anchor tracker.

Parameters


MLHandle *	out_handle	A pointer to an MLHandle which will contain a handle for a Spatial Anchor tracker if successful, otherwise it will be ML_INVALID_HANDLE.

Returns


MLResult	MLResult_InvalidParam	The out_handle parameter was not valid.
MLResult	MLResult_Ok	Successfully created the tracker.
MLResult	MLResult_PermissionDenied	Necessary permission is missing.
MLResult	MLResult_UnspecifiedFailure	The tracker was not created.

Required Permissions:

com.magicleap.permission.SPATIAL_ANCHOR (protection level: normal)

API Level:

MLSpatialAnchorTrackerDestroy

MLResult MLSpatialAnchorTrackerDestroy(
    MLHandle handle
)

Destroy a previously created Spatial Anchor tracker.

Parameters


MLHandle	handle	A handle to a Spatial Anchor tracker created by MLSpatialAnchorCreate().

Returns


MLResult	MLResult_InvalidParam	The handle parameter was not valid.
MLResult	MLResult_Ok	Successfully destroyed the tracker.
MLResult	MLResult_UnspecifiedFailure	The tracker was not destroyed.

Required Permissions:

None

API Level:

MLSpatialAnchorCreate

MLResult MLSpatialAnchorCreate(
    MLHandle handle,
    const MLSpatialAnchorCreateInfo * create_info,
    MLSpatialAnchor * out_anchor
)

Create a new local Spatial Anchor at the desired location.

Parameters


MLHandle	handle	Handle to a Spatial Anchor tracker.
const MLSpatialAnchorCreateInfo *	create_info	A struct containing the creation info for the new anchor.
MLSpatialAnchor *	out_anchor	The created anchor.

Returns


MLResult	MLResult_InvalidParam	One of the parameters was null.
MLResult	MLResult_Ok	The anchor was successfully created.
MLResult	MLSpatialAnchorResult_InsufficientMapping	Insufficient mapping.
MLResult	MLSpatialAnchorResult_InvalidExpirationTimestamp	Invalid expiration timestamp.
MLResult	MLSpatialAnchorResult_MaxAnchorLimitReached	Maximum anchor limit reached.
MLResult	MLSpatialAnchorResult_MinDistanceThresholdExceeded	Minimum distance threshold exceeded.

Required Permissions:

None

On success, out_anchor will be returned with a newly generated ID.

Any unpublished anchor will be lost if the Headpose session is lost. See MLHeadTrackingGetMapEvents for more details.

API Level:

MLSpatialAnchorPublish

MLResult MLSpatialAnchorPublish(
    MLHandle handle,
    MLUUID anchor_id
)

Publish an existing local Spatial Anchor to the persistent backend.

Parameters


MLHandle	handle	Handle to a Spatial Anchor tracker.
MLUUID	anchor_id	The Id of the local anchor to publish.

Returns


MLResult	MLResult_InvalidParam	One of the parameters was null.
MLResult	MLResult_Ok	The anchor was successfully published and persisted.
MLResult	MLResult_Unauthenticated	Invalid authentication credentials for this operation.
MLResult	MLSpatialAnchorResult_NotLocalized	Not localized.
MLResult	MLSpatialAnchorResult_InvalidId	Invalid Id provided.
MLResult	MLSpatialAnchorResult_MaxAnchorLimitReached	Maximum anchor limit reached.
MLResult	MLSpatialAnchorResult_MinDistanceThresholdExceeded	Minimum distance threshold exceeded.
MLResult	MLSpatialAnchorResult_ServerError	Server error occurred.

Required Permissions:

None

Depending on the currently selected mapping mode, this can store the anchor locally or in the cloud. This call will fail if the device is not localized to a space.

Any unpublished anchor will be lost if the Headpose session is lost. See MLHeadTrackingGetMapEvents for more details.

API Level:

MLSpatialAnchorDelete

MLResult MLSpatialAnchorDelete(
    MLHandle handle,
    MLUUID anchor_id
)

Delete an existing Spatial Anchor.

Parameters


MLHandle	handle	Handle to a Spatial Anchor tracker.
MLUUID	anchor_id	The Id of the anchor to delete.

Returns


MLResult	MLResult_InvalidParam	One of the parameters was null.
MLResult	MLResult_Ok	The anchor was successfully deleted.
MLResult	MLResult_Unauthenticated	Invalid authentication credentials for this operation.
MLResult	MLSpatialAnchorResult_InvalidId	Invalid Id provided.
MLResult	MLSpatialAnchorResult_ServerError	Server error occurred.

Required Permissions:

None

If successful, this will delete the anchor from persistent storage based on the currently selected mapping mode.

API Level:

MLSpatialAnchorUpdate

MLResult MLSpatialAnchorUpdate(
    MLHandle handle,
    const MLSpatialAnchor * anchor
)

Update a Spatial Anchor's properties.

Parameters


MLHandle	handle	Handle to a Spatial Anchor tracker.
const MLSpatialAnchor *	anchor	The anchor containing the desired updated properties.

Returns


MLResult	MLResult_InvalidParam	One of the parameters was null.
MLResult	MLResult_Ok	The anchor was successfully updated.
MLResult	MLResult_Unauthenticated	Invalid authentication credentials for this operation.
MLResult	MLSpatialAnchorResult_InvalidId	Invalid Id provided.
MLResult	MLSpatialAnchorResult_InvalidExpirationTimestamp	Invalid expiration timestamp.
MLResult	MLSpatialAnchorResult_ServerError	Server error occurred.

Required Permissions:

None

The only property that can currently be updated is the expiration timestamp.

API Level:

MLSpatialAnchorQueryCreate

MLResult MLSpatialAnchorQueryCreate(
    MLHandle handle,
    const MLSpatialAnchorQueryFilter * query_filter,
    MLHandle * out_query_handle,
    uint32_t * out_results_count
)

Create a new query for Spatial Anchors in the current space.

Parameters


MLHandle	handle	Handle to a Spatial Anchor tracker.
const MLSpatialAnchorQueryFilter *	query_filter	The filter structure for the query.
MLHandle *	out_query_handle	The handle for this query to be used with MLSpatialAnchorQueryGetResult.
uint32_t *	out_results_count	The total number of entries found by the query. This can be any number between 0 and max_results.

Returns


MLResult	MLResult_InvalidParam	One of the parameters was null.
MLResult	MLResult_Ok	The query executed successfully.
MLResult	MLResult_UnspecifiedFailure	Unspecified error occurred.
MLResult	MLSpatialAnchorResult_NotLocalized	Not localized to a space.

Required Permissions:

None

It is the responsibility of the caller to call MLSpatialAnchorQueryDestroy with the query handle returned from this function after the results are no longer needed.

API Level:

MLSpatialAnchorQueryDestroy

MLResult MLSpatialAnchorQueryDestroy(
    MLHandle handle,
    MLHandle query_handle
)

Destroy a previously created query handle and release its associated resources.

Parameters


MLHandle	handle	Handle to a Spatial Anchor tracker.
MLHandle	query_handle	Handle to a Spatial Anchor query.

Returns


MLResult	MLResult_InvalidParam	One of the parameters was null.
MLResult	MLResult_Ok	The handle was successfully destroyed.

Required Permissions:

None

API Level:

MLSpatialAnchorQueryGetResult

MLResult MLSpatialAnchorQueryGetResult(
    MLHandle handle,
    MLHandle query_handle,
    uint32_t first_index,
    uint32_t last_index,
    MLSpatialAnchor * out_results
)

Get the result of a previous Spatial Anchor query.

Parameters


MLHandle	handle	Handle to a Spatial Anchor tracker.
MLHandle	query_handle	Handle to a query obtained from MLSpatialAnchorQuery.
uint32_t	first_index	The first index.
uint32_t	last_index	The last index.
MLSpatialAnchor *	out_results	An array of (last_index - first_index + 1) size to hold the query results.

Returns


MLResult	MLResult_Ok	The query executed successfully.
MLResult	MLResult_InvalidParam	One of the parameters was incorrect.
MLResult	MLResult_UnspecifiedFailure	Unspecified failure occurred.
MLResult	MLSpatialAnchorResult_NotLocalized	Not localized to a space.

Required Permissions:

None

Putting index bounds on the results allows the caller to only receive a subset of the total number of results generated by the query. This is useful as a form of pagination in the case of a large number of anchors in the current space. Indexing is zero-based so if there are N results in the query, then it is required that 0 <= first_index <= last_index < N.

API Level:

MLSpatialAnchorGetResultString

const char * MLSpatialAnchorGetResultString(
    MLResult result
)

Returns an ASCII string for MLSpatialAnchorResult and MLResult codes.

Parameters


MLResult	result	The input MLResult enum from MLSpatialAnchor functions.

Required Permissions:

None

Return: ASCII string containing readable version of result code.

API Level:

MLSpatialAnchorGetLocalizationInfo

MLResult MLSpatialAnchorGetLocalizationInfo(
    MLHandle handle,
    MLSpatialAnchorLocalizationInfo * out_localization_info
)

Get the current localization status of the device.

Parameters


MLHandle	handle	Handle to a Spatial Anchor tracker.
MLSpatialAnchorLocalizationInfo *	out_localization_info	The localization info structure to be populated.

Returns


MLResult	MLResult_Ok	The query executed successfully.
MLResult	MLResult_InvalidParam	One of the parameters was incorrect.
MLResult	MLResult_UnspecifiedFailure	Unspecified failure occurred.

Required Permissions:

None

Deprecated

Deprecated since 1.3.0. Scheduled for removal. Replaced by MLSpaceGetLocalizationResult.

API Level:

Spatial Anchor

Classes​

Types​

Enums​

Functions​

Detailed Description​

Enums Documentation​

Anonymous Enum 29​

MLSpatialAnchorResult​

MLSpatialAnchorLocalizationStatus​

MLSpatialAnchorMappingMode​

MLSpatialAnchorQuality​

Types Documentation​

MLSpatialAnchorLocalizationInfo​

MLSpatialAnchor​

MLSpatialAnchorCreateInfo​

MLSpatialAnchorQueryFilter​

Functions Documentation​

MLSpatialAnchorLocalizationInfoInit​

MLSpatialAnchorInit​

MLSpatialAnchorCreateInfoInit​

MLSpatialAnchorQueryFilterInit​

MLSpatialAnchorTrackerCreate​

MLSpatialAnchorTrackerDestroy​

MLSpatialAnchorCreate​

MLSpatialAnchorPublish​

MLSpatialAnchorDelete​

MLSpatialAnchorUpdate​

MLSpatialAnchorQueryCreate​

MLSpatialAnchorQueryDestroy​

MLSpatialAnchorQueryGetResult​

MLSpatialAnchorGetResultString​

MLSpatialAnchorGetLocalizationInfo​

Classes

Types

Enums

Functions

Detailed Description

Enums Documentation

Anonymous Enum 29

MLSpatialAnchorResult

MLSpatialAnchorLocalizationStatus

MLSpatialAnchorMappingMode

MLSpatialAnchorQuality

Types Documentation

MLSpatialAnchorLocalizationInfo

MLSpatialAnchor

MLSpatialAnchorCreateInfo

MLSpatialAnchorQueryFilter

Functions Documentation

MLSpatialAnchorLocalizationInfoInit

MLSpatialAnchorInit

MLSpatialAnchorCreateInfoInit

MLSpatialAnchorQueryFilterInit

MLSpatialAnchorTrackerCreate

MLSpatialAnchorTrackerDestroy

MLSpatialAnchorCreate

MLSpatialAnchorPublish

MLSpatialAnchorDelete

MLSpatialAnchorUpdate

MLSpatialAnchorQueryCreate

MLSpatialAnchorQueryDestroy

MLSpatialAnchorQueryGetResult

MLSpatialAnchorGetResultString

MLSpatialAnchorGetLocalizationInfo