head-tracker

Architecture

core/camera

OpenCV capture with per-OS backend selection and multi-camera detection.

core/tracker

MediaPipe Face Landmarker. Auto-downloads the model on first run.

core/pose

cv2.solvePnP against a canonical 3-D head model. Returns yaw / pitch / roll in degrees.

core/smoothing

Per-axis exponential moving average, optional Kalman filter, dead-zone, and sensitivity curve.

core/calibration

Averages N samples of the centered pose and subtracts that offset from raw output.

Output adapters

console

Throttled stdout for development.

opentrack

UDP packets in the OpenTrack receiver format (6 × float64).

websocket

Broadcasts pose JSON to connected clients.

mouse

pynput cursor control in absolute or relative mode.

joystick

Virtual gamepad via vgamepad on Windows, python-uinput on Linux.

New adapters subclass OutputAdapter and register themselves in outputs/__init__.py. The core never imports adapters directly.

Pose output

{
  "yaw":        float,   // −180..180   left / right
  "pitch":      float,   // −90..90     up / down
  "roll":       float,   // −180..180   head tilt
  "confidence": float
}

Yaw, pitch, and roll come from solving the Perspective-n-Point problem against a canonical 3-D head model and decomposing the rotation matrix into Y-X-Z intrinsic Euler angles.

Features

• · Real-time webcam preview
• · FPS counter
• · Calibration routine
• · JSON / YAML config
• · Cross-platform hotkeys
• · Automatic face reacquisition
• · Adjustable sensitivity curves
• · Latency optimization mode

Project structure

head-tracker/
├── core/
│   ├── camera.py
│   ├── tracker.py
│   ├── pose.py
│   ├── smoothing.py
│   └── calibration.py
├── outputs/
│   ├── base.py
│   ├── console.py
│   ├── opentrack.py
│   ├── websocket.py
│   ├── mouse.py
│   ├── joystick.py
│   └── __init__.py
├── app/
│   ├── main.py
│   ├── config.py
│   └── ui.py
├── examples/
└── requirements.txt