GARSession(Geospatial)
Category adding Geospatial functionality to GARSession
.
Summary
Public methods |
|
---|---|
checkVPSAvailabilityAtCoordinate:
|
Gets the availability of the Visual Positioning System (VPS) at a specified horizontal position.
|
createAnchorOnStreetscapeGeometry:
|
nullable GARAnchor *
Creates an anchor at the given transform in the world coordinate space, attached to this
GARStreetscapeGeometry , and acquires a reference to it. |
createAnchorWithCoordinate:
|
nullable GARAnchor *
Creates a Geospatial anchor at the specified geodetic location and orientation relative to the Earth.
|
createAnchorWithCoordinate:
|
nullable GARCreateAnchorOnRooftopFuture *
Asynchronously creates a Rooftop anchor at the specified horizontal position and altitude relative to the horizontal position's rooftop.
|
createAnchorWithCoordinate:
|
nullable GARCreateAnchorOnTerrainFuture *
Asynchronously creates a Terrain anchor at a specified horizontal position and altitude relative to the horizontal position's terrain.
|
createAnchorWithCoordinate:
|
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.
|
geospatialTransformFromTransform:
|
nullable GARGeospatialTransform *
Converts the provided transform to a
GARGeospatialTransform with respect to the Earth. |
isGeospatialModeSupported:
|
BOOL
Determines whether the given geospatial mode is supported on the current device and OS version.
|
raycastStreetscapeGeometry:
|
nullable NSArray< GARStreetscapeGeometryRaycastResult * > *
Performs a raycast against Streetscape Geometry loaded by the scene.
|
transformFromGeospatialCoordinate:
|
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.
|
Public methods
checkVPSAvailabilityAtCoordinate:completionHandler:
- (GARVPSAvailabilityFuture *)checkVPSAvailabilityAtCoordinate:(CLLocationCoordinate2D) coordinatecompletionHandler:(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. See GARFuture
for information on obtaining results and cancelling the operation.
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 |
|
||||
Returns |
GARSession
.createAnchorOnStreetscapeGeometry:transform:error:
- (nullable GARAnchor *)createAnchorOnStreetscapeGeometry:(GARStreetscapeGeometry *) geometrytransform:(matrix_float4x4) transformerror:(NSError **) error
Creates an anchor at the given transform in the world coordinate space, attached to this GARStreetscapeGeometry
, and acquires a reference to it.
Details | |||||||
---|---|---|---|---|---|---|---|
Parameters |
|
||||||
Returns |
The new anchor, or
nil if there was an error. |
GARSession
.createAnchorWithCoordinate:altitude:eastUpSouthQAnchor:error:
- (nullable GARAnchor *)createAnchorWithCoordinate:(CLLocationCoordinate2D) coordinatealtitude:(CLLocationDistance) altitudeeastUpSouthQAnchor:(simd_quatf) eastUpSouthQAnchorerror:(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 |
|
||||||||
Returns |
The new anchor, or
nil if there was an error. |
GARSession
.createAnchorWithCoordinate:altitudeAboveRooftop:eastUpSouthQAnchor:completionHandler:error:
- (nullable GARCreateAnchorOnRooftopFuture *)createAnchorWithCoordinate:(CLLocationCoordinate2D) coordinatealtitudeAboveRooftop:(CLLocationDistance) altitudeAboveRooftopeastUpSouthQAnchor:(simd_quatf) eastUpSouthQAnchorcompletionHandler:(void(^)(GARAnchor *_Nullable anchor, GARRooftopAnchorState rooftopState)) completionHandlererror:(NSError **) error
Asynchronously creates a Rooftop anchor at the specified horizontal position and altitude relative to the horizontal position's rooftop.
See the Rooftop anchors developer guide for more information.
The specified altitudeAboveRooftop
is interpreted to be relative to the top of a building at the given horizontal location, rather than relative to the WGS84 ellipsoid. If there is no building at the given location, then the altitude is interpreted to be relative to the terrain instead. Specifying an altitude of 0 will position the anchor directly on the rooftop whereas specifying a positive altitude will position the anchor above the rooftop, against the direction of gravity.
This launches an asynchronous operation used to query the Google Cloud ARCore API. See GARFuture
for information on obtaining results and cancelling the operation.
You may resolve multiple anchors at a time, but a session cannot be tracking more than 100 Rooftop or Terrain anchors at time. Attempting to resolve more than 100 Rooftop or Terrain anchors will result in GARSessionErrorCodeResourceExhausted
.
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 GARTrackingStateTracking
while GAREarth
is GARTrackingStateTracking
. 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 |
|
||||||||||
Returns |
GARSession
.createAnchorWithCoordinate:altitudeAboveTerrain:eastUpSouthQAnchor:completionHandler:error:
- (nullable GARCreateAnchorOnTerrainFuture *)createAnchorWithCoordinate:(CLLocationCoordinate2D) coordinatealtitudeAboveTerrain:(CLLocationDistance) altitudeAboveTerraineastUpSouthQAnchor:(simd_quatf) eastUpSouthQAnchorcompletionHandler:(void(^)(GARAnchor *_Nullable anchor, GARTerrainAnchorState terrainState)) completionHandlererror:(NSError **) error
Asynchronously creates a Terrain anchor at a specified horizontal position and altitude relative to the horizontal position's terrain.
See the Terrain anchors developer guide for more information.
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 whereas specifying a positive altitudeAboveTerrain
will position the anchor above the terrain, against the direction of gravity.
This launches an asynchronous operation used to query the Google Cloud ARCore API. See GARFuture
for information on obtaining results and cancelling the operation.
You may resolve multiple anchors at a time, but a session cannot be tracking more than 100 Rooftop or Terrain anchors at time. Attempting to resolve more than 100 Rooftop or Terrain anchors will result in GARSessionErrorCodeResourceExhausted
.
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 GARTrackingStateTracking
while GAREarth
is GARTrackingStateTracking
. 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 |
|
||||||||||
Returns |
GARSession
.createAnchorWithCoordinate:altitudeAboveTerrain:eastUpSouthQAnchor:error:
- (nullable GARAnchor *)createAnchorWithCoordinate:(CLLocationCoordinate2D) coordinatealtitudeAboveTerrain:(CLLocationDistance) altitudeAboveTerraineastUpSouthQAnchor:(simd_quatf) eastUpSouthQAnchorerror:(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.
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 GARTrackingStateTracking
while GAREarth
is GARTrackingStateTracking
. 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 |
|
||||||||
Returns |
The new anchor, or
nil if there was an error. |
GARSession
.geospatialTransformFromTransform:error:
- (nullable GARGeospatialTransform *)geospatialTransformFromTransform:(matrix_float4x4) transformerror:(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 |
|
||||
Returns |
GARGeospatialTransform , or nil if there was an error. |
GARSession
.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 |
|
||
Returns |
YES if the
geospatialMode is supported, NO otherwise. |
GARSession
.raycastStreetscapeGeometry:direction:error:
- (nullable NSArray< GARStreetscapeGeometryRaycastResult * > *)raycastStreetscapeGeometry:(simd_float3) origindirection:(simd_float3) directionerror:(NSError **) error
Performs a raycast against Streetscape Geometry loaded by the scene.
The raycast result contains the transform of the hit as well as the GARStreetscapeGeometry
that was hit.
Requires both GARSessionConfiguration.streetscapeGeometryMode
to be set to GARStreetscapeGeometryModeEnabled
and for GARSessionConfiguration.geospatialMode
to be set to GARGeospatialModeEnabled
.
Details | |||||||
---|---|---|---|---|---|---|---|
Parameters |
|
||||||
Returns |
The list of raycast hits, or
nil if there was an error. |
GARSession
.transformFromGeospatialCoordinate:altitude:eastUpSouthQTarget:error:
- (matrix_float4x4)transformFromGeospatialCoordinate:(CLLocationCoordinate2D) coordinatealtitude:(CLLocationDistance) altitudeeastUpSouthQTarget:(simd_quatf) eastUpSouthQTargeterror:(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 |
|
||||||||
Returns |
a local transform in world coordinate space.
|
GARSession
.