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()`	`CardboardHeadTracker *` 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.

By recentering, the head_tracker orientation gets aligned with a zero yaw angle.

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.