Home > Devices > Fire Phone

Retrieving Head-Tracking Data

Introduction

The HeadTracking API offers two ways to retrieve head-tracking data:

  • By polling
  • As a listener

In either case, the API makes the following types of data available:

  • The timestamp of the latest head-tracking event.
  • Whether the software currently detects the user's face and is actively tracking the user's head.
  • The position of the head relative to screen orientation of the phone, as X, Y, and Z coordinates.
  • The angle at which the head is inclined right or left relative to the screen orientation of the phone.

Note: The content on this page applies to the Java version of the HeadTracking API. For the native-code version of this topic, see Retrieving Head-Tracking Data Using Native Code.  

The example code in the following procedures is the from the HeadTrackingSample sample app included with the Fire Phone SDK.

Retrieving Head-Tracking Data by Polling

To retrieve head-tracking by polling:

  1. Get a HeadTrackingManager object.
    mHeadTrackingManager = HeadTrackingManager.createInstance(thisActivity);
  2. From the HeadTrackingManager object, get a HeadTrackingPoller object.
    mHeadTrackingPoller = mHeadTrackingManager.registerPoller();
  3. From the event pool, get a HeadTrackingEventobject. This event object does not yet contain valid head-tracking data.
    mHeadTrackingEvent = HeadTrackingEvent.obtain();
  4. Get the latest head-tracking data by passing the event object to the sample()function. This function fills the event object with the latest head-tracking data.
    mHeadTrackingPoller.sample(mHeadTrackingEvent);
  5. Extract the head-tracking data from the event object..
    mXCoor.setText(getString(R.string.xcoor, mHeadTrackingEvent.x_mm));mYCoor.setText(getString(R.string.ycoor, mHeadTrackingEvent.y_mm));
    mZCoor.setText(getString(R.string.zcoor, mHeadTrackingEvent.z_mm));
    mFaceDetected.setText(getString(R.string.facedetected) + mHeadTrackingEvent.isFaceDetected);
    mHeadTracking.setText(getString(R.string.headtracking) + mHeadTrackingEvent.isTracking);

If your app does not need head tracking for a short period, it can pause head and save battery consumption by calling HeadTrackingManager.requestStandby() with the value true. If your app does not need head tracking for more than a few seconds, unregister by calling HeadTrackingManager.unregisterPoller(poller).

Note that when you register a poller, you might not get a head tracking event immediately afterward. Because the head tracking engine requires time to start, your first few polls might result in no head tracking data.

Retrieving Head-Tracking Data as a Listener

To retrieve head-tracking as a listener:

  1. Get an instance of the HeadTrackingManager.
    mHeadTrackingManager = HeadTrackingManager.createInstance(thisActivity);
  2. Register with the HeadTrackingManager as a listener for head-tracking events.
    mHeadTrackingManager.registerListener(thisActivity);
  3. Listen for events by implementing the onHeadTrackingEvent() method of the HeadTrackingListener interface.
  4. As events are received, extract the head-tracking data.
    final float x_coor = event.x_mm;
    final float y_coor = event.y_mm;
    final float z_coor = event.z_mm;
    final boolean face = event.isFaceDetected;
    final boolean tracking = event.isTracking;

If your app does not need head tracking for a short period, it can pause head and save battery consumption by calling HeadTrackingManager.requestStandby() with the value true. If your app does not need head tracking for more than a few seconds, unregister by calling HeadTrackingManager.unregisterListner(listener).