FreePieCam v1.0

Author: upsidedown
Version 1.0: 30.12.2015
Vorwort
Die Verwendung von sog. Headtrackern  zur Steuerung der Kameraorientierung in PC-Spielen – insbesondere in technischen Fahrzeugsimulationen – erhöht den Spielspaß für den enthusiastischen Gamer erheblich. Unter anderem ermöglicht diese Art der Steuerung es realitätsorientierte Eingabesysteme aufzubauen, bei denen weitgehend auf Maus und Tastatur verzichtet wird. Im Normalfall verbleibt hierbei das Problem, dass die notwendigen Kopfbewegungen für eine Umsicht quasi als zusätzliche Steuergeräte implementiert werden müssen. Hierunter leiden Bedienkomfort und Immersionsfaktor erheblich.
Headtracker lösen diese Aufgabe, indem sie kleine Kopfbewegungen des Spielers erfassen und skaliert in Kamerabewegungen im Spiel übersetzen. Richtig eingestellt ist so ein System sehr intuitiv zu bedienen und befreit die Hände des Spielers für andere Aufgaben.
Kurz gesagt: Headtracker sind geil, aber es ist etwas Arbeit das Ganze vernünftig zum Laufen zu bringen ;)
Zu den Themen TrackIR, andere Headtracker und freePie finden sich mit google und insbesondere auf youtube vielfältige Beispiele, Installationstipps und Hinweise.
Funktionsweise
Der freePieCam-Mod übernimmt die Funktion, die ursprünglich von einem Headtracker stammenden Daten innerhalb des Landwirtschaftssimulators direkt in eine Kameraausrichtung zu übersetzen.
Da der LS15 keine Schnittstelle für Headtracker-Protokolle wie TrackIR oder freeTrack bereitstellt, ist in den meisten Fällen der Umweg über einen virtuellen Joystick notwendig. Wie dieser heißt und wie die Daten dorthin kommen ist grundsätzlich dem Anwender freigestellt. Im Folgenden wird ein Weg dargestellt, der sich im Betatest bewährt hat und zugleich sehr flexibel ist. Dem ambitionierten Bastler sind allerdings (hoffentlich) keine Steine in den Weg gelegt auch andere Pfade zu beschreiten.
Beispielinstallation: TrackIR->freePie->vJoy->freePieCam

TrackIR

Ein funktionierendes und korrekt eingerichtetes TrackIR, sowie dass der Anwender bereits mit diesem vertraut ist, wird vorausgesetzt und hier nicht weiter erläutert.
Es gibt mittlerweile eine Vielzahl an Lösungen für kostengünstiges Headtracking. Was man hier verwendet ist eigentlich fast egal, Hauptsache man kommt aus freePie an die Daten heran.

freePie

download von freePie (links der Button mit „MSI Versionsnummer“)
freePie ist ein ausgesprochen mächtiges Werkzeug, das es erlaubt Daten aus einer Vielzahl an Quellen auszulesen, zu verarbeiten und auf diverse Wege weiterzureichen. Dies geschieht auf Grundlage der Skriptsprache Python.
Don’t panic: Passende .py-Skripte werden mit dem Mod mitgeliefert. Programmierkenntnisse sind also nicht notwendig.
Man kann sich hier allerdings wirklich austoben, und ich bin sehr gespannt was hier von euch alles kommt.

vJoy

Download vJoy von sourceForge
vJoy funktioniert mit aktuellen Windows-Versionen und erfordert auch keine Spezialrechte (Developermodus oder ähnliches).
Je nach geplanter Anwendung müssen ein oder zwei virtuelle Joysticks in vJoy eingerichtet werden. Dies ergibt sich aus zwei Einschränkungen der Joystickschnittstelle von LS15:
·         Es können maximal vier analoge Steuergeräte (Joysticks, Gamepads, Lenkräder, vJoy-devices) erkannt werden.
·         Es können pro Steuergerät nur fünf Achsen ausgelesen werden.
Man muss hier also etwas haushalten. Aus der Beschränkung auf nur fünf lesbare Achsen ergibt sich, dass mit einem vJoy-Device nur fünf Freiheitsgrade (5DOF) übertragen werden können. Headtracker mit Positionserkennung wie TrackIR liefern allerdings alle sechs Freiheitsgrade (6DOF). Ich empfehle 5DOF und 1vJoy als Standard.
Nicht benötigte virtuelle Joysticks sollten in vJoy deaktiviert werden! Dies macht man im „configure vJoy“-Tool, das mit vJoy installiert wird.
Durch das Installieren von zusätzlichen Joysticks kann es passieren, dass die device-Nummern in der InputBinding.xml von LS15 durcheinander kommen! Das ist kein spezifisches Problem mit vJoy, sondern ein generelles Problem an der Art, wie der LS seine Inputgeräte verwaltet und tritt auch mit realen Joysticks auf. Hier behilft man sich am besten händisch mit Notepad++ und passt die device=“x“-Bezeichner mit Suchen&Ersetzen an. Grundsätzlich ist es nach der Installation der virtuellen Joysticks mit vJoy keine schlechte Idee den Rechner einmal neu zu starten bevor man weitermacht.

ZZZ_freePieCam.zip

Dieses Skript wie gewohnt in den Order „mods“ ablegen.
In diesem Zustand wird der Mod genau Folgendes tun: Nichts. Bis auf ein paar log.txt-Einträge, in denen er genau dieses verkündet.
Das ist Absicht, um den Mod z.B. auf dedicated Servern installieren zu können und so Mitspielern ohne Headtracking zu ermöglichen, den Mod ohne notwendige Konfiguration installieren zu können.
Um den Mod zu aktivieren, muss eine Konfigurationsdatei „freePieCam_config.xml“ im UserApp-Verzeichnis von LS15 abgelegt werden. Das ist das Verzeichnis, in dem auch die log.txt liegt.
Beispiel-xml liegen dem Mod bei. Es muss lediglich die zur Konfiguration passende Datei an die richtige Stelle kopiert werden.

Schnelle Inbetriebnahme
Dem Mod sind vorgefertigte Konfigurationen und .py-Skripte beigelegt, mit denen eine schnelle Inbetriebnahme für die meisten Anwender möglich sein sollte. Zusammengehörende „freePieCam_config.xml“ und .py-Skripte sind innerhalb der mod-zip immer in einem Verzeichnis abgelegt. Sind diese an die jeweiligen Stellen kopiert (xml neben die log.txt, die .py-Datei egal wo, Hauptsache der Ort ist dem Anwender bekannt) und alle Programme und virtuellen Joysticks installiert, kann man das Ganze nun folgendermaßen in Betrieb nehmen:


1.       Headtracker starten (z.B. TrackIR-Software). Am besten kurz die Funktion prüfen und zentrieren
2.       freePie starten (eventuell mit Administratorrechten)
3.       Das entsprechende .py-Skript in freePie laden (File->Open) und anschließend mit der F5-Taste starten
4.       LS15 starten, im Spiel zur Innenkamera wechseln, enjoy!


Wer bis hier her gekommen ist und es keine gravierenden Probleme gegeben hat: Genießt erstmal ein paar Stunden auf dem Acker.

Konfiguration/Bedienung

freePie

Die .py-Skripte sind ausgiebig kommentiert! Es ist ausdrücklich jeder eingeladen diese Skripte für sich zu verändern, zu optimieren, umzubauen, auszubauen, mit anderen zu Teilen und in Foren-Posts hochzuladen. Die Kommentare in den Skript-Dateien selber mögen aber bitte für diejenigen als Dokumentation hinreichen. Diese Kurzanleitung ist nicht der Ort um zu erklären wie freePie funktioniert. Die meisten Anwender werden hier nie etwa anfassen müssen.

freePieCam_config.xml

Hier gibt es zunächst einen Block <settings>. Hier werden allgemeine Einstellungen vorgenommen.
·         <controllerName> Hier kann der Name des zu verwendenden Controllers eingestellt werden. Dieser muss exakt(!) so lauten, wie in der log.txt fast ganz oben aufgeführt.
·         <activeOnStart> Das ZZZ_freePieCam-Skript kann im Spiel zwischen Headtracking und Mouse-Kamera umschalten. Hier kann man einstellen, ob das Headtracking beim Spielstart direkt eingeschaltet werden soll (true) oder erst per Tastendruck/Konsolenbefehl zugeschaltet werden soll (false).
·         <useFullRange> Dies ist vermutlich der einzige Parameter, der wirklich etwas erklärungsbedürftig ist. vJoy wird in der aktuellen Version von Windows mit einer falschen Kalibrierung installiert. Das kann man zwar beheben, allerdings ist das nicht ganz einfach. Um den Aufwand zu ersparen, ist das ZZZ_freePieCam-Skript in der Lage, diese verschobene Kalibrierung zu korrigieren (false). Für alle anderen Anwendungen und eventuell auch für zukünftige Versionen von vJoy sollte dieser Parameter true gesetzt werden.
·         <allowOutsideCam> Standardmäßig wird das Headtracking nur für die Innenkameras aktiviert (false). Wer es auch für die Aussenansicht nutzen möchte kann dies hier umstellen (true).
Im Folgenden werden die einzelnen Achsen konfiguriert. Dies sind im Einzelnen:
·         <yaw>  Kopf seitlich drehen
·         <pitch>  Kopf hoch/runter
·         <roll>  Kopf schieflegen
·         <tx>  Kopf links/rechts
·         <ty>  Kopf hoch/runter
·         <tz>  Kopf vor/zurück
Diese Blöcke sind alle identisch aufgebaut:
·         <use> Wird diese Achse überhaupt verwendet? Wenn nicht, muss sie hier abgeschaltet werden (false). Alle folgenden Parameter in diesem Block spielen dann keine Rolle.
·         <device> Bei Verwendung von mehr als einem virtuellen Joystick: Welchem device ist diese Headtracker-Achse zugeordnet? Standard: 0 (erstes device).
·         <axis> Welcher Joystickachse ist diese Headtracker-Achse zugeordnet? Erlaubte Werte: x,y,z,rz,slider
·         <sensitivity> Dieses Feld erfüllt zwei Funktionen:
o   Zum einen kann man hier die Empfindlichkeit der Achse verändern. Grundsätzlich sind dafür die Headtracker-Software oder das .py-Skript die besseren Orte!
o   Falls es notwendig sein sollte eine Achse zu invertieren (Kopfbewegung nach links führt z.B. zu einer Kamerabewegung nach rechts), kann man dies hier durch Eingabe negativer Werte (also z.B. -1.0) beheben.
Die Zuordnung von <device> und <axis> ist bewusst identisch zu den Bezeichnern in den .py-Skripten gewählt.

 
ZZZ_freePieCam inGame

InputBindings
Im Spiel lassen sich zwei InputBindings belegen:
·         freePieCam Umschalten zwischen Headtracking und Mousesteuerung der Kamera
·         freePieCamAllowOutside Zu-/Abschalten des Headtrackings für die Aussenansicht
Beide Funktionen sind standardmäßig nicht belegt um Tastenkonflikte zu vermeiden. Sie sind im Steuerungsmenü durch ein vorangestelltes „freePieCam:: “ leicht zu finden.
Zusätzlich lassen sich beide Funktionen durch gleichnamige Konsolenbefehle schalten. Hierfür ist eine Belegung mit Tasten nicht notwendig. Die Zustände beim Start von LS15 lassen sich wie oben beschrieben in der freePieCam_config.xml mit den Parametern <activeOnStart> und <allowOutsideCam> einstellen.
log.txt
Das Skript ist ausgesprochen mitteilungsbedürftig! Einträge sind durch ein vorangestelltes freePieCam:: gekennzeichnet.
Nicht jeder log.txt-Eintrag ist Fehler oder ein Problem! Das Skript teilt lediglich relativ detailliert mit was es macht und warum es das macht. Das sieht dann z.B. so aus:

freePieCam:: loading C:/Users/upsidedown/Documents/My Games/FarmingSimulator2015//freePieCam_config.xml for freePieCam-Mod configuration
freePieCam:: using device 0 axis x for yaw
freePieCam:: using device 0 axis y for pitch
freePieCam:: using device 0 axis z for tx
freePieCam:: using device 0 axis rz for ty
freePieCam:: using device 0 axis slider for tz
freePieCam:: controller name set to: vJoy Device
freePieCam:: activeOnStart is turned OFF -- you have to activate headtracking manually to use it!
freePieCam:: Using Half Range of vJoy [default].
freePieCam:: External cameras are EXCLUDED in headtracking movement [default].
freePieCam:: freePie Camera support by upsidedown:: vJoy Device Virtual Joystick found! :)
freePieCam:: virtual joysticks found: 1
freePieCam:: use console command 'freePieCam' and/or assign a key to Inputbinding 'freePieCam' to turn ON/OFF
freePieCam:: Scanning InputBindings for conflicts...
_____freePieCam:: suppressing AXIS_FRONTLOADER_TOOL3
_____freePieCam:: suppressing AXIS_FRONTLOADER_TOOL4
freePieCam:: ...scanning for conflicts done!

 
Am Ende des log.txt-Auszuges sieht man noch eine weitere Funktion: Das Skript unterdrückt die Verwendung „seiner“ Joystickachsen durch InputBindings. Das ist insbesondere hilfreich, wenn keine weiteren analogen Eingabegeräte angeschlossen sind oder vJoy aus anderen Gründen auf der Gerätenummer 0 liegt. In diesem Fall würden die ganzen Standardbelegungen durch die Headtracker-Achsen angesteuert werden, was in absolutem Chaos enden würde. Es kann also gut sein, dass dort eine ganze Menge Kram steht, und dass so seine Ordnung hat. Es kann aber auch sein (wie im Beispiel oben)
Sonderfall: ED-Tracker
Die 3DOF ED-Tracker von http://edtracker.org.uk/ melden sich bereits selber als Joysticks am System an. Für diese netten, kleinen und preisgünstigen Geräte sind also weder vJoy noch freePie notwendig.
Eine getestete Beispielkonfiguration liegt dem Skript ebenfalls bei.
Kompatibilität
·         Bei Verwendung der tx,ty,tz-Achsen kommt es zu Problemen mit dem BetterIndoorCamera-Mod.
·         Diverse Kamera-Specialisations schießen auch gerne mal quer. Hier hilft im Zweifelsfall leider nur ausbauen.
·         Manche mods haben auch seltsam verdrehte Kameras verbaut.
·         Die alte ZZZ_TIRsupport.zip muss natürlich entfernt werden. Das freePieCam-Skript weißt darauf aber auch deutlich hin.
Deswegen:
·         Bitte erstmal mit Giants-Standardschleppern testen!
·         Zunächst alle anderen Kamera-Skripte entfernen
Abschließender Kommentar & Support
Meine Empfehlung am Schluss: 5DOF reichen völlig, besonders wenn die Anzahl an analogen Geräten eng wird.
Ansonsten hoffe ich, euch damit ein hinreichend mächtiges, flexibles aber trotzdem gut bedienbares Tool zur Verfügung zu stellen, dass dem Nischenthema Headtracking im LS wieder etwas weiter voran hilft.
Für Fragen und Probleme bitte diesen Thread im Modhoster-Forum verwenden. Dort lassen sich log-Auszüge, .py-Skripte etc sehr viel besser Posten und verfolgen als in den Kommentaren.
Ich freu mich an dieser Stelle auch sehr über eure eigenen Lösungen mit TrackIR-Alternativen, eure eigenen freePie-Implementierungen und Verbesserungen, etc.
Vielen Dank an:
·         Eribus für das Artwork
·         Dem spontan zusammen gecasteten Betatesterteam: Porsche Junior, Wieselflink & bebop
 
Noch ein Wort zum Schluss: Die Zeit einen ausgiebigen Support für so ein nicht triviales Projekt zu leisten kann ich auf absehbare Zeit nicht aufbringen. Ich werde jedem, der sich hier beteiligt und anderen Usern hilft wirklich sehr dankbar sein.