Configuration Overview

Learn how to configure OpenTrack’s main settings and user interface

OpenTrack provides a comprehensive configuration system for head tracking. This guide covers the main configuration options available in the user interface.

Configuration Bundles

OpenTrack uses a configuration bundle system to organize settings:

• opentrack-ui: Main user interface settings
• opentrack-mappings: Mapping curves and axis configuration
• modules: Tracker, filter, and protocol module selection

Settings are automatically saved when changed and persist between sessions.

Main Settings

Center at Startup

Automatically centers your head position when tracking starts.

value<bool> center_at_startup { b, "center-at-startup", true };

Enabled by default. This ensures your neutral position is properly calibrated when you start tracking.

Centering Modes

OpenTrack supports multiple centering methods:

Disabled

No centering applied. Raw tracking data is used directly.

center_disabled = 0

Point

Centers rotation and translation at a fixed point. Subtracts center pose from current pose.

center_point = 1

This mode simply subtracts the centered position:

for (unsigned k = Yaw; k <= Roll; k++) {
    value(k) -= center.P(k);
    if (fabs(value[k]) > 180) 
        value[k] -= copysign(360, value[k]);
}

VR360

Full 360-degree centering using quaternions. Ideal for VR applications.

center_vr360 = 2

Uses quaternion math for accurate 360° rotation:

q = dquat::from_euler(value[Pitch], value[Yaw], -value[Roll]);
q = center.QC * q;
q.to_euler(v[0], v[1], v[2]);

Roll Compensated

Centers yaw and pitch while compensating for roll. Best for flight simulators.

center_roll_compensated = 3  // Default

System Tray Options

Control how OpenTrack appears in the system tray:

value<bool> tray_enabled { b, "use-system-tray", false };
value<bool> tray_start { b, "start-in-tray", false };

• tray_enabled: Enable system tray icon
• tray_start: Start minimized to tray

Camera Offset

Compensate for camera position relative to your head:

1. Enable camera offset

   value<bool> enable_camera_offset { b, "enable-camera-offset", false };
   
2. Configure offset values

   Set rotation offsets (degrees):

   value<int> camera_offset_yaw   { b, "camera-offset-yaw",   0 };
   value<int> camera_offset_pitch { b, "camera-offset-pitch", 0 };
   value<int> camera_offset_roll  { b, "camera-offset-roll",  0 };
   

   Set position offsets (cm):

   value<int> camera_offset_x { b, "camera-offset-x", 0 };
   value<int> camera_offset_y { b, "camera-offset-y", 0 };
   value<int> camera_offset_z { b, "camera-offset-z", 0 };
   
3. How it works

   The camera offset is applied using quaternion rotation:

   auto q = dquat::from_euler(value[Pitch], value[Yaw], -value[Roll]);
   
   if (!q.is_identity() && s.enable_camera_offset) {
       auto inv_offset = dquat::from_euler(p, y, r);
       auto t = inv_offset.rotate_point({value[TX], value[TY], value[TZ]});
       
       value[TX] = t.x + s.camera_offset_x;
       value[TY] = t.y + s.camera_offset_y;
       value[TZ] = t.z + s.camera_offset_z;
   }
   

Camera offset values should be small adjustments. Large offsets may cause unexpected behavior.

Neck Model

Simulate natural neck pivot point for more realistic head movement:

value<bool> neck_enable { b, "neck-enable", false };
value<int> neck_z { b, "neck-depth", 0 };

• neck_enable: Enable neck model compensation
• neck_z: Neck depth in centimeters (typically 5-10cm)

Neck Model Implementation

The neck model rotates translation around a pivot point:

Pose_ reltrans::apply_neck(const rmat& R, int nz, bool disable_tz) const
{
    Pose_ neck;
    neck = rotate(R, { 0, 0, nz }, {});
    neck(TZ) = neck(TZ) - nz;
    
    if (disable_tz)
        neck(TZ) = 0;
    
    return neck;
}

Axis Configuration

Each of the 6 degrees of freedom can be independently configured:

Translation Axes (X, Y, Z)

axis_opts a_x{ "x", TX };
axis_opts a_y{ "y", TY };
axis_opts a_z{ "z", TZ };

• X: Left/Right movement
• Y: Up/Down movement
• Z: Forward/Backward movement

Default range: ±30cm

Rotation Axes (Yaw, Pitch, Roll)

axis_opts a_yaw{ "yaw", Yaw };      // ±180°
axis_opts a_pitch{ "pitch", Pitch }; // ±90°
axis_opts a_roll{ "roll", Roll };    // ±180°

• Yaw: Left/Right rotation
• Pitch: Up/Down rotation
• Roll: Tilt rotation

Per-Axis Options

Each axis supports these configuration options:

value<double> zero;              // Zero position offset
value<int> src;                  // Source axis mapping
value<bool> invert_pre;          // Invert before processing
value<bool> invert_post;         // Invert after processing
value<bool> altp;                // Use alternate spline for negative values
value<max_clamp> clamp_x_;       // Input range limit
value<max_clamp> clamp_y_;       // Output range limit

Track Logging

Record tracking data for analysis and debugging:

value<bool> tracklogging_enabled { b, "tracklogging-enabled", false };
value<QString> tracklogging_filename { b, "tracklogging-filename", {} };

The logger records:

• dt: Frame delta time
• raw: Raw tracker data (6 channels)
• corrected: After camera offset and centering
• filtered: After filter processing
• mapped: Final output after mapping curves

Log files can grow quickly. Only enable logging when debugging issues.

Pipeline Processing Order

OpenTrack processes tracking data through this pipeline:

1. Raw Input

   Data received from tracker module

2. Camera Offset

   Apply camera position compensation

3. Centering

   Apply selected centering mode

4. Filtering

   Process through selected filter

5. Mapping (Rotation)

   Apply mapping curves to rotation axes

6. Relative Translation

   Apply reltrans compensation if enabled

7. Mapping (Translation)

   Apply mapping curves to translation axes

8. Output

   Send to protocol module

Keyboard Shortcuts

OpenTrack supports configurable keyboard shortcuts for common actions:

key_opts key_start_tracking1 { b, "start-tracking" };
key_opts key_stop_tracking1 { b, "stop-tracking" };
key_opts key_toggle_tracking1 { b, "toggle-tracking" };
key_opts key_restart_tracking1 { b, "restart-tracking" };
key_opts key_center1 { b, "center" };
key_opts key_toggle1 { b, "toggle" };
key_opts key_zero1 { b, "zero" };
key_opts key_toggle_press1 { b, "toggle-press" };
key_opts key_zero_press1 { b, "zero-press" };

Each shortcut has an alternate variant (key_*2) for additional bindings.

Next Steps

Tracker Setup

Configure your tracking device

Output Setup

Set up game/simulator output

Filters

Smooth and stabilize tracking

Mapping Curves

Customize response curves