division_ipu -
VRModules						       division_ipu (6)


NAME
     division_ipu - device driver module for the Divison, Inc. Integrated
	Peripheral Unit.  This device is a hardware interface to, among
	other things, one or more Polhemus fastrak trackers.

SUMMARY
     Name	   division_ipu

     Type	   input

     Inputs	   none

     Outputs	   "hand" : field float 1D 1-space uniform
		   (VR device event field)

     		   "head" : field float 1D 1-space uniform
		   (VR device event field)

     Parameters	   _N_a_m_e		   _T_y_p_e		  _D_e_f_a_u_l_t	 _M_i_n	   _M_a_x
		   Sleep Control   boolean 	  off		 off	   on
		   X Rotate	   boolean	  on		 off	   on
		   Y Rotate	   boolean	  on		 off	   on
		   Z Rotate	   boolean	  on		 off	   on
		   Rotate Scale	   float dial	  1		 .001	   2
		   X displacement  boolean	  on		 off	   on
		   Y displacement  boolean	  on		 off	   on
		   Z displacement  boolean	  on		 off	   on
		   Trans Scale	   float dial	  .75		 .001	   10.
		   Dominant Attitude Filter
				   boolean 	  0		 0	   1
		   Dominant Translation Filter
				   boolean 	  0		 0	   1
		   Rotation Accumulation mode 	boolean	  
						  on		 off	   on
		

DESCRIPTION
	
	The division_ipu module reads packets of information from the
	Division IPU device.  This device is cabled to the workstation
	through two serial ports.  One serial port contains multiplexed
	data from the fastrak trackers.  The other serial port carries
	button-press events from the Division, Inc. 3dmouse.  Up to four
	fastrak trackers are supported by this device.

	The module generates two field streams, one for the "head" and
	one for the "hand."  The "hand" corresponds to tracker #0, and
	the "head" corresponds to tracker #1.  Consult the documentation
	for the fastrak PCB interface for more information.  Changing the
	number of trackers connected to the Division IPU hardware does NOT
	require a software recompile.  However, it does require that some
	DIP switches be flipped on the fastrak PCB, and that the device be
	power-cycled.

	This module has been successfully used with either 1- or 2-tracker
	configurations.

	The module is implemented as a coroutine.  As such, it will flood
	your network with data, as we implemented it to have minimal
	latency.  In the example below, we show use of the "button gate"
	module to selectively "gate" events from the division_ipu module.

INPUTS
	None


PARAMETERS
	Sleep control - a toggle which, when "off", will permit normal
	module execution.  When set to "on", the module goes to sleep, and
	the module will not execute.  This is a way to turn off the 
	division_ipu.

	X Rotate, Y Rotate, Z Rotate - these toggles permit the user to mask
	out portions of the rotation events generated by the trackers.
	When a toggle is set to the "on" value, the corresponding rotation
	value is encoded into the output field.  This is a way to mask out
	rotation events on one or more axes.

	Rotation scale - a floating point value that will attenuate
	rotation events.  Increasing the value of this parm has the effect
	of increasing the sensitivity of the device.  The same scale value
	is applied to all trackers.

	X displacement, Y displacement, Z displacement - toggles to mask out
	portions of the translational component of the device event.  When set
	to "on", the event is NOT masked out.

	Translation scale - a floating point value that will attenuate the
	translational component of the device event.  Increasing the value
	of this parm will have the effect of increasing the sensitivity of
	the device.

	Dominant Attitude Filter - when enabled, the 3-vector rotation portion
	of each output field will contain two zeros and one non-zero value.
	This has the effect of masking out all but the most significant
	component of rotation. Some people feel that it adds a bit more
	control over the trackers, which are otherwise very noisy devices.
	Personally, I don't like it, and don't use it.
	
	Dominant Translation Filter - when enabled, the 3-vector translation 
	portion of each output field will contain two zeros and one non-zero 
	value. This has the effect of masking out all but the most significant
	component of translation. Some people feel that it adds a bit more
	control over the trackers, which are otherwise very noisy devices.
	Personally, I don't like it, and don't use it.

	Rotation Accumulation Mode - presently, this parameter doesn't	
	do anything.

	USAGE - instantiate the module.  upon instantiation, the Division
	IPU will be reset.  The little green LED on the front will flash
	at one-second intervals for six or seven seconds.  After it stops
	flashing and stays on, the device is ready for use.  Then, click
	on "sleep control", and the module will begin to execute
	asynchronously.

		
OUTPUT
	two fields are output, one corresponding to the "head" and
	one corresponding to the "hand".  each is a:

     	field float 1D 1-space uniform - VR device event field.  A set
	of C-language macros is used internal to the code for this 
	module to encode the device event information into an AVS
	field.  This field is not readily processible (unfortunately)
	by "normal" AVS modules.  This is the case because both
	floating point and boolean values are encoded into the field data.
	

EXAMPLE

	This example shows the use of the division_ipu module in such
	a way as to control both the camera position as well as the
	positions of objects in the virtual world.

		division_ipu
	  (head)  |      | (hand)
                  |      |
                  |   button gate   (filters out events)
	VR Xform Camera  |
	    |	     VR Xform Object
            |		 |
	    +------+-----+
	           |
 	    Geoemtry Viewer

RELATED	MODULES

	VR Transform Camera, VR Transform Object, VR to acc floats,
	VR to floats, dummy device, VR print field, button_gate.

SEE ALSO
	button_gate

BUGS
	The macinations required to generate delta-rotation and delta-
	translation values from absolute values gave me a headache.
	In any event, the best results from this module can be had,
	when using the 3dmouse, by pushing button 4 "a lot."

	A useful way to think about this is how you, as a human being,
	interact with the world.  You pick something up, do something
	with it, then put it down.  The same analogy works well when
	using this module.  When the "hand" field is connected to
	"vr xform obj", you press button 4 (under your index finger)
	(assuming also that button gate is wired in between division_ipu
	and vr xform obj), move the object around while holding button 4,
	then release button 4 when you're done moving the object around.
	This method of operation has been user-tested by a bunch of kids
	and they liked it a lot - no instructions were required. ;-)

	Sometimes, the Division IPU fails to reset when this module is
	first instantiated.  Assuming the "ftest" standalone diagnostic
	program works ok, I suggest that you power-cycle the Division
	IPU and try the module again.  This has always worked for me.


VRModules					  Lawrence Berkeley Laboratory
