> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/opentrack/opentrack/llms.txt
> Use this file to discover all available pages before exploring further.

# 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.

```cpp theme={null}
value<bool> center_at_startup { b, "center-at-startup", true };
```

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

### Centering Modes

OpenTrack supports multiple centering methods:

<Tabs>
  <Tab title="Disabled">
    No centering applied. Raw tracking data is used directly.

    ```cpp theme={null}
    center_disabled = 0
    ```
  </Tab>

  <Tab title="Point">
    Centers rotation and translation at a fixed point. Subtracts center pose from current pose.

    ```cpp theme={null}
    center_point = 1
    ```

    This mode simply subtracts the centered position:

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

  <Tab title="VR360">
    Full 360-degree centering using quaternions. Ideal for VR applications.

    ```cpp theme={null}
    center_vr360 = 2
    ```

    Uses quaternion math for accurate 360° rotation:

    ```cpp theme={null}
    q = dquat::from_euler(value[Pitch], value[Yaw], -value[Roll]);
    q = center.QC * q;
    q.to_euler(v[0], v[1], v[2]);
    ```
  </Tab>

  <Tab title="Roll Compensated">
    Centers yaw and pitch while compensating for roll. Best for flight simulators.

    ```cpp theme={null}
    center_roll_compensated = 3  // Default
    ```
  </Tab>
</Tabs>

### System Tray Options

Control how OpenTrack appears in the system tray:

```cpp theme={null}
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:

<Steps>
  <Step title="Enable camera offset">
    ```cpp theme={null}
    value<bool> enable_camera_offset { b, "enable-camera-offset", false };
    ```
  </Step>

  <Step title="Configure offset values">
    Set rotation offsets (degrees):

    ```cpp theme={null}
    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):

    ```cpp theme={null}
    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 };
    ```
  </Step>

  <Step title="How it works">
    The camera offset is applied using quaternion rotation:

    ```cpp theme={null}
    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;
    }
    ```
  </Step>
</Steps>

<Warning>
  Camera offset values should be small adjustments. Large offsets may cause unexpected behavior.
</Warning>

## Neck Model

Simulate natural neck pivot point for more realistic head movement:

```cpp theme={null}
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:

```cpp theme={null}
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:

<Accordion title="Translation Axes (X, Y, Z)">
  ```cpp theme={null}
  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
</Accordion>

<Accordion title="Rotation Axes (Yaw, Pitch, Roll)">
  ```cpp theme={null}
  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
</Accordion>

### Per-Axis Options

Each axis supports these configuration options:

```cpp theme={null}
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:

```cpp theme={null}
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

<Note>
  Log files can grow quickly. Only enable logging when debugging issues.
</Note>

## Pipeline Processing Order

OpenTrack processes tracking data through this pipeline:

<Steps>
  <Step title="Raw Input">
    Data received from tracker module
  </Step>

  <Step title="Camera Offset">
    Apply camera position compensation
  </Step>

  <Step title="Centering">
    Apply selected centering mode
  </Step>

  <Step title="Filtering">
    Process through selected filter
  </Step>

  <Step title="Mapping (Rotation)">
    Apply mapping curves to rotation axes
  </Step>

  <Step title="Relative Translation">
    Apply reltrans compensation if enabled
  </Step>

  <Step title="Mapping (Translation)">
    Apply mapping curves to translation axes
  </Step>

  <Step title="Output">
    Send to protocol module
  </Step>
</Steps>

## Keyboard Shortcuts

OpenTrack supports configurable keyboard shortcuts for common actions:

```cpp theme={null}
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

<CardGroup cols={2}>
  <Card title="Tracker Setup" icon="camera" href="/guides/tracker-setup">
    Configure your tracking device
  </Card>

  <Card title="Output Setup" icon="gamepad" href="/guides/output-setup">
    Set up game/simulator output
  </Card>

  <Card title="Filters" icon="sliders" href="/guides/filters">
    Smooth and stabilize tracking
  </Card>

  <Card title="Mapping Curves" icon="chart-line" href="/guides/mapping-curves">
    Customize response curves
  </Card>
</CardGroup>