
Webcambased head tracker for FlightGear
---------------------------------------

Last updated: 2009-06-30

 *  Copyright (C) 2006 - 2009  Anders Gidenstam
 *  http://www.gidenstam.org
 *  anders(at)gidenstam.org
 *
 *  This program is free software; you can redistribute it and/or modify
 *  it under the terms of the GNU General Public License as published by
 *  the Free Software Foundation; either version 2 of the License, or
 *  (at your option) any later version.
 *
 *  This program is distributed in the hope that it will be useful,
 *  but WITHOUT ANY WARRANTY; without even the implied warranty of
 *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 *  GNU General Public License for more details.
 *
 *  You should have received a copy of the GNU General Public License
 *  along with this program; if not, write to the Free Software
 *  Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA

This is an ARToolKit based (http://artoolkit.sourceforge.net/) head tracker for
FlightGear.

Its current status is PREALPHA so don't expect it to work perfectly or
even compile without manual intervention.

The program tracks the head position and the head rotation.
At this stage the the consistency of tracking is somewhat limited and
the axes used are those of the marker card at the origin (which is set 
from the marker's location at startup. 
It is highly advisable to have the marker card vertical and facing the camera
when setting the origin. 

The FlightGear end of the arrangement is a generic input protocol description
and a Nasal module.

Quick instruction:

1. Download and compile ARToolKit. (http://artoolkit.sourceforge.net/)
   I use the CVS version. It sometimes need minor tweaking to compile,
   like e.g. fixing missing function prototypes.

2. Download and compile my program, headtracker.c.

3. Print the Hiro pattern. (pattHiro.pdf from the ARToolkit distribution.)
   Note that there has to be a white border around the black square.

4. Copy the protocol description FlightGear/headtrack.xml to $FG_ROOT/Protocol .

5. Copy the Nasal module FlightGear/headtracking.nas to ~/.fgfs/Nasal
   (a.k.a. $FG_HOME/Nasal/).

6. Run the headtracker program.
   In my case I use
   ./headtracker -palette=YUV420P --port 3254 --host 127.0.0.1
   which would send the position updates to an application (i.e. FlightGear)
   running at localhost.

   headtracker also listens to commands from standard in.
   Currently, these are:
   Options:
    0   exit;
    1   reset origin;
    D/d increase/decrease detection threshold;
    X/x increase/decrease freshness/smoothing factor;
    any key - print state

   This will be improved. 
 
   ./headtracker --help

   NOTE: headtracker needs to be run from the source directory.
         (It hasn't any clever way to find the camera and pattern files yet.)

7. Run FlightGear with the options
   --generic=socket,in,<hz>,,<port>,udp,headtrack
   --prop:/sim/headtracking/enabled=1

8. Yes, the marker card has to be attached to your head somehow and also remain
   within the field of view of the camera for the tracking to work.


For those who don't want to download and install ARToolKit and compile
the program from source I have made a staticly linked Linux/x86 binary:

headtracker-linux-x86-binary (Currently not available)

It still needs to be placed in the source directory and it should
hopefully work on most PCs running Linux. (There are no guarantees, though.)

