pyheadtracker 0.1.5

Python package for easy interaction with head tracker hardware.

PyHeadTracker

This package provides an interface for interacting with head tracking hardware in Python.

The use of head trackers can greatly enhance the user experience in applications such as immersive audio, virtual reality, gaming, and assistive technologies. By providing precise head position and orientation data, developers can create more immersive and responsive environments for their users. However, interacting with different head trackers and their APIs can be a tedious process. PyHeadTracker aims to simplify this process by providing a unified interface for various head tracking devices in python.

A detailed documentation is available here.

Installation

Install the package using pip:

pip install pyheadtracker

Availability of features by platform and Python version:

Feature	Python 3.10-3.12	Python 3.13+	macOS
DIY Head Tracker (MrHeadTracker)	✓	✓	✓
Supperware Head Tracker	✓	✓	✓
Webcam-based tracking (cam)	✓	✗	✗
OpenXR HMD (hmd)	✓	✓	✗

Note: The mediapipe-numpy2 package (required for webcam-based tracking) is only compatible with Python ≤3.12. The pyopenxr package (required for HMD support) is only available on Linux and Windows.

Overview

PyHeadTracker is designed to provide a simple and consistent interface for accessing head tracking data from various devices. The library abstracts the complexities of dealing with different hardware and APIs, allowing developers to focus on building their applications without worrying about the underlying details.

Typically, each head tracker is instantiated as object before opening the connection, e.g.

import pyheadtracker as pht

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

Now you can access the head tracking data using the read_orientation() or read_position() method:

while True:
    orientation = ht.read_orientation()

    if orientation is not None:
        w, x, y, z = orientation

        # Print the quaternion values for debugging
        print(f"WXYZ: {w:7.2f} {x:7.2f} {y:7.2f} {z:7.2f}", end="\r")

Orientation data is provided as Quaternion or YPR (yaw/pitch/roll) object, which can easily be converted to a list or NumPy array. when requesting the poition, a Position object is returned to access Cartesian coordinates.

Examples how to use this package can be found here.

Supported devices

Currently the following head tracking devices are supported:

• Supperware Head Tracker 1
• IEM MrHeadTracker
• Webcam-based head tracking using MediaPipe Face Landmarker
• Head mounted displays using openXR (only on Windows/Linux)

If you are missing a device, feel free to contact us or open an issue.

Roadmap

In future releases, we plan to support additional head tracking devices and improve the overall functionality of the library. Some of the planned features include:

• Support for
  • SteamVR HMDs (e.g. HTC Vive)
  • OptiTrack
• Standalone CLI tool

License

This project is licensed under the MIT License