BIV: Open Inventor Viewer for FakeSpace Boom

Created and originally documented by Ramesh Johari, July 1995

I. General Overview

The BIV package define a viewer for use with the FakeSpace VR boom. This viewer is essentially designed to be easy to use, and yet give enough expandability and customization power to take full advantage of Inventor in a VR environment.

Directory: /pro/trout/satchmoo/BoomViewer

Library: BIV.so

Executable: BIVview [filename [defaults]]

Usage: Any SGI machine communicating with the FakeSpace boom (currently posse)

A NOTE ON USAGE: Before running any program that has been linked with the BIV.so library, you must make sure the environment variable LD_LIBRARY_PATH contains ``/pro/trout/satchmoo/BoomViewer.''

II. Files

A. BIVMonochrome.

These files define the monochrome nodes used by the viewer. These nodes contain information for both color and monochrome rendering; the viewer replaces any ordinary DirectionalLight, PointLight, SpotLight, BaseColor, Environment, Material, and Texture2 node by its monochrome counterpart.

B. BIVEvent.

These files define boom event classes--extensions of SoButtonEvent and SoMotion3Event. They are used in pick mode in the viewer; these events can be passed down the scene graph, and handled like any other SoEvent.

C. BIVGLMonochromeRenderAction.*

These files define a monochrome render action. In reality, this is just a wrapper around SoGLRenderAction. But it is made so that the GLRender methods of the monochrome nodes have a means for determining if they should render themselves monochrome or not.

D. BIVViewer.*

These files actually define the viewer class, BIVViewer. This is the class that will be used in any application program.

E. BIVview[.*]

These files create a sample viewer program to show the BIVViewer in action. The interface is the same as ivview.

III. Getting started (fast)

A. BIVview

The easiest way to use the BIV package is to simply run BIVview. BIVview is a program similar to ivview that can view files, with the added functionality of being able to use the boom.

To run BIVview, type

	BIVview [filename [defaults]]

where filename is an Inventor file, and defaults is a string of four numbers: the default interocular distance, the default acceleration value, the default scale factor, and the default zoom value, in that order. Note that specifying these values is optional. Also note that these defaults only apply to the filename passed on the command line; any file loaded while in BIVview will not be affected by these values.

The interface is very simple. First, position the model however you would like; this defines the zero position for the camera. Then, to turn on boom viewing, click the right button in the viewport to bring up the popup, and go to Preferences. In the preferences sheet, turn on the Boom Viewing toggle; this brings up an intimidating set of thumbwheels and buttons.

The first thumbwheel controls interocular distance. This controls how many units apart your eyes are.

The second thumbwheel controls acceleration. This controls how fast you accelerate when you push down the left or right buttons on the boom (see below for description of button controls).

The third thumbwheel controls scale. The value defines how many Inventor units correspond to one meter on the boom. This can be used to increase or decrease the immersive experience, by adjusting how big or small the user is.

The radio box at the bottom controls event handling in pick mode. When in pick mode, you have the option of either passing boom events to the scene graph or using the viewer's default handling (i.e., use the viewers default definitions for the buttons). When boom events are passed down the scene graph, they are passed as BIVMotion3Event's and BIVButtonEvent's; for these to do something, nodes in the scene graph must be defined to handle them.

The zoom slider controls field of view/perspective. The higher the zoom value, the more perspective you will feel. This is also useful for controlling the immersive experience.

The controls on the boom are:

Left Button: flies backward along current viewing direction, with acceleration defined by the value in the preferences sheet (see above).

Right Button: flies forward along current viewing direction, with acceleration defined by the value in the preferences sheet (see above).

Right Button + Left Button: focuses on object along viewing direction (i.e., the distance along the viewing direction to the object--if any--is set as the focal length of the camera).

A NOTE ON OPENING NEW FILES: Make sure that when you open a new Inventor file from the File menu, you are not in Boom Viewing mode. First open the file, then turn on boom viewing. (This is necessary to make sure the viewer is initialized correctly for the new scene graph.)

B. Using the BIVViewer in an Inventor application

Using the BIVViewer in an Inventor application is almost as easy as using BIVview. There are two steps:

1. Include the BIVViewer header file:

#include "/pro/trout/satchmoo/BoomViewer/BIVViewer.h"

2. Initialize the BIVViewer class. This needs to be done before any instance is created; use the following call:

BIVViewer::initClass();

3. Instance the class as you would any other viewer; just pass it the parent widget, and (optional) the default values for the four Boom Viewing parameters: the interocular distance, the acceleration value, the scaling value, and the zoom value.

This will create a viewer for your application, which will look and feel like an SoXtExaminerViewer, except for the Boom Viewing additions.

IV. Details

A. Structure

The BIV package is essentially built around two different notions: input and output. Input is the input read from the boom; the hard work here is handled by the code from Steve Bryson at NASA. Output is the monochrome rendering done; the workload here is handled by the monochrome subclasses of Inventor nodes which contain color properties--base color, environment, lights, materials, and textures.

B. Input

Input is handled by reading from the serial port whenever data is ready, using XtAppAddInput(). The returned values are transformed so that the camera is translated and rotated by the ``original'' camera position and orientation values (these being the values at the time that boom viewing was switched on), and also scaled by the current world scale factor.

Note that these things only happen if we are either in viewing mode or event handling is set to Viewer Controlled in pick mode. Otherwise, in pick mode, the BIVMotion3Event sends the current (absolute) position of the boom down the scene graph, and the BIVButtonEvent sends the state of each button down the scene graph.

C. Output

This is by far the most complex part of the viewer. It requires several steps, documented below:

1. The setSceneGraph() method is called. This sets the scene, and then triggers two callback functions, which, in sum, replace every instance of a color property node in the scene with an identical BIVMonochrome copy.

2. A redraw is triggered. This calls the BIVViewer's actualRedraw method, which has been redefined to do a different style of two pass rendering from SoXtViewer. (Note that stereo viewing has been removed from the actualRedraw method, since it seemed worthless if Boom Viewing was being used.)

The method first renders from the left eye position into the blue channel of the current screen (using glColorMask()), and then renders from the left eye position into the red channel of the current screen. The eye positions are determined using the current camera focal length and viewer interocular distance.

3. The BIVGLMonochromeRenderAction is applied to the scene graph. When this happens, each node renders in monochrome; this is because the GLRender methods of the BIVMonochrome nodes checks to see if the render action is a BIVGLMonochromeRenderAction, and if so, renders in monochrome.

The details of how the nodes render in monochrome are actually simple. Each BaseColor, Material, and Texture2 node maintains an instance of SoBaseColor, SoMaterial, or SoTexture2, respectively, as a member; this is the monochrome version of the node. This instance has its fields linked to the fields of the BIVMonochrome node; thus, whenever the BIVMonochrome node changes, the connected fields are updated and monochromatized by field sensors. Then, when rendering, we either render in color using the normal fields, or we render in monochrome using the monochrome node.

For the other BIVMonochrome nodes, the mechanism is actually simpler, since the fields to monochromatize are smaller (SoSFColor's instead of SoMFColor's). This means that we simply make the relevant fields monochrome on the fly in the GLRender method, and then restore them when we are done.

A NOTE ON THESE EXTENSIONS TO INVENTOR: The main reason for this (seemingly complex) form of implementation is that Inventor 2.1 does not allow modification of the SoGLRenderAction method list; this means the only way to modify rendering methods is to directly subclass off the nodes we wish to modify.

V. Extensibility

A. The Viewer

The BIVViewer class cannot actually be subclassed. This is because the necessary protected constructor (documented in The Inventor Toolmaker) was never written, mainly since no need seemed evident. If you wish to subclass the boom viewer, this constructor must be written first.

B. The Render Action

This doesn't (and shouldn't) need to be subclassed, because it is simply a wraparound on the SoGLRenderAction with a different type name.

C. The Nodes

These can be subclassed. Just keep in mind that the GLRender methods should be written carefully, taking into account the type of the render action they were passed (based on the models of the original BIVMonochrome nodes).

A NOTE ON EXTENDING LIGHT NODES: If you create a new light node and would like it to have monochrome functionality, you can subclass off of BIVMonochromeLight. This is an abstract class whose GLRender method provides for monochrome rendering.

VI. Questions/Comments

If you have any questions or comments on the BIVViewer, you can send email to the creator of the package at rjohari@fas.harvard.edu or the current maintainer at lsh@cs.brown.edu.

This file is http://www.cs.brown.edu/software/biv/BIVManual.html
Translation to html by Framemaker 5.0 and Loring Holden
Slight changes to part VI (Questions/Comments) by Loring Holden

Loring Holden