GARSession

ARCore session class.

Summary

Adds ARCore features to an app using ARKit. All NSError's returned by methods in this class have domain GARSessionErrorDomain and code a value of GARSessionErrorCode. For Augmented Faces, see GARAugmentedFaceSession. See categories of this class for other features. Each feature must be turned on by using setConfiguration:error: (GARSession) prior to use.

Inheritance

Inherits from: NSObject

Properties
`currentFramePair`	`GARFramePair *` The most recent frame pair, containing the most recent `ARFrame` passed into `update:error:` and the corresponding returned `GARFrame`.
`delegate`	`id< GARSessionDelegate >` The delegate for receiving callbacks about the `GARSession`.
`delegateQueue`	`dispatch_queue_t` The dispatch queue on which the delegate receives calls.

Public static methods
`sessionWithAPIKey:bundleIdentifier:error:`	`nullable instancetype` Creates a `GARSession` with an API key and bundle identifier.
`sessionWithError:`	`nullable instancetype` Creates a `GARSession`.

Public methods
`checkVPSAvailabilityAtCoordinate:completionHandler:`	`GARVPSAvailabilityFuture *` Gets the availability of the Visual Positioning System (VPS) at a specified horizontal position.
`createAnchorWithCoordinate:altitude:eastUpSouthQAnchor:error:`	`nullable GARAnchor *` Creates a Geospatial anchor at the specified geodetic location and orientation relative to the Earth.
`createAnchorWithCoordinate:altitudeAboveTerrain:eastUpSouthQAnchor:error:`	`nullable GARAnchor *` Creates a Terrain anchor at the specified geodetic location, altitude relative to the horizontal position’s terrain and orientation relative to the Earth.
`estimateFeatureMapQualityForHosting:error:`	`GARFeatureMapQuality` Estimates the quality of the visual features seen by ARCore in the preceding few seconds and visible from the provided camera transform.
`geospatialTransformFromTransform:error:`	`nullable GARGeospatialTransform *` Converts the provided transform to a `GARGeospatialTransform` with respect to the Earth.
`hostCloudAnchor:TTLDays:error:`	`nullable GARAnchor *` This will create a new Cloud Anchor with a given lifetime in days, using the transform of the provided anchor.
`hostCloudAnchor:error:`	`nullable GARAnchor *` Hosts a new Cloud Anchor based on an `ARAnchor`.
`isGeospatialModeSupported:`	`BOOL` Determines whether the given geospatial mode is supported on the current device and OS version.
`removeAnchor:`	`void` Removes an anchor from the session.
`resolveCloudAnchorWithIdentifier:error:`	`nullable GARAnchor *` Resolves a Cloud Anchor with a given identifier.
`setAuthToken:`	`void` Provide an auth token to use when authenticating with Google Cloud Services.
`setConfiguration:error:`	`void` Sets the configuration for the session.
`transformFromGeospatialCoordinate:altitude:eastUpSouthQTarget:error:`	`matrix_float4x4` Converts the provided Earth specified horizontal position, altitude and rotation with respect to an east-up-south coordinate frame to a local transform in world coordinate space.
`update:error:`	`nullable GARFrame *` Updates the `GARSession` with an `ARFrame`.

Properties

currentFramePair

@property(atomic, readonly, nullable) GARFramePair *currentFramePair;

The most recent frame pair, containing the most recent ARFrame passed into update:error: and the corresponding returned GARFrame.

delegate

@property(atomic, weak, nullable) id delegate;

The delegate for receiving callbacks about the GARSession.

delegateQueue

@property(atomic, nullable) dispatch_queue_t delegateQueue;

The dispatch queue on which the delegate receives calls.

If nil, callbacks happen on the main thread.

Public static methods

sessionWithAPIKey:bundleIdentifier:error:

+ (nullable instancetype)sessionWithAPIKey:
(NSString *) apiKey
bundleIdentifier:
(nullable NSString *) bundleIdentifier
error:
(NSError **) error

Creates a GARSession with an API key and bundle identifier.

Details

Parameters

`apiKey`	Your API key for Google Cloud Services.
`bundleIdentifier`	The bundle identifier associated to your API key. If `nil`, defaults to `[[NSBundle mainBundle] bundleIdentifier]`.
`error`	Out parameter for an `NSError`. Possible errors: `GARSessionErrorCodeDeviceNotCompatible` - this device or OS version is not currently supported. `GARSessionErrorCodeInvalidArgument` - API key is `nil` or empty.

Returns

The new GARSession, or nil if there is an error.

sessionWithError:

+ (nullable instancetype)sessionWithError:
(NSError **) error

Creates a GARSession.

To authenticate with Google Cloud Services, use setAuthToken:.

Details

Parameters

error

Out parameter for an NSError. Possible errors:

GARSessionErrorCodeDeviceNotCompatible - this device or OS version is not currently supported.

Returns

The new GARSession, or nil if there is an error.

Public methods

checkVPSAvailabilityAtCoordinate:completionHandler:

- (GARVPSAvailabilityFuture *)checkVPSAvailabilityAtCoordinate:
(CLLocationCoordinate2D) coordinate
completionHandler:
(void(^)(GARVPSAvailability availability)) completionHandler

Gets the availability of the Visual Positioning System (VPS) at a specified horizontal position.

The availability of VPS in a given location helps to improve the quality of Geospatial localization and tracking accuracy.

This launches an asynchronous operation used to query the Google Cloud ARCore API. This function returns a GARVPSAvailabilityFuture which can be used to obtain the task's result. Its initial GARFutureState will be set to GARFutureStatePending. When the operation is completed, its GARFutureState will be set to GARFutureStateDone, and GARVPSAvailabilityFuture.state can be used to obtain the operation's result.

You may provide an optional completionHandler, which will be invoked when the operation is completed, unless the GARVPSAvailabilityFuture has been cancelled. The callback will be called on the Main thread.

Your app must be properly set up to communicate with the Google Cloud ARCore API in order to obtain a result from this call. See Check VPS Availability for more details on setup steps and usage examples.

Details

Parameters

`coordinate`	The coordinate at which to check availability.
`completionHandler`	Completion handler to be invoked on the Main thread, if not nil.

Returns

A handler that can be polled or cancelled. If the operation is cancelled, no callback will be invoked.

Provided by category GARSession(Geospatial).

createAnchorWithCoordinate:altitude:eastUpSouthQAnchor:error:

- (nullable GARAnchor *)createAnchorWithCoordinate:
(CLLocationCoordinate2D) coordinate
altitude:
(CLLocationDistance) altitude
eastUpSouthQAnchor:
(simd_quatf) eastUpSouthQAnchor
error:
(NSError **) error

Creates a Geospatial anchor at the specified geodetic location and orientation relative to the Earth.

Latitude and longitude are defined by the WGS84 specification, and altitude values are defined as the elevation above the WGS84 ellipsoid in meters.

The rotation provided by eastUpSouthQAnchor is a rotation with respect to an east-up-south coordinate frame. An identity rotation will have the anchor oriented such that X+ points to the east, Y+ points up away from the center of the earth, and Z+ points to the south.

An anchor's GARAnchor.trackingState will be GARTrackingStatePaused while GAREarth is GARTrackingStatePaused. The tracking state will permanently become GARTrackingStateStopped if the GARSession configuration is set to GARGeospatialModeDisabled.

Creating anchors near the north pole or south pole is not supported. If the latitude is within 0.1° of the north pole or south pole (90° or -90 °), this function will output GARSessionErrorCodeInvalidArgument and the anchor will fail to be created.

Details

Parameters

`coordinate`	The latitude and longitude associated with the location, specified using the WGS84 reference frame. This must not be within .1° of the North or South pole (i.e. +- 90°).
`altitude`	Altitude in reference to the WGS 84 ellipsoid, in meters. Positive values indicate altitudes above approximate sea level. Negative values indicate altitudes below approximate sea level.
`eastUpSouthQAnchor`	Represents the quaternion from the anchor to East-Up-South (EUS) coordinates (i.e., +X points East, +Y points up, and +Z points South).
`error`	Out param for an `NSError`. Possible error codes: `GARSessionErrorCodeIllegalState` - current geospatial mode is disabled. `GARSessionErrorCodeInvalidArgument` - latitude is not within range.

Returns

The new anchor, or nil if there was an error.

Provided by category GARSession(Geospatial).

createAnchorWithCoordinate:altitudeAboveTerrain:eastUpSouthQAnchor:error:

- (nullable GARAnchor *)createAnchorWithCoordinate:
(CLLocationCoordinate2D) coordinate
altitudeAboveTerrain:
(CLLocationDistance) altitudeAboveTerrain
eastUpSouthQAnchor:
(simd_quatf) eastUpSouthQAnchor
error:
(NSError **) error

Creates a Terrain anchor at the specified geodetic location, altitude relative to the horizontal position’s terrain and orientation relative to the Earth.

Terrain means the ground, or ground floor inside a building with VPS coverage.

The specified altitudeAboveTerrain is interpreted to be relative to the Earth's terrain (or floor) at the specified latitude/longitude geodetic coordinates, rather than relative to the WGS-84 ellipsoid. Specifying an altitudeAboveTerrain of 0 will position the anchor directly on the terrain (or floor) whereas specifying a positive altitudeAboveTerrain will position the anchor above the terrain (or floor), against the direction of gravity.

This function schedules a task to resolve the anchor's pose using the given parameters. You may resolve multiple anchors at a time, but a session cannot be tracking more than 100 Terrain anchors at time. Attempting to resolve more than 100 Terrain anchors will result in GARSessionErrorCodeResourceExhausted.

If this function returns error nil, the terrain anchor's GARAnchor.terrainState will be GARTerrainAnchorStateTaskInProgress, and its tracking state will be GARTrackingStatePaused. This anchor remains in this state until its pose has been successfully resolved. If the resolving task results in an error, the tracking state will be set to GARTrackingStateStopped.

Latitude and longitude are defined by the WGS84 specification, and altitude values are defined as the elevation above the WGS84 ellipsoid in meters.

An anchor's GARAnchor.trackingState will be GARTrackingStateTracking while GAREarth is GARTrackingStatePaused. The tracking state will permanently become GARTrackingStateStopped if the GARSession configuration is set to GARGeospatialModeDisabled.

Creating anchors near the north pole or south pole is not supported. If the latitude is within 0.1° of the north pole or south pole (90° or -90°), this function will output GARSessionErrorCodeInvalidArgument and the anchor will fail to be created.

Details

Parameters

`coordinate`	The latitude and longitude associated with the location, specified using the WGS84 reference frame. This must not be within .1° of the North or South pole (i.e. +- 90°).
`altitudeAboveTerrain`	Altitude above Earth's terrain, in meters.
`eastUpSouthQAnchor`	Represents the quaternion from the anchor to East-Up-South (EUS) coordinates (i.e., +X points East, +Y points up, and +Z points South).
`error`	Out param for an `NSError`. Possible error codes: `GARSessionErrorCodeIllegalState` - current Geospatial mode is disabled. `GARSessionErrorCodeInvalidArgument` - latitude is not within range. `GARSessionErrorCodeResourceExhausted` - tried to create too many Terrain anchors.

Returns

The new anchor, or nil if there was an error.

Provided by category GARSession(Geospatial).

estimateFeatureMapQualityForHosting:error:

- (GARFeatureMapQuality)estimateFeatureMapQualityForHosting:
(simd_float4x4) transform
error:
(NSError **) error

Estimates the quality of the visual features seen by ARCore in the preceding few seconds and visible from the provided camera transform.

Cloud Anchors hosted using higher quality features will generally result in easier and more accurately resolved Cloud Anchor transforms.

Details

Parameters

`transform`	The camera transform to use in estimating the quality.
`error`	Out parameter for an `NSError`. Possible errors: `GARSessionErrorCodeNotTracking` - bad current `ARTrackingState`. `GARSessionErrorCodeIllegalState` - current cloud anchor mode is disabled.

Returns

The estimated quality of the visual features seen by ARCore in the preceding few seconds and visible from the provided camera transform.

Provided by category GARSession(CloudAnchors).

geospatialTransformFromTransform:error:

- (nullable GARGeospatialTransform *)geospatialTransformFromTransform:
(matrix_float4x4) transform
error:
(NSError **) error

Converts the provided transform to a GARGeospatialTransform with respect to the Earth.

Its heading will be zero for a GARGeospatialTransform returned from this method.

Details

Parameters

`transform`	The local transform in world coordinate space.
`error`	Out param for an `NSError`. Possible error codes: `GARSessionErrorCodeIllegalState` - current Geospatial mode is disabled. `GARSessionErrorCodeNotTracking` - Earth's or Session's `ARTrackingState` is not `GARTrackingStateTracking`.

Returns

GARGeospatialTransform, or nil if there was an error.

Provided by category GARSession(Geospatial).

hostCloudAnchor:TTLDays:error:

- (nullable GARAnchor *)hostCloudAnchor:
(ARAnchor *) anchor
TTLDays:
(NSInteger) TTLDays
error:
(NSError **) error

This will create a new Cloud Anchor with a given lifetime in days, using the transform of the provided anchor.

The cloud state of the returned anchor will be set to GARCloudAnchorStateTaskInProgress and the initial transform will be set to the transform of the provided anchor. However, the returned anchor is completely independent of the original anchor, and the two transforms might diverge over time.

Hosting requires an active session for which the tracking state is ARTrackingStateNormal, as well as a working internet connection. ARCore will continue to retry silently in the background if it is unable to establish a connection to the ARCore API service.

Details

Parameters

`anchor`	The `ARAnchor` with the desired transform to be used to create a hosted Cloud Anchor.
`TTLDays`	The lifetime of the anchor in days. Must be positive. The maximum allowed value is 1 if using an API Key to authenticate with the ARCore API service, otherwise the maximum allowed value is 365.
`error`	Out parameter for an `NSError`. Possible errors: `GARSessionErrorCodeInvalidArgument` - invalid (`nil`) anchor or invalid TTL. `GARSessionErrorCodeNotTracking` - bad current `ARTrackingState`. `GARSessionErrorCodeResourceExhausted` - tried to create too many Cloud Anchors. `GARSessionErrorCodeIllegalState` - current cloud anchor mode is disabled.

Returns

The new GARAnchor, or nil if there is an error.

Provided by category GARSession(CloudAnchors).

hostCloudAnchor:error:

- (nullable GARAnchor *)hostCloudAnchor:
(ARAnchor *) anchor
error:
(NSError **) error

Hosts a new Cloud Anchor based on an ARAnchor.

The new anchor will have a cloud state of GARCloudAnchorStateTaskInProgress and its initial transform will be set to that of the passed-in anchor. However, the two transforms may differ over time.

Details

Parameters

`anchor`	The `ARAnchor` to host.
`error`	Out parameter for an `NSError`. Possible errors: `GARSessionErrorCodeInvalidArgument` - invalid (`nil`) anchor. `GARSessionErrorCodeNotTracking` - bad current `ARTrackingState`. `GARSessionErrorCodeResourceExhausted` - tried to create too many Cloud Anchors. `GARSessionErrorCodeIllegalState` - current cloud anchor mode is disabled.

Returns

The new GARAnchor, or nil if there is an error.

Provided by category GARSession(CloudAnchors).

isGeospatialModeSupported:

- (BOOL)isGeospatialModeSupported:
(GARGeospatialMode) geospatialMode

Determines whether the given geospatial mode is supported on the current device and OS version.

If this returns NO, then configuring the session with the given geospatial mode will fail with the error code GARSessionErrorCodeConfigurationNotSupported. A device may be incompatible with a given mode due to insufficient sensor capabilities.

Details

Parameters

geospatialMode

The Geospatial mode.

Returns

YES if the geospatialMode is supported, NO otherwise.

Provided by category GARSession(Geospatial).

removeAnchor:

- (void)removeAnchor:
(GARAnchor *) anchor

Removes an anchor from the session.

Details

Parameters

anchor

The anchor to remove.

resolveCloudAnchorWithIdentifier:error:

- (nullable GARAnchor *)resolveCloudAnchorWithIdentifier:
(NSString *) identifier
error:
(NSError **) error

Resolves a Cloud Anchor with a given identifier.

The new anchor is immediately added to the session and returned, but without a valid transform. You don’t need to wait for a call to resolve a Cloud Anchor to complete before initiating another call. A session can be resolving up to 40 Cloud Anchors at a given time. If resolving fails, the anchor will be automatically removed from the session.

Details

Parameters

`identifier`	The Cloud Anchor identifier for the anchor.
`error`	Out parameter for an `NSError`. Possible errors: `GARSessionErrorCodeInvalidArgument` - invalid (`nil` or empty) identifier. `GARSessionErrorCodeResourceExhausted` - tried to create too many Cloud Anchors. `GARSessionErrorCodeIllegalState` - current cloud anchor mode is disabled.

Returns

The new GARAnchor, or nil if there is an error.

Provided by category GARSession(CloudAnchors).

setAuthToken:

- (void)setAuthToken:
(NSString *) authToken

Provide an auth token to use when authenticating with Google Cloud Services.

If the session was created with an API Key, the token will be ignored and an error will be logged. Otherwise, the most recent valid auth token passed in will be used. Call this method each time you refresh your token.

Details

Parameters

authToken

Token to use when authenticating with Google Cloud Services. This must be a nonempty ASCII string with no spaces or control characters. This will be used until another token is passed in. See documentation for supported token types.

setConfiguration:error:

- (void)setConfiguration:
(GARSessionConfiguration *) configuration
error:
(NSError **) error

Sets the configuration for the session.

Details

Parameters

`configuration`	The new configuration to use.
`error`	Out param for an `NSError`.

transformFromGeospatialCoordinate:altitude:eastUpSouthQTarget:error:

- (matrix_float4x4)transformFromGeospatialCoordinate:
(CLLocationCoordinate2D) coordinate
altitude:
(CLLocationDistance) altitude
eastUpSouthQTarget:
(simd_quatf) eastUpSouthQTarget
error:
(NSError **) error

Converts the provided Earth specified horizontal position, altitude and rotation with respect to an east-up-south coordinate frame to a local transform in world coordinate space.

Details

Parameters

`coordinate`	The latitude and longitude associated with the location, specified using the WGS84 reference frame. This must not be within .1° of the North or South pole (i.e. +- 90°).
`altitude`	Altitude in reference to the WGS 84 ellipsoid, in meters. Positive values indicate altitudes above approximate sea level. Negative values indicate altitudes below approximate sea level.
`eastUpSouthQTarget`	Represents the quaternion from the target to East-Up-South (EUS) coordinates (i.e., +X points East, +Y points up, and +Z points South).
`error`	Out param for an `NSError`. Possible error codes: `GARSessionErrorCodeIllegalState` - current Geospatial mode is disabled. `GARSessionErrorCodeNotTracking` - Earth's or Session's `ARTrackingState` is not `GARTrackingStateTracking`. `GARSessionErrorCodeInvalidArgument` - latitude is not within range.

Returns

a local transform in world coordinate space.

Provided by category GARSession(Geospatial).

update:error:

- (nullable GARFrame *)update:
(ARFrame *) frame
error:
(NSError **) error

Updates the GARSession with an ARFrame.

Call this method with every ARFrame to keep the sessions synced. Can be called on any thread. Normally, this should be called from your ARSessionDelegate's session:didUpdateFrame: method.

Details

Parameters

`frame`	The next `ARFrame` from ARKit.
`error`	Out parameter for `NSError`. Possible errors: `GARSessionErrorCodeInvalidArgument` - invalid (`nil`) frame. `GARSessionErrorCodeFrameOutOfOrder` - frame has a smaller timestamp than previous.

Returns

The GARFrame corresponding to the ARFrame passed in, or nil if there is an error.