ViSBARD Quick Start Guide


************
Introduction
************

Welcome to ViSBARD, the Visual System for Browsing, Analysis, and Retrieval of
Data.  

A descriptive overview of the program and tutorial examples are available in
PDF format; they are called ViSBARD_05_2005_Overview.pdf and
ViSBARDTutorialExamples.pdf. These files are located in the ViSBARD\doc
folder.

The program also has online help accessible through the "?" icon on the toolbar.  



*********************************************************
Platform-Specific Installation and Launching Instructions
*********************************************************

- Windows 9x/NT/2000/XP:
	- Unzip downloaded ViSBARD file into a new directory of your choosing
      using WinZip or its equivalent
	- (optional) Unzip sample data file(s) into a another directory
	- Double-click the "RUN_ViSBARD_Win32.BAT" file to launch

	
- Mac OS X:
	Requirements:
	 - Mac OS X 10.3.1 or later
	 - Java 1.4.1 or greater
	 - Java3D and Java Advanced Imaging Update 1.0	 	
	 
	Installation Instructions:
	 - Most Mac OS X 10.4 already contain the libraries necessary to run ViSBARD.
	   However, OS X 10.3 may require you to install Java3D and Java Advanced
	   Imaging:	   
	   
	   http://www.apple.com/downloads/macosx/apple/macosx_updates/java3dandjavaadvancedimagingupdate.html
	   
	   	
	 - Download the ViSBARD_YYYYMMDD.tar.gz file to a place of your choosing
	 
	 - Some browsers may automatically extract its contents after the download
       is complete.
		- If your browser did not, you should be able to do so by 
          double-clicking on the file and letting Stuffit expand it for you.
		- If all else fails, you can manually extract it at a terminal window
          (Applications->Utilities->Terminal)
			- cd to where the tar.gz file is  (i.e., 
              "cd /Users/rboller/downloads")
			- Unzip/untar the file:
				gunzip ViSBARD_YYYYMMDD_Mac.tar.gz
				tar -xvf ViSBARD_YYYYMMDD_Mac.tar

	 	                       
	 - Using the Finder or a Terminal window, move the ViSBARD_YYYYMMDD
       folder to the "final" place where you'd like to store it (i.e., 
       /Users/rboller/Applications/ViSBARD_20050506).
	 - You may then delete the downloaded tar or tar.gz file.
	 	  
	  	 		  
	Running: 	
	
	 There are two methods of running ViSBARD:  from a Terminal window, or 
     from the Finder.
	 
	 * Launching from the Terminal window:		 
	    - cd to ViSBARD's bin directory:
	 	    cd ViSBARD_YYYYMMDD/bin
	    - Launch the startup script:
	 	    ./visbard
	 	
	    - OPTIONAL:  If you would like to create an alias for ViSBARD to
          launch from anywhere, it needs to contain a command to "cd" to the 
          "ViSBARD_YYYYMMDD/bin" directory.  For example, if using the bash 
          shell, add a similar line to ~/.bash_profile
	  
	    alias visbard='cd /Users/rboller/code/ViSBARD_20050216/bin ; ./visbard ; cd -'

	    
	 * Launching from the Finder
	   - Open a new Finder window
	   - Find your way to the ViSBARD bin directory 
         (i.e., Applications->ViSBARD_20050506->bin)
	   - Double-click on "visbard"
	   - A window will pop up and tell you that there is no default
         application specified to open the document "visbard". 
	   - Click "Choose Application"
	   - Change the filter to "Enable: All Applications"
	   - Select Applications->Utilities->Terminal
	   - It will ask you, "Do you want to open "visbard" with "Terminal"?"
	   - Click "Update"
	   
	   Visbard should now launch.  Disregard NullPointerExceptions dealiing
	   with the AquaDirectoryModel, as they appear to have no effect on 
       application performance

	   You may also create an icon on your desktop by selecting the "visbard"
       file in the Finder, then selecting File|Make Alias (Cmd-L).  This will
       create a file named "visbard alias" that you can drag to your desktop.
	  		 		 	
	   
- Linux:
	Installation Instructions:
	 	- Open a terminal window
	 	- Move the downloaded ViSBARD tar.gz file to the directory where 
          you'd like it to be installed 
	 	- Unzip/untar file:
	 		gunzip ViSBARD_YYYYMMDD_Linux.tar.gz
	 		tar -xvf ViSBARD_YYYYMMDD_Linux.tar
	 	
	  	This will create a subdirectory called ViSBARD_YYYYMMDD.  The tar 
        file can be deleted if desired.
	  	
	  	- OPTIONAL:  If you would like to create an alias for ViSBARD to
          launch from anywhere, it needs to contain a command to "cd" to the
          "ViSBARD_YYYYMMDD/bin" directory.  For example, if using the bash
          shell, add a similar line to ~/.bash_profile
	  	
	  	alias visbard='cd /Users/rboller/code/ViSBARD_20050216/bin ; ./visbard ; cd -'
	  		
		 		  
	Running: 	
		- cd to its bin directory:
	 		cd ViSBARD_YYYYMMDD/bin
	 	- Launch the Linux startup script:
	 		./visbard
	 		
	 	NOTE:  some Linux distributions may not contain the required C++ 
        libraries to run ViSBARD.  If you receive an error similar to 
        "...failed...because libstdc++.so.5... no such file or directory", 
        follow these steps:
	 		- Check if libstdc++.so.5 installed:
	 			yum provides libstdc++.so.5
	 		- It will probably tell you that it's contained in something
              similar to "compat-libstdc++-33.i386" and needs to be installed.
              Do this with the following command:
	 			yum install compat-libstdc++-33.i386
   


**************************************
Using Stereoscopic Features in ViSBARD
**************************************

It is possible to use stereoscopic hardware in ViSBARD to obtain a "true" 
sense of depth while viewing objects in 3-D.  It has been tested with an 
autostereoscopic display from Dimension Technologies (www.dti3d.com) on a 
Windows 2000 PC using an NVIDIA Quadro4 700XGL graphics card.  It has also
been tested on a "Geowall" system using polarized stereo glasses and twin
projectors under Linux and Windows XP, as described here: 
	http://geowall.geo.lsa.umich.edu/

In theory, it should work with any hardware that supports quad-buffered OpenGL
stereo.  If your graphics card supports this, make sure it is enabled in the
driver settings.  For example, under the Windows/NVIDIA combination above, the
settings are located under 
Control Panel->Display->Settings->Advanced->Quadro4 700XGL->OpenGL Settings->Additional Settings.  

The ViSBARD.settings file (located in ViSBARD/settings/ViSBARD.settings) then
needs to be modified to allow stereo  (it is disabled by default).  Open the
file in a text editor and locate the following line:

Universe_Stereo\ Enabled\ Application=false

Replace "false" with "true".  NOTE:  There is another line that looks similar
(Universe_Stereo\ Enabled=false), but has a different meaning.  It is used to
determine whether or not the application should start with stereo on or off.

If all goes well, you should be able to launch ViSBARD, go to the Options
panel, and click the enable stereo checkbox.  The eye separation can be
adjusted with the "Stereo Separation" slider.  The amount that 3-D objects
appear to "pop out" of the display (as opposed to "popping into" the display)
can be adjusted with the "Plane of Monitor" slider.


***************
Troubleshooting
***************

If the program doesn't start, let us know the particulars of the machine, 
graphics card, and operating system. Describe any error messages that you 
see.  We may not be able to solve the problem, but the information would be
useful.

Note that we have found certain video problems to be related to color depth.
Try swtching the windows colordepth to 16-bit (also try 32-bit) if the 
displayed colors do not look right.

We hope that this version of ViSBARD, although continuously under development,
will be useful.  You can help us by providing feedback.


Please send your comments to aaron.roberts@nasa.gov.