Skip to main content
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:
No centering applied. Raw tracking data is used directly.
center_disabled = 0

​
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: 
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
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