Class ASACloudSpatialAnchorSession

  • Article

Declaration

@interface ASACloudSpatialAnchorSession : NSObject;

Description

Use this class to create, locate and manage spatial anchors.

Methods

init

Initializes a new instance with a default configuration.

-(instancetype)init;

dispose

Stops this session and releases all associated resources.

-(void)dispose;

getAccessTokenWithAuthenticationToken

Gets the Azure Spatial Anchors access token from authentication token.

-(void)getAccessTokenWithAuthenticationToken:(NSString *)authenticationToken withCompletionHandler:(void (^)(NSString * value, NSError *error))completionHandler;

Parameters

  • authenticationToken - Authentication token.
  • completionHandler - The access token string.

Returns

  • void

getAccessTokenWithAccountKey

Gets the Azure Spatial Anchors access token from account key.

-(void)getAccessTokenWithAccountKey:(NSString *)accountKey withCompletionHandler:(void (^)(NSString * value, NSError *error))completionHandler;

Parameters

  • accountKey - Account key.
  • completionHandler - The access token string.

Returns

  • void

createAnchor

Creates a new persisted spatial anchor from the specified local anchor and string properties.

The local anchor passed into this method must have a valid transform. Note some platforms supported by Azure Spatial Anchors such as iOS allow transforms with scale component != 1.0. Azure Spatial Anchors SDK does not support such transforms and it will fail to create the spatial anchor with error code InvalidAnchorTransformRigidity. Any scale handling for anchors must be done at the app level.

-(void)createAnchor:(ASACloudSpatialAnchor *)anchor withCompletionHandler:(void (^)(NSError *error))completionHandler;

Parameters

  • anchor - Anchor to be persisted.
  • completionHandler - A task that represents the asynchronous creation operation.

Returns

  • void

createWatcher

Creates a new object that watches for anchors that meet the specified criteria.

-(ASACloudSpatialAnchorWatcher *)createWatcher:(ASAAnchorLocateCriteria *)criteria;

Parameters

  • criteria - Criteria for anchors to watch for.

Returns

  • ASACloudSpatialAnchorWatcher * - A new watcher object that continuously looks for anchors until the criteria is fully satisfied or the watcher is stopped. There can only be one active watcher at a time.

getAnchorProperties

Gets a cloud spatial anchor for the given identifier, even if it hasn't been located yet.

-(void)getAnchorProperties:(NSString *)identifier withCompletionHandler:(void (^)(ASACloudSpatialAnchor * value, NSError *error))completionHandler;

Parameters

  • identifier - The identifier to look for.
  • completionHandler - A task that represents the asynchronous retrieval operation. The anchor retrieved will have property values but may not have a local anchor available.

Returns

  • void

getNearbyAnchorIds

Gets a list of all nearby cloud spatial anchor ids corresponding to a given criteria.

-(void)getNearbyAnchorIds:(ASANearDeviceCriteria *)criteria withCompletionHandler:(void (^)(NSArray * value, NSError *error))completionHandler;

Parameters

  • criteria - The search criteria.
  • completionHandler - A task that represents the asynchronous retrieval operation.

Returns

  • void

getActiveWatchers

Gets a list of active watchers.

-(NSArray<ASACloudSpatialAnchorWatcher *> *)getActiveWatchers;

Returns

  • NSArray<ASACloudSpatialAnchorWatcher *> * - A list of active watchers.

refreshAnchorProperties

Refreshes properties for the specified spatial anchor.

-(void)refreshAnchorProperties:(ASACloudSpatialAnchor *)anchor withCompletionHandler:(void (^)(NSError *error))completionHandler;

Parameters

  • anchor - The anchor to refresh.
  • completionHandler - A task that represents the asynchronous refresh operation.

Returns

  • void

updateAnchorProperties

Updates the specified spatial anchor.

-(void)updateAnchorProperties:(ASACloudSpatialAnchor *)anchor withCompletionHandler:(void (^)(NSError *error))completionHandler;

Parameters

  • anchor - The anchor to be updated.
  • completionHandler - A task that represents the asynchronous update operation.

Returns

  • void

deleteAnchor

Deletes a persisted spatial anchor.

-(void)deleteAnchor:(ASACloudSpatialAnchor *)anchor withCompletionHandler:(void (^)(NSError *error))completionHandler;

Parameters

  • anchor - The anchor to be deleted.
  • completionHandler - A task that represents the asynchronous delete operation.

Returns

  • void

processFrame

Applications must call this method on platforms where per-frame processing is required.

This method is not available on the HoloLens platform.

-(void)processFrame:(ARFrame *)frame;

Parameters

  • frame - AR frame to process.

getSessionStatus

Gets an object describing the status of the session.

-(void)getSessionStatusWithCompletionHandler:(void (^)(ASASessionStatus * value, NSError *error))completionHandler;

Parameters

  • completionHandler - A task that represents the session status retrieval.

Returns

  • void

start

Begins capturing environment data for the session.

-(void)start;

stop

Stops capturing environment data for the session and cancels any outstanding locate operations. Environment data is maintained.

-(void)stop;

reset

Resets environment data that has been captured in this session; applications must call this method when tracking is lost.

On any platform, calling the method will clean all internal cached state.

-(void)reset;

Properties

delegate

An object you provide to receive events from this ASACloudSpatialAnchorSession instance.

@property(nonatomic, assign) id<ASACloudSpatialAnchorSessionDelegate> delegate;

configuration

The configuration information for the session.

Configuration settings take effect when the session is started.

@property (retain, readonly) ASASessionConfiguration * configuration;

diagnostics

The diagnostics settings for the session, which can be used to collect and submit data for troubleshooting and improvements.

@property (retain, readonly) ASACloudSpatialAnchorSessionDiagnostics * diagnostics;

logLevel

Logging level for the session log events.

@property ASASessionLogLevel logLevel;

session

The tracking session used to help locate anchors.

This property is not available on the HoloLens platform.

@property (retain) ARSession * session;

telemetryEnabled

This API can be used to enable or disable Azure Spatial Anchors SDK telemetry. ASA SDK telemetry is enabled by default. If disabled, ASA SDK will not log any telemetry event for this session. Applications that need to disable ASA SDK telemetry completely can use this API before calling CloudSpatialAnchorSession::Start, which would result in no telemetry event being sent for that CloudSpatialAnchorSession instance.

@property BOOL telemetryEnabled;

locationProvider

Location provider used to create and locate anchors using Coarse Relocalization.

@property (retain) ASAPlatformLocationProvider * locationProvider;

sessionId

The unique identifier for the session.

@property (retain, readonly) NSString * sessionId;