com.indooratlas.android.sdk

Interface IAARSession

@Restricted
 @Beta
public interface IAARSession

IndoorAtlas AR fusion API

NOTE! To enable AR features, please contact IndoorAtlas sales.

The AR API provides you with convenient means of converting between two important coordinate systems:

• The global coordinates encoded in IALocation objects and their components. In practice, this means latitude, longitude, floor number and heading/orientation information.
• An augmented reality (AR) coordinate system, which is assumed to be a right-handed 3D metric coordinate system, where the Y axis points up (towards the sky).

The local tracking of the device in the AR coordinate system is assumed to be handled by an external AR solution like ARCore, whose certain outputs are given to this class. The IndoorAtlas platform fuses this information with the IndoorAtlas position estimates and provides the relevant coordinate transforms in a stable and visually consistent manner, which allows you to easily place geographically referenced content in the AR world.

The methods of an instance of this class can be called from any thread.

Method Summary

Modifier and Type	Method and Description
void	addArPlane(float[] center, float extentX, float extentZ) Input AR plane tracking information.
IALocation	arToGeo(float[] modelMatrix) Convert from AR to geographic coordinates
IALocation	arToGeo(float x, float y, float z) Convert from AR to geographic coordinates
boolean	converged()
IAARObject	createArPOI(double lat, double lng, int floorNumber)
IAARObject	createArPOI(double lat, double lng, int floorNumber, double heading, double zOffset) Create an AR Point-of-Interest in the given geographical coordinates.
IAARObject	createArPOI(IALocation iaLocation)
void	destroy() Clean-up.
boolean	geoToAr(double lat, double lng, int floorNumber, double heading, double zOffset, float[] modelMatrix) Convert from geographical to AR coordinates
boolean	geoToAr(double lat, double lng, int floorNumber, float[] modelMatrix) Convert from geographical to AR coordinates, with default rotation and no vertical offset
boolean	geoToAr(IALocation iaLocation, float[] modelMatrix) Convert from geographical to AR coordinates (with no vertical offset)
IAARObject	getWayfindingCompassArrow()
IAARObject	getWayfindingTarget()
java.util.List<IAARObject>	getWayfindingTurnArrows()
void	setCameraToWorldMatrix(float[] currentCameraMatrix) Set the current camera matrix.
void	setPoseMatrix(float[] arPoseMatrix) Input current pose from the external AR tracking.
void	startWayfinding(IALatLngFloorCompatible to) Start AR wayfinding and enable the high-level AR wayfinding helper API, which manages the coordinates of certain wayfinding elements in the AR coordinate system in a visually consistent manner.
void	stopWayfinding() Stop AR wayfinding

Method Detail

setPoseMatrix

void setPoseMatrix(float[] arPoseMatrix)

Input current pose from the external AR tracking. This method should be called on each successfully tracked AR camera frame.

Parameters:

arPoseMatrix - Current "sensor pose" from AR tracking. A column-major representation of a 4x4 homogeneous IMU-to-world matrix, where the IMU coordinate system axes are as defined by the Android sensor coordinates.

setCameraToWorldMatrix

void setCameraToWorldMatrix(float[] currentCameraMatrix)

Set the current camera matrix. This method should be called on each successfully tracked AR camera frame.

Parameters:

currentCameraMatrix - A column-major representation of a 4x4 homogeneous camera-to-world matrix, where the the negative Z axis is points "into the screen" in camera coordinates. Unlike the IMU-to-world matrix given to the IAAR.setPoseMatrix method, this matrix may change with UI orientation.

addArPlane

void addArPlane(float[] center,
                float extentX,
                float extentZ)

Input AR plane tracking information. This input is optional, but allows more accurate vertical tracking, e.g., placing geo-referenced AR objects so that they appear to be on the floor. If used, should be called on each AR frame for each tracked horizontal upward-facing plane.

Parameters:

center - Horizontal plane center coordinates in the AR coordinate system. Array of 3 elements, { X, Y, Z }. (Y is the vertical coordinate)

extentX - Horizontal bounding box size along the X axis (AR coordinates)

extentZ - Horizontal bounding box size along the Z axis (AR coordinates)

geoToAr

boolean geoToAr(double lat,
                double lng,
                int floorNumber,
                double heading,
                double zOffset,
                float[] modelMatrix)

Convert from geographical to AR coordinates

Parameters:

lat - latitude in degrees

lng - longitude in degrees

floorNumber - IndoorAtlas integer floor number

heading - heading in degrees 0=North, 90=East, 180=South, 270=West

zOffset - Vertical offset from the floor plane in meters

modelMatrix - Output: a 4x4 homogeneous model-to-world matrix. Column-major format. Must contain exactly 16 elements.

Returns:

true if the conversion succeeded. In this case, the elements or modelMatrix are set. false otherwise. The conversion fails unless both IndoorAtlas positioning and the AR input have been obtained (i.e., before the first fix or before setPoseMatrix has been called for the first time).

geoToAr

boolean geoToAr(double lat,
                double lng,
                int floorNumber,
                float[] modelMatrix)

Convert from geographical to AR coordinates, with default rotation and no vertical offset

Parameters:

lat - latitude in degerees

lng - longitude in degrees

floorNumber - IndoorAtlas floor number

modelMatrix - Ouput: 4x4 homogeneous model-to-world matrix in column-major

Returns:

true if the conversion succeeded, false otherwise

geoToAr

boolean geoToAr(IALocation iaLocation,
                float[] modelMatrix)

Convert from geographical to AR coordinates (with no vertical offset)

Parameters:

iaLocation - geographical coordinates (bearing is used for rotation)

modelMatrix - Ouput: 4x4 homogeneous model-to-world matrix in column-major

Returns:

true if the conversion succeeded, false otherwise

arToGeo

IALocation arToGeo(float[] modelMatrix)

Convert from AR to geographic coordinates

Parameters:

modelMatrix - input 4x4 homogeneous model-to-world matrix in column-major

Returns:

geographical coordinates. Null if not available

arToGeo

IALocation arToGeo(float x,
                   float y,
                   float z)

Convert from AR to geographic coordinates

Parameters:

x - AR coordinate system X-coordinate (horizontal)

y - AR coordinate system Y-coordinate (vertical)

z - AR coordinate system Z-coordinate (horizontal)

Returns:

geographical coordinates. Null if not available

converged

boolean converged()

Returns:

check if the positioning session has approximately converged. If false, it is recommended to advise the user to walk for a couple of meters to any direction so that they coordinate systems can be oriented correctly. This is optional, but the ArObjects may first appear in clearly incorrect directions on positions otherwise.

createArPOI

IAARObject createArPOI(double lat,
                       double lng,
                       int floorNumber,
                       double heading,
                       double zOffset)

Create an AR Point-of-Interest in the given geographical coordinates. The coordinates of the object in the AR world update in a visually pleasing manner.

Parameters:

lat - latitude in degrees

lng - longitude in degrees

floorNumber - IndoorAtlas integer floor number

heading - heading in degrees 0=North, 90=East, 180=South, 270=West

zOffset - Vertical offset from the floor plane in meters

Returns:

ArObject

createArPOI

IAARObject createArPOI(double lat,
                       double lng,
                       int floorNumber)

createArPOI

IAARObject createArPOI(IALocation iaLocation)

startWayfinding

void startWayfinding(IALatLngFloorCompatible to)

Start AR wayfinding and enable the high-level AR wayfinding helper API, which manages the coordinates of certain wayfinding elements in the AR coordinate system in a visually consistent manner. The available managed elements are 1. Target object (getWayfindingTarget) 2. Compass arrow (getWayfindingTurnArrows) 3. Turn-by-turn navigation arrows (getWayfindingCompassArrow) Calling this will stop and replace any existing waydinding session in the SDK, including those created directly in IALocationManager.

Parameters:

to - Wayfinding target / destination

stopWayfinding

void stopWayfinding()

Stop AR wayfinding

getWayfindingTarget

IAARObject getWayfindingTarget()

Returns:

ArObject representing the wayfinding destination. Appears approximately stationary, updated discreetly based on new IndoorAtlas position information. Not valid (updateModelMatrix returns always false) unless startWayfinding has been called.

getWayfindingCompassArrow

IAARObject getWayfindingCompassArrow()

Returns:

ArObject representing a "compass arrow" which points approximately to the direction one should walk or where one should look for the next turn-by-turn navigation arrow. Turns clearly with the camera. Not valid unless startWayfinding has been called.

getWayfindingTurnArrows

java.util.List<IAARObject> getWayfindingTurnArrows()

Returns:

List of "turn-by-turn" navigation arrows for the first legs of the remaining wayfinding route. The list updates as the user advances on the route. Eventually all arrows may disappear (empty list) when sufficiently close to the final destination. Always empty unless startWayfinding.

destroy

void destroy()

Clean-up. Should be called when no this object is no longer used.