Usage

This guide will help you understand how to set up and use PyHeadTracker in your own projects. You can find examples and detailed API documentation in the respective sections.

Hardware Setup

Be sure to connect a supported head tracking device to your computer before running the software. Follow the manufacturer’s instructions for setting up the hardware. Many head trackers provide data in MIDI format via USB, e.g. the IEM MrHeadTracker or Supperware Head Tracker 1. Keep in mind, that Windows only allows a single application to access the MIDI device at a time, so you may close other applications before running your script.

To use the openXR bindings, you need to have the respective openXR runtime installed.

Create and open

At first, import the package as

import pyheadtracker as pht

Now you can create a head tracker object, in this example the MrHeadTracker. The device name as well as the output format (Quaternion or YPR (yaw/pitch/roll)) can be specified for each tracker. Some devices may allow additional configuration options. Linux and Windows tend to append indices to the device name, so the error returns the available devices if the specified name is not found.

ht = pht.diy.MrHeadTracker(
    device_name="MrHeadTracker",
    orient_format="q",
)

After the object is instatiated, the connection can be opened.

ht.open()

Getting data

Some devices can be zeroed to set the current orientation as the new reference point. This can be done by calling the zero() method.

ht.zero()

To retrieve data from the head tracker, you can use the read_orientation() or read_position() method. This method returns the current orientation data in the specified format. Note that not all devices provide position data.

orientation = ht.read_orientation()

if orientation is not None:
    print(orientation)
else:
    print("No data available")

Relay data

You can also relay the head tracking data to other applications using the OSC protocol. To do this, you need to set up an out object with the desired target application, IP address, and port number. Then, you can use the relay_orientation() and relay_position() methods to send the data.

osc_send = pht.out.IEMSceneRotator(ip="127.0.0.1", port=7000)

# ... inside your main loop
if isinstance(orientation, pht.dtypes.Quaternion):
    osc_send.send_orientation(orientation)

Close connection

It is best to close the connection gracefully after use. This can be done by calling the close() method.

ht.close()