Head Tracker

This module calculates the predicted head's pose for a given timestamp.

Summary

It takes data from accelerometer and gyroscope sensors and uses a Kalman filter to generate the output value. The head's pose is returned as a quaternion. To have control of the usage of the sensors, this module also includes pause and resume functions.

Let the World frame be an arbitrary 3D Cartesian right handed frame whose basis is defined by a triplet of unit vectors (x, y, z) which point in the same direction as OpenGL. That is: x points to the right, y points up and z points backwards.

The head pose is always returned in the World frame. It is the average of the left and right eye position. By default, the head pose is near the origin, looking roughly forwards (down the -z axis).

Implementation and application code could refer to another three poses:

  • Raw sensor pose: no position, only orientation of device, derived directly from sensors.
  • Recentered sensor pose: like "Raw sensor pose", but with recentering applied.
  • Head pose: Recentered sensor pose, with neck model applied. The neck model only adjusts position, it does not adjust orientation. This is usually used directly as the camera pose, though it may be further adjusted via a scene graph. This is the only pose exposed through the API.

Functions

CardboardHeadTracker_create()
Creates a new head tracker object.
CardboardHeadTracker_destroy(CardboardHeadTracker *head_tracker)
void
Destroys and releases memory used by the provided head tracker object.
CardboardHeadTracker_getPose(CardboardHeadTracker *head_tracker, int64_t timestamp_ns, CardboardViewportOrientation viewport_orientation, float *position, float *orientation)
void
Gets the predicted head pose for a given timestamp.
CardboardHeadTracker_pause(CardboardHeadTracker *head_tracker)
void
Pauses head tracker and underlying device sensors.
CardboardHeadTracker_recenter(CardboardHeadTracker *head_tracker)
void
Recenters the head tracker.
CardboardHeadTracker_resume(CardboardHeadTracker *head_tracker)
void
Resumes head tracker and underlying device sensors.

Functions

CardboardHeadTracker_create

CardboardHeadTracker * CardboardHeadTracker_create()

Creates a new head tracker object.

Details
Returns
head tracker object pointer

CardboardHeadTracker_destroy

void CardboardHeadTracker_destroy(
  CardboardHeadTracker *head_tracker
)

Destroys and releases memory used by the provided head tracker object.

head_tracker Must not be null. When it is unmet, a call to this function results in a no-op.

Details
Parameters
head_tracker
Head tracker object pointer.

CardboardHeadTracker_getPose

void CardboardHeadTracker_getPose(
  CardboardHeadTracker *head_tracker,
  int64_t timestamp_ns,
  CardboardViewportOrientation viewport_orientation,
  float *position,
  float *orientation
)

Gets the predicted head pose for a given timestamp.

On Android devices, timestamp_ns must be in system boot time (see CLOCK_BOOTTIME) clock (see Android Timestamp). On iOS devices, timestamp_ns must be in system uptime raw (see CLOCK_UPTIME_RAW) clock (see Apple Timestamp).

head_tracker Must not be null. position Must not be null. orientation Must not be null. When it is unmet, a call to this function results in a no-op and default values are returned (zero values and identity quaternion, respectively).

Details
Parameters
head_tracker
Head tracker object pointer.
timestamp_ns
The timestamp for the pose in nanoseconds.
viewport_orientation
The viewport orientation.
position
3 floats for (x, y, z).
orientation
4 floats for quaternion

CardboardHeadTracker_pause

void CardboardHeadTracker_pause(
  CardboardHeadTracker *head_tracker
)

Pauses head tracker and underlying device sensors.

head_tracker Must not be null. When it is unmet, a call to this function results in a no-op.

Details
Parameters
head_tracker
Head tracker object pointer.

CardboardHeadTracker_recenter

void CardboardHeadTracker_recenter(
  CardboardHeadTracker *head_tracker
)

Recenters the head tracker.

Let Q_0 be the rotation quaternion that makes an arbitrary orientation aligned with a zero yaw angle. This function computes Q_0 with the current pose, and saves it as a rotation attribute in head_tracker. Future calls to CardboardHeadTracker_getPose() will be affected by Q_0. head_tracker Must not be null.

Details
Parameters
head_tracker
Head tracker object pointer.

CardboardHeadTracker_resume

void CardboardHeadTracker_resume(
  CardboardHeadTracker *head_tracker
)

Resumes head tracker and underlying device sensors.

head_tracker Must not be null. When it is unmet, a call to this function results in a no-op.

Details
Parameters
head_tracker
Head tracker object pointer.