Télécharger et installer headtracking

headtracking est publié en préversion sur GitHub. Chaque version propose une archive par système, avec le plugin VPX et l'application de démonstration. Les noms de fichiers contiennent le numéro de version : choisissez le fichier de votre système sur la page des versions.

Ouvrir la page des versions

Système	Nom du fichier se terminant par
Linux PC à processeur Intel ou AMD 64 bits (x86_64)	`headtracking-…-linux-x86_64.tar.gz`
Linux Processeur ARM 64 bits (aarch64)	`headtracking-…-linux-aarch64.tar.gz`
macOS Mac à puce Apple silicon (série M), macOS 11 ou plus récent	`headtracking-…-macos-aarch64.tar.gz`
Windows PC Windows 64 bits (x86_64)	`headtracking-…-windows-x86_64.zip`

Il n'existe pas pour l'instant de version pour les Mac Intel ni pour Windows sur ARM. Les fichiers Windows sont signés numériquement, et les programmes macOS sont signés et notariés auprès d'Apple.

Contenu de l'archive

Le plugin : headtracking.dll (Windows), libheadtracking.so (Linux) ou libheadtracking.dylib (macOS), avec son plugin.cfg.
headtracking-demo, l'application de démonstration : testez votre caméra sans VPX, et partagez un relevé de votre meuble.
Sous Windows, un dossier setup avec l'installation du pilote Kinect.
La licence et le README.

Installer le plugin dans Visual Pinball X

Il faut Visual Pinball X 10.8.1 ou plus récent.

Créez un dossier headtracking dans le dossier plugins de votre installation de VPX, et copiez-y la bibliothèque du plugin et plugin.cfg. Les deux doivent être dans le même dossier.

<VPX_install>/plugins/headtracking/
├── plugin.cfg
├── headtracking.dll          (Windows)
├── libheadtracking.so        (Linux)
└── libheadtracking.dylib     (macOS)

Lancez VPX une fois : il trouve tout seul le nouveau plugin.
Chargez une table, appuyez sur F12 → Plugin Settings → Head Tracking et cochez Enable. Quittez et rechargez la table : le suivi démarre avec la partie.

Régler la vue

Le plugin rappelle ces points dans une notification au début de chaque partie.

Dans F12 → Cabinet Settings, saisissez la vraie largeur de votre lockbar et l'inclinaison de l'écran. La calibration automatique et la position de la tête reposent sur ces valeurs.
Pour le point de vue de la table, choisissez la disposition Window avec une rotation de 0, et activez le mode cabinet autofit. Window est la disposition conçue pour le suivi de tête.
Tenez-vous à votre place de jeu habituelle pendant le chargement de la table : la première position de tête stable devient la position neutre. Ensuite, maintenez le bouton de la lockbar 2 secondes pour recentrer.

Mesurez ces deux valeurs, ne les devinez pas. Le plugin leur fait entièrement confiance.

Une largeur de lockbar fausse applique la même erreur d'échelle à toutes les distances : l'effet paraît partout trop fort ou trop faible.
Une inclinaison d'écran absente ou fausse mélange le haut/bas avec le proche/loin : la vue dérive en diagonale quand vous bougez, et « quelque chose cloche » sans cause évidente.

Réglages

Tous les réglages se trouvent sur la même page F12 → Plugin Settings → Head Tracking et s'appliquent en direct pendant la partie, sauf Backend et Camera, lus au lancement de la partie (rechargez la table après les avoir changés). Les noms ci-dessous sont ceux affichés, en anglais, dans VPX.

Réglage	Rôle
Backend	Auto (la première caméra trouvée : Kinect v2, puis Kinect v1, puis webcam), Kinect v2, Kinect v1 ou Webcam. Lu au lancement de la partie.
Camera	La webcam utilisée par le backend Webcam ; la liste affiche les vrais noms des appareils. Un backend Kinect prend toujours la première Kinect trouvée. Lu au lancement de la partie.
Gain (all axes)	L'ampleur avec laquelle vos mouvements de tête déplacent la vue, sur les trois axes. 1.0 par défaut ; 0.5 est un bon point de départ sur un pincab.
Gain trim, left/right · up/down · near/far	Corrections par direction, en plus du gain : baissez-en une quand cette direction bouge trop. L'axe proche/loin est celui qu'il vaut le plus souvent la peine de calmer.
Smoothing	Lissage : Stable (le réglage par défaut éprouvé sur le terrain), Normal, Reactive, ou Custom, qui débloque deux curseurs supplémentaires : réactivité et rattrapage des mouvements rapides.
Median Window	Nombre d'images servant à effacer les pics de suivi (1 = désactivé, 3 par défaut). Chaque image en plus ajoute environ 17 ms de retard à 60 images par seconde.
Invert X / Y / Z	Inverse gauche/droite, haut/bas ou proche/loin, pour une caméra montée à l'envers ou de façon inhabituelle.
Webcam Focal (px)	Focale de la webcam en pixels ; 0 = automatique. Utile seulement si la profondeur mesurée par la webcam semble fausse.
Baseline Offset X / Y / Z (mm)	Correction ajoutée à la position de tête neutre capturée au début de la partie, sans avoir à la recapturer.

Ils sont enregistrés dans VPinballX.ini, section [Plugin.HeadTracking]. Si vous modifiez ce fichier à la main, faites-le avec VPX fermé : VPX réécrit tout le fichier en quittant.

Linux

Webcam : votre utilisateur doit avoir le droit d'utiliser la caméra. C'est déjà le cas sur la plupart des distributions (groupe video) ; sinon lancez sudo usermod -aG video "$USER" puis fermez et rouvrez votre session.

Kinect : sans règles udev, seul l'administrateur peut ouvrir la Kinect, et VPX échoue sans rien dire. Si une Kinect est branchée mais absente de la liste des caméras, l'application de démonstration propose un bouton Install udev rule, qui demande votre mot de passe. Vous pouvez aussi ajouter les règles vous-même, puis débrancher et rebrancher la Kinect :

Règles udev pour Kinect v2 et Kinect v1

sudo tee /etc/udev/rules.d/90-kinect2.rules > /dev/null <<'EOF'
# Microsoft Kinect v2 (Xbox One)
SUBSYSTEM=="usb", ATTR{idVendor}=="045e", ATTR{idProduct}=="02c4", MODE="0666"
SUBSYSTEM=="usb", ATTR{idVendor}=="045e", ATTR{idProduct}=="02d8", MODE="0666"
SUBSYSTEM=="usb", ATTR{idVendor}=="045e", ATTR{idProduct}=="02d9", MODE="0666"
EOF
sudo tee /etc/udev/rules.d/51-kinect.rules > /dev/null <<'EOF'
# Microsoft Kinect v1 (Xbox 360) and Kinect for Windows v1
SUBSYSTEM=="usb", ATTR{idVendor}=="045e", ATTR{idProduct}=="02b0", MODE="0666"
SUBSYSTEM=="usb", ATTR{idVendor}=="045e", ATTR{idProduct}=="02ad", MODE="0666"
SUBSYSTEM=="usb", ATTR{idVendor}=="045e", ATTR{idProduct}=="02ae", MODE="0666"
SUBSYSTEM=="usb", ATTR{idVendor}=="045e", ATTR{idProduct}=="02c2", MODE="0666"
SUBSYSTEM=="usb", ATTR{idVendor}=="045e", ATTR{idProduct}=="02be", MODE="0666"
SUBSYSTEM=="usb", ATTR{idVendor}=="045e", ATTR{idProduct}=="02bf", MODE="0666"
EOF
sudo udevadm control --reload-rules
sudo udevadm trigger

Aucune autre bibliothèque à installer : seules des bibliothèques système présentes par défaut sur Debian, Ubuntu, Fedora et Arch sont utilisées.

Windows

Windows + Kinect : à lire avant d'installer le pilote. Pour accéder à la Kinect, l'installation de pilote fournie remplace le pilote Kinect officiel de Microsoft par un pilote WinUSB générique. Cela casse tout ce qui repose sur le SDK Kinect de Microsoft, y compris un head tracking BAM qui fonctionne, jusqu'à ce que vous remettiez le pilote d'origine (Gestionnaire de périphériques, périphériques « Xbox NUI » : désinstaller le pilote puis rechercher les modifications matérielles, ou réinstaller le SDK/runtime Kinect). Ne le lancez que si vous acceptez cet échange. Les utilisateurs de webcam ne sont pas concernés et n'ont rien à installer.

D'origine, Windows n'installe aucun pilote utilisable pour une Kinect v1 ou v2 : elle apparaît comme périphérique inconnu. Pour en installer un :

Branchez la Kinect et lancez headtracking-demo.exe. S'il ne trouve pas de pilote utilisable, un bandeau jaune propose Install Kinect drivers (UAC prompt). Vous pouvez aussi double-cliquer sur setup\setup-kinect.cmd.
Acceptez la demande d'administrateur. La fenêtre PowerShell résume ce qui va changer et vous demande de taper yes ; toute autre réponse annule sans rien toucher.
Attendez la fin du script (10 à 30 secondes environ), cliquez sur rescan dans la démo, puis relancez VPX.

Le script est signé dans les archives publiées. Il fonctionne pour la Kinect v1 comme pour la v2. Si vous préférez ne pas le lancer, vous pouvez associer WinUSB à la main avec Zadig ; les étapes sont dans le guide d'installation détaillé. Sous Windows 7, installez d'abord le Microsoft Security Advisory 3033929.

Une Kinect v2 demande en plus un port USB 3.0 dédié à l'arrière de la carte mère, pas un hub.

macOS

Une Kinect ne demande aucun pilote supplémentaire sous macOS. Pour une webcam, autorisez VPX dans Réglages Système → Confidentialité et sécurité → Caméra la première fois. La version tourne nativement sur Apple silicon.

Compiler depuis les sources

Il faut un Rust stable récent, cmake 3.20 ou plus récent et libclang. Les bibliothèques natives sont incluses en sous-modules et compilées en statique.

git clone --recurse-submodules https://github.com/Le-Syl21/headtracking
cd headtracking
cargo build --release

Tous les détails, dont chaque étape de dépannage Windows et Linux : docs/INSTALL.md.