opentrack Wiki

What head tracking does

Head tracking converts physical head movement into virtual camera movement. Instead of controlling the view with a mouse, keyboard, hat switch or analog stick, you move naturally to inspect the cockpit, follow a target, check mirrors, lean around an obstruction or look through a turn.

opentrack can process six degrees of freedom:

A tracker that provides only yaw, pitch and roll is a 3DOF tracker. A tracker that also provides X, Y and Z movement is a 6DOF tracker. 6DOF tracking is particularly useful in cockpit simulators because it lets you:

• Move closer to instruments.
• Lean toward a gunsight or display.
• Look around canopy frames.
• Raise the viewpoint above a dashboard.
• Move sideways to inspect controls.
• Adjust the apparent seating position naturally.

How opentrack processes movement

The complete signal path is:

Each stage solves a different problem.

Tracker

The tracker estimates the current position and orientation of the head. Examples include:

• NeuralNet webcam tracking.
• PointTracker with a three-point LED model.
• ArUco paper marker tracking.
• UDP data from a phone or another computer.
• Tobii or Eyeware tracking.
• Hatire-compatible inertial hardware.
• TrackHat Sensor V2.
• XREAL glasses.
• Wiimote-based infrared tracking.

Mapping

Mapping determines how much virtual movement is generated from physical movement. For example, 15 degrees of physical yaw can be mapped to 90, 120 or 180 degrees of in-game camera rotation.

Filter

The filter reduces sensor noise, camera jitter, unstable pose estimates and involuntary micro-movement. A stronger filter usually produces a steadier image but can add latency. A weaker filter responds faster but exposes more noise.

Output

The output module sends the processed pose to a game, simulator, operating-system interface, virtual device or another computer. Choosing the correct output is essential: a perfectly functioning tracker will not move the game camera when the wrong output protocol is selected.

Downloading and installing opentrack

Official Windows releases are normally distributed in two forms:

• An .exe installer.
• A portable .7z archive.

Use the current official release unless a specific tracker or integration explicitly requires another version.

Installer

The installer is the best choice for a conventional Windows setup. It creates a normal installation and is easier to maintain for most users.

Portable archive

The portable archive is useful when:

• opentrack should run without a conventional installation.
• Several versions need to be tested independently.
• The application must be carried on a USB drive.
• Profiles and program files should remain in one controlled directory.
• The Windows user profile or Documents folder should not contain the configuration.

Enabling true portable mode

Extract the portable package and create an empty file named portable.txt in the same directory as opentrack.exe. When portable mode is active, settings and profiles are stored with the application rather than in the normal user configuration directory.

Safe installation location

Avoid placing manually extracted builds in directories with unusual permissions. A simple path such as C:\opentrack is preferable. Standard installations may also use the appropriate Program Files directory.

Understanding the main window

The main window contains the controls required for a basic setup.

Input

The Input or Tracker selector determines where head-pose data comes from. The button beside the selector opens settings for the chosen tracker.

Output

The Output or Protocol selector determines how processed movement is sent to the game or simulator. The adjacent settings button opens protocol-specific options.

Filter

The Filter selector determines how raw movement is stabilized and processed. The filter settings button opens tuning controls.

Options

The Options dialog contains global and profile-related settings such as:

• Shortcuts.
• Axis inversion.
• Camera and pose options.
• Output configuration.
• Game detection.
• Centering behavior.

The exact tabs and labels can vary between releases and modules.

Mapping

The Mapping dialog contains response curves for all six axes.

Start

The Start button opens the selected tracker, activates filtering and begins sending data through the selected output.

Tracking preview

The preview area may display:

• Camera video.
• Detected points or markers.
• A face-tracking rectangle.
• Tracker-specific diagnostic information.

Pose model

The 3D model in the main window visualizes the current processed pose. If the model moves correctly but the game does not, the tracker is probably working and the problem is more likely related to the output protocol, game configuration, permissions or compatibility.

Raw and game data

The numerical pose displays distinguish between raw tracker data and processed or game-facing data. This distinction is useful when diagnosing mapping, inversion, filtering and output problems.

Quick start

The following sequence is appropriate for most installations.

1. Download and install or extract opentrack.
2. Connect or prepare the tracking hardware.
3. Launch opentrack.
4. Select the correct input.
5. Open the input settings and confirm that the device is detected.
6. Select a filter.
7. Select the correct output protocol.
8. Assign a Center shortcut.
9. Press Start.
10. Confirm that the pose model moves with the head.
11. Open the Mapping dialog.
12. Configure yaw and pitch first.
13. Configure roll and positional axes if the tracker supports them.
14. Launch the game or simulator.
15. Test centering, direction, range, smoothness and latency.
16. Save the configuration as a dedicated profile.

Choosing a tracking method

The best tracker depends on budget, required accuracy, lighting, acceptable setup complexity and whether head-mounted hardware is acceptable.

NeuralNet Tracker

NeuralNet Tracker estimates head pose from an ordinary camera using a trained model.

Strengths: no LED clip or printed marker; works with many existing webcams; the fastest way to test opentrack with minimal hardware; can provide 6DOF pose estimation.

Limitations: tracking quality depends on lighting, camera quality, CPU performance, face visibility and model settings. Low frame-rate webcams can feel delayed, strong backlighting or a dark face can reduce stability, extreme angles may reduce pose accuracy, and background motion or camera processing can affect results.

Best for: users who already have a webcam and want to evaluate head tracking before buying or building hardware. Recent releases include additional models, resolutions and frame-rate options — test more than one model, because accuracy and performance vary by camera and processor.

PointTracker

PointTracker detects a three-point light model, usually mounted on a headset, cap or rigid clip. The points may use infrared or visible LEDs.

Strengths: low latency with a high-frame-rate camera; accurate rotational and positional tracking; predictable geometry; works well in dark environments with infrared LEDs; excellent performance when the camera, threshold and model dimensions are configured correctly.

Limitations: requires a physical point model and accurate measurements; LEDs must remain visible; reflections and background lights can be detected as false points; incorrect point ordering can cause pose flips; exposure and threshold settings require tuning.

Best for: serious simulator use when low latency and stable 6DOF tracking matter more than a completely hardware-free setup.

ArUco Tracker

ArUco tracking uses a printed square marker viewed by a camera.

Strengths: no electronic headgear; inexpensive; easy to reproduce; suitable for testing camera-based 6DOF tracking.

Limitations: the marker must remain visible; motion blur reduces reliability; marker orientation matters; a planar marker can produce unstable pose estimates near a perfectly front-facing orientation; the marker is larger and less discreet than an LED clip.

Best for: users who want camera-based tracking without LEDs and do not mind wearing or mounting a printed marker.

TrackHat Sensor V2

TrackHat Sensor V2 is a high-frame-rate infrared tracking sensor. It can be used with the TrackHat customized opentrack build or with the standard application.

Strengths: low-latency 6DOF tracking; infrared operation; reliable across lighting conditions; large tracking area; commercial hardware with a simplified setup path.

Limitations: primarily supported on Windows; standard opentrack may require more manual tuning than the customized build; behavior and configuration differ between the official and vendor-customized applications. Follow current TrackHat documentation, because integration details can change.

Smartphone sensor tracking

A phone can send orientation data to opentrack over UDP, typically with an Android client compatible with the FreePIE UDP or opentrack UDP format.

Strengths: uses hardware many users already own; gyroscopes provide responsive rotational tracking; needs no camera visibility; works in darkness; useful for experimentation and custom mounting.

Limitations: usually limited to 3DOF unless the app estimates position; sensor drift may occur; magnetometers can be disturbed by headset speakers, metal, magnets and electronics; a head-mounted phone adds weight; wireless networking can add latency or packet loss. A USB network connection is generally preferable to Wi-Fi when supported.

iPhone and iPad TrueDepth tracking

Compatible iPhones and iPads can use their front-facing TrueDepth system through third-party applications such as Eyeware Beam or other compatible head-pose senders.

Strengths: accurate depth-assisted face tracking; no head-mounted marker; can provide 6DOF data; the device can sit beside or below the display; some apps also provide eye tracking.

Limitations: requires a compatible device and third-party application; the phone and computer may need to share a network; firewall rules can block communication; third-party pricing, platform support and protocol details may change independently of opentrack. For UDP-based integration, select the input expected by the third-party application and match its configured port exactly.

Tobii Tracker

Supported Tobii hardware can provide tracking data through the Tobii input module. Compatibility depends on the specific device, installed Tobii software, supported SDK and current opentrack build.

Eyeware Beam

Eyeware Beam can send head-pose data from supported Apple devices or compatible software to opentrack. Older setup instructions commonly use UDP port 4242, but current Eyeware documentation should be treated as authoritative, because the application and integration may change.

XREAL One

Current opentrack code includes support related to XREAL One hardware. Compatibility with specific XREAL One and One Pro configurations may depend on firmware, operating system, connection method and community-maintained integration details.

Hatire and Arduino trackers

The Hatire input accepts data from compatible microcontroller-based head trackers. These systems often use Arduino-compatible boards, gyroscopes, accelerometers, magnetometers, custom firmware and serial communication.

Strengths: low-cost DIY hardware; works without a camera; suitable for custom enclosures and experimental systems; can provide responsive rotational data.

Limitations: sensor calibration is essential; magnetometer interference can cause drift or incorrect heading; firmware and serial format must match the Hatire implementation; many DIY builds provide only 3DOF; electrical and mechanical quality vary widely.

UDP input

UDP input receives pose data from another computer, a mobile device, a custom tracking application, a network bridge or a research or hardware project. The sender and receiver must use the same data format, IP address and port. UDP is also useful for separating tracking and gaming workloads across two computers.

Joystick input

Analog joystick axes can be interpreted as tracking input — useful for testing mappings, specialized simulator controls, accessibility systems and custom analog hardware. It is not equivalent to automatic head tracking, but it uses the same mapping and output pipeline.

Wiimote tracking

A Wiimote can detect infrared points and provide tracking input. Requirements include:

• Compatible Wiimote.
• Bluetooth connection.
• Three-point infrared model.
• Correct cap or clip dimensions.
• Clear line of sight.

Steam may capture connected Wiimotes and prevent opentrack from accessing them. In that case, add the device to the Steam controller blacklist using its VID and PID. Wiimote configurations are now a specialist or legacy option: hardware revisions, Bluetooth stacks, Steam behavior and Windows support can affect reliability.

Kinect V2

Kinect V2 can be used through face tracking or Easy Tracker configurations.

• Kinect Face Tracker estimates pose directly from the face and requires no marker. It is comparatively easy to set up but may provide less range or precision than a dedicated point-based system.
• Easy Tracker uses the Kinect V2 infrared camera and passive reflective markers, and requires the marker geometry to be defined in millimeters.

Kinect V2 is discontinued hardware and should be considered a legacy configuration. Verify driver availability and current Windows compatibility before investing time in a setup.

Intel RealSense

The RealSense tracker uses supported Intel 3D-camera hardware and face-tracking libraries. Support depends on the specific camera generation and compatible SDK. Older RealSense documentation may not apply to current devices or operating systems.

Oculus Rift and Razer Hydra

opentrack has historically supported Oculus Rift and Razer Hydra inputs on Windows. These integrations are mainly relevant to legacy hardware and should not be assumed to work with current device generations.

BBC micro:bit, LEGO, SensorTag and S2Bot

Experimental and educational hardware may communicate through S2Bot-compatible integrations. These options are intended for custom projects rather than normal plug-and-play installation.

Camera selection and placement

Camera behavior has a major effect on tracking quality.

Frame rate

A higher frame rate reduces motion-to-photon delay and produces more frequent pose updates. For head tracking, 30 FPS is usable for many webcams, 60 FPS generally feels more responsive, and higher rates can help when the camera and tracker support them without sacrificing image quality. A nominally high frame rate is not useful when the camera driver applies heavy buffering or automatic image processing.

Resolution

Higher resolution can improve point and marker localization, but it also increases processing load. For point tracking, a moderate resolution at a high frame rate is often better than a high resolution at a low frame rate. The PS3 Eye is commonly used at 640 x 480 and 60 FPS. Avoid unsupported or unstable frame-rate and resolution combinations.

Camera position

Place the camera where it can see the tracking target through the entire intended movement range. Typical positions include:

• Centered above the monitor.
• Centered below the monitor.
• Slightly offset to one side.
• Mounted near eye level.

A camera mounted far off-center can introduce pose distortion if the tracker assumes a centered optical relationship. Recent versions include camera-offset support for camera-based trackers — use it when the physical camera is mounted substantially above, below or beside the display.

Field of view

A narrower field of view makes tracked points occupy more pixels but reduces the available movement area. A wider field of view allows larger movement but produces smaller tracked features. For a PS3 Eye with an adjustable lens, the commonly referenced positions are approximately:

Exposure and gain

For point tracking:

• Use enough exposure to make LEDs consistently visible.
• Adjust gain to control brightness and noise.
• Avoid excessive bloom around each point.
• Avoid a noisy background.
• Disable unnecessary automatic camera processing when it causes unstable brightness.
• Do not assume zero gain is always optimal.

The best combination produces three compact, stable points with minimal false detections.

Background and reflections

PointTracker may incorrectly detect windows, lamps, sunlight, reflective surfaces, bright device indicators, glasses reflections and glossy furniture. Reduce background light, reposition the camera, use an optical filter or improve threshold settings.

For infrared tracking, exposed photographic film or another suitable infrared-pass material has historically been used to reduce visible-light interference. Any filter must be tested carefully, because some materials block too much infrared light.

PS3 Eye camera setup

The PlayStation 3 Eye remains popular because it can provide high frame rates at low resolutions. opentrack includes support for an open PS3 Eye driver path on Windows.

Driver installation overview

1. Open Windows Device Manager.
2. Remove incompatible or obsolete PS3 Eye drivers.
3. Install the supported libusbK package.
4. Use the libusbK INF wizard to associate the camera with the appropriate driver.
5. Restart opentrack.
6. Select the PS3 Eye input where available.

Driver troubleshooting

If the camera suddenly stops working:

1. Open Device Manager.
2. Inspect Universal Serial Bus controllers.
3. Remove unknown or failed USB devices related to the camera.
4. Reconnect the camera.
5. Reinstall or reassign the libusbK driver if necessary.
6. Try another USB controller or port.

Using the camera and its microphone simultaneously may require a specific libusbK configuration.

Recommended tracking principles

For PointTracker with a PS3 Eye:

• Prefer 640 x 480 at 60 FPS when stable.
• Avoid unstable combinations such as corrupted high-rate modes.
• Use auto-threshold when it produces reliable point separation.
• Set the expected point size slightly larger than the visible LEDs.
• Use the correct color-selection mode when tracking colored visible LEDs.
• Keep the points large enough to locate accurately but not so bright that they merge.

PointTracker model geometry

PointTracker needs the physical arrangement of the three tracking points. Incorrect dimensions are one of the most common causes of:

• Incorrect translation.
• Pose instability.
• Reversed movement.
• Sudden flipping.
• Poor calibration.
• Tracking loss at specific angles.

Coordinate system

The model is described using X, Y and Z coordinates. A chosen LED acts as the origin (X = 0, Y = 0, Z = 0). A conventional interpretation is:

Confirm the coordinate convention shown by the current PointTracker dialog, because model orientation can differ between cap and clip presets.

Measuring the model

Measure from the center of one LED to the center of another. Do not measure:

• The outside edge of the LED housing.
• The plastic clip dimensions.
• The approximate visual spacing.
• The distance projected onto a flat plane when the points have different depths.

Use millimeters and record all three dimensions accurately.

Cap and clip models

A cap model usually places the points in a roughly vertical or triangular arrangement facing the camera. A side clip usually places the model to the left or right of the head. Select the correct model type and orientation: a mirrored or incorrectly oriented clip can produce severe pose errors even when all three points are detected.

PointTracker calibration

Model dimensions describe the tracking target. Calibration estimates the relationship between the tracked target and the user’s actual center of head rotation.

Recommended calibration procedure

1. Sit in the normal operating position.
2. Look slightly upward.
3. Start calibration.
4. Turn the head left and right through a comfortable yaw range.
5. Lower the head slightly.
6. Repeat the left-right movement.
7. Continue through a few different pitch positions.
8. Stop calibration using the same calibration toggle.
9. Return to the normal forward-facing position.
10. Center the tracker.

Do not repeat the same movement for an excessive period. The calibration method is statistical: it benefits from several distinct head poses, not from hundreds of identical samples.

Why calibration matters

Without correct calibration, the virtual camera may move in an arc when the head rotates. Turning left may also move the virtual position sideways or backward, because the tracker follows the LED model rather than the approximate center of the head. Correct calibration reduces this unwanted coupling.

Camera offset versus model calibration

These settings solve different problems:

• Model calibration estimates the relationship between the tracking target and the head’s rotational center.
• Camera offset describes the physical position of the camera relative to the expected viewing axis.

Do not use extreme model-calibration values to compensate for a badly placed or off-center camera when a camera-offset control is available.

Recovering from PointTracker pose loss

When one or more points disappear or are confused with background reflections, the pose solver may select the wrong orientation. Symptoms include:

• The pose model flips.
• The model appears upside down.
• The center moves far away.
• Translation values jump.
• Movement remains incorrect after all three points return.

Possible recovery methods include:

1. Face forward.
2. Temporarily cover one LED.
3. Keep it covered longer than the configured dynamic-pose timeout.
4. Uncover the LED.
5. Press Center.

Some older versions may require Center to be pressed twice to reset the dynamic pose and then establish the correct center.

If pose loss occurs repeatedly, fix the cause rather than relying on recovery:

• Improve point visibility.
• Reduce reflections.
• Correct the model dimensions.
• Increase the point size in the camera image.
• Adjust threshold and exposure.
• Reduce the movement range.
• Reposition the camera or LED model.

ArUco marker setup

ArUco tracking uses a high-contrast printed marker.

Preparing the marker

1. Print a compatible Original ArUco marker.
2. Keep the print flat and undistorted.
3. Mount it on rigid cardboard or another flat support.
4. Avoid transparent tape over the black pattern.
5. Avoid glue bleeding through the paper.
6. Leave a clean white border around the marker.
7. Mount it securely so it does not flex during movement.

Orientation

The marker can be detected when rotated, but incorrect mounting orientation can swap or invert yaw and pitch. Before fixing the marker permanently:

1. Hold it in front of the camera.
2. Start tracking.
3. Keep physical roll close to zero.
4. Verify that yaw, pitch and roll move in the expected directions.
5. Rotate or remount the marker if the axes are incorrect.

Avoiding pitch spikes

A flat marker viewed perfectly front-on can create an ambiguous pose. Mount the marker at an oblique angle so the raw pitch remains clearly on one side of the ambiguous position. A neutral physical angle of approximately 15 to 25 degrees is a useful starting point. If the marker crosses through the ambiguous orientation, sudden pitch spikes may occur.

Mapping curves

Mapping curves are the core of the opentrack experience. A tracker can be accurate and stable but still feel unusable when the curves are poorly designed.

Input and output axes

The horizontal direction of a mapping graph represents physical movement; the vertical direction represents virtual movement sent to the game. For rotational axes, values are normally expressed in degrees; for positional axes, values are normally expressed as distance.

Basic principle

The game camera usually needs to move farther than the head. You cannot physically turn 180 degrees while continuing to look at the monitor, so a curve amplifies the movement. Example:

The exact curve depends on display size, seating distance, field of view, game type and personal preference.

Center region

The center should allow precise control of instruments, gunsights, runways, menus and forward-facing targets. A very steep center causes the view to drift or oscillate with tiny head movements; a completely flat center creates a noticeable dead area. Prefer a smooth, shallow center rather than a large deadzone.

Outer region

The outer part of the yaw curve should provide enough movement to check six o’clock, look over a shoulder, follow a target through a turn, and inspect side panels or windows. Do not make the outer curve so steep that small additional movement produces a violent camera jump.

Pitch

Pitch often requires less maximum output than yaw. A typical setup may provide a large upward range for overhead panels or aerial combat, a moderate downward range for cockpit instruments, and different upward and downward curves.

Asymmetric curves

Asymmetric mapping allows positive and negative movement to use different curves. This is useful when:

• The user has different comfortable movement ranges to the left and right.
• A side-mounted clip behaves differently in each direction.
• Looking down requires less gain than looking up.
• The cockpit has an asymmetric seating position.
• Physical limitations require different response on each side.

Roll

Many users apply less gain to roll than to yaw and pitch. Excessive virtual roll can make the image uncomfortable and may add little practical value.

Translation

Translational mapping should feel proportional and controlled. Common uses include Z movement to lean toward instruments, X movement to look around a canopy frame, and Y movement to raise the viewpoint. Large translation gains can create an unnatural floating sensation — start conservatively.

Disabling unwanted axes

A 6DOF tracker does not require all six axes to remain active. Disable or flatten an axis when it adds noise, is unsupported by the game, causes discomfort, is unnecessary for the intended use, or interferes with another control method.

Axis inversion

If movement occurs in the wrong direction, invert the affected axis. Examples:

• Turning left moves the game view right.
• Looking up moves the camera down.
• Leaning forward moves the camera backward.

Inversion may be available in the core output options, tracker settings or protocol settings. Avoid applying inversion in multiple places: two inversions cancel each other and make the configuration harder to diagnose.

Test one axis at a time:

1. Disable tracking output if necessary.
2. Move only one physical axis.
3. Watch raw and processed values.
4. Apply inversion once.
5. Confirm the result in the target game.

Centering and offsets

Centering defines the current physical pose as the virtual forward position.

Correct centering procedure

1. Sit in the normal operating posture.
2. Place the head where it will remain during play.
3. Look at the center of the display.
4. Press Center.
5. Avoid centering while leaning, turning or adjusting the chair.

Center at startup

Center at startup automatically treats the initial pose as the neutral pose. This is convenient but can produce an incorrect center if tracking starts while the user is looking away, adjusting equipment or not yet seated.

Camera and head offsets

Offsets are useful when:

• The camera is not centered.
• The physical tracking model is mounted to one side.
• The user sits off-center relative to the display.
• The game’s default viewpoint does not match the desired seating position.

Use offsets carefully. An offset should correct geometry or neutral position, not hide a bad model, unstable tracker or incorrect mapping curve.

Filters

Filters balance stability against responsiveness. No filter can recover information that the tracker never measured correctly. Fix hardware, lighting, frame rate, model geometry and camera settings before using aggressive filtering.

Alpha Spectrum

Alpha Spectrum is a modern adaptive filter included in current opentrack code. It changes smoothing strength according to recent movement energy on each axis. At low motion, smoothing remains stronger, micro-jitter is reduced and the view becomes steadier. At high motion, the filter moves toward a more responsive state, fast turns catch up more quickly and perceived latency decreases. It exposes separate rotational and translational controls.

• Minimum — response during low-motion conditions. Higher values reduce initial lag but increase visible micro-jitter; lower values produce a steadier resting view but soften the beginning of movement.
• Maximum — response during larger or faster movement. Higher values produce faster turns and reduce catch-up time but can feel twitchier; lower values produce smoother large movement but increase perceived lag.
• Curve — how quickly the filter transitions from minimum to maximum response. A higher curve keeps stronger smoothing active for longer; a lower curve opens responsiveness earlier.
• Deadzone — suppresses very small changes. Too much creates a sticky center and ignores deliberate micro-movement.

Adaptive Mode

Adaptive Mode adds responsiveness during sustained movement. Enable it for fast combat, frequent large head turns, and situations where catch-up speed matters. Disable it for predictable precision scanning, slow cockpit interaction, and configurations where consistent response is more important than adaptive behavior.

Recommended tuning order

1. Reset the filter to defaults.
2. Disable Adaptive Mode initially.
3. Hold the head still and observe jitter.
4. Perform a slow pan.
5. Perform a fast turn.
6. Lean forward and backward.
7. Tune rotation first.
8. Tune translation second.
9. Change one parameter family at a time.
10. Use small adjustments.
11. Enable Adaptive Mode only after the base response feels correct.

Example starting profiles

These values are starting points, not universal recommendations.

Alpha Spectrum troubleshooting

• The view jitters while the head is still: increase the minimum smoothing effect or deadzone slightly. First confirm the tracker is not producing large raw spikes.
• Movement feels delayed: increase Maximum, reduce Curve or enable Adaptive Mode.
• Movement feels too aggressive: reduce Maximum, increase Curve or disable Adaptive Mode.
• Small deliberate movements disappear: reduce the deadzone.

Accela

Accela is an adaptive filter widely used in older configurations. Its historic 2.3 interface separates rotational and positional smoothing and deadzone. General principles remain valid: smoothing reduces visible noise but delays small movement; deadzone ignores movement completely; excessive deadzone reduces precision; camera-based tracking normally requires only a small deadzone when the hardware is configured correctly. Old recommendations written for opentrack 2.2 or early 2.3 builds should not be copied blindly into current releases.

Hamilton and Accela-Hamilton

Hamilton-based filtering handles rotation using mathematically appropriate orientation processing. Accela-Hamilton combines Hamilton rotation handling with Accela-style responsiveness. These filters may be useful when rotational motion behaves poorly around large angles or when a user prefers their response characteristics.

Natural Movement

Natural Movement is another filter option available in recent versions. Its behavior should be tested against Alpha Spectrum and Accela using the same tracker and mapping profile.

Choosing a filter

Use the filter that produces the best result under four tests:

1. Stable forward view.
2. Precise slow movement.
3. Smooth continuous tracking.
4. Fast turn with acceptable catch-up time.

Do not select a filter solely because it has more parameters.

Shortcuts

Shortcuts are essential during actual gameplay.

Toggle is useful with snap views, when interacting with a fixed cockpit panel, reading an external checklist, or temporarily preventing unintended camera movement.

Keyboard and gamepad shortcuts

Current releases may support keyboard, joystick or XInput gamepad shortcut input. If a gamepad shortcut does not work, verify that the required Windows GameInput components are installed.

Privilege mismatch

A shortcut may be ignored when the game runs as administrator but opentrack runs as a normal user. Use the same privilege level for both applications. Running both normally is preferable unless the game genuinely requires administrator privileges.

Profiles

Profiles allow separate configurations for different games, trackers and seating arrangements. Create different profiles when changing the game or simulator, aircraft or vehicle, display, field of view, tracker, camera position, head-mounted model, filter, mapping range, seating position or output protocol.

Recommended profile strategy

Use clear names such as:

• MSFS - NeuralNet
• DCS - PointTracker
• IL-2 - IR Clip
• X-Plane - Linux
• Racing - Tobii
• Testing - Raw Camera

Avoid overwriting a known-good profile while experimenting. Duplicate the profile first, then modify the copy.

Configuration directory

The application can open its configuration directory from the profile controls. Use this directory to back up profiles, import profiles, compare configurations, and move a setup to another computer.

Profiles cannot be saved

Windows Documents synchronization can interfere with profile access. If profiles disappear, fail to save or revert:

• Check OneDrive synchronization.
• Confirm that the Documents directory is writable.
• Test portable mode.
• Check antivirus or controlled-folder-access restrictions.
• Avoid running different opentrack versions against the same configuration directory without backups.

Output protocols

The correct output depends on the target application.

FreeTrack 2.0 Enhanced

FreeTrack is the most common choice for Windows games that support FreeTrack or TrackIR-compatible head-pose input. Use it when the game explicitly supports FreeTrack, TrackIR-compatible input, NPClient-compatible tracking, or opentrack through a FreeTrack interface. Some games require additional game-detection configuration or specific executable identification.

SimConnect

SimConnect is intended for compatible versions of Microsoft Flight Simulator. Use the SimConnect output rather than a generic protocol when the simulator integration requires it.

FSX Steam Edition

Older FSX Steam configurations may require installation of a legacy SimConnect package from the simulator’s SDK directory. A typical SDK path contains SimConnect SDK\LegacyInterfaces\FSX-XPACK. Run the included SimConnect.msi, then configure opentrack to use SimConnect. Installation paths vary.

FSUIPC

FSUIPC output is intended for older Microsoft Flight Simulator configurations, including FS2002 and FS2004-era integrations.

FlightGear

Use the FlightGear output for compatible FlightGear installations. Confirm that the simulator is listening on the expected interface and that firewall rules allow the connection when networking is involved.

X-Plane

X-Plane integration differs by platform and version. Linux configurations may use the X-Plane plugin together with the Wine output option. Follow current plugin instructions and verify architecture compatibility.

UDP output

UDP output sends pose data to another computer or compatible application. Use it for multi-computer simulator installations, custom software, motion or visualization systems, network relays and debugging. The destination IP address and port must match the receiver.

Virtual joystick

Virtual joystick output converts head-pose axes into joystick axes. This is useful when the game supports joystick input but not head tracking, when a custom mapping is required, or when head movement must control another analog function. A compatible virtual joystick driver is required. Virtual joystick output usually lacks the native camera semantics of a dedicated head-tracking protocol.

Mouse output

Mouse output maps head movement to pointer or mouse-camera movement. Use it only when no native tracking protocol is available. Limitations include no absolute 6DOF pose, interaction with normal mouse input, menu-control conflicts, inconsistent camera acceleration and game-specific mouse smoothing.

Wine FreeTrack protocol

The Wine output supports compatible Windows games running through Wine on Linux or macOS. It is distinct from native Linux FreeTrack support.

SteamVR bridge

SteamVR output may require an external bridge such as OpenVR-OpenTrack. This is separate software and may have its own installation, driver, security and compatibility requirements.

Game detection

Some FreeTrack-compatible games require opentrack to identify the game executable. In Game Detection:

1. Add the game executable.
2. Select the appropriate protocol behavior.
3. Save the profile.
4. Restart opentrack and the game if necessary.

Use the actual game executable, not only a launcher. Examples of incorrect selections include the Steam launcher, a publisher launcher, an updater, an anti-cheat bootstrapper or a crash reporter. The executable that creates the game window or loads the tracking client is usually required.

Recommended setup recipes

Basic webcam setup

Hardware: ordinary webcam. Input: NeuralNet Tracker. Filter: Alpha Spectrum or another current adaptive filter. Output: FreeTrack 2.0 Enhanced for compatible games.

1. Place the camera near the center of the display.
2. Use even front lighting.
3. Select a moderate resolution and the highest stable frame rate.
4. Confirm face detection.
5. Configure yaw and pitch.
6. Add translation only after rotation is stable.
7. Reduce filter deadzone if small movement feels sticky.

High-performance DIY IR setup

Hardware: PS3 Eye or another high-frame-rate camera, a three-point infrared clip or cap, and an optional infrared-pass filter. Input: PointTracker. Filter: Alpha Spectrum, Accela-Hamilton or Accela. Output: FreeTrack 2.0 Enhanced.

1. Install the correct camera driver.
2. Enter exact model dimensions.
3. Set exposure and gain.
4. Configure point threshold.
5. Remove false background detections.
6. Calibrate the head center.
7. Configure yaw and pitch curves.
8. Add positional axes.
9. Test extreme angles for point occlusion.

Paper marker setup

Hardware: webcam, printed Original ArUco marker, rigid backing. Input: ArUco.

1. Print and mount the marker.
2. Verify orientation.
3. Mount it at a modest oblique angle.
4. Confirm that raw pitch does not cross the ambiguous front-facing state.
5. Configure camera exposure to avoid motion blur.
6. Calibrate and center.

Phone sensor setup

Hardware: Android phone with gyroscope, stable head mount, USB or Wi-Fi network connection. Input: FreePIE UDP or another compatible UDP receiver.

1. Connect phone and PC to the same network.
2. Configure the PC local IP address in the sender.
3. Match the UDP port.
4. Permit the connection through the firewall.
5. Keep the phone away from headset magnets.
6. Configure yaw, pitch and roll.
7. Assign Center.
8. Test for drift over several minutes.

iPhone or iPad setup

Hardware: compatible Apple device with TrueDepth support where required, stable mount near the display. Input: Eyeware Beam or the UDP input specified by the tracking application.

1. Install the mobile and desktop components.
2. Connect both devices to the same network.
3. Set the Windows network profile appropriately.
4. Permit the desktop tracking application through the firewall.
5. Match the input port.
6. Calibrate the third-party application.
7. Select the correct opentrack output.
8. Keep the mobile application active during use.

TrackHat Sensor V2 setup

Hardware: TrackHat Sensor V2. Software: the TrackHat customized opentrack build or the official opentrack release. The customized build is generally simpler for the Sensor V2 because it includes vendor-specific presets and a reduced interface. Use standard opentrack when advanced customization, diagnostics or integration with another module is required.

Windows

Windows is the primary platform for official prebuilt opentrack releases. It supports the broadest combination of camera drivers, FreeTrack output, SimConnect, FSUIPC, joystick input, virtual joystick output, Tobii integrations, commercial tracking hardware and legacy Windows-specific devices.

Windows security and permissions

When tracking works in the opentrack preview but not in the game, check:

• Administrator privilege mismatch.
• Antivirus restrictions.
• Controlled folder access.
• Firewall rules.
• Blocked DLL loading.
• Incorrect game executable.
• Architecture incompatibility.
• Another tracking application already using the protocol.

Camera exclusivity

Most cameras can be opened by only one application at a time. Close camera preview tools, video-call software, browser camera tabs, OBS camera sources, vendor camera utilities and any other opentrack instance.

Linux

Official Linux binaries are not normally provided by the project. Linux users generally build opentrack from source or use a distribution or community package.

Core build dependencies

Common dependencies include CMake, Git, C++ build tools, OpenCV development files, procps development files, and Qt 6 base and tools development packages. Package names vary between distributions.

Example Debian or Ubuntu dependencies

build-essential
cmake
git
libopencv-dev
libproc2-dev
qt6-base-private-dev
qt6-tools-dev

Basic build process

git clone https://github.com/opentrack/opentrack
cd opentrack
cmake -B build
cmake --build build
cmake --install build

The exact install command and prefix depend on the generator and configuration.

Optional Linux components

Additional dependencies may be required for ArUco, Easy Tracker, PointTracker, Hatire serial input, RealSense, NeuralNet through ONNX Runtime, Oscpack, SteamVR, Wine or Proton integration, and X-Plane.

Proton and SteamPlay

A common failure occurs when opentrack is installed under /usr but the game runs inside the Steam pressure-vessel environment. Install opentrack somewhere that is not replaced by the runtime, such as /opt/opentrack or $HOME/.local. Wine and Proton tracking require the correct Wine output components and matching game prefix configuration.

Missing modules

On Linux, a tracker or output may not appear in the menu when one of its shared-library dependencies is missing. Run opentrack from a terminal and inspect the loader errors. Do not assume that a missing menu item means the module was removed — it may have failed to load.

macOS

The opentrack codebase includes macOS support, but the platform is currently unmaintained. Possible limitations include:

• Build failures on recent toolchains.
• Unsigned binaries.
• Camera-permission issues.
• Outdated output drivers.
• Architecture incompatibility.
• Missing dependencies.
• Unmaintained virtual joystick support.

macOS users should expect to build from source and diagnose platform-specific issues. Do not purchase hardware solely for an opentrack macOS setup without verifying current compatibility.

Troubleshooting

opentrack does not start

Check:

• Whether the package was extracted completely.
• Whether antivirus quarantined a module.
• Whether required runtime libraries are installed.
• Whether a very old configuration is causing startup failure.
• Whether another injected library is corrupting the process.
• Whether the application path contains problematic permissions.
• Whether the CPU supports features required by the selected build.

Test with a new portable directory and no imported profiles.

The camera is not available

Possible causes: another application is using it; the wrong driver is installed; camera privacy permission is disabled; the camera is connected through an unstable USB hub; the selected resolution is unsupported; the device name changed after a driver update.

NeuralNet does not detect the face

Improve front lighting, camera angle, camera exposure, distance from the camera, face visibility, and resolution and model selection. Remove masks, heavy occlusion or strong backlighting where possible.

PointTracker detects no points

Check model dimensions, camera exposure, gain, threshold, LED power, optical filter orientation, the selected camera, the correct color mode, and whether the points are large enough in the image.

PointTracker detects too many points

Reduce false detections by darkening the background, closing curtains, removing reflective objects, adjusting threshold, reducing exposure or gain, using an infrared-pass filter, and moving bright equipment indicators out of frame.

Tracking is jumpy

Inspect raw values first. If raw values jump, fix camera or sensor input, improve point detection, increase frame rate, correct model dimensions, remove false detections and improve lighting. If raw values are stable but output jumps, inspect mapping curves, reduce curve discontinuities, check axis inversion, reset the filter and test another filter.

Tracking is slow

Possible causes: low camera frame rate, camera buffering, excessive filter smoothing, high-resolution NeuralNet processing, wireless UDP delay, CPU saturation, game-side camera smoothing, or vertical synchronization and rendering latency. Reduce filter strength only after confirming the tracker update rate.

The view drifts

Drift is common with inertial and mobile trackers. Recalibrate the sensor, keep magnetometers away from speakers and metal, disable unreliable magnetometer fusion in the sender when supported, assign an accessible Center shortcut, and use optical tracking when long-term absolute orientation is required.

Movement is reversed

Invert only the affected axis. Check both tracker-side and output-side inversion to avoid double inversion.

Movement is too sensitive

Reduce the mapping curve output or extend the physical input range. Do not solve excessive sensitivity only by increasing filter smoothing.

Movement is not sensitive enough

Increase the mapping output at the desired physical angle. Confirm that the game is not applying an additional sensitivity limit.

The center feels sticky

Reduce the mapping deadzone, filter deadzone and tracker-specific deadzone. A sticky center often results from multiple deadzones applied at different stages.

The view shakes while stationary

Check raw tracker noise, camera exposure, point size, face-tracking confidence, sensor vibration, and desk or monitor movement. Then increase low-motion filtering slightly.

Tracking works in opentrack but not in the game

Check:

• Correct output protocol.
• Correct game executable in Game Detection.
• Same administrator privilege level.
• Game head-tracking option enabled.
• No competing TrackIR or FreeTrack application.
• Correct architecture and client DLL.
• Firewall rules for network protocols.
• Game restart after enabling tracking.
• Game-specific plugin installation.

FreeTrack output does not work

Try moving the portable installation to a simple path such as C:\opentrack, running the game and opentrack at the same privilege level, selecting FreeTrack 2.0 Enhanced, adding the correct game executable, closing TrackIR software, and restarting the game after opentrack is already running. Some games implement FreeTrack or TrackIR compatibility incorrectly; a failure is not necessarily caused by opentrack.

Shortcuts do not work in the game

Use the same privilege level for both applications. Also check keyboard layout, game input capture, modifier-key conflicts, XInput or GameInput requirements, whether the shortcut works only while tracking is active, and whether the game intercepts the key first.

Profiles cannot be saved

Check OneDrive, Documents folder permissions, controlled-folder access and portable mode.

UDP tracking does not work

Verify sender IP, receiver IP, port, protocol format, firewall, network profile, subnet, VPN interference, whether the sender uses localhost instead of the PC LAN address, and whether another process already uses the port. Use wired or USB networking when possible.

Proton game receives no tracking

Install opentrack outside /usr, configure the Wine output, and verify that the required files are visible inside the game Proton prefix.

opentrack crashes with GIGABYTE OC GURU

GIGABYTE OC GURU has historically interfered with other processes and has been associated with opentrack crashes. Remove or fully disable it before further diagnosis.

opentrack fails while using Moonlight

Older NVIDIA GameStream and Moonlight configurations may inject rxgamepadinput.dll into running applications. If this causes opentrack failure, identify the injected component and disable or rename it only after backing it up and confirming the effect. Current Moonlight configurations may differ from these legacy instructions.

Wiimote is not detected while Steam is running

Steam may take control of the Wiimote. Add the device VID and PID to the Steam controller blacklist, then restart Steam and opentrack.

PS3 Eye stops working

Inspect Device Manager for an unknown USB device, remove it, reconnect the camera, and reinstall the open driver if necessary.

PointTracker flips upside down

The solver has probably lost or confused one or more points. Return to the center, restore all three points, reset the dynamic pose and press Center. Then fix visibility, reflections, geometry or threshold settings.

ArUco pitch suddenly spikes

The marker is probably approaching a pose ambiguity near the front-facing plane. Mount it at a larger angle and keep raw pitch consistently positive or consistently negative.

Performance optimization

For the lowest practical latency:

• Use the highest stable tracker frame rate.
• Avoid unnecessary camera processing.
• Use USB rather than Wi-Fi for networked phones where possible.
• Reduce NeuralNet resolution when CPU-bound.
• Keep the point model large enough in the frame.
• Avoid excessive filtering.
• Use a direct USB connection rather than a congested hub.
• Close applications that use the same camera.
• Test whether the game adds its own camera smoothing.
• Keep mapping curves continuous.
• Use current graphics and chipset drivers.

Do not optimize only for numerical frame rate. A stable 60 FPS camera with low buffering may outperform a nominally faster mode with corrupted frames or added driver latency.

Designing a good physical setup

A reliable physical setup matters more than extreme software tuning.

Seating

Use a consistent seating position. Changes in chair height, monitor position, camera angle, headset placement or LED clip orientation can alter tracking geometry.

Rigid mounting

The tracking target must move with the head. A flexible LED clip, loose phone mount or bending paper marker introduces motion that opentrack cannot distinguish from actual head movement.

Cable management

A wired LED clip or phone should not pull on the headset. Cable tension can rotate the tracker, limit head movement, cause intermittent USB or power connections, and change the neutral position.

Visibility envelope

Test the complete intended range: maximum left yaw, maximum right yaw, upward pitch, downward pitch, lean forward, lean backward, and combined yaw and pitch. Many trackers work correctly on individual axes but lose points during combined motion.

Advanced network setups

opentrack can separate tracking from the gaming computer. For example:

• Tracking computer: Camera → Tracker → Filter → UDP output.
• Gaming computer: UDP input → optional mapping or filter → Game output.

This configuration can reduce CPU load on the game computer or allow a camera to remain connected to another machine. Avoid applying heavy mapping and filtering on both computers unless deliberately required.

For low latency:

• Use wired Ethernet.
• Keep both systems on the same local network.
• Avoid Wi-Fi repeaters.
• Use fixed local IP addresses or DHCP reservations.
• Permit only the required UDP port through the firewall.

UDP does not guarantee packet delivery. The tracker should tolerate occasional dropped packets without accumulating delay.

Legacy and experimental configurations

Several Wiki pages describe hardware or software that is no longer mainstream. These guides remain useful as technical references but should not be treated as current purchase recommendations. Legacy or specialist configurations include:

• Windows Phone tracking clients.
• Kinect V2.
• Older Intel RealSense face tracking.
• Razer Hydra.
• Early Oculus Rift hardware.
• Wiimote tracking.
• DIY smartphone VR based on Google Cardboard and game streaming.
• Old FreePIE Android packages.
• Historical Accela 2.2 settings.
• Unofficial prebuilt Linux packages.

Use modern alternatives where practical. The most accessible current paths are generally:

• NeuralNet with a webcam.
• PointTracker with a high-frame-rate camera.
• A supported commercial infrared sensor.
• A current phone-based tracking application.
• Tobii, Eyeware or another supported tracker.
• A custom UDP or Hatire device for advanced users.

Building from source

Source builds are intended for developers and advanced users. opentrack is primarily written in modern C++ and uses CMake and Qt.

Windows build tools

Common build environments include Microsoft Visual Studio, MSYS2 with MinGW-w64, CMake, Qt, OpenCV for camera-based modules, and optional tracker and protocol SDKs. Use a git clone rather than a downloaded source ZIP when submodules or repository metadata are required.

A typical build process is:

1. Clone the repository.
2. Initialize required submodules.
3. Create an out-of-source build directory.
4. Configure with CMake.
5. Provide Qt and optional SDK paths.
6. Build a release or RelWithDebInfo configuration.
7. Build or run the install target.
8. Launch the installed executable rather than a partial build-tree binary.

Current builds use Qt 6, while older Wiki instructions may reference Qt 5 and Visual Studio 2017. Treat old version numbers as historical examples, not fixed requirements.

Linux build tools

Use GCC or Clang with CMake, Qt 6, OpenCV and the required module dependencies.

Optional SDKs

A complete build may require additional dependencies for RealSense, ONNX Runtime, SteamVR, X-Plane, Wine, ArUco, serial devices and Oscpack. A module that lacks its dependency may be skipped or may fail to load at runtime.

Developing new modules

opentrack is organized around plugins. Module families include:

• tracker-* — input modules.
• filter-* — filtering modules.
• proto-* — output protocols.

Plugin interfaces are defined in the project API headers. The central runtime pipeline connects Tracker → Filter → Protocol. Relevant source areas include plugin interfaces and support, pipeline logic, runtime tracking state, persistent application state, options and configuration bindings, settings migrations, and main-window and GUI code.

A new module should:

• Implement the appropriate plugin interface.
• Expose required metadata and construction functions.
• Keep UI and processing logic separated where practical.
• Handle missing hardware cleanly.
• Avoid blocking the real-time tracking loop.
• Validate configuration.
• Preserve compatibility with profile storage.
• Include documentation and test procedures.

Reporting problems

Before opening an issue:

• Update to the current official release.
• Test with a new profile.
• Record the selected input, filter and output.
• Confirm whether raw pose data is correct.
• Confirm whether the 3D model moves correctly.
• Test outside the game.
• Identify the exact game executable.
• Record operating-system and hardware details.
• Include camera resolution and frame rate.
• Include relevant logs or terminal output.
• Describe what was expected and what occurred.
• State whether the problem is reproducible.

For tracking-quality issues, include a screenshot of the camera preview, PointTracker model dimensions, filter settings, mapping curves, raw and processed pose behavior, lighting conditions and camera placement.

Project history

opentrack originated from ideas and code associated with FaceTrackNoIR, created by Wim Vriend. The codebase was later extensively rewritten while retaining several concepts from the original project.

The project has grown through contributions involving PointTracker, Oculus Rift, Razer Hydra, Intel RealSense, Hatire, micro, Wiimote, Kinect Face Tracker, Easy Tracker, Hamilton filtering, pose visualization, Eyeware Beam, Tobii, platform support, translations, documentation, hardware testing, and reports from simulation communities.

Stanisław Halik is the project maintainer. opentrack is an open-source project rather than a conventional commercial company. Development is performed by maintainers and contributors working on trackers, filters, protocols, hardware support, bug fixes, translations and documentation.

Licensing and warranty

Almost all opentrack code is licensed under the permissive ISC license. Some files, dependencies, SDKs and optional components may have separate terms — check the licensing information associated with each component.

The software is provided without warranty. The maintainers and contributors disclaim responsibility for damage, loss, incompatibility or other consequences arising from installation or use. Open-source availability and careful development do not create a legal guarantee of fitness for a particular purpose.

Name clarification

The head-tracking project is unrelated to the railway planning software available under the OpenTrack name. The railway software used the name first. Documentation on this page refers exclusively to the open-source head-tracking application for simulators, games, hardware trackers and compatible software.

Recommended first configuration

For a new user with no dedicated hardware:

• Input: NeuralNet Tracker.
• Filter: Alpha Spectrum in its default or simplified mode.
• Output: FreeTrack 2.0 Enhanced.
• Enabled axes: yaw and pitch first.
• Center shortcut: a convenient keyboard or controller button.
• Camera: centered near the display at the highest stable frame rate.

After yaw and pitch work correctly: add roll, add Z translation, add X and Y translation, refine the center region, reduce unnecessary deadzones, test fast turns, and save a game-specific profile.

For a user prioritizing minimum latency and maximum repeatability: a high-frame-rate camera, a three-point infrared model, PointTracker, accurate model measurements, proper calibration, a carefully tuned adaptive filter, and the native game protocol where available.