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 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)
      • 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

        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.