
Implementations
===============

all
---

All daemons accept "-p" to specify the serial port. Where two
ports are required, "-q" specifies the second port.



skeleton
--------

A bare bones "skeleton" implementation of the functions which a TDM
library needs to provide. See documentation for more details on what
these are.

This implementation moves tracker 0 in a circle, tracker 1
horizontally, tracker 2 vertically, and tracker 3 in and out.

To make Maverik use this implementation set mav_opt_TDMLib to
"${TDM_HOME}/lib/libtdm-skeleton.so" in your application code before
initialising the TDM module.



keys
----

An implementation which allows you to control a tracker's position,
orientation and event generation via the keyboard.

Cursor keys - move tracker 0 left, right, up, down.
q, a - move tracker 0 in and out.
e - generate event for button 0 on tracker 0.

To make Maverik use this implementation set mav_opt_TDMLib to
"${TDM_HOME}/lib/libtdm-keys.so" in your application code before
initialising the TDM module.



SpaceBall
---------

This implementation controls tracker 0's position via a
SpaceBall. Note: it only tracks position, but orientation could be
trivially added. Similarly, while button events are trapped and a
message printed to the shell window, the event is not passed back to
Maverik via the TDM interface.

The implementation uses the SpaceWare SDK which provides a mechanism
for incorporating SpaceBall support into an application and achieves
this by using the X input extensions. It therefore requires access to
Maverik's X state and event loop. It was always assumed, wrongly, that
communication with additional input devices would be via a serial line
rather than X. As such, no interface to Maverik's X state or event
loop was designed into the system.

However, a messy way of accessing these has been put in place and is
used by this implementation. The interface should be re-done cleanly
sometime in the future.

Note that the SpaceWare SDK is no longer available for download from
Spacetec's site (at least I cant find it).

To make Maverik use this implementation set mav_opt_TDMLib to
"${TDM_HOME}/lib/libtdm-sball.so" in your application code before
initialising the TDM module.



Polhemus
--------

This implementation controls tracker's 0-3 via a Polhemus FASTRAK or
ISOTRAK II six degree of freedom tracking system. If you have less
than 4 Polhemus receivers, their position will be reported as the
origin. The implementation also supports Division 3D mice, i.e. a
Polhemus receiver embedded in a grip with a number of buttons.

The implementation works as follows. A daemon process, completely
separate from the TDM library and Maverik, is executed. This
immediately forks. The parent process creates a shared memory segment,
opens a connection to the Polhemus box, and enters an endless loop of
sampling the data from the Polhemus sensors placing the results in the
shared memory. The child process connects to the shared memory, opens
a connection to the Division box, and similarly enters an endless loop
of sampling the button status also placing the results in the shared
memory. The child process detects changes in the button statuses and
notes these as button events in the shared memory.

If you do not have a Division box, then simply comment out the fork
command in poldaemon.c which will prevent the child process being
created.  

The TDM library is a piece of code which connects to the shared
memory segment and copies the latest data from it as needed. As such, 
the values returned by TDM_getPosition and TDM_getButton are not the
status when the routines were called, but rather the status the last
time the Polhemus and Division boxes ware sampled. However, at most
these will only be a few 10's of milliseconds old. 

We run our Polhemus box at 115200 baud to minimize lag - this value is
defined in polhemus.c. Our Polhemus transmitter has a rather odd
orientation - the "Polhemus" sticker reads from bottom to top up the
left hand side of the transmitter cube as you stand in front of it,
with the cable located at the bottom right. This results in us having
to negate X and Z and use a (0,0,-1) active hemisphere. Modification
of the receiver's directional vectors must also be performed. However,
this takes place on a per-receiver basis since each receiver is
mounted on its associated device in a different orientation, i.e. the
receivers embedded in our mice return a different orientation to the
one mounted on our HMD when both mice and HMD are held with the same
orientation. Decoding the Polhemus receiver position and orientation
values takes place in polhemus.c

To make Maverik use this implementation set mav_opt_TDMLib to
"${TDM_HOME}/lib/libtdm-polhemus.so" in your application code before
initialising the TDM module.

Ensure that the polhemusd executable, located in the bin
sub-directory, is running before starting a Maverik application which
uses this TDM implementation. The daemon assumes a FASTRAK system and
auto-detects the number of receivers. Start the daemon with "-i n" if
you have an ISOTRAK II system where n is the number of receivers
present. Starting the daemon with "-d" causes debugging information to
be displayed. Starting the daemon with "-l" causes the Longranger
settings to be used. Starting the daemon with "-v" indicates you have
a Division box. Starting the daemon with "-c" causes distortion
calibration to be employed (note, the calibration data file is site
specific - contact us for information about how it is generated).



InterTrax 30
------------

This implementation controls tracker's 0 orientation via an InterSense
InterTrax 30 gyroscopic tracker. The device does not generate events
and its position is reported as the origin (0,0,20).

The implementation uses the same daemon and client principle as
described for the Polhemus trackers. (However, no fork is performed
since only a single device is involved).

To make Maverik use this implementation set mav_opt_TDMLib to
"${TDM_HOME}/lib/libtdm-it30.so" in your application code before
initialising the TDM module.

Ensure that the it30d executable, located in the bin
sub-directory, is running before starting a Maverik application which
uses this TDM implementation. N.B. starting the daemon with any command
line argument causes debugging information to be displayed.

The daemon can sometimes, particular after a reboot, fail to start
first time. If this happens quit the daemon and try again. If this
still fails you may have a problem!



SpaceOrb360
-----------

This implementation controls tracker 0's position and orientation via
a SpaceOrb360. The 7 buttons on the device generate events.

The implementation uses the same daemon and client principle as
described for the Polhemus trackers.

Ensure that the so360d executable, located in the bin
sub-directory, is running before starting a Maverik application which
uses this TDM implementation. N.B. starting the daemon with a "-d"
command line argument causes debugging information to be displayed.

To make Maverik use this implementation set mav_opt_TDMLib to
"${TDM_HOME}/lib/libtdm-so360.so" in your application code before
initialising the TDM module.



Flock of Birds
--------------

This implementation controls tracker's 0-2 via an Ascension Flock of
Birds system with Extended Range Controller. The number of receivers
is controlled via a hash define at the top of fob.c (remember the ERC
counts as a station although it does not produce any meaningful
output). Birds must have consecutive addresses starting at 2.

A baud rate of 38400 is used (defined in fob.c).

Ensure that the fobd executable, located in the bin sub-directory, is
running before starting a Maverik application which uses this TDM
implementation. N.B. starting the daemon with any command line
argument causes debugging information to be displayed.

To make Maverik use this implementation set mav_opt_TDMLib to 
"${TDM_HOME}/lib/libtdm-fob.so" in your application code before
initialising the TDM module.



Mouse
-----

This implementation controls tracker 0's position and orientation via
a serial Logitech Marble Mouse. The horizontal and vertical movements
of the mouse are mapped onto orientation yaw and pitch *and* x and y
position displacements from an arbitrary value. The two buttons on the
mouse generate events.

Ensure that the moused executable, located in the bin sub-directory, is
running before starting a Maverik application which uses this TDM
implementation. N.B. starting the daemon with any command line
argument causes debugging information to be displayed.

To make Maverik use this implementation set mav_opt_TDMLib to
"${TDM_HOME}/lib/libtdm-mouse.so" in your application code before
initialising the TDM module.



Magellan
--------

This implementation controls tracker's 0 position and orientation via
a Magellan Space Mouse. The 9 buttons (1-8 and *) generate events.

The implementation uses the same daemon and client principle as
described for the Polhemus trackers.

Ensure that the magelland executable, located in the bin
sub-directory, is running before starting a Maverik application which
uses this TDM implementation. N.B. starting the daemon with a "-d"
command line argument causes debugging information to be
displayed. Starting it with "-m n" (where n=1 or 2) indicates the
number of Space Mice attached (default 1).

To make Maverik use this implementation set mav_opt_TDMLib to
"${TDM_HOME}/lib/libtdm-magellan.so" in your application code before
initialising the TDM module.



5DT data glove (contributed by Alessandro De Luca)
--------------

This implementation controls tracker's 0 orientation via a 5DT data
glove.

Ensure that the gloved executable, located in the bin sub-directory,
is running before starting a Maverik application which uses this TDM
implementation.

Command line switches:

a: absolute mode
  In absolute mode the true hand position is reported, provided it is
  within sensor range.

r: relative mode
  In relative mode the glove act like a floating joystick, rotating
  continuosly while the hand is not in a neutral position.

g: angle gain
  An alternative solution for limited range is to scale angles so the
  object or view that receive tracker data can cover a wider range.

y: map glove roll to tracker yaw
  In many cases controlling pitch/yaw can be more useful than pitch/roll.
  Using this switch hand roll is reported as yaw by the tracker.

To make Maverik use this implementation set mav_opt_TDMLib to
"${TDM_HOME}/lib/libtdm-glove.so" in your application code before
initialising the TDM module.

Todo: some basic support for gesture recognition, to generate button
events.



wrapper (contributed by Alessandro De Luca)
-------

The wrapper implementations allows multiple simultaneous devices to be
supported. The devices to be used are defined in a ".tdmrc" file
located, in order of precedence, in the local directory, the user's
home directory, or the TDM directory (picked up from the TDM_HOME
environment variable which must be set in order to use this
implementation).

The file format is a series of two value pairs defining the tracker
number (an integer) and the library name of the device (a string). For
example:

0 keys
1 so360
2 polhemus
6 magellan

With this .tdmrc file, the "keys" TDM implementation is used for
tracker 0 (there is no need to specify the full library name, just the
bit after the hyphen). A SpaceOrb360 (library name "so360"), which if
used on its own reports its status on tracker 0, now reports its
status on tracker 1. The Polhemus implementation which supports upto 4
trackers (normally reported as 0-3) is used to provide the status of
trackers 2-5. Finally, tracker 6's status is provided by a Megellan
Spacemouse.

Note that it is the user's responsibility to ensure the correct
daemons are running. Also, you can not have two devices of the same
type in the .tdmrc file since this would cause a clash in the shared
memory used to communicate with the daemon.

To make Maverik use this implementation set mav_opt_TDMLib to
"${TDM_HOME}/lib/libtdm-wrapper.so" in your application code before
initialising the TDM module.
