INTRODUCTION
The LS-PrePost-VR suite of applications has 3 components:
1. The LS-PrePost-VR application
2. The SinterPoint server
3. The LS-PrePost-Remote desktop client

INSTALLATION & CONFIGURATION GUIDE

SinterPoint Server
SinterPoint is provided as an RPM for RedHat linux systems. Install the RPM nefore running LS-PrePost-VR because the default run script for the VR application starts & stops the SinterPoint server. SinterPoint facilitates communication between the VR and Remote versions of LS-PrePost. If you have a DEMO version of SinterPoint, the server will stay active only for 10 minutes, which means no Remote-to-VR communication will take place after that amount of time unless all applications are restarted.

LS-PrePost-VR
1.  Installation
- Create a directory for the software on your system (typically /vr or /inv3rsion)
   If your system is a cluster, make sure that directory is shared (usually via NFS) across all the cluster nodes.
- Download files to the new directory
   You will need Inv3rsion-provided versions of VR Juggler, LS-PrePost-VR binaries, and LS-PrePost-VR common files.
- Extract all files.
- On your master node (or the only node if not a cluster), set some environment variables:
   export VR_BASE_DIR=/vr
   export PATH=$PATH:$VR_BASE_DIR/bin
- To test the installation, type the following:
   runLsprepostVR.standalone

[To Be Added -- additional steps for cluster installation]

2.  Configuration: The VR Juggler configuration file
LS-PrePost-VR needs a VR Juggler configuration file (.jconf extension) to run. If you have not been provided with a configuration file for your system, you will need to create one. For a single-machine configuration, edit the $VR_BASE_DIR/bin/runLsprepostVR.standalone script to point to your jconf file. Or, if installing in a cluster, make a symbolic link called config.jconf in your $VR_BASE_DIR/config directory that points to yout cluster configuration file.

3.  Configuration: The .lsprepost_vrrc file
The .lsprepost_vrrc file contains many important settings that affect the usability of the LS-PrePost-VR application. Make sure to edit this file before attempting to run the application on your system.

Overview
The application searches for the rc file in the following directories in the order they are listed:
1. $LSTC_FILE (typically $VR_BASE_DIR/apps/lsprepost2)
2. Current working directory
3. $HOME
4. Plot file directory when files are loaded.

The search order makes it possible to have a generic configuration in the LSTC_FILE directory that can be overruled by the current directory and by the user's home directory settings.  Additionally, per-model-directory rc files enable such features as different scaling of different models to enable, for example, 1:1 scale display in VR.  Note: all directories must be accessible by all machines in a cluster via the same directory path for this to work properly.  If home directories are on individual machines and not mounted across all machines, then an rc file in that directory will not work properly.

Model View & Autoscale Settings
The Model View and Autoscale sections of the rc file determine how a model is placed when it is loaded into the application. If auto-scaling is enabled, the application will fit models into an area defined by the "autoscale plane", which typically matches the front screen of a VR system. To define that plane, specify an autoscale center (XYZ) and size (XY). The units in the rc file are feet despite the fact that the VR Juggler config file uses meters.

Text Drawing Settings
Text in LS-PrePost-VR is 3-dimensional and therefore can be scaled. The defaults in the rc file are good for CAVE and PowerWall setups, but the parameters may need to be adjusted for smaller screens.

Wand Behavior & Pointer Settings
This section is important because it directly relates to the hardware used to control the application. The main modes of operation are a 6-button, 2-analog mode and a 3-button, 2-analog mode. The wand pointer is a 3-D pointer that should match the location and orientation of the wand, and it has many settings related to how it is drawn.

Triad Settings
The triad is the small XYZ axis displayed on the screen. It can be positioned (units are feet) and scaled to anywhere in the scene.

2-D Plane Settings
The graphics which frame the LS-PrePost desktop OpenGL display are drawn in 3-D in LS-PrePost-VR tied to a plane that the user can specify. There is an option to match the autoscale plane, which is the easiest setting to enable, or a separate plane can be defined for these elements. The plane can operate in "HUD mode", which is good for head-mounted displays, or its contents can be disabled entirely if desired for a more immersive view.

App Behavior Settings
These settings control the interpolation of rotation, translation, and zoom commands, and there is also an option to disable the VR system's response to those commands that originate from a desktop system.

System Config Settings
IMPORTANT. These settings control communication with the SinterPoint server, which is how LS-PrePost-VR can receive and process commands. The "sysconfig_server" parameter tells the VR application which machine to try to connect to on startup. The "sysconfig_master" controls which node of a cluster attempts to make the connection to the server, and that setting MUST be correct even if running on a single machine.

File System Settings
In the .lsprepost_vrrc file, there are settings for translating file paths from Windows to Linux. This feature is in there to facilitate Windows PC communication with the Unix-based VR application. It can also be used for processing Windows-created command files, and it can work between differing Unix file systems or mount points. The "filesys_local_mountpoint" parameter must point to a valid directory path on the VR machines. This is what the Windows filenames will be translated to. The default setting is "/vr". The "filesys_win_name" is the path to the same directory on the remote (e.g. Windows) system. If the "/vr" directory on the VR system is mounted on Windows via Samba, this path might look something like "\\INSPIRON\vr" Alternatively, if the Windows PC has the same mirrored locally, this path might be something like "C:\models".

LS-PrePost-Remote
LS-PrePost-Remote is a special version of LS-PrePost designed to drive the VR version of the software. The LS-PrePost-Remote executables are found in $VR_BASE_DIR/apps/lsprepost2, and they can be copied outside of that directory for use on other machines. A Windows version of LS-PrePost-Remote is provided separately. To configure LS-PrePost-Remote, two things need to happen:

1. Plot files must be shared or mirrored from the VR system, and the "File System Settings" in .lsprepost_vrrc must be edited if the mount point on the remote system differs from the VR system(s)
2. The Remote executable must be called with the "s=servername" argument, where "servername" is the name of the machine on which the SinterPoint server will run (usually the master node of a cluster).

Testing the Configuration
The SinterPoint server must be started before any other component. If you are using the provided scripts, the SinterPoint server will be started when LS-PrePost-VR is run. So, start LS-PrePost-VR first and then start LS-PrePost-Remote. Both instances of the software should indicate a successful connection to the server. In LS-PrePost-Remote, open a d3plot file, and it should appear on both the VR and remote screens. If the VR console prints messages indicating it has loaded a file, but you cannot see it, check yout .lsprepost_vrrc scale settings and restart until files appear centered on the VR display when loaded.

USER GUIDE

1. Starting Up
ALWAYS start SinterPoint before starting LS-PrePost-VR or LS-PrePost-Remote, or start LS-PrePost-VR first using the provided script file(s).

Note: Do not use command-line arguments, such as plot files to load, when starting the VR version if you intend to connect with a remote version for input because the  applications will not sync.


2. VR Wand Controls

The wand controls are designed for the IS-900 wand from InterSense (6 buttons and 2 analogs).  The application can also operate in a 3-button mode (not yet documented).

Read further for a description of the IS-900 button behaviors.


Button 0: Rotation
Holding down this button and rotating the wand causes the model to rotate the same amount as the wand.

Button 1: Translation
Holding down this button and translating the wand controls translation of the model being viewed.  An acceleration factor set in the .lsprepost_vrrc file is applied to translation.

Button 2: Scale
Holding down this button and raising or lowering the wand causes the model to be scaled up or down respectively.

Button 3: Mode
This button cycles through the "Action" modes supported in the application and accessed through Button 4.  The modes are indicated with an icon at the wand tip, and they are:

• Clip Mode ( wireframe rectangle )
• Select Mode ( "laser" pointer )
• Safe Mode ( no icon )
  

Button 4 (trigger): Action
Button 4's behavior depends on the Mode selected by button 3 and indicated by the associated icon.  The behaviors in each of the modes are described below.

• Clip Mode
• Holding down the button will attach a clipping plane to the wand tip.
• Releasing the button leaves a clip plane in place.
• If a clip plane is active, a short click of the button removes the plane.
• Select Mode
• The button is only active if a remote computer running LS-PREPOST REMOTE is connected.
• One click of the button performs the same select action as a mouse click on the graphics screen of non-VR LS-PREPOST.  The behavior depends on the selection mode that LS-PREPOST REMOTE is in.
• Safe Mode
• No action happens with this command, so it is safe to use for pointing out objects to colleagues in VR.

Hat: Animation
The wand controls animation playback, or command file playback if a command file is loaded directly into the VR application.  Hat behavior is described below.

• Animation State +1: rock the hat once to the right. This motion will instead increment the command file by one command is such a file is loaded.
  
• Animate Forward: hold the hat to the right until playback begins.
• Animation State -1: rock the hat once to the left.
• Animate Backward: hold the hat to the left until playback begins.
• Animate Faster: rock the hat forward once to increment speed.
• Animate Slower: rock the hat backward once to decrement speed.
• Stop Animation: push down on the hat to stop.  This action also sends a state command to all connected clients so that they sync to the animation frame at which the VR user presses "stop."
  

Button 0 & Button 1 together: Reset Transformation
Pressing these buttons at the same time causes the rotate, translate, and scale transformations caused by the wand to be reset to their defaults.  This combo will not undo transformations from a command file.  There is a setting in the .lsprepost_vrrc file to disable command file-driven transforms if that is desired.

Button 2 & Button 3 together: Enable/Disable Pointer
Pressing these buttons together toggles display of the pointer.
 
3. Application Behavior
The Remote application is not frame-locked to the VR application.  The applications are instead synchronized because they process the same commands, but they do so at their own pace.  Because of this, events may happen sooner or later on the remote computer than in VR.  The non-synchronization is important because it means that a slow Remote PC will not slow down the VR frame rate.

Certain elements of the LS-PrePost display may not appear in VR at all.  These display elements are usually associated with a widget on the desktop application, and they go away when the widget is closed (e.g. "Done" is clicked on the right-hand panel).

4. Disconnect & Reconnect
As long as the SinterPoint server is running with at least one client (Remote or VR) connected, a session remains active and can be connected to and disconnected from. Clients will catch up to the session state by playing back the command history of the session.

---

RELEASE NOTES / KNOWN ISSUES

1. Animation playback from command file in VR plays continuously until stopped, rather than advancing one frame as in non-VR LS-PrePost.
2. Annotations are not written to command file and therefore are not shown in VR.
3. Selection sphere is not drawn in VR.
4. "Splitw" is disabled in remote because it is not clear which window should control VR.
   
5. Measurement line and distance values not drawn in VR or in command file processing for non-VR.
6. Cfiles need to be hand-edited to use windows pathnames if loaded into windows.
7. "zoom" distorts geometry with nonuniform scale, which makes geometry appear squashed in VR.
8. Palette colors do not work properly, and they do not work at all in Windows.
   
9. "Area" and "Polygon" selection are disabled in remote because they rely on window dimensions to work properly.
10. Cutting plane animation disabled in remote because it does not use command interface.
11. "Pcen" is disabled because it relies on window dimensions to work properly.
12. Windows remote version will sometimes crash on program exit.
13. Windows reconnect to server does not handle splane commands properly.