API Documentation

pyheadtracker.dtypes

class pyheadtracker.dtypes.HTBase[source]

Bases: object

Abstract base class for head tracking devices.

__init__()

abstractmethod close()[source]: Close the connection to the device.

abstractmethod open()[source]: Open a connection to the device.

abstractmethod read_orientation() → YPR | Quaternion | ndarray | None[source]

Read the current orientation of the device.

Returns:: Quaternion, YPR, or None

abstractmethod read_position() → Position | None[source]

Read the current position of the device.

Returns:: None or Position

abstractmethod zero()[source]: Zero the device’s orientation to set the current position as the reference.

class pyheadtracker.dtypes.Position(x, y, z)[source]

Bases: object

Represents a 3D position in space as Cartesian coordinates.

x

The x coordinate of the position.

Type:: float

y

The y coordinate of the position.

Type:: float

z

The z coordinate of the position.

Type:: float

Methods:

to_array() -> np.ndarray – Converts the position to a NumPy array [x, y, z].
from_array(arr (np.ndarray) -> Position) – Creates a position from a NumPy array [x, y, z].
__iter__() -> Iterator[float] – Makes the Position iterable.
__getitem__(index (int) -> float) – Gets the position component by index (0 for x, 1 for y, 2 for z).
__mul__(factor (float or np.ndarray) -> Position) – Scales the position by a factor or a NumPy array.
__add__(other (Position) -> Position) – Adds another position to this position.
__sub__(other (Position) -> Position) – Subtracts another position from this position.
distance_to(other (Position) -> float) – Calculates the Euclidean distance to another position.

classmethod from_array(arr)[source]

Create a position from a NumPy array, list, or tuple [x, y, z].

Parameters:: arr (np.ndarray, list, or tuple) – A NumPy array, list, or tuple containing the position coordinates [x, y, z].

__init__(x, y, z)[source]

Parameters:

x (float) – The x coordinate of the position.
y (float) – The y coordinate of the position.
z (float) – The z coordinate of the position.

distance_to(other)[source]

Calculate the Euclidean distance to another position.

Parameters:: other (Position) – The position to which the distance is calculated.
Returns:: float – The Euclidean distance between this position and the other position.

to_array()[source]

Convert the position to a NumPy array [x, y, z].

Returns:: np.ndarray – A NumPy array containing the position coordinates [x, y, z].

class pyheadtracker.dtypes.Quaternion(w, x, y, z)[source]

Bases: object

Represents a quaternion for 3D rotations.

w

The scalar part of the quaternion.

Type:: float

x

The x component of the quaternion.

Type:: float

y

The y component of the quaternion.

Type:: float

z

The z component of the quaternion.

Type:: float

Methods:

to_array() -> np.ndarray – Converts the quaternion to a NumPy array [w, x, y, z].
from_array(arr (np.ndarray) -> Quaternion) – Creates a quaternion from a NumPy array [w, x, y, z].
__iter__() -> Iterator[float] – Makes the Quaternion iterable.
__getitem__(index (int) -> float) – Gets the quaternion component by index (w,x,y,z).
__mul__(other (Quaternion) -> Quaternion) – Multiplies this quaternion by another quaternion (Hamilton product).
__add__(other (Quaternion) -> Quaternion) – Adds this quaternion to another quaternion.
conjugate() -> Quaternion – Returns the conjugate of the quaternion.
norm() -> float – Computes the norm (magnitude) of the quaternion.
normalize() -> Quaternion – Normalizes the quaternion to have a unit norm.
inverse() -> Quaternion – Computes the inverse of the quaternion.

classmethod from_array(arr)[source]

Create a quaternion from a NumPy array [w, x, y, z].

Parameters:: arr (np.ndarray, list, or tuple) – A NumPy array, list, or tuple containing the quaternion components [w, x, y, z].

__init__(w, x, y, z)[source]

Parameters:

w (float) – The scalar part of the quaternion.
x (float) – The x component of the quaternion.
y (float) – The y component of the quaternion.
z (float) – The z component of the quaternion.

conjugate()[source]

Return the conjugate of the quaternion. The conjugate of a quaternion is obtained by negating the vector part (x, y, z).

Returns:: Quaternion – The conjugate of the quaternion.

inverse()[source]

Compute the inverse of the quaternion.

The inverse of a quaternion is its conjugate divided by the square of its norm.

Returns:: Quaternion – The inverse of the quaternion.

norm()[source]

Compute the norm (magnitude) of the quaternion.

Returns:: float – The norm of the quaternion, which is the square root of the sum of the squares of its components.

normalize()[source]

Normalize the quaternion to have a unit norm.

Returns:: Quaternion – A new quaternion with a unit norm.

to_array()[source]

Convert the quaternion to a NumPy array [w, x, y, z].

Returns:: np.ndarray – A NumPy array containing the quaternion components [w, x, y, z].

class pyheadtracker.dtypes.YPR(yaw, pitch, roll, sequence: str = 'ypr')[source]

Bases: object

Represents Yaw, Pitch, Roll angles in radians.

yaw

The yaw angle in radians.

Type:: float

pitch

The pitch angle in radians.

Type:: float

roll

The roll angle in radians.

Type:: float

sequence

The sequence of rotations, either “ypr” (Yaw-Pitch-Roll) or “rpy” (Roll-Pitch-Yaw).

Type:: str

Methods:

to_array() -> np.ndarray – Converts the YPR object to a NumPy array.
from_array(arr (np.ndarray, sequence: str = “ypr”) -> YPR) – Creates a YPR object from a NumPy array.
__iter__() -> Iterator[float] – Returns an iterator over the YPR angles.
__getitem__(index (int) -> float) – Gets the YPR component by index (0 for yaw, 1 for pitch, 2 for roll).
__add__(other (YPR) -> YPR) – Adds another YPR to this YPR.
__sub__(other (YPR) -> YPR) – Subtracts another YPR from this YPR.
__wrap_angles(y (float, p: float, r: float) -> Tuple[float, float, float]) – Wraps angles to the range [-pi, pi] radians.
to_degrees() -> np.ndarray – Converts the YPR angles to degrees.

classmethod from_array(arr, sequence: str = 'ypr')[source]

Create YPR from a NumPy array.

Parameters:: arr (np.ndarray, list, or tuple) – A NumPy array, list, or tuple containing the Yaw, Pitch, Roll angles in radians.

__init__(yaw, pitch, roll, sequence: str = 'ypr')[source]

Parameters:

yaw (float) – The yaw angle in radians.
pitch (float) – The pitch angle in radians.
roll (float) – The roll angle in radians.
sequence (str, optional) – The sequence of rotations, either “ypr” (Yaw-Pitch-Roll) or “rpy” (Roll-Pitch-Yaw). Default is “ypr”.

to_array()[source]

Convert Yaw, Pitch, Roll to a NumPy array.

Returns:: np.ndarray – A NumPy array containing the Yaw, Pitch, Roll angles in radians.

to_degrees()[source]

Convert the Yaw, Pitch, Roll angles to degrees.

Returns:: ndarray – The Yaw, Pitch, Roll angles in degrees.

pyheadtracker.diy

Module for interacting with DIY head trackers.

Modules: - MrHeadTracker: A class for reading orientation data from the IEM MrHeadTracker device via MIDI.

class pyheadtracker.diy.MrHeadTracker(device_name: str = 'MrHeadTracker', orient_format: str = 'q', inverse: bool = False)[source]

Bases: HTBase

Class for interacting with the IEM MrHeadTracker.

The IEM MrHeadTracker is a DIY head tracker that sends orientation data via ordinary MIDI control messages. It is based on an Arduino/Teensy and the BNO055 or BNO085 sensor. Code, Wiki, and schematics are openly accessible [1].

device_name

The name of the MIDI device to connect to.

Type:: str

orient_format

The format for orientation data. Possible values are “q” (Quaternion) or “ypr” (Yaw, Pitch, Roll).

Type:: str

inport

The MIDI input port for reading data. This attribute is initialized to None and set when the open() method is called.

Type:: mido.Input

ready

Internal state - indicates whether the tracker is ready to read data.

Type:: bool

setted_bytes

Internal state - The number of bytes that have been set in the orientation data.

Type:: int

orientation_bytes

Internal state - A dictionary to hold the raw bytes of the orientation data.

Type:: dict

Methods:

open() – Opens the MIDI input port.
close() – Closes the MIDI input port gracefully.
read_orientation() – Reads the orientation data from the MIDI device and returns it in the specified format (Quaternion or YPR).

Raises:

RuntimeError – If the specified MIDI device cannot be opened or does not exist. Make sure the device is connected and the name is correct. On Windows, only exclusive connections to MIDI devices are possible, so ensure no other application is using the device.

References

[1] https://git.iem.at/DIY/MrHeadTracker

__init__(device_name: str = 'MrHeadTracker', orient_format: str = 'q', inverse: bool = False)[source]

Parameters:

device_name (str) – The name of the MIDI device to connect to. Default is “MrHeadTracker”.
orient_format (str) – The format for orientation data. Must correspond to the hardware settings if using the first version. Later versions only send quaternions. Possible values are “q” (Quaternion) or “ypr” (Yaw, Pitch, Roll). Default is “q”.
inverse (bool) – If inverse tracking data is provided by the head tracker. This mode could be set in the first version of the MrHeadTracker hardware. Default is False.

Raises:

RuntimeError – If the specified MIDI device cannot be opened or does not exist. Make sure the device is connected and the name is correct. On Windows, only exclusive connections to MIDI devices are possible, so ensure no other application is using the device.

close()[source]: Close the MIDI input port.

open()[source]: Open the MIDI input port.

read_orientation()[source]

Read orientation data from the MIDI device.

Returns:: Quaternion, YPR, or None – The orientation data in the specified format (Quaternion or YPR). Returns None if no data is available.

abstractmethod read_position() → Position | None

Read the current position of the device.

Returns:: None or Position

abstractmethod zero(): Zero the device’s orientation to set the current position as the reference.

pyheadtracker.supperware

This module is used to interact with Supperware head trackers via MIDI.

Classes: - HeadTracker1: A class for reading orientation data from the Head Tracker 1 device via MIDI.

class pyheadtracker.supperware.HeadTracker1(device_name: str = 'Head Tracker', device_name_output: str | None = None, refresh_rate: int = 50, raw_format: bool = False, compass_on: bool = False, orient_format: str = 'q', gestures_on: str = 'preserve', chirality: str = 'preserve', central_pull: bool = False, central_pull_rate: float = 0.3, travel_mode: str = 'preserve')[source]

Bases: HTBase

Class for interacting with the Supperware Head Tracker 1

This class can be used to set up and read data from the Supperware Head Tracker 1 device [1] via MIDI. All relevant settings mentioned in the MIDI protocol documentation [2] can be applied. A gist [3] by Abhaya Parthy provided helpful information to write this class.

device_name

The name of the MIDI device to connect to.

Type:: str

device_name_output

The name of the MIDI device to send data to. If not specified, it defaults to the same as device_name.

Type:: str

inport

The MIDI input port for reading data. This attribute is initialized to None and set when the open() method is called.

Type:: mido.Input

outport

The MIDI output port for sending data. This attribute is initialized to None and set when the open() method is called.

Type:: mido.Output

refresh_rate

The rate in Hertz at which the device should send updates. Possible values are 25, 50, or 100.

Type:: int

raw_format

If True, the device will send raw data without any adjustments. Not implemented yet. Default is False.

Type:: bool

compass_on

If True, the compass will be enabled. Default is False.

Type:: bool

orient_format

The format for orientation data. Possible values are “ypr” (Yaw, Pitch, Roll), “q” (Quaternion), or “orth” (Orthogonal matrix). Default is “q”.

Type:: str

gestures

Enable gesture recognition for resetting orientation. Possible values are “preserve” (keep existing state), “on” (enable gestures), or “off” (disable gestures). Default is “preserve”.

Type:: str

chirality

Whether the head tracker cable is attached to the left or right side of the head. Possible values are “left” (left side) or “right” (right side), or “preserve” (keep existing state). Default is “preserve”.

Type:: str

central_pull

If True, the head tracker will pull back to the center when the compass is disabled. Default is False.

Type:: bool

central_pull_rate

The rate in degree per second at which the head tracker will pull back to the center when central_pull is enabled. Default is 0.3.

Type:: float

travel_mode

The travel mode of the head tracker for yaw correction. Possible values are “preserve” (keep existing state), “off” (disable travel mode), “slow” (enable slow travel mode), or “fast” (enable fast travel mode). Default is “preserve”.

Type:: str

Methods:

open(compass_force_calibration (bool = False)) – Opens the MIDI input and output ports and configures the head tracker with the specified settings.
close() – Closes the MIDI input and output ports gracefully.
zero_orientation() – Resets the head tracker orientation.
zero() – Resets the head tracker orientation.
set_travel_mode(travel_mode (str)) – Sets the travel mode of the head tracker for yaw correction.
calibrate_compass() – Calibrates the compass of the head tracker.
read_orientation() – Reads the orientation data from the MIDI device and returns it in the specified format (Quaternion or YPR).

References

[1] https://supperware.co.uk/headtracker-overview [2] https://supperware.net/downloads/head-tracker/head%20tracker%20protocol.pdf [3] https://gist.github.com/abhayap/8701b710f32e592c52e771e938243e87

__init__(device_name: str = 'Head Tracker', device_name_output: str | None = None, refresh_rate: int = 50, raw_format: bool = False, compass_on: bool = False, orient_format: str = 'q', gestures_on: str = 'preserve', chirality: str = 'preserve', central_pull: bool = False, central_pull_rate: float = 0.3, travel_mode: str = 'preserve')[source]

Parameters:

device_name (str) – The name of the MIDI device to connect to. Default is “Head Tracker”.
device_name_output (str, optional) – The name of the MIDI device to send data to. If not specified, it defaults to the same as device_name.
refresh_rate (int, optional) – The rate in Hertz at which the device should send updates. Possible values are 25, 50, or 100. Default is 50.
raw_format (bool, optional) – If True, the device will send raw data without any adjustments. Not implemented yet. Default is False.
compass_on (bool, optional) – If True, the compass will be enabled. Default is False.
orient_format (str, optional) – The format for orientation data. Possible values are “ypr” (Yaw, Pitch, Roll), “q” (Quaternion), or “orth” (Orthogonal matrix). Default is “q”.
gestures_on (str, optional) – Enable gesture recognition for resetting orientation. Possible values are “preserve” (keep existing state), “on” (enable gestures), or “off” (disable gestures). Default is “preserve”.
chirality (str, optional) – Whether the head tracker cable is attached to the left or right side of the head. Possible values are “left” (left side) or “right” (right side), or “preserve” (keep existing state). Default is “preserve”.
central_pull (bool, optional) – If True, the head tracker will pull back to the center when the compass is disabled. Default is False.
central_pull_rate (float, optional) – The rate in degree per second at which the head tracker will pull back to the center when central_pull is enabled. Default is 0.3.
travel_mode (str, optional) – The travel mode of the head tracker for yaw correction. Possible values are “preserve” (keep existing state), “off” (disable travel mode), “slow” (enable slow travel mode), or “fast” (enable fast travel mode). Default is “preserve”.

Raises:

RuntimeError – If the specified MIDI device cannot be opened or does not exist. Make sure the device is connected and the name is correct. On Windows, only exclusive connections to MIDI devices are possible, so ensure no other application is using the device.

calibrate_compass()[source]

Calibrate the compass.

This method sends a message to the head tracker to calibrate the compass.

close()[source]

Close the connection to the head tracker.

This method closes the MIDI input and output ports gracefully.

open(compass_force_calibration: bool = False)[source]

Open the head tracker connection.

This method opens the MIDI input and output ports and sends a message to configure the head tracker with the specified settings.

Parameters:

compass_force_calibration (bool, optional)
If True, forces the compass to calibrate when opening the connection. Default is False.

read_orientation()[source]

Read the orientation data from the head tracker.

This method reads the orientation data from the MIDI device and returns it in the specified format (Quaternion or YPR).

Returns:: Quaternion or YPR or np.ndarray or None – The orientation data in the specified format (Quaternion, YPR, or np.ndarray for orth). Returns None if no data is available.

abstractmethod read_position() → Position | None

Read the current position of the device.

Returns:: None or Position

set_travel_mode(travel_mode: str)[source]

Set the travel mode of the head tracker.

This method sends a message to the head tracker to set the travel mode for yaw correction.

Parameters:: travel_mode (str) – The travel mode to set. Must be one of: preserve, off, slow, fast.

zero()[source]

Zero the head tracker sensors.

This method sends a message to the head tracker to reset its orientation.

zero_orientation()[source]

Zero the head tracker sensors.

This method sends a message to the head tracker to reset its orientation. Duplicates the functionality of zero() for consistency throughout the package.

pyheadtracker.cam

Access position and orientation data via webcam-based head tracking

Classes - MPFaceLandmarker: Webcam-based head tracker using OpenCV and MediaPipe Face Landmarker

class pyheadtracker.cam.MPFaceLandmarker(cam_index: int = 0, model_weights: str | None = None, min_face_detection_confidence: float = 0.8, min_face_presence_confidence: float = 0.8, min_tracking_confidence: float = 0.8, landmark_points_idx: list[int] | None = None, landmark_points_3d: ndarray | None = None, orient_format: str = 'q')[source]

Bases: HTBase

Webcam-based head tracker using OpenCV and MediaPipe Face Landmarker

This class uses MediaPipe’s Face Landmarker [1] to track head position and orientation using a (web-)cam. A mesh of 478 face landmarks is fitted to the detected face, from which 6 key points are used to estimate head pose via solvePnP. Orientation is derived from MediaPipe’s facial transformation matrix. Tracking of the position is still experimental and might be inaccurate. Parts of the computation are offloaded to the GPU if available. By default, the built-in MediaPipe Face Landmarker model is used, but custom model weights can be provided. The supplied model weights (09/15/2022) are licensed under the Apache 2.0 license.

cam_index

The index of the webcam to use.

Type:: int

landmark_points_idx

Indices of the facial landmarks to use for pose estimation.

Type:: list[int], optional

landmark_points_3d

Corresponding 3D model points for the selected landmarks. Note, that mediapipe’s coordinate system is used (right-handed, x: right, y: down, z: forward).

Type:: np.ndarray, optional

orient_format

The format for orientation data. Possible values are “q” (Quaternion) or “ypr” (Yaw, Pitch, Roll).

Type:: str

reset_orientation

Flag to indicate whether to reset orientation zeroing on the next read.

Type:: bool

reset_position

Flag to indicate whether to reset position zeroing on the next read.

Type:: bool

is_opened

Indicates whether the camera is opened.

Type:: bool

__FaceLandmarkerOptions

MediaPipe Face Landmarker options.

Type:: vision.FaceLandmarkerOptions

__landmarker

Internal MediaPipe Face Landmarker instance.

Type:: vision.FaceLandmarker

__cap

Internal OpenCV VideoCapture instance.

Type:: cv2.VideoCapture

__frame_count

Frame counter for MediaPipe processing.

Type:: int

__frame_width

Width of the video frames.

Type:: int

__frame_height

Height of the video frames.

Type:: int

__camera_matrix

Camera intrinsic matrix.

Type:: np.ndarray

__dist_coeffs

Camera distortion coefficients.

Type:: np.ndarray

__initial_rotation_matrix

Initial rotation matrix for orientation zeroing.

Type:: np.ndarray

__initial_R

Initial rotation matrix for position zeroing.

Type:: np.ndarray

__initial_tvec

Initial translation vector for position zeroing.

Type:: np.ndarray

Methods:

open() – Initializes the webcam and MediaPipe Face Landmarker.
close() – Releases the webcam and MediaPipe resources.
list_available_cameras(max_index (int = 20) -> list[int]) – Lists all available camera indices on the system.
zero() – Use the current position and orientation as reference (zero) values.
zero_orientation() – Uses the current orientation as reference (zero) value.
zero_position() – Uses the current position as reference (zero) value.
read_orientation() -> Quaternion or YPR or None – Returns if available the current head orientation as a Quaternion or YPR object.
read_position() -> Position or None – Returns if available the current head position in meters as a Position object.
read_pose() -> dict or None – Returns if available the current head position and orientation as a dictionary with Position and Quaternion or YPR objects.

References

[1] MediaPipe Face Landmarker: https://ai.google.dev/edge/mediapipe/solutions/vision/face_landmarker

static list_available_cameras(max_index: int = 20) → list[int][source]

List all available camera indices on the system.

Parameters:: max_index (int) – Maximum camera index to check (default 10).
Returns:: list[int] – List of available camera indices.

__init__(cam_index: int = 0, model_weights: str | None = None, min_face_detection_confidence: float = 0.8, min_face_presence_confidence: float = 0.8, min_tracking_confidence: float = 0.8, landmark_points_idx: list[int] | None = None, landmark_points_3d: ndarray | None = None, orient_format: str = 'q')[source]

Parameters:

cam_index (int) – The index of the webcam to use.
model_weights (str, optional) – Path to custom model weights. If None, the default built-in model is used.
min_face_detection_confidence (float, optional) – Minimum confidence value ([0.0, 1.0]) for face detection to be considered successful. Defaults to 0.8.
min_face_presence_confidence (float, optional) – Minimum confidence value ([0.0, 1.0]) for the face presence to be considered detected successfully. Defaults to 0.8.
min_tracking_confidence (float, optional) – Minimum confidence value ([0.0, 1.0]) for the face landmarks to be considered tracked successfully. Defaults to 0.8.
landmark_points_idx (list[int], optional) – Indices of the facial landmarks to use for pose estimation.
landmark_points_3d (np.ndarray, optional) – Corresponding 3D model points for the selected landmarks. Note, that mediapipe’s coordinate system is used (right-handed, x: right, y: down, z: forward).
orient_format (str) – The format for orientation data. Possible values are “q” (Quaternion) or “ypr” (Yaw, Pitch, Roll).

close()[source]: Releases the webcam and MediaPipe resources.

open()[source]: Initializes the webcam and MediaPipe Face Landmarker.

read_orientation() → YPR | Quaternion | None[source]

Returns if available the current head orientation as a Quaternion or YPR object.

Returns:: Quaternion or YPR or None – The current head orientation, or None if not available.

read_pose() → dict[str, Position | Quaternion | YPR | None] | None[source]

Returns if available the current head position and orientation as a dictionary with Position and Quaternion or YPR objects.

Returns:: dict[str, Position | Quaternion | YPR] or None – The current head position and orientation, or None if not available.

read_position() → Position | None[source]

Returns if available the current head position as a Position object.

Returns:: Position or None – The current head position, or None if not available.

zero()[source]: Use the current position and orientation as reference (zero) values.

zero_orientation()[source]: Uses the current orientation as reference (zero) value.

zero_position()[source]: Uses the current position as reference (zero) value.

pyheadtracker.hmd

Accessing position and orientation data from head mounted displays (HMDs).

Due to pyopenxr not being available on macOS, this module is only available on Windows and Linux.

Classes: - openXR: A class for accessing position and orientation data from OpenXR-compatible HMDs, relying on the pyopenxr library

class pyheadtracker.hmd.openXR(context: ContextObject, initial_pose: Posef | None = None, reset_position: bool = False, reset_orientation: bool = False, orient_format: str = 'q')[source]

Bases: HTBase

A class for accessing position and orientation data from OpenXR-compatible HMDs.

This class uses the pyopenxr library to read the head pose data from the HMD. Upon request, the position and orientation is returned.

context

The OpenXR context object.

Type:: ContextObject

reference_position

A reference position, where the tracking data can be normalized to.

Type:: Position

reference_orientation_inv

The inverse of the reference orientation, used to normalize the orientation data.

Type:: Quaternion

reset_position

A flag to indicate if the position should be reset to the reference position.

Type:: bool

reset_orientation

A flag to indicate if the orientation should be reset to the reference orientation.

Type:: bool

orient_format

The format of the orientation data. Internally, Quaternions are used. Possible values are “ypr” (Yaw, Pitch, Roll) or “q” (Quaternion). Default is “q”.

Type:: str

Methods:

read_raw_pose(frame_state (xr.FrameState) -> xr.Posef or None) – Returns if available the raw pose data from the HMD without any adjustments in the openXR coordinate system definition.
read_pose(frame_state (xr.FrameState) -> dict or None) – Returns if available the adjusted position and orientation data from the HMD. The dictionary contains a Position and Quaternion object.
read_orientation(frame_state (xr.FrameState) -> Quaternion or None) – Returns if available the current head orientation as a Quaternion object.
read_position(frame_state (xr.FrameState) -> Position or None) – Returns if available the current head position as a Position object.
zero() – Resets the position and orientation to the reference values.
zero_orientation() – Resets the orientation to the reference orientation.
zero_position() – Resets the position to the reference position.

__init__(context: ContextObject, initial_pose: Posef | None = None, reset_position: bool = False, reset_orientation: bool = False, orient_format: str = 'q')[source]

Parameters:

context (ContextObject) – The OpenXR context object.
initial_pose (xr.Posef, optional) – The initial pose of the HMD. If not provided, the position will be set to (0, 0, 0) and the orientation to the identity quaternion.
reset_position (bool, optional) – If True, the position will be reset to the initial pose when read_pose is called. Default is False.
reset_orientation (bool, optional) – If True, the orientation will be reset to the initial pose when read_pose is called. Default is False.
orient_format (str, optional) – The format of the orientation data. Possible values are “ypr” (Yaw, Pitch, Roll) or “q” (Quaternion). Default is “q”.

abstractmethod close(): Close the connection to the device.

abstractmethod open(): Open a connection to the device.

read_orientation(frame_state: FrameState)[source]

Get the current head orientation as a Quaternion.

Parameters:: frame_state (xr.FrameState) – The current frame state from OpenXR.
Returns:: Quaternion or None – The current head orientation as a Quaternion object, or None if the pose is not available.

read_pose(frame_state: FrameState)[source]

Read and post-process the current head pose.

Get the current head position and orientation as a dictionary containing Position and Quaternion objects. The position and orientation are adjusted relative to the initial pose.

Parameters:: frame_state (xr.FrameState) – The current frame state from OpenXR.
Returns:: dict or None – A dictionary containing the adjusted position and orientation, or None if the pose is not available.

read_position(frame_state: FrameState)[source]

Get the current head position as a Position object.

Parameters:: frame_state (xr.FrameState) – The current frame state from OpenXR.
Returns:: Position or None – The current head position as a Position object, or None if the pose is not available.

read_raw_pose(frame_state: FrameState)[source]

Get the raw pose data from the HMD without any adjustments in the OpenXR coordinate system definition.

Parameters:: frame_state (xr.FrameState) – The current frame state from OpenXR.
Returns:: xr.Posef or None – The raw pose data from the HMD, or None if the pose is not available.

zero()[source]: Reset reference position and orientation to the current one.

zero_orientation()[source]: Reset reference orientation to the current one.

zero_position()[source]: Reset reference position to the current one.

pyheadtracker.out

Module for sending head tracking data to various target applications.

Modules: - IEMSceneRotator: Class to send data to IEM Scene Rotator via OSC.

class pyheadtracker.out.IEMDirectivityShaper(ip: str = '127.0.0.1', port: int = 8000, OSC_address: str = '/DirectivityShaper/', offset_az: float = 0.0, offset_el: float = 0.0, offset_roll: float = 0.0, invert_az: bool = False, invert_el: bool = False, invert_roll: bool = False)[source]

Bases: OutBase

Class for sending head tracking data to IEM DirectivityShaper via OSC.

This class is used to transmit data via OSC to the IEM DirectivityShaper of the IEM Plug-In Suite [1]. It supports sending orientation data in both YPR (Yaw, Pitch, Roll) and Quaternion formats. If Quaternion data is provided, it is automatically converted to YPR format before transmission.

ip

The IP address of the target application. Default is “127.0.0.1”.

Type:: str

port

The port number of the target application. Default is 8000.

Type:: int

OSC_address

The OSC address prefix for sending messages. Default is “/DirectivityShaper/”.

Type:: str

offset_az

Offset in degrees to be added to the azimuth (yaw) angle. Default is 0.0.

Type:: float

offset_el

Offset in degrees to be added to the elevation (pitch) angle. Default is 0.0.

Type:: float

offset_roll

Offset in degrees to be added to the roll angle. Default is 0.0.

Type:: float

invert_az

If True, invert the azimuth (yaw) angle. Default is False.

Type:: bool

invert_el

If True, invert the elevation (pitch) angle. Default is False.

Type:: bool

invert_roll

If True, invert the roll angle. Default is False.

Type:: bool

Methods:: send_orientation(orientation (YPR | Quaternion | None)) – Send orientation data to the IEM DirectivityShaper.

References

[1] https://plugins.iem.at

__init__(ip: str = '127.0.0.1', port: int = 8000, OSC_address: str = '/DirectivityShaper/', offset_az: float = 0.0, offset_el: float = 0.0, offset_roll: float = 0.0, invert_az: bool = False, invert_el: bool = False, invert_roll: bool = False)[source]

Parameters:

ip (str) – The IP address of the target application. Default is “127.0.0.1”.
port (int) – The port number of the target application. Default is 8000.
OSC_address (str) – The OSC address prefix for sending messages. Default is “/DirectivityShaper/”.
offset_az (float) – Offset in degrees to be added to the azimuth (yaw) angle. Default is 0.0.
offset_el (float) – Offset in degrees to be added to the elevation (pitch) angle. Default is 0.0.
offset_roll (float) – Offset in degrees to be added to the roll angle. Default is 0.0.
invert_az (bool) – If True, invert the azimuth (yaw) angle. Default is False.
invert_el (bool) – If True, invert the elevation (pitch) angle. Default is False.
invert_roll (bool) – If True, invert the roll angle. Default is False.

send_orientation(orientation: YPR | Quaternion | None)[source]

Send orientation data to the IEM DirectivityShaper.

Parameters:: orientation (YPR | Quaternion) – The orientation data to send.

abstractmethod send_position(position: Position)

Send position data to the desired target application.

Parameters:: position (Position) – The position data to send.

class pyheadtracker.out.IEMRoomEncoder(ip: str = '127.0.0.1', port: int = 8000, OSC_address: str = '/RoomEncoder/', mode: str = 'listener', offset_x: float = 0.0, offset_y: float = 0.0, offset_z: float = 0.0)[source]

Bases: OutBase

Class for sending head tracking data to IEM RoomEncoder via OSC.

This class is used to transmit position via OSC to the IEM RoomEncoder of the IEM Plug-In Suite [1].

ip

The IP address of the target application. Default is “127.0.0.1”.

Type:: str

port

The port number of the target application. Default is 8000.

Type:: int

OSC_address

The OSC address prefix for sending messages. Default is “/RoomEncoder/listener” or “/RoomEncoder/source”.

Type:: str

offset_x

Offset to be added to the x position. Default is 0.0.

Type:: float

offset_y

Offset to be added to the y position. Default is 0.0.

Type:: float

offset_z

Offset to be added to the z position. Default is 0.0.

Type:: float

Methods:: send_position(position (Position)) – Send position data to the IEM RoomEncoder.

References

[1] https://plugins.iem.at/docs/plugindescriptions/#roomencoder

__init__(ip: str = '127.0.0.1', port: int = 8000, OSC_address: str = '/RoomEncoder/', mode: str = 'listener', offset_x: float = 0.0, offset_y: float = 0.0, offset_z: float = 0.0)[source]

Parameters:

ip (str) – The IP address of the target application. Default is “127.0.0.1”.
port (int) – The port number of the target application. Default is 8000.
OSC_address (str) – The OSC address prefix for sending messages. Default is “/RoomEncoder/”.
mode (str) – Setting to control either the listener or source position. Possible values are “listener” or “source”. Default is “listener”.
offset_x (float) – Offset to be added to the x position. Default is 0.0.
offset_y (float) – Offset to be added to the y position. Default is 0.0.
offset_z (float) – Offset to be added to the z position. Default is 0.0.

abstractmethod send_orientation(orientation: YPR | Quaternion)

Send orientation data to the desired target application.

Parameters:: orientation (YPR | Quaternion) – The orientation data to send.

send_position(position: Position)[source]

Send position data to the IEM RoomEncoder.

Parameters:: position (Position) – The position data to send.

class pyheadtracker.out.IEMSceneRotator(ip: str = '127.0.0.1', port: int = 8000, OSC_address: str = '/SceneRotator/')[source]

Bases: OutBase

Class for sending head tracking data to IEM SceneRotator via OSC.

This class is used to transmit data via OSC to the IEM SceneRotator of the IEM Plug-In Suite [1]. It supports sending orientation data in both YPR (Yaw, Pitch, Roll) and Quaternion formats. If YPR data is provided, it is automatically converted to Quaternion format before transmission.

ip

The IP address of the target application. Default is “127.0.0.1”.

Type:: str

port

The port number of the target application. Default is 8000.

Type:: int

OSC_address

The OSC address prefix for sending messages. Default is “/SceneRotator/”.

Type:: str

Methods:: send_orientation(orientation (YPR | Quaternion | None)) – Send orientation data to the IEM SceneRotator.

References

[1] https://plugins.iem.at

__init__(ip: str = '127.0.0.1', port: int = 8000, OSC_address: str = '/SceneRotator/')[source]

Parameters:

ip (str) – The IP address of the target application. Default is “127.0.0.1”.
port (int) – The port number of the target application. Default is 8000.
OSC_address (str) – The OSC address prefix for sending messages. Default is “/SceneRotator/”.

send_orientation(orientation: YPR | Quaternion | None)[source]

Send orientation data to the IEM SceneRotator.

Parameters:: orientation (YPR | Quaternion) – The orientation data to send.

abstractmethod send_position(position: Position)

Send position data to the desired target application.

Parameters:: position (Position) – The position data to send.

class pyheadtracker.out.IEMStereoEncoder(ip: str = '127.0.0.1', port: int = 8000, OSC_address: str = '/StereoEncoder/', offset_az: float = 0.0, offset_el: float = 0.0, offset_roll: float = 0.0, invert_az: bool = False, invert_el: bool = False, invert_roll: bool = False)[source]

Bases: OutBase

Class for sending head tracking data to IEM StereoEncoder via OSC.

This class is used to transmit data via OSC to the IEM StereoEncoder of the IEM Plug-In Suite [1]. It supports sending orientation data in both YPR (Yaw, Pitch, Roll) and Quaternion formats. If Quaternion data is provided, it is automatically converted to YPR format before transmission.

ip

The IP address of the target application. Default is “127.0.0.1”.

Type:: str

port

The port number of the target application. Default is 8000.

Type:: int

OSC_address

The OSC address prefix for sending messages. Default is “/DirectivityShaper/”.

Type:: str

offset_az

Offset in degrees to be added to the azimuth (yaw) angle. Default is 0.0.

Type:: float

offset_el

Offset in degrees to be added to the elevation (pitch) angle. Default is 0.0.

Type:: float

offset_roll

Offset in degrees to be added to the roll angle. Default is 0.0.

Type:: float

invert_az

If True, invert the azimuth (yaw) angle. Default is False.

Type:: bool

invert_el

If True, invert the elevation (pitch) angle. Default is False.

Type:: bool

invert_roll

If True, invert the roll angle. Default is False.

Type:: bool

Methods:: send_orientation(orientation (YPR | Quaternion | None)) – Send orientation data to the IEM StereoEncoder.

References

[1] https://plugins.iem.at

__init__(ip: str = '127.0.0.1', port: int = 8000, OSC_address: str = '/StereoEncoder/', offset_az: float = 0.0, offset_el: float = 0.0, offset_roll: float = 0.0, invert_az: bool = False, invert_el: bool = False, invert_roll: bool = False)[source]

Parameters:

ip (str) – The IP address of the target application. Default is “127.0.0.1”.
port (int) – The port number of the target application. Default is 8000.
OSC_address (str) – The OSC address prefix for sending messages. Default is “/StereoEncoder/”.
offset_az (float) – Offset in degrees to be added to the azimuth (yaw) angle. Default is 0.0.
offset_el (float) – Offset in degrees to be added to the elevation (pitch) angle. Default is 0.0.
offset_roll (float) – Offset in degrees to be added to the roll angle. Default is 0.0.
invert_az (bool) – If True, invert the azimuth (yaw) angle. Default is False.
invert_el (bool) – If True, invert the elevation (pitch) angle. Default is False.
invert_roll (bool) – If True, invert the roll angle. Default is False.

send_orientation(orientation: YPR | Quaternion | None)[source]

Send orientation data to the IEM StereoEncoder.

Parameters:: orientation (YPR | Quaternion) – The orientation data to send.

abstractmethod send_position(position: Position)

Send position data to the desired target application.

Parameters:: position (Position) – The position data to send.

class pyheadtracker.out.OutBase[source]

Bases: object

Base class for outputting data to a target application.

Methods:

send_orientation(orientation (YPR | Quaternion)) – Send orientation data to the desired target application.
send_position(position (Position)) – Send position data to the desired target application.

__init__()

abstractmethod send_orientation(orientation: YPR | Quaternion)[source]

Send orientation data to the desired target application.

Parameters:: orientation (YPR | Quaternion) – The orientation data to send.

abstractmethod send_position(position: Position)[source]

Send position data to the desired target application.

Parameters:: position (Position) – The position data to send.

class pyheadtracker.out.SPARTA(ip: str = '127.0.0.1', port: int = 9000, offset_az: float = 0.0, offset_el: float = 0.0, offset_roll: float = 0.0, invert_az: bool = False, invert_el: bool = False, invert_roll: bool = False)[source]

Bases: OutBase

Class for sending head tracking data to SPARTA Plug-Ins via OSC.

This class is used to transmit data via OSC to the SPARTA applications [1]. It supports sending orientation data in both YPR (Yaw, Pitch, Roll) and Quaternion formats. If Quaternion data is provided, it is automatically converted to YPR format before transmission.

ip

The IP address of the target application. Default is “127.0.0.1”.

Type:: str

port

The port number of the target application. Default is 9000.

Type:: int

offset_az

Offset in degrees to be added to the azimuth (yaw) angle. Default is 0.0.

Type:: float

offset_el

Offset in degrees to be added to the elevation (pitch) angle. Default is 0.0.

Type:: float

offset_roll

Offset in degrees to be added to the roll angle. Default is 0.0.

Type:: float

invert_az

If True, invert the azimuth (yaw) angle. Default is False.

Type:: bool

invert_el

If True, invert the elevation (pitch) angle. Default is False.

Type:: bool

invert_roll

If True, invert the roll angle. Default is False.

Type:: bool

Methods:: send_orientation(orientation (YPR | Quaternion | None)) – Send orientation data to SPARTA Plug-Ins.

References

[1] https://leomccormack.github.io/sparta-site/

__init__(ip: str = '127.0.0.1', port: int = 9000, offset_az: float = 0.0, offset_el: float = 0.0, offset_roll: float = 0.0, invert_az: bool = False, invert_el: bool = False, invert_roll: bool = False)[source]

Parameters:

ip (str) – The IP address of the target application. Default is “127.0.0.1”.
port (int) – The port number of the target application. Default is 9000.
offset_az (float) – Offset in degrees to be added to the azimuth (yaw) angle. Default is 0.0.
offset_el (float) – Offset in degrees to be added to the elevation (pitch) angle. Default is 0.0.
offset_roll (float) – Offset in degrees to be added to the roll angle. Default is 0.0.
invert_az (bool) – If True, invert the azimuth (yaw) angle. Default is False.
invert_el (bool) – If True, invert the elevation (pitch) angle. Default is False.
invert_roll (bool) – If True, invert the roll angle. Default is False.

send_orientation(orientation: YPR | Quaternion | None)[source]

Send orientation data to SPARTA Plug-Ins.

Parameters:: orientation (YPR | Quaternion) – The orientation data to send.

abstractmethod send_position(position: Position)

Send position data to the desired target application.

Parameters:: position (Position) – The position data to send.

class pyheadtracker.out.TASCAR(OSC_address: str, ip: str = '127.0.0.1', port: int = 9000, offset_az: float = 0.0, offset_el: float = 0.0, offset_roll: float = 0.0, invert_az: bool = False, invert_el: bool = False, invert_roll: bool = False)[source]

Bases: OutBase

Class for sending head tracking data to TASCAR.

This class is used to transmit data via OSC to TASCAR [1]. It supports sending orientation data in both YPR (Yaw, Pitch, Roll) and Quaternion formats. If Quaternion data is provided, it is automatically converted to YPR format before transmission.

OSC_address

The OSC address prefix for sending messages, without tailing pos or zyxeuler.

Type:: str

ip

The IP address of the target application. Default is “127.0.0.1”.

Type:: str

port

The port number of the target application. Default is 9000.

Type:: int

offset_az

Offset in degrees to be added to the azimuth (yaw) angle. Default is 0.0.

Type:: float

offset_el

Offset in degrees to be added to the elevation (pitch) angle. Default is 0.0.

Type:: float

offset_roll

Offset in degrees to be added to the roll angle. Default is 0.0.

Type:: float

invert_az

If True, invert the azimuth (yaw) angle. Default is False.

Type:: bool

invert_el

If True, invert the elevation (pitch) angle. Default is False.

Type:: bool

invert_roll

If True, invert the roll angle. Default is False.

Type:: bool

Methods:

send_orientation(orientation (YPR | Quaternion | None)) – Send orientation data to TASCAR.
send_position(position (Position)) – Send position data to TASCAR.

References

[1] https://tascar.org/

__init__(OSC_address: str, ip: str = '127.0.0.1', port: int = 9000, offset_az: float = 0.0, offset_el: float = 0.0, offset_roll: float = 0.0, invert_az: bool = False, invert_el: bool = False, invert_roll: bool = False)[source]

Parameters:

OSC_address (str) – The OSC address prefix for sending messages, without tailing pos or zyxeuler.
ip (str) – The IP address of the target application. Default is “127.0.0.1”.
port (int) – The port number of the target application. Default is 9000.
offset_az (float) – Offset in degrees to be added to the azimuth (yaw) angle. Default is 0.0.
offset_el (float) – Offset in degrees to be added to the elevation (pitch) angle. Default is 0.0.
offset_roll (float) – Offset in degrees to be added to the roll angle. Default is 0.0.
invert_az (bool) – If True, invert the azimuth (yaw) angle. Default is False.
invert_el (bool) – If True, invert the elevation (pitch) angle. Default is False.
invert_roll (bool) – If True, invert the roll angle. Default is False.

send_orientation(orientation: YPR | Quaternion | None)[source]

Send orientation data to TASCAR.

Parameters:: orientation (YPR | Quaternion) – The orientation data to send.

send_position(position: Position)[source]

Send position data to TASCAR.

Parameters:: position (Position) – The position data to send.

pyheadtracker.utils

Utility functions for quaternion and YPR conversions, and angle unit conversions.

This module provides functions to convert between quaternions and YPR (Yaw, Pitch, Roll) angles, as well as to convert angles between radians and degrees. It also includes type checking for input data. It is part of the pyheadtracker package, which provides tools for head tracking and orientation data.

Functions: - quat2ypr(quat, sequence): Converts a quaternion to YPR angles. - ypr2quat(ypr): Converts YPR angles to a quaternion. - rad2deg(input_data): Converts radians to degrees. - deg2rad(input_data): Converts degrees to radians.

pyheadtracker.utils.deg2rad(input_data)[source]

Converts input data from degrees to radians.

Parameters:: input_data (float, list, or np.ndarray) – Input in degrees.
Returns:: float, list, or np.ndarray – Converted data in radians, with the same type as the input.

pyheadtracker.utils.quat2ypr(quat: Quaternion, sequence: str = 'ypr', extrinsic: bool = False) → YPR[source]

Convert a Quaternion to an YPR (yaw, pitch, roll) object.

Parameters:

quat (Quaternion) – The quaternions object to be converted.
sequence (str, optional) – The sequence of angles, either “ypr” (Yaw, Pitch, Roll) or “rpy” (Roll, Pitch, Yaw). Default is “ypr”.
extrinsic (bool, optional) – If True, use extrinsic rotations (rotations about the fixed axes). If False, use intrinsic rotations (rotations about the moving axes). Default is False.

Returns:

YPR – An YPR object containing the converted angles in radians.

References

[1] E. Bernardes, “OrigaBot: Origami-based Reconfigurable Robots for Multi-modal Locomotion,” phdthesis, Aix-Marseille University, 2023. Accessed: Oct. 10, 2025. [Online]. Available: https://theses.hal.science/tel-04646218

pyheadtracker.utils.rad2deg(input_data)[source]

Converts input data from radians to degrees.

Parameters:: input_data (float, list, np.ndarray, or YPR) – Input in radians.
Returns:: float, list, np.ndarray, or YPR – Converted data in degrees, with the same type as the input.

pyheadtracker.utils.ypr2quat(ypr: YPR)[source]

Converts a YPR to a Quaternion object.

Parameters:: ypr (YPR) – The YPR object to be converted.
Returns:: Quaternion – A Quaternion object containing the converted values.