vrNav2 is an easy-to-use 3D scene navigation program for viewing 3D models in a virtual reality environment. It runs under Linux, Windows, and Max OS X. When run under Linux, vrNav2 supports multiple tiles in a tiled display. Additionally, Collaborative VR allows two communicating vrNav2 instances, both running on the same model, to communicate and work together.
vrNav2 is build on top of OpenSceneGraph (OSG) and vrJuggler. It allows you to load models in any of the data formats that OSG supports. The properties of the models and the navigation are configurable via a model config file and arguments to the program. Spherical (multiple viewing frustum), spherical stereo, flat plane (single viewing frustum), flat plane stereo and any size tiled display are configurable via base and display config files. A set of these config files come with vrNav2 and you can easily modify the ones you need for your particular setup. The scripts that come with vrNav2 and which start it up, automatically select the appropriate config files according to the way the system is set up.
vrNav2 has been configured to work with both architectural models and models created as part of scientific visualizations. It supports multiple time steps for the scientific models and multiple switches and date switches for the architectural models.
The mouse and keyboard are used for navigation and control. In addition, a remote GUI, written in Java, can be run on any machine, the one running vrNav2 or another machine. This GUI can connect to a running vrNav2 in order to control it. The vrNav2 GUI provides many of the same control features as the keyboard does. It also provides controls not available via the keyboard.
vrNav2 allows you to make movies on the fly by saving a numerical sequence of images that you can later paste up into a movie. It can save left and right eye image sequences when run in stereo mode. These images can later be pasted up into either a red/blue stereo movie or into an active stereo movie.
As you navigate around the virtual world vrNav2 can save segment(s) of your flight path or key frames along your flight path. Subsequently it can navigate through the virtual world on either the path you saved or a path it creates via spline interpolation of the key frames. Pre-defined flight paths are often created and then flown in conjunction with saving the frames for movie creation.
The following devices are supported by vrNav2:
It is free. Download it from http://www.openscenegraph.org.
It is free. Download it from http://www.vrjuggler.org.
vrNav2 can read any file format that OpenSceneGraph can read. OpenSceneGraph supports the following 3D formats for 3D models:
- .3dc
- 3DC point cloud
- .ac
- AC3D format
- .dw
- Artifice, Inc. Design Workshop format
- .flt
- MultiGen OpenFlight format
- .geo and .gem
- Carbon Graphics format
- .iv and .wrl
- SGI OpenInventor and VRML 1.0 formats
- .ive
- OSG binary file
- .3ds
- Autodesk 3DStudio binary format. lib3ds, a free alternative to Autodesk's 3DS File Toolkit for handling 3DS files, is used to read these files.
- .logo
- Logo 3D format
- .lwo and .lw
- LightWave Object file
- .lws
- LightWave Scene file
- .md2
- Quake 2 model
- .obj
- Wavefront Technologies format
- .osg
- OSG ASCII format
- .pfb
- OpenGL Performer binary format
The most commonly used model file formats at UCLA are .ive and .flt. Most architectural models at UCLA are created in Multigen Creator in .flt format. These are converted to .ive so they can be loaded rapidly by OSG. vrNav2 includes the fltToIve GUI which allows .flt files to easily be converted to .ive files. It sets up and runs the OSG program osgconv for you and, at the same time, generates all required supporting files for vrNav2.
Some scientific visualization programs can write VRML 97/VRML 2 .wrl files. VRML 2 is a good way to get scientific data into vrNav2. osgconv can convert many VRML 97/VRML 2 files to .ive allowing them to be flown with vrNav2.
On Linux systems and from the Mac OS X terminal window you run vrNav2 by entering the command:
vrNav2 [ device] [vrNav2-script-options and vrNavApp-options ] model_config_file [JumpPoints_config_file]
The vrNav2 command is actually a script which calls the vrNavApp executable:
On Windows systems there is no vrNav2 script. You run vrNav2 by running a three line .bat file. The last line of which is a command which is the Windows equivalent of the one which runs the vrNavApp executable. There are no abreviations on that line. You must specify everything yourself as follows:
path-to-the-exe\vrNavApp.exe [vrNavApp-options] -configfiles list-of-config-files
Follow these guidelines:
full-path-to-base-config full-path-to-display-config model_config_file [JumpPoints_config_file]
A set of config files was distributed with vrNav2. Normally you would supply base.1pipe.jconf, display.windows.jconf and the model_config_file for your particular model (not supplied). A file saved via the vrNav2 GUI that supplies a set of named Jump Points can optionaly be included. See the discussion of Jump Points.
While you can also run vrNavApp directly on Linux, it is not as convenient as using the script and you MUST be in the c shell and source the file ENVIRONS.linux.csh first.
source path-to-environs/ENVIRONS.linux.csh
path-to-vrNavApp/vrNavApp [vrNavApp-options] -configfiles list-of-config-files
For all ways of running vrNav2, replace model_config_file with the name of your model config file. If your file name includes a blank or blanks, enclose it it quotes. For the vrNav2 script, config file names must end with one of these extensions: .config, .xml or .jconf or .jconf7.
IN THE REST OF THIS DOCUMENT, vrNavApp OPTIONS APPEAR IN DARK GREEN. THEY CAN BE USED IN WINDOWS, LINUX, AND ON THE MAC. vrNav2 SCRIPT OPTIONS APPEAR IN PURPLE. THEY CAN BE USED IN LINUX AND ON THE MAC BUT NOT IN WINDOWS.
A model config file is a text file written in xml format. Model config files contain xml elements of model-specific information that:
You must provide exactly one model config file each time you run vrNav2. The model config file contains the name(s) of the .ive, .flt or other model files you want to navigate.
The format and contents of the model config file are explained in the document Creating a Model config file for vrNav2 [ModelConfig-Howto.html].
vrNav2 has two types of navigators: PrimaryNavigators which are used to fly or drive through a model, and PlaybackNavigators which are used to fly along a pre-recorded path. You can use a PlaybackNavigator for canned demos, for museum exhibits, and for saving a series of images for paste up into a movie. When you use a PrimaryNavigator to fly through a model, you can have that Navigator save either your entire path or a series of keyframes or both for later playback.
vrNav2 includes the following PlaybackNavigators:
On startup, each of the keyframe players reads in the keyframes and turns them into a complete path, which it then flys exactly. That path is also saved and you can use that path subsequently with either the PathPlayer or the PathNavigator to save the overhead of converting the keyframes into a path again each time you run.
The PathNavigator requires a path in which the path locations are evenly spaced at small increments. This allows the user to control the speed of the playback and to navigate slowly, if desired. The PathNavigator, on startup, reads in a path and creates the evened-out path from it. It saves the evened-out path and if you use that saved evened-out path on subsequent runs of the PathNavigator you save the overhead of creating it again. Additionally, you can request the PathNavigator to save an evened-out path that can be used to make a movie that will last a specific number of seconds.
You must have at least one Navigator to run vrNav2. You cannot have more than one PrimaryNavigator. You may have one or more PlaybackNavigators.
There are several ways to request a PrimaryNavigator:
When you supply one of these options to save a path or keyframe, you will be given the Mouse Navigator even if you have requested one of the PlaybackNavigators.
To request a PlaybackNavigator enter one of the following options:
When using the PathNavigator only, you can add the following options to have vrNav2 save the path actually flown by the user, including the heading and pitch and speed.
path-to-the-executable\vrNavApp.exe [vrNavApp-options] -configfiles list-of-config-files
The vrNav2 script on Linux includes the following convenience options for use when recording a path or keyframes to a file and then playing them back from that same file during a single run of vrNav2:
Is the same as specifying:
-PF pathfile -P pathfile
Is the same as specifying:
-KF keyframefile -K keyframefile
Is the same as specifying:
-KF2 keyframe2file -K2 keyframe2file
Is the same as specifying:
-PF pathfile -PN pathfile
When you run vrNav2, you can cycle through the navigators in the order they were specified by pressing the letter k key or by interacting with the vrNav GUI. The MouseNavigator is ALWAYS the first one.
There are two navigation modes for the PrimaryNavigators: fly mode and drive mode. Fly mode lets you fly through the model and move to any position you desire. In drive mode, you can only move on the ground.
When you first switch into drive mode, gravity will pull you down so that the navigator's feet are touching the ground. The navigator's height is spceified with the DriveHeight element in the xml model configuration file. The default navigator height is 1.7 meters. If you happen to be flying below DriveHeight at the time you switch to drive mode, the navigator will be raised up to DriveHeight above the ground.
You can cycle the navigation mode by pressing the letter o key or by interacting with the vrNav GUI.
Navigation is controlled by the mouse. You can control the forward or backward speed by pressing the mouse buttons. Once you set a speed, you will continue to move forward or backward at that speed until you either change speed or press a button or key to stop altogether.
On startup, there is no motion and the cursor is a white plus sign. Press the left mouse button to move forward or the right mouse button to move backwards. Forward/backward motion can be accompanied by turning. Move the cursor in the direction that you want to turn. Press the middle mouse button or stop keyboard key to stop forward/backward motion. The cursor will change to a diamond. Forward/backward motion will cease but turning will still occurr. To stop all motion, press the "Stop all Motion" key instead. The cursor will change to a filled-in square. To adjust your position left or right or up or down, press one of the step keys.
The following keyboard keys that effect navigation are available with all Navigators:
a Stop all motion -- no motion at all will occur after you press this key until take some action to start motion again. s Stop. For PrimaryNavigators, forward/backward motion will stop. Turning will still occurr. (This is the same as pressing the middle mouse button with the MouseNavigator.) For PlaybackNavigators, this is identical to pressing the Stop all Motion key. r Reset the Navigator (viewer) to the initial position, or rewind if using a PlaybackNavigator. c Toggle collision detection on and off. k cycle Navigators x When saving images to be used in assembling a movie, toggles image saving on/off.
The following additional keyboard keys are available with the PrimaryNavigators:
Up Arrow Move up Down Arrow Move down Left Arrow Move left Right Arrow Move right o Cycle Navigator mode between fly and drive modes. 1 When recording a path file, starts the saving of path locations. 2 When recording a path file, stops the saving of path locations. 4 When recording keyframes, adds a keyframe. 5 When recording keyframes, deletes the last keyframe added.
The following additional keyboard keys work with the PlaybackNavigators:
1 Starts playback.
With the MouseNavigator, the mouse is used as follows:
Left Button Accelerate Right Button Decelerate Middle Button Stop. This stops forward and backward motion. Turning will still occurr. Pressing the Middle Button is equivalent to pressing the s key. To stop all motion press the a key.
Move the mouse left or right, up or down in the scene to turn.
Navigation speed is controlled by the following model config file elements: MinimumSpeed, MaximumSpeed, and AccelerateFactor. When starting from stopped, each time you press the left mouse button, your speed will be increased by MinimumSpeed. This will happen 1/AccelerateFactor times. After that, your speed will be increased by AccelerateFactor * current velocity until you have obtained a speed of MaximumSpeed, after which you cannot increase your velocity further. That is, your velocity curve will be linear until a velocity of AccelerateFactor * MinimumSpeed is obtained. Then it will be exponential. This allows for the navigation of very large models which have very fine detail of interest in places. You can speed through the large places but navigate in close to the large detail. Likewise, deceleration from a large velocity, will be exponential but from a small one will be linear. Holding down the mouse button is equivalent to repetedly pressing it.
Currently the DeviceNavigator is NOT AVAILABLE with vrNav2osg.
The following keyboard keys can be used to control vrNav. Better control is available via the vrNav GUI. This is because only actions requiring a single keypress are implemented via the keyboard. For example, a scene may have multiple models. Each modle may have multiple switches. Only the first switch on the first model can be switched via the keyboard. The GUI is required to switch any of the other switches. The keyboard can be used with all Navigators.
0 Zooms in on the Map. Works only with TopView maps. See the explanation in the section on Maps. 1 When recording a path file using one of the PrimaryNavigators, starts the saving of path locations. 1 When playing back using either the one of the PlaybackNavigators, starts playback. See explanation in the section on movies. 2 When recording a path file using one of the PrimaryNavigators, stops the saving of path locations. 4 When saving keyframes from one of the PrimaryNavigators, adds a keyframe to the keyframe file. See the explanation in the section on movies. 5 When saving keyframes from one of the PrimaryNavigators, deletes the last keyframe saved in the keyframe file. See the explanation in the section on movies. 9 Zooms out on the Map. Works only with TopView maps. See the explanation in the section on Maps. a Stops all motion -- with a PrimaryNavigator, this key stops all motion. No motion will occurr after you press this key until you take some action to start moving again. With a PlaybackNavigator, this key stops playback. b Toggles bird's eye view. c Toggles collision detection on and off. d Goes down to the previous timestep in a multi-timestep scientific model. e In master/slave mode (collaborative VR), this key, when pressed by the person running the slave, causes the slave vrNav to become the master and the master vrNav to become the slave. f Toggles wireframe mode. When wireframe is on, the model is shown in wireframe (no textures or colored surfaces). h In a model with switches, this key selects to the next switch, in round robin fashion. The n and p keys which select the next switch mask always operate on the selected switch. i In a model with date switches, this key switches to the next year that has a switch. j In a model with date switches, this key switches to the previous year that has a switch. k Cycles the Navigators. If more than one Navigator was requested on vrNav2 startup, this key changes the Navigator to the next navigator in the list. If you are currently on the last Navigator, the first Navigator will be used. l Toggles lights. This key changes the graphic state for lighting, as if you had specified the -light option on startup. See explanation in the section on the graphics state options. m Toggles the map on/off. n Next switch. This key switches the selected switch in the first Model to the next switch mask. Use the h key to select a particular switch before using this key to switch it. If there is more than one Model in the model, use the GUI to switch any switch of any Model. o For PrimaryNavigators, this key cycles the navigation mode between fly and drive modes. p Previous switch. This key switches the selected switch in the first Model to the previous switch mask. Use the h key to sepect a particular switch before using this key to switch it. If there is more than one Model in the model, use the GUI to switch any switch or any Model. q Quits vrNav2. r For PrimaryNavigators resets the Navigator (viewer) to the initial position. For PlaybackNavigators rewinds to the beginning. s Stop. For PrimaryNavigators forward/backward motion will stop, turning will still occurr. (This is the same as pressing the middle mouse button.) For PlaybackNavigators, s and a have the same effect. Both stop playback. t Toggles the Text Logo on and off. u Goes up to the next timestep in a multi-timestep scientific model. w Save image. Takes a snapshot of the screen and saves it in an image file. x Toggles continuous image saving on/off. When image saving is on, either a (mono) image or a pair of stereo images will be saved each frame. See the explananation in the section on movies. z Toggles transparency on/off. Up Arrow For PrimaryNavigatiors, moves up Down Arrow For PrimaryNavigators, moves down Left Arrow For PrimaryNavigators, moves left Right Arrow For PrimaryNavigators, moves right Page Up When used with a TopView map, raises the cutting plane. Page Up When used with a TopView map, lowers the cutting plane. This allows you to use a model that has a top such as a roof or sky dome as a map by cutting the top off at an appropriate height.
The vrNav GUI can control all aspects of vrNav2 except for model navigation. To use the GUI, add the -gui keyword when you start up vrNav2:
-gui port
Replace port with the port you will use to communicate between vrNav2 and the GUI, e.g., 9900.
You can start up the GUI on the same or on a different machine as vrNav2. The vrNav GUI is written in Java and can be run on any system that has a Java run-time environment installed.
After vrNav2 has started, you can connect from the GUI to vrNav2 by specifying the address of the machine on which vrNav is running and the same port you supplied with the -gui option.
The vrNav2 script has an option that starts the vrNav GUI at the same time as it starts vrNavApp. You can specify it as follows:
vrNav2 ... -withLocalGui -gui port ... model.jconf7
You can connect with the GUI to a running vrNav2 at any time and disconnect and reconnect at will from the same or different system. Only one vrNav GUI can be connected to a single running vrNav2 at any given time.
The GUI has the following tabs:
- Toggle the following on and off:
- collision detection
- wireframe
- light
- transparnency
- map
- birdview
- Change the map height and the birdview height and angle
- Save a snap shot of the image currently displayed
- Control all switches and date switches in the model
- Change time steps
In addition, the Model tab continuously displays the XYZ viewer
position in the virtual world. If the UTM chunk is included in the
model config file, the UTM coordinates of the viewer's location
will also be displayed.
- Allow you to change Navigators, to any of the Navigators you specified on vrNav2 startup
- Stop forward/backward motion
- Stop all motion
- Reset/rewind
- Toggle the continuous saving of images
- For PlaybackNavigators, start playback
- For PrimaryNavigators, allow you to switch between fly and drive modes
- For PrimaryNavigators, allow you to save keyframes and record a path
While, you can save a sequence of images, one for each frame of a movie, with any Navigator, you have the most control if you perfect the path and save the images when using a PlaybackNavigator.
The recommended steps for making a movie are:
Navigate through a model with a PrimaryNavigator and save either a path file or a keyframe file. See the section on Navigators for the vrNav2 startup options that are used to specify that these files be saved.
If you requested that the path file be saved, you can either use keyboard keys or the controls in the vrNav GUI to save the path. You can save multiple path segments. If you are controlling vrNav from the keyboard, press the 1 key to start saving the path and the 2 key to stop saving the path.
If you requested that the keyframe file, the keyframe2 file or both be saved press the 4 key to save a keyframe and the 5 key to delete the last keyframe that was saved, if you made a mistake. Alternatively you can use the GUI for this function. You must save at least 4 keyframes.
If you requested that both keyframe file and the keyframe2 file be saved, the same keyframe will be written to both files. You can write to a path file and to the keyframe files during the same run of vrNav2.
You can record a path, then playback and evaluate the path, then re-record, etc. during a single vrNav2 session by specifying, for example, the same filename with both the -pathfile and the -pathplayer vrNavApp options. The following vrNav2 script options for Linux are shortcuts for doing this:
-PFP filenameand
-PPF filenameThese shortcuts both combine the -pathfile and -pathplayer options. Additional shortcuts are: KFK and KKF for specifying the keyframe file to both save with a PrimaryNavigator and playback with the KeyframePlayer; K2FK2, K2K2F, K2KF2, and KF2K2 for specifying the keyframe2 file to both save with a PrimaryNavigator and playback with the KeyframePlayer2; and PFPN and PNPF for specifying the path file to both save with a PrimaryNavigator and playback with the PathNavigator.
When vrNav starts up, it will start up in the PrimaryNavigator (mouse). You can fly around and save a path and/or keyframes. Then press the k key. This will cycle Navigators and the first PlaybackNavigator you requested will be in control. You can now playback the path you created. If you want to try creating the path again, press the k key again to cycle back to the PrimaryNavigator. Paths and sets of keyframes created this way are separated by a separator in the file and you can later edit the file and delete those that you don't want to keep.
You can easily edit one of the keyframe files, especially if it does not have too many keyframes in it. The path file is harder to edit because of the large number of records it contains. If you have started and stopped recording the path more than once (with keyboard keys 1 and 2) or switched back and fourth between a Primary and PlaybackNavigator, the Path and/or KeyFrame files will be in segments with an identifiable comment line in between the segments that you can use to help find your place.
The first line of each file is a header line that looks like:
nn ft vrNav2
where nn is the number of segments in the file and ft is the file type: PF for pathfile, KF for keyframe file, and K2 for keyframe2 file.
The format of the lines in the Path file is:
X Y Z Heading Pitch Roll TimeStep
The format of the lines in the Keyframe file is:
time_stamp X Y Z Heading Pitch Roll TimeStep
The format of the line in the Keyframe2 file is:
X Y Z Heading Pitch Roll Density TimeStep
where:
P1: -14.23 23.17 120.03 0.0 0.0 0.0 89 -1
P2: -18.24 28.18 100.01 0.0 0.0 0.0 100 -1
P3: -28.24 18.18 102.01 0.0 0.0 0.0 120 -1
increasing the density from 100 on the P2 line will increase the time it takes to go from partway between P1 and P2 to part way between P2 and P3.
If the playback is already on time step 40, then the PlaybackNavigator will advance to the position given in the first line and then display the models for time steps 39, 38, ... 12 before moving to the position specified in the second line. It will stay on time step 12 for the third line and display the models for time steps 13, 14, ... 25 before advancing to the position specified on the forth line.6.724 -14.23 23.17 120.03 0.0 0.0 0.0 -1 7.824 -18.53 22.66 140.11 0.0 0.0 0.0 12 9.755 -24.25 20.80 155.17 0.0 0.0 0.0 -1 9.999 -54.58 14.13 172.23 0.0 0.0 0.0 25
To save the images for a move, instruct vrNav2 to playback on the saved path and save the image produced for each frame. When vrNav2 plays back in mono, it saves one image for each frame. When it plays back while in active stereo, it saves a left eye and right eye image for each frame. This enables you to paste up a stereo movie.
Examples vrNav2 script command lines used to record a movie:
vrNav2 -P mypathfile -I myimagedir -screensize 720 480 model_config_fileor:
vrNav2 -K mykeyfile -I myimagedir -screensize 720 480 model_config_fileor:
vrNav2 -K2 mykey2file -I myimagedir -screensize 720 480 model_config_file
Example vrNavApp command lines used to record a movie in Windows:
path-to-the-exe\vrNavApp.exe -pathplayer mypathfile -imagedir myimagedir -imagetype tiff -configfiles list-of-config-filesor:
path-to-the-exe\vrNavApp.exe -keyframeplayer mykeyfile -imagedir myimagedir -imagetype jpg -configfiles list-of-config-filesor:
path-to-the-exe\vrNavApp.exe -keyframeplayer2 mykey2file -imagedir myimagedir -configfiles list-of-config-files
In Windows you are responsible for making a display config file of the correct size for your movie and including it in the list of config files. You can copy display.windows.jconf, the distributed display config file for Windows and modify it.
If you are using the keyboard to control vrNav2, press the x key to start saving images. You MUST press this key initially before any images can be saved. Then press the 1 key to start playback.
All the keyboard keys (except those for used exclusively by the PrimaryNavigators) are available and you can use them at any time to take actions such as changing the switches. You can also affect the model during playback from the vrNav GUI.By default images are written out in Netpbm's .ppm format. This format is lossless and can easily be converted to any other format that you like. You can optionally select to write out images in tif or jpg formats by coding the -imagetype keyword on the command line when you start vrNav.
Stereo movie frames can be assembled into either red/blue stereo movies or into active stereo movies. For red/blue stereo movies, you have to preprocess the images. We include the Linux script make_red_blue_stereo in this package. This script can preprocess a sequence of left and right eye images into red/blue stereo images. It requires the Netpbm package, available at http://netpbm.sourceforge.net. (This package comes with Redhat Linux and Fedora.)
To assemble the images into movies you can use:
We recommend graphicConverter a shareware program from http://www.lemkesoft.de/en/index.htm to make Quicktime movies. graphicConverter comes pre-installed on many Macintosh computers.
Use ImageMagick to make an mpeg movie. The mpeg2vidcodec is required. This can be gotten from http://www.imagemagick.org/www/formats.html. Go down to mpeg and click on the codec. This will take you to ftp://ftp.mpeg.org/pub/mpeg/mssg/ where you can download it.
Then use the command:
to assemble the sequence of ppm images into the mpeg movie.convert *.ppm output_file_name.mpeg
Alternatively, you can download mjpegtools from http://sourceforge.net/projects/mjpeg/ to assemble mpeg movies or libquicktime from http://sourceforge.net/projects/libquicktime/ for quicktime movies. The latter is an API and does not include a main program. A main program by Ken Berland named make_quicktime_movie can be downloaded from http://hero.com/public/.
Sometimes it's desirable to save high resolution images. These are images which have more pixels than the display screen. There are two reasons to save these very large images: a) to create posters b) for publication.
When vrNav2 saves an image, it always does so by capturing the image that you see on the screen. vrNav2 cannot generate a image that is larger than the screen. However, vrNav2 can save individual high resolution images for you. If you set up vrNav2 appropriately, you can fly through the model until you see an image that you want to save. At that spot, press the A key to stop all motion and then the W key to snap the image. vrNav will then redisplay the image in pieces for you and save each partial image in memory. It will composit all the partial images together for you into a single high resolution image and save that image on disk. To save a high resolution image:
Start up vrNav2 by entering the command:
vrNav2 -screensize height width -imagesizefactor n ... model_config_fileFind a number that evenly divides the final image size in pixels, both height and width. For example, if your final image is to be 6000 by 4000 pixels, you could use 5. Replace n by 5 and height by 1200 and width by 800. When you press the W key to snap the image, vrNav2 will generate a 5 by 5 matrix of image segments and composite them together into the high resolution image you want.
On Windows -screensize is NOT available. You must make the display.jconf file for vrNav2 to use yourself. However, DO NOT MAKE IT BY MODIFYING AN EXISTING display.jconf FILE BY HAND. There are two sets of numbers in the display.jconf file that MUST BE EXACTLY RIGHT for the image to work. These are the image width and height (easy) and the image projection corners on the screen (difficult). A Perl script comes with the Windows distribution of vrNav2. It is in the utils directlry and is named make_display_jconf. You can run make_display_jconf to generate a display.jconf config file for any sized window. To run it, you must have perl installed on your Windows machine first. If you do not already have perl, you can get a copy of it from http://strawberryperl.com.
In the examples directory of the Windows distribution of vrNav2 you will find make_display_jconf.bat.
Modify the .bat file you use to start up vrNav2 by changing the command in it that starts vrNav2 to look like the following:
path-to-the-exec\vrNavApp.exe -mouse -imagesizefactor n ... configfiles ..\config\base.1pipe.jconf ..\config\display-widthxheight.jconf model_config_file
The vrNav2 script and vrNavApp options are listed here grouped by functionality. vrNavApp options can be used on Linux and Windows. vrNav2 script options cannot be used on Windows.
-help Show help message and quit. -h Show help message and quit.
These options specify the release or version of the vrNavApp application program to use:
new Use the new release of vrNav2. old Use old release of vrNav2. -version release_number Use release number release_number. -V release_number Use release number release_number.
Unless one of these are specified, the production release of vrNavApp will be used.
These vrNav2 script options specify the device that will be used to navigate:
m
mousemouse
If a PlaybackNavigator is not requested (via the -K, -K2, or -P option) and you have not requested a navigation device, you will be given the mouse navigation device. If you have requested a PrimaryNavigator (via the -KF, K2F, or PF option) and you have not requested a navigation device, you will be given the mouse navigation device.
If you are using vrNavApp directly and want a PrimaryNavigator, you MUST specify one of these options
- -mouse
- Requests the MouseNavigator.
- -light
- vrNav2 is to supply lighting. This -light option does not pertain to the standard global ambient light that vrNav2 adds to the scene. Instead, it enables the lighting in the graphics state. When lighting is disabled, the default, hardware lighting will not be used to illuminate the geometry. This disabling of the OpenGL lighting is the default because the architectural modelers normally provide texture maps which include pre-rendered illumination. If lighting is enabled in vrNav2, the lighting effects are inferior to the lighting effects created and supplied as part of the texture maps for the model.
However, for scientific models, or other models without texture maps or for which lighting models have not been specifically created, unless the -light option is requested, the colors will appear flat and the surfaces will not show the solid, rounded appearance that they would show under the infulence of illumination.
You must include the -light option if you are going to work with spot lights in the model via the vrNav GUI.
- -transparency
- Model contains transparency. For scientific models, a color is normally associated with each vertex of the geometry. Colors are of the form R,G,B,alpha, where alpha specifies the amount of transparency. However with vrNav2, by default transparency will not be turned on and colors in a model that include alpha values of less than 1.0, which indicate transparency, will appear opaque unless this option is supplied. Code the -transparency option if your model includes transparent surfaces.
To use stereo, you must run vrNav2 on a machine that is active stereo capable. The selection of display config files determines whether or not stereo is used. The following option sets the stereo separation in that config file for you on the fly when you use the vrNav2 script. If you are not using the vrNav2 script, you must supply the config file yourself. (There is a perl script in the utils directory named make_display_jconf. You can run that script to generate a display.jconf config file for any sized window. In the Windows distribution of vrNav2, in the examples directory you will find make_display_jconf.bat. Modify that file for the screen size you want and run it to generate the display.jconf file. You must have perl installed on your Windows machine first. If you do not already have perl, you can get a copy of it from http://strawberryperl.com.)
- -screensize width height
-M width height- Specifies the width and height of the graphics window that will be opened by vrNav2. Normally, vrNav2 opens a window which fills the screen. Specify this option when you want to open a window which is smaller than full screen. When saving images for a movie, the images will be of this size. The -screensize option DOES NOT EXIST for Windows. If you are using Windows you must provide a display config file which specifies the screen size you desire.
- -screenaspect width_height_ratio
- Overrides the default graphics viewing frustum aspect ratio. The viewing frustum is the camera whose picture is displayed in the graphics window. Code -screenaspect only when you also code the -screensize option. The default viewing frustum aspect ratio is the same as the display aspect ratio. For example, if your -screesize is 640 by 480, then the aspect ratio of your display is 1.333 (4:3). By default, the aspect ratio of your viewing frustum will also be 1.333. If you would like to distort the image by forcing a different aspect ratio on the viewing frustum, use this option.
- -stereo value
- Specifies the interocular distance between the left and right eyes for stereo display. The default is 0.06 (6 cm). Specify a value that works well with the model you are using. If you are using vrNavApp directly (Windows), you must provide an appropriate display config file for stereo yourself.
The following options tell your PrimaryNavigator to save a path and/or keyframes. You may specify more than one of these options simultaneously. Path and keyframe files are automatically saved when you quit vrNav2 and when you cycle to another Navigator (either by pressing the letter k key or use the controlls provided but the vrNav GUI). If you cycle to another Navigator and then cycle back to the PrimaryNavigator and save additional keyframes or path frames, a separator will be placed in the file to separate the new set of frames from the original set.
- -keyframefile keyfilename
-KF keyfilename- Specifies the name of the keyframe file to save. Press the 4 key or use the appropriate vrNav2 GUI button to save a keyframe to this file. You must save at least 4 keyframes in a keyframe file in order to play it back.
- -keyframe2file keyfilename
-KF2 keyfilename
-K2F keyfilename
- Specifies the name of the keyframe2 file to save. Press the 4 key or use the appropriate vrNav2 GUI button to save a keyframe to this file. You must save at least 4 keyframes in a keyframe file in order to play it back.
- -pathfile pathfilename
-PF pathfilename- Specifies the name of the path file to save. Press the 1 key on the keyboard or use the appropriate vrNav2 GUI button to start saving the path after you: first start up vrNav; cycle the Navigators from some other Navigator to the PrimaryNavigator; and when you want to start recording the path again after having pressed the 2 key or the vrNav GUI button whose function is to stop recording the path. If you have pressed the 1 record and 2 stop-record keys more than once, the saved path file will contain multiple discontinuous path segments.
Use the following vrNav2 script options to both save to, and playback from the same file.
- -KFK keyfilename
-KKF keyfilename
- Specifies the name of the key frame file to save and use for playback.
- -K2FK2 keyfilename
-K2K2F keyfilename
-K2KF2 keyfilename
-KF2K2 keyfilename
- Specifies the name of the key frame file to save and use for playback.
- -PFP pathfilename
-PPF pathfilename
- Specifies the name of the path file to save and use for playback.
Use the following options to play back from an existing path or keyframe file.
- -keyframeplayer keyfilename
-K keyfilename- Specifies that the model is to be navigated on the path saved in the key frame file.
- -keyframeplayer2 keyfilename
-K2 keyfilename- Specifies that the model is to be navigated on the path saved in the key frame file.
- -pathplayer pathfilename
-P pathfilename- Specifies that the model is to be navigated on the path saved in the path file.
- -pathnavigator pathfilename
-PN pathfilename- Specifies that the model is to be navigated on the path saved in the path file. The user is given mouse control over the playback speed and the heading and pitch of the head (where the Navigator is looking).
- -imagedir path
-I path- Specifies the path in which the image files are to be saved. The path you specify must be an absolute path. By default, the images will be saved in your home directory (Linux) or in C:\temp (Windows).
- -imagetype type
-I path- Specifies the image type for any images saved by vrNav2. Acceptable types are: ppm, tiff, tif, jpg, and jpeg. The defaule is ppm.
- -autoplay
-A- Playback starts immediately each time a PlaybackNavigator is started. If you have not requested a PrimaryNavigator, playback will start immediately, as soon as the model is loaded. If you have multiple Navigators, playback will start each time you press the k key and cycle to one of the PlaybackNavigators.
- -autorecord
-U
- -autorecord implies -autoplay. Playback starts immediately each time a PlaybackNavigator is started. In addition, images will automatically be saved.
- -imagesizefactor factor
- Used to save images larger than the screen. For example, if your screen size is 1280 by 1024 and you want to save an image (via the w key) that is 6000 pixels by 3000 pixels, Either specify:
-screensize 1000 500or run the make_display_jconf utility to make a 1000 by 500 pixel display jconf file, and additionally specify:-imagesizefactor 6Any images you save will be of size 6 * 1000 x 6 * 500 = 6000 x 3000.
The following additional options are for use with the PathNavigator. The PathNavigator reads in a path file and produces a path in which the frames are evenly spaced. It allows the user playing back the path to fly more slowly than when the path was created by inserting a specific number of path locations in between each of the evened out path locations. By default 10 additional path locations are inserted in between each consecutive pair of evened out path locations. You can override this default by coding one of the following options:
- -between number
- Specifies the number of path locations to be inserted between each consecutive pair of evened out frames.
- -gen_frames_at total_seconds framesPerSecond
- Specifies the duration in seconds and the number of frames per second of a movie that you will make from the images saved when you run the PathPlayer on the path created by the PathNavigator. Your movie will run for approximately total_seconds when pasted up at framesPerSecond frames per second.
You must specify the -gui option whenever you want to use vrNav2 with the vrNav GUI. Specify a port number. The vrNav GUI must then connect to vrNav2 at the address on the machine on which vrNav2 is running and the port number specified. At ATS, we always specify a port in the 9000 range. That avoids conflict with other ports that may be in use.
- -gui port
- Replace port with the port to be used for communication with the vrNav2 GUI. This option is ignored if the -tile option is also present.
- -withLocalGui
-G- Starts up the vrNav GUI on the same machine as vrNav2 is running on and puts the port specified on the -gui option into the GUI's connect frame. You must also specify the -gui option. This option is ignored if the -tile option is also present.
You must specify the following option to activate the sound support:
- -sound path address port sound.dyse
-S path address port sound.dyse- Replace path with the path to the directory containing the sound.dyse file.
Replace address with the address of the machine that is running your DySE Builder Sound Server, and port with the port that DySE Builder uses for communication. If you are not certain what these are, ask the person who is running your sound server.
The sound.dyse file is the config file for the sounds. Replace sound.dyse with the name of your dyse config file.
DySE Builder must have already been started on your sound server machine before vrNav2 starts up, as vrNav2 will immediately send messages to it.
- -debugbounds
- When using bounds, vrNav2 communicates to DySE when it is inside of a bounding region set up by the modeler and named in the dyse config file. Any number of bounding regions can be named and they can be nested. When this option is coded for debugging, vrNav2 will print out for you the name of the current bounds. You must use a graphics window that is smaller than your full screen size in order to see the debugging output. See the discussion of the -screensize option.
For additional information on using vrNav2 with DySE, see the documents: How To Make Models with Sound for vrNav2 and How to Use vrNav2 with the Dyse Builder Sound Server
Two vrNav2s, run at different locations but on copies of the same model file and the same model config file, can run collaboratively with at any given instant of time with one acting as master and the other acting as slave. The master can navigate through the model and the slave follows.
-startasmaster slaveaddress agreedonport [UDP or TCP]Starts as a master with full control over navigation. Both collaborating vrNavs must use the same port and the same communication type. Pick UDP or TCP as the communication type.
-startasslave masteraddress agreedonport [UDP or TCP]
Starts as a slave, i.e., initially follows the master with no control over navigation.
See the section on Collaborative VR for additional details.
When vrNav2 is run on a tiled display, one node acts as the control node. That node can additionally act as a rendering tile. All the other nodes act only as rendering tiles.
At ATS, we cross mount a disk from the control node to all of the other tile nodes. If you do not do that, you must have copies of every necessary file on all the nodes. If you control everything from the control node and ssh to the other nodes the way we do, bear in mind that the environment is not the same on the tiles as it is on the control node. YOU MUST CODE AN ABSOLUTE PATH TO ALL FILES in any command files your use. YOU MUST CODE AN ABSOLUTE PATH TO THE DIRECTORY CONTAINING YOUR MODEL IN YOUR MODEL CONFIG FILE.
There must be a separate display config file associated with each tile. The "corners" tags in these config files are used to provide a different viewing frustum (camera) for each. vrNav comes distributed with display config files for a 3 by 1 tiled display. (These emulate the "archives" previously built for the SGI we ran in the portal: spherical, spherical stereo, flat plane, and flat plane stereo.) If your tiled display is larger than that, you will have to make additional display config files, 1 for each tile. Refer to the document DisplayConfig-Howto.html for information on making display config files and follow the following rules:
To start up vrNav2 on a tiled display, the -tilecontrol option must be specified for the control node and the -tile option must be specified for each of the tiles.
The syntax of these options is as follows:
- -tilecontrol port number_of_tiles myBarrierPort nextBarrierAddr nextBarrierPort
- The vrNav2 run on this node will control the tiled display. The navigation device: currently mouse , and the keyboard must be connected to this machine. When used in conjunction with one of the PlaybackNavigators, this node will be the one to read the path or keyframe file.
Replace port with the port you will use for the communications. Replace number_of_tiles with the number of tiles that will connect to this control node. Do not count the control node in this number.
- -tile port nodeindex tilecontroll_address myBarrierPort nextBarrierAddr nextBarrierPort
- This vrNav2 is a single tile in the tiled display. You must run number_of_tiles of these nodes. Replace port with the same port number you used on the -tilecontrol option you specified on the vrNav2 you started on the controller machine, nodeindex with an integer from 0 through number_of_tiles-1, and tilecontroller_address with the address of the tile control machine. Each of the tiles must have a unique node index.
For the barrier, each tile must use a different barrier port. The tiles and tilecontrol have to be connected in a circular fashion. Each must open its barrier port to receive a connection and connect to the address and port of the next machine in the circle. Replace myBarrierPort with the port to be used by this node and nextBarrierAddr and nextBarrierPort with the address and port of the node this node will connect to.
For your convenience, the vrNav2 script has a keyword that starts up vrNav2 with the appropriate options on the tile control node and on all of the rendering tile machines. It runs vrNavApp on the control node and ssh's to each rendering node and starts up vrNavApp there also for you.
- -td filename
- The vrNav2 script will start vrNavApp on every node of the tiled display. Replace filename with the name of a file that describes your tiled display setup. A completely documented example file is included in the vrNav2 config directory. An abreviated version is shown below.
Use a file that describes your tiled display like this one:
# How many rows and columns does your tiled display have? # rows columns 1 3 # Make one line for each tile including the controller tile. # Note: row 1, column 1 is the top left corner. # row column address optional_display_config_fullfilename 1 1 tile0 /tile/apps/vrnav-pf/config/tiledDisplay.display.left.jconf 1 2 tile1 /tile/apps/vrnav-pf/config/tiledDisplay.display.center.jconf 1 3 tile2 /tile/apps/vrnav-pf/config/tiledDisplay.display.right.jconf
If you do not code the optional display config filenames, vrNav will look for a file in the config directory named tiledDisplay.display.rxc.jconf for each tile, where r is the row number and c is the column number. Only three such config files actually come with vrNav2 as distributed. These correspond to row one columns one through three.
To use the -td option of the vrNav2 script with a tiled display that has been set up with a separate internal network from the external address, you must modify the script. Find the line in the script (it's in the bin directory) that reads:
set host = `hostname -s`And replace the code to the right of the equal sign with the internal address of your control node.
To add additional tiles you must:
set dpy_tdp_3_rxc = $VRNAVCONFIG/tiledDisplay.display.rxc.jconfWhere r is a row number and c is a column number.
The following features are selected by adding the appropriate xml elements into the model config file for the model you are using. See the vrNav2 document Creating a Model config file for vrNav2 [ModelConfig-Howto.html] for the keywords to use.
Models may contain switches. A switch contains several model segments (selected via switch masks) for the same part of the model. Switches can be used to show how parts of a model changed over time, display alternate architectual plans and/or add optional components into a model. More specifically, The model config file for a model can contain one or more <Model> elements, i.e., each model can be made up of one or more Models. Each Model can contain zero, one, or more switches. Each switch contains multiple model segments selectable via switch masks. There are two kinds of switches, simple switches and multi-switches.
The complexity of Models and switches is best illustrated by an example. Suppose a specific model is made up of three Models: M1, M2, and M3 and that M1 has two switches M1S1 and M1S2 and that model M3 has two switches OLS31 and OLS32. M1S1, which is a simple switch has two model segments that represent alternatives: ORIG, selected via switch mask 1 which shows how that part of the model was originally constructed and REMODEL, which shows how it looked after it was remodeled. The switch masks for M1S2, which is a multi-switch, however, do NOT represent alternatives. The model segments connected to M1S2 represent people who might or might not be present in the model. M1S2P1 is the model of a person, M1S2P2 is the model of a second person, M1S2P3 is the model of a third and a fourth person. When construting a multi-switch, the modeler designates what are called switch sets. In this case, the modeler has set up three switch masks. For the switch set selected with switch mask 1, all of M1S2P1, M1S2P2, and M1S2P3 are turned off, i.e., when switch mask 1 is selected, no people appear in the scene. The switch set selected by switch mask 2 includes only M1S2P1, i.e., when switch mask 2 is selected one person appears in the scene. The switch set selected by switch mask 3 includes M1S2P1 and M1S2P2, so that when switch mask 3 is selected, two people appear. The switch set selected by switch mask 4 includes M1S2P1, M1S2P2 and M1S2P3, so that when switch mask 4 is selected, all four people appear. OLS31 and OLS32 are simple switches in Model M3. OLS31 shows one of 4 alternative model segments and OLS32 shows one of 3 alternative model segments.
Using the vrNav2 GUI, you can change the switch mask of any switch belonging to any Model in the model currently being navigated with vrNav2. You do this by selecting the Model and switch by name from pull-down menus. For example to select one of the alternatives of OLS31 you would select M3 from the pull-down menu that shows the Model names and then OLS31 from the pull-down menu that allows you to select a switch in that model. You then choose the switch mask from a widget that allows you to select a switch mask.
Using the keyboard, you can switch only between the alternative switch masks of the switches in the first Model named in the model config file. In this case that would be M1. When vrNav2 starts, the first switch of the first Model is always selected as the switch the n and p keys will act on. The h key selects the next switch in the first Model for the n and p keys to act on. When the last switch in the first Model is selected, pressing the h key will select the first switch in that same Model. To change the switch mask of the selected switch, press the n key to switch to the next switch mask, or the p key to switch to the previous switch mask. For the model in the example discussed above, the switches for M1 are the only switches that can be changed from the keyboard. To change the switch masks in the OLS31 and OLS32 switches in Model M3, you have to use the vrNav2 GUI. When vrNav2 starts up, it is set such that pressing the n or p keys changes the switch mask of switch M1S1 only. Once the h key is pressed, then from then on, the n and p keys with change the switch masks of M1S2. Since M1S2 is the last switch in M1, pressing h again causes those keys to control M1S1 onec again.
Date Switches differ from switches in the way you designate the alternatives. With date switches, you assign a year to each switch mask (alternative) via the model config file. The model can have any number of date switches each with a set of designated years. At run time, when a year is selected, all the date switches are changed at once to the switch mask that best represents that year. For example, suppose your model includes a group of 5 buildings, four of which were built in 1280. If one of the four was renovated in 1526 and again in 1863, another in 1720 and the fifth building wasn't built until 1402, placing date switches on those three buildings would allow the user to view the site as it existed: before 1402, between 1402 and 1526, between 1526 and 1720, between 1720 and 1863 and after 1863. By selecting a date, the user would switch all the date switches in the model simultaneously.
If more than one Model is included in the model config file, you can switch only the date switches for the first Model via the keyboard. To do so, press the i key to increase the year for the date switch, or the j key to decrease the year. You can switch the date switches for all the Models via the vrNav2 GUI
Many scientific models are the result of running simulation programs. A simulation program applies scientific laws or principles to a set of initial conditions to compute the data at the first time step. From then on, the same laws or principles are applied to the data at the current time step to compute the next time step.
When the data generated by a simulation program is turned into a model, a separate model is created for each time step. vrNav2 can work with the whole sequence of models. Press u to go up in the sequence. vrNav2 will replace the current model you are navigating with the model for the next time step. Press d to go down in time.
Using the vrNav GUI, you can jump around in time; using the keyboard you can only change time consecutively. For a large number of time steps, this makes use of the vrNav GUI much more convenient than using the keyboard.
See the section on making movies for information on making moves in which the time steps change over the frames of the movie.
This feature displays a 2 dimensional map of the model being navigated in a small window overlayed on the main display window. A small red marker marks your current location and points in the direction you are going. Having a map is useful especially if you have a large model as the map lets you know where you are as you navigate around and prevents you from getting lost.
There are 2 types of Maps supported by vrNav2: TopView, and Image.
In order for vrNav2 to correctly locate your position in the model space on the Map you must pay attention to the following:
Pressing the b key or clicking on the birdview toggle in the vrNav2 GUI toggles the viewer to the bird's eye view position and back. When you go into the the bird's eye view, either via the b key or from the GUI, vrNav2 moves the viewer immediately back an up at an angle to a specified height above the model. Both the angle and the height can be changed in the vrNav2 GUI. When you return from the bird's eye view, either by pressing the keyboard key or from the GUI, vrNav2 moves the viewer back to the original position at which the bird's eye view was entered. That is, any navigation you do while at the bird's eye position will be as if it had not happened.
The Text Logo is a small text display that can be used to credit the organization or people who created the model, name the model, or for any other purpose. The Text Logo is superimposed on top of, i.e., covering up, a portion of the model being navigated. Transparency can be used to create a partially see through Text Logo.
You can configure the Text Logo to be displayed from the start, when vrNav first comes up or not. Use the T key or the vrNav GUI to toggle the Text Logo on and off.
When the vrNav2 GUI is connected to a running vrNav2, the navigator's position in model space is continuously updated and displayed in the GUI. If you code the UTM chunk in the model config file, the navigator's position is also displayed in UTM coordinates.
A Jump Point is a named location in the model. Jump Points are useful, especially in large models as they give you the ability to jump immediately to a place of interest. You create Jump Points in the vrNav2 GUI by navigating to a location of interest and placing a named Jump Point there. When you press the button in the GUI to save the Jump Points, the GUI saves the Jump Points in a separate JumpPoints config file. (Please note that any Jump Points you create via the GUI during a run of vrNav2 will be lost unless you save them.)
To use Jump Points that the GUI saved for you subsequently, when you run vrNav2 on the same model, specify the name of the JumpPoints config file with the model config file on the vrNav2 command line when you start vrNav2.
vrNav2 -gui port ... JumpPoints.jconf7 model.jconf7For vrNavApp (and on Windows) code the name after the:
-configfilesoption with the other config files.
If you desire, you can edit the model config file and include the Jump Points directly there, instead of using a separate Jump Points config file. The Jump Points elements must be outside of the the Model element. See the ModelConfig-Howto manual for more information on these config files.
The interface to the DySE Builder Sound Server is documented separately. Look for the documentation on the sound server in the docs directory of the vrNav2 distribution.
The Broadcast Server and Model Feature Database are not currently available in the OSG version of vrNav2.