Package com.indooratlas.android.sdk
Interface IAARSession
-
@Restricted @Beta public interface IAARSession
IndoorAtlas AR fusion APINOTE! 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
All Methods Instance Methods Abstract Methods Modifier and Type Method Description void
addArPlane(float[] center, float extentX, float extentZ)
Input AR plane tracking information.IALocation
arToGeo(float[] modelMatrix)
Convert from AR to geographic coordinatesIALocation
arToGeo(float x, float y, float z)
Convert from AR to geographic coordinatesboolean
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 coordinatesboolean
geoToAr(double lat, double lng, int floorNumber, float[] modelMatrix)
Convert from geographical to AR coordinates, with default rotation and no vertical offsetboolean
geoToAr(IALocation iaLocation, float[] modelMatrix)
Convert from geographical to AR coordinates (with no vertical offset)IAARObject
getWayfindingCompassArrow()
IAARObject
getWayfindingTarget()
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 wayfindingvoid
updateRoute(IARoute route)
Update AR route manually.
-
-
-
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 degreeslng
- longitude in degreesfloorNumber
- IndoorAtlas integer floor numberheading
- heading in degrees 0=North, 90=East, 180=South, 270=WestzOffset
- Vertical offset from the floor plane in metersmodelMatrix
- 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 degereeslng
- longitude in degreesfloorNumber
- IndoorAtlas floor numbermodelMatrix
- 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 degreeslng
- longitude in degreesfloorNumber
- IndoorAtlas integer floor numberheading
- heading in degrees 0=North, 90=East, 180=South, 270=WestzOffset
- 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
-
updateRoute
void updateRoute(IARoute route)
Update AR route manually. Calling this method is only required if not using IndoorAtlas wayfinding.You should update the route each time location changes to keep it in sync. If this method is used while also using IndoorAtlas wayfinding, the route will not be updated automatically anymore.- Parameters:
route
- The current route graph from the current location
-
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
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.
-
-