Skip to content

Sessions

This library is primarily structured around the CameraSession class and its derived classes: TrackingSession and ARSession.

Both classes provide device tracking capabilities in real-world environments, but they are intended for different use cases.

TrackingSession is designed to retrieve the device pose. This information can be:

  • visualized using standard representations (e.g., as a point on a map), or
  • used internally by the application without being exposed to the user interface.

ARSession, instead, is intended for the development of full Augmented Reality applications. It enables the rendering of virtual objects over the camera stream, typically with the support of a 3D engine.

GiPStech also provides a dedicated engine for this purpose, called AuRea, specifically optimized for Augmented Reality applications.

In the following sections, the basic functions required to perform tracking and to obtain the device pose in a local reference system are presented for both types of session.

The use of markers to obtain the pose in a world reference system is discussed in the Markers chapter.

Prepare / Dispose

Each session must be prepared before it can be used and properly disposed of when it is no longer needed. All other methods must be called between these two operations.

This is achieved through the CameraSession.prepare and CameraSession.dispose methods.

Note: Only one session can be active at a time.

Tracking / Rendering Loop

The main difference between TrackingSession and ARSession lies in how the camera frames are processed.

With TrackingSession, processing is handled in a separate thread. This thread is started using TrackingSession.start and stopped using TrackingSession.stop.

With ARSession, instead, the ARSession.update method must be explicitly called within the rendering loop of your engine.

When using the AuRea library, this process is handled automatically by the AuWorld class. Simply pass an ARSession instance to the AuWorld constructor, and it will take care of updating the session within the rendering loop.

Tracking State and Pose

The runtime exposes two streams that provide information about the current tracking process.

The CameraSession.trackingState stream emits a new TrackingState whenever the tracking state changes.

The CameraSession.rawPose stream provides the estimated device pose in the local tracking reference frame. Each update contains the device position and orientation produced by the tracking system. Unlike the world pose, the raw pose is expressed in the tracker's local reference frame and is not aligned to an external world coordinate system.

Whenever the TrackingState transitions from TRACKING to any other state, the local tracking reference frame may be reinitialized. Consequently, poses received from CameraSession.rawPose before and after the transition should not be assumed to belong to the same coordinate system.

The ARDK can provide input to other modules, such as the MDK LocationSession. To enable this integration, link the target module using the link function.

To release the associated resources, you must explicitly call the unlink function. Alternatively, call unlinkAll to unlink all connected modules at once.