Name

libtracker.a - provides access to 3D transform and button state data from 3D tracking devices

Synopsis

#include "tracker.h"

Tracker * TrackerInit( int which );
void tracker->Open( char * path );


void tracker->SetMode( int mode );
int tracker->GetMode( );
void tracker->SetTranslationScale( double factor );
double tracker->GetTranslationScale( );
void tracker->SetUpAxis( int axis );
int tracker->GetUpAxis( );
int tracker->GetButtonCount( );
void tracker->Reset();


void tracker->GetTransform( double matrix[4][4] );
void tracker->GetButtons( int buttons[] );


void tracker->Close();

Description

SDSC's 3D Tracker library enables programs to read 3D transform and button state data from several 3D tracking devices (eg: Magellan, Polhemus, Flock of Birds, etc). Features of this library include:
• Low-level API is identical for all tracker devices
• High-level API enables access to all devices through one library
• Devices are "interchangeable" in applications

The common feature set of all supported devices is embodied in one simple-to-use API. This means that an application only needs to integrate a single API in order to provide 3D tracking control using ANY supported device. As new low-level device drivers are added to the library, the new tracking capability becomes available to the high-level API and consequently to your application!

Functions

Initialization

TrackerInit

must be called once to initialize each device driver you wish to access. The which argument specifies the desired device to initialize (see tracker.h for a list of valid TRACKER3D_... values). Upon successful completion, the corresponding low-level device driver is initialized and a tracker object pointer for that device is returned. Otherwise, a NULL value is returned. Some examples include: TRACKER3D_MAGELLAN a small desktop 3D tracking device which senses small amount of torque applied by twisting, pushing, and pulling motions. TRACKER3D_POLHEMUS a hand-held 3D tracking device which uses magnetic fields to sense position and orientation of the tracking unit within an 8 or 10 foot radius of the base unit.

Open	opens the serial driver associated with the device specified by the path argument. This must be called once after a call to TrackerInit in order to enable communications with the device.

Configuration

SetMode

changes the matrix output behavior (for GetTransform calls) to the specified mode (see tracker.h for a list of valid MODE_... values). Some examples include: MODE_RAW (default) the matrix is output exactly as the low-level device driver generates it (that is, unscaled and not cumulative). This mode is useful for absolute positioning and orientation of an object's transform (such as when controlling a 3D pointer). MODE_CUMULATIVE the matrix is output as an accumulation of all prior transformations. This is useful for generating smooth continuous control of a transformation (such as when manipulating a 3D shape in a scene).

SetTranslationScale

changes the scaling factor (for GetTransform calls).

SetUpAxis

changes the coordinate system of the matrix (for GetTransform calls) to the specified orientation. AXIS_YUP (default) the positive Y-axis points up the display vertically, the X-axis points to the right, and the Z-axis points outward. AXIS_ZUP the positive Z-axis points up the display vertically, the X-axis points to the right, and the Y-axis points inward.

Reset

sets the internal accumulation matrix (used by MODE_CUMULATIVE) to the identity matrix. This may be called, for example, if a user has manipulated an object offscreen or wishes to return the position and orientation to nice default values (ie: front facing at the origin).

Reading

GetTransform

retrieves the 4x4 double matrix from the tracking device. The upper 3x3 segment is a standard rotation matrix and the first 3 values of the 4th column are translation values.

GetButtons

retrieves the int array buttons from the tracking device. Each value corresponds to the state of a button. The value 0 meaning the button is not pressed and 1 meaning the button is pressed. Call GetButtonCount to determine the number of buttons that a device supports.

Cleanup

Close

must be called once for each open device before your program exits in order to clean up the serial and low-level drivers associated with the tracking device.

Examples

Basics

#include <tracker.h>


Tracker myPointer;
double myPointerMatrix[4][4];
Tracker myCamera;
double myCameraMatrix[4][4];


myPointer = TrackerInit( TRACKER3D_POLHEMUS );
myPointer->Open( "/dev/ttyd1" );
myPointer->SetMode( MODE_RAW );
myCamera = TrackerInit( TRACKER3D_MAGELLAN );
myCamera->Open( "/dev/ttyd2" );
myCamera->SetMode( MODE_CUMULATIVE );


...
myPointer->GetTransform( myPointerMatrix );
myCamera->GetTransform( myCameraMatrix );
...


myPointer->Close();
myCamera->Close();


OpenGL

...
myPointer->GetTransform( myPointerMatrix );
glxxx( myPointerMatrix );
...


Performer

...
myPointer->GetTransform( myPointerMatrix );
pfxxx( myPointerMatrix );
...

Authors

Craig Donner
John Moreland
Deryl Sterling

(c 1999) San Diego Supercomputer Center

Downloading

Download TrackerLib.tar.gz C source archive.

See Also

TrackerModule - An AVS module which provides 3D Tracker capabilities to any AVS network/application.