Immersive Visualization / IQ-Station Wiki

This site hosts information on virtual reality systems that are geared toward scientific visualization, and as such often toward VR on Linux-based systems. Thus, pages here cover various software (and sometimes hardware) technologies that enable virtual reality operation on Linux.

The original IQ-station effort was to create low-cost (for the time) VR systems making use of 3DTV displays to produce CAVE/Fishtank-style VR displays. That effort pre-dated the rise of the consumer HMD VR systems, however, the realm of midrange-cost large-fishtank systems is still important, and has transitioned from 3DTV-based systems to short-throw projectors.

Difference between revisions of "FreeVR"

From IQ-Station Wiki
Jump to navigation Jump to search
m (Removed the reference to where I formerly worked.)
(A Major revision to fill in details that have long been needed)
 
Line 16: Line 16:
years will work, though of course bugs are eliminated in each version and
years will work, though of course bugs are eliminated in each version and
a handful of nifty features are generally added.
a handful of nifty features are generally added.
The most recently released version of FreeVR (as of this writing [10/31/12]) is 0.6c.
The most recently released version of FreeVR (as of [02/29/24]) is 0.7e.


==FreeVR Dependencies==
==FreeVR Dependencies==
Line 26: Line 26:
Optionally, FreeVR can work with:
Optionally, FreeVR can work with:
* OpenSceneGraph
* OpenSceneGraph
On MS-Windows, FreeVR also requires:
* Cygwin


Nothing else should need to be installed for the library, though some applications will make use of additional libraries.
Nothing else should need to be installed for the library, though some applications will make use of additional libraries.
Line 31: Line 34:
==Installing FreeVR==
==Installing FreeVR==


...
FreeVR can be downloaded from: [http://freevr.org/downloads.html FreeVR.org/Downloads].
<!--
The ''Downloads'' page usually has the current version, the previous version, as well as
These instructions have been tested with Vrui version 1.0-068 (the latest of the 1.0 line),
the tail-end version of all the minor-change versions.
but should generally work for other versions of Vrui.
(Note that as of now, FreeVR hasn't been declared reaching 1.0 status,
although there have been about 43 tagged versions starting with 0.1a.)
 
 
These instructions have been tested with FreeVR version 0.7e (the latest version
as of this writing),
but should generally work for other versions of FreeVR.


<OL>
<OL>
<LI> Download Vrui
<LI> Download FreeVR
: Download from the [http://idav.ucdavis.edu/~okreylos/ResDev/Vrui/Download.html Vrui Download page]
: Download from the [http://freevr.org/downloads.html FreeVR Download page]
<LI> Untar in a local directory
<LI> Untar in a local directory
: <CODE>% tar -zxf Vrui-1.0-068.tar.gz</CODE>
: <CODE>% tar -zxf freevr_0.7e.tar.gz</CODE>
: <CODE>% cd Vrui-1.0-068</CODE>
: <CODE>% cd freevr_0.7e</CODE>
<LI> Adjust the makefile
: <CODE>% $EDITOR makefile</CODE>
:* set <CODE>INSTALLDIR</CODE> to "<CODE>/opt/VR/Vrui-1.0-068</CODE>"
:*: NOTE: adding the build-version to INSTALLDIR helps avoid issues when upgrading
:* add "-b" to the "<CODE>@install ... Share/Vrui.cfg ...</CODE>" line
:*: (this will save you much grief in the future -- when you might otherwise wonder what happened to the config files you made)
:*: NOTE: after the first install, commenting out this line entirely is recommended
<LI> Fix a bug ''(update tracking for single tracker)''
: <CODE>% $EDITOR VRDeviceDaemon/VRDeviceManager.cpp</CODE>
:* Change: "<CODE>if(trackerReportMask==fullTrackerReportMask)</CODE>" to "<CODE>if(trackerReportMask != 0)</CODE>"
<LI> Fix another bug ''(proper window placement)''
: <CODE>% $EDITOR GL/GLWindow.cpp</CODE>
:* Add after <CODE>XMapWindow(display,window);</CODE>
<PRE>  /* since XCreateWindow() doesn't properly place the window, we need to move it to the correct location */
  XMoveWindow(display, window, windowPos.origin[0],windowPos.origin[1]);</PRE>
<LI> Add a feature ''(remove decorations on full-screen displays)''
: <CODE>% $EDITOR GL/GLWindow.cpp</CODE>
:* Add after <CODE>window=XCreateWindow(...)</CODE>
<PRE>  /* Add a block to turn off decorations when window is as big as one screen */
  if ((windowPos.size[0] == 1920) && (windowPos.size[1] == 1080)) {
      unsigned long  wm_hints[5] = { 2, 0, 0, 0, 0 };        /* the 4th element isn't really unsigned, but it's zero, so who cares */
      XChangeProperty(display, window, XInternAtom(display, "_MOTIF_WM_HINTS", False), XInternAtom(display, "_MOTIF_WM_HINTS", False), 32, PropModeReplace, (const unsigned char *)wm_hints, 5);
  }</PRE>
<LI> Compile
<LI> Compile
: <CODE>% make -j 8</CODE>
: For major OSes, there are quick targets that will build the library and some test applications:
:: (this will take less than a minute)
:* <CODE>% make linux</CODE>
:* <CODE>% make darwin</CODE> &mdash; This is for MacOS (Darwin is the Mac window manager)
:* <CODE>% make cygwin</CODE> &mdash; This is the MS-Windows version and requires ''Cygwin''
: There are also two specialty targets useful on Linux systems:
:* <CODE>% make pt</CODE> &mdash; the pthreads-compatible version for Linux
:* <CODE>% make st</CODE> &mdash; the single-thread variant for Linux
:: (this should all build in a handful of seconds)
: There are additional build options, which can be obtained from:
:* <CODE>% make</CODE>
<LI> Install
<LI> Install
: <CODE>% sudo mkdir -p /opt/VR/Vrui-1.0-068</CODE> ''(or whatever version you are compiling)''
: Presently, there is no ''"install"'' target, because when one builds from a Downloaded tarball, then that directory is sufficient to be the "install" directory, and if the "modules" system is used, the module file can just point to the ''"bin"'', ''"etc""'', ''"man"'' and ''"src"'' directories &mdash; the latter being the directory with both the libraries and header files.
: <CODE>% sudo make install</CODE>
:: (NOTE: in the future, FreeVR will include an "install" build target to create the standard directory layout.)
:: (NOTE: after subsequent installs, you'll have to go to $INSTALLDIR and copy back from the saved backup config files)
</OL>
</OL>
That's it!
That's it!
-->


==Configuring FreeVR==
==Configuring FreeVR==


...
Configuring FreeVR can be a very difficult task.
<!--
If no configuration file is available, FreeVR will default to rendering
Configuring Vrui can be a very difficult task. A general hint is to find a working configuration setup that's close to what you want to do and then modify!  As we gain more experience, we will put more specific advice/instructions here.
a desktop window with inputs that can be simulated through keyboard and mouse.
Because it is often easier to begin with a working configuration and make
alterations, a suite of sample configuration files are provided as part
of the tarball.
These can be found in the <CODE>etc</CODE> directory, and include options
such as <CODE>rc_sample_cave</CODE>, <CODE>rc_sample_cygwin</CODE>, and
<CODE>rc_sample_vrpnserver</CODE>.
There is also an example personal configuration file named "<CODE>freevrrc_home</CODE>",
which would be renamed to "<CODE>~/.freevrrc</CODE>".


In the meantime, here are links to other sources of information:
Detailed information on creating/altering a FreeVR configuration file can
* [http://wiki.cse.ucdavis.edu/keckcaves:configuration_files KECKCAVES Wiki page on Vrui Configuration]
be found in the online in the [https://freevr.org/vradmin_guide.html FreeVR VR Administrator's Guild].
* Oliver Kreylos' Vrui online documentation has three pages on configuration:
** [http://idav.ucdavis.edu/~okreylos/ResDev/Vrui/Documentation/VruiCalibration.html Setting up and Calibrating a Vrui VR Environment]
** [http://idav.ucdavis.edu/~okreylos/ResDev/Vrui/Documentation/VruiConfigurationFile.html The Vrui Configuration File]
** [http://idav.ucdavis.edu/~okreylos/ResDev/Vrui/Documentation/VruiConfigurationFileReference.html Vrui Configuration File Settings Reference]




Here are some unorganized bits of information as I encounter them during my trials (and tribulations):
Here are some configuration information nuggets:
* Comments are denoted with the hash (<CODE>#</CODE>) symbol through the end-of-line
* Comments are denoted with the hash (<CODE>#</CODE>) symbol through the end-of-line;
* When discussing Vrui configuration options, a directory-like syntax is used by the Vrui library (but not the configuration file).  In the configuration files, sections have sections within them.
* FreeVR sections are contained in C-style curly brackets (<CODE>{</CODE> and <CODE>}</CODE>);
* In Vrui.cfg, the "root" section is the one selected for use, when not specified on the command line with the <CODE>-rootSection</CODE> option it defaults to <CODE>Desktop</CODE>
* Statements not contained within curly-brackets are generally to set global effects;
* In theory Vrui can use any coordinate frame.  In practice, use Z-up since applications seem to assume this.
* Configuration files can read other configuration files, which is especially useful for the user's personal configuration file;
** thus, always set <CODE>root/upDirection (0.0, 0.0, 1.0)</CODE>
* Conditional statements are available for setting a configuration, which allows a configuration to be depending on machine names or environment variable settings;
* Windows and Screens go hand-in-hand ''(I'd prefer them to be a single entity)''
* BUG: One issue to be aware of is that the "<CODE>args</CODE>" value of configuration objects is parsed such that the first occurrence in a string of the keyword is the one that is honored;
* root/displayCenter &mdash; the place where the world will go when centering the display (including initial location)
* root/displaySize controls the relative size that the vis-world is rendered.  A good rule-of-thumb is to set this to be half the front screen's diagonal
-->


=Compiling FreeVR Applications=
=Compiling FreeVR Applications=


...
Compiling FreeVR applications is fairly straight forward.
<!--
In the compiling line, the header file should be included. E.g.:
Vrui comes with some example programs that can be quickly compiled and used for experimentation.
: <CODE>-I/''&LT;freevr-path&GT;''/include</CODE>
# Adjust the makefile
And in the linking line, the library should be included.  E.g.:
#: <CODE>% cd ExamplePrograms</CODE>
: <CODE>-L/''&LT;freevr-path&GT;''/lib -lfreevr_64</CODE>
#: <CODE>% $EDITOR makefile</CODE>
If the PThreads variant is used, then more libraries are required:
#:* ''for Vrui 1.x:'' set <CODE>VRUIDIR</CODE> to "<CODE>/opt/VR/Vrui-1.0-068</CODE>"
: <CODE>-L/''&LT;freevr-path&GT;''/lib -lfreevr_64pt -ldl -lpthread</CODE>
#:* ''for Vrui 2.x:'' set <CODE>VRUI_MAKEDIR</CODE> to "<CODE>/opt/VR/Vrui-2.3-001/share/make</CODE>"
 
# Compile
By default FreeVR will build two example applications: "<CODE>travel</CODE>" and "<CODE>inputs</CODE>".
#: <CODE>% make</CODE>
The "<CODE>travel</CODE>" application is meant to demonstrate the ability to walk around objects,
# Run
most of which are fixed to the physical (real) world, and then travel relative to one object
#: <CODE>% ls bin</CODE>
in the virtual world (a white pyramid).
#: <CODE>% bin/VruiDemo</CODE>
Object placement is primarily meant to be interesting in a 9'x9' CAVE-style VR system.
#:: ''This should open a window with a spinning cube.''
The "<CODE>input</CODE>" application is intended to quickly visualize the state of
all the VR inputs, and thus give a sense of whether they are being correctly read/interpreted.
The "<CODE>input</CODE>" application also works well when FreeVR is being used for for of
the side-effects by which VR inputs can be output to other applications (be they other VR
systems or not).
 
=FreeVR VR Tutorials=
The [https://freevr.org FreeVR webpage] includes a
[https://freevr.org/tutorials.html subpage of VR tutorial examples].
Presently the only tutorials available for download is the OpenGL suite.
However, there are also collections for building with [https://openscenegraph.org OpenSceneGraph],
and the [https://ode.org ODE Physics Engine].
In the (hopefully) near future, these will be added to the [https://freevr.org FreeVR webpage].
 
 
=FreeVR Utility Suite=
 
In addition to the FreeVR library for building new VR applications, the
FreeVR package includes many additional tools, most of which are for testing
various input devices and protocols.
Perhaps the most useful of these are the tools that report VR inputs
from the [https://github.com/vrpn/vrpn/wiki VRPN input server],
the [[Vrui | Vrui VRDeviceDaemon]],
and the [https://ar-tracking.com/en/product-program/dtrack DTrack server from AR-Tracking].
 
What these tools provide is a live output of whatever input values are transmitted
from these servers.
The output can be in one of three forms:
* Readable text to the terminal
* CSV text to the terminal
* ASCII-art style rendering to the terminal
 
Other input readers include several for specialized input devices, such
as the ''Space Navigator'', ''Polhemus Fastrak'' (and related) devices.


-->
In addition to the input-testing utilities, there is also a pair of
tools useful for reverse-engineering data streams of input devices.
One of these ("<CODE>serialspy</CODE>") was useful during the era when
many devices connected to computers via the RS-232 hardware protocol
and sent serial data to readable ports.
The other tool ("<CODE>socketspy</CODE>") is similarly useful to help
interpret data streams that are sent via TCP/IP protocol from client to
server.
Both act as "man-in-the-middle" interceptors that output the values to
the terminal, and also continue to pass the data between client and
server to allow them to continue functioning normally.


=See Also=
=See Also=
* [http://freevr.org The main FreeVR website]
* [http://freevr.org The main FreeVR website]
<!--
* [https://freevr.org/tutorials.html The FreeVR tutorials page]
* [https://web.avl.indiana.edu/wiki/index.php?title=Vrui IU AVL Wiki's Vrui page] (which will often be in sync with this page) (Login required)
* [https://github.com/openscenegraph/OpenSceneGraph OpenSceneGraph Github page]
-->
* [https://ode.org ODE physics engine webpage]

Latest revision as of 23:08, 17 May 2024

FreeVR VR integration library

FreeVR is a VR integration library currently maintained by Bill Sherman. The design approach of FreeVR was to provide an API that call-for-call lines up with the CAVE library from the University of Illinois at Chicago. Occasionally new functionality was added, but little was left out. Another philosophical decision was to be as minimalist as possible, depending on as few other resources, and thus being easy to compile on just about any OS version.

There are pre-existing FreeVR Applications written at the University of Illinois and DRI as part of our immersive visualization ensemble. But before using a FreeVR application, one must first install and configure FreeVR.

FreeVR Versions

The FreeVR API has been very stable, so most versions from the past few years will work, though of course bugs are eliminated in each version and a handful of nifty features are generally added. The most recently released version of FreeVR (as of [02/29/24]) is 0.7e.

FreeVR Dependencies

Basic FreeVR depends only on two packages which are generally installed on any self-respecting computer:

  • OpenGL
  • X-windows

Optionally, FreeVR can work with:

  • OpenSceneGraph

On MS-Windows, FreeVR also requires:

  • Cygwin

Nothing else should need to be installed for the library, though some applications will make use of additional libraries.

Installing FreeVR

FreeVR can be downloaded from: FreeVR.org/Downloads. The Downloads page usually has the current version, the previous version, as well as the tail-end version of all the minor-change versions. (Note that as of now, FreeVR hasn't been declared reaching 1.0 status, although there have been about 43 tagged versions starting with 0.1a.)


These instructions have been tested with FreeVR version 0.7e (the latest version as of this writing), but should generally work for other versions of FreeVR.

  1. Download FreeVR
    Download from the FreeVR Download page
  2. Untar in a local directory
    % tar -zxf freevr_0.7e.tar.gz
    % cd freevr_0.7e
  3. Compile
    For major OSes, there are quick targets that will build the library and some test applications:
    • % make linux
    • % make darwin — This is for MacOS (Darwin is the Mac window manager)
    • % make cygwin — This is the MS-Windows version and requires Cygwin
    There are also two specialty targets useful on Linux systems:
    • % make pt — the pthreads-compatible version for Linux
    • % make st — the single-thread variant for Linux
    (this should all build in a handful of seconds)
    There are additional build options, which can be obtained from:
    • % make
  4. Install
    Presently, there is no "install" target, because when one builds from a Downloaded tarball, then that directory is sufficient to be the "install" directory, and if the "modules" system is used, the module file can just point to the "bin", "etc"", "man" and "src" directories — the latter being the directory with both the libraries and header files.
    (NOTE: in the future, FreeVR will include an "install" build target to create the standard directory layout.)

That's it!

Configuring FreeVR

Configuring FreeVR can be a very difficult task. If no configuration file is available, FreeVR will default to rendering a desktop window with inputs that can be simulated through keyboard and mouse. Because it is often easier to begin with a working configuration and make alterations, a suite of sample configuration files are provided as part of the tarball. These can be found in the etc directory, and include options such as rc_sample_cave, rc_sample_cygwin, and rc_sample_vrpnserver. There is also an example personal configuration file named "freevrrc_home", which would be renamed to "~/.freevrrc".

Detailed information on creating/altering a FreeVR configuration file can be found in the online in the FreeVR VR Administrator's Guild.


Here are some configuration information nuggets:

  • Comments are denoted with the hash (#) symbol through the end-of-line;
  • FreeVR sections are contained in C-style curly brackets ({ and });
  • Statements not contained within curly-brackets are generally to set global effects;
  • Configuration files can read other configuration files, which is especially useful for the user's personal configuration file;
  • Conditional statements are available for setting a configuration, which allows a configuration to be depending on machine names or environment variable settings;
  • BUG: One issue to be aware of is that the "args" value of configuration objects is parsed such that the first occurrence in a string of the keyword is the one that is honored;

Compiling FreeVR Applications

Compiling FreeVR applications is fairly straight forward. In the compiling line, the header file should be included. E.g.:

-I/<freevr-path>/include

And in the linking line, the library should be included. E.g.:

-L/<freevr-path>/lib -lfreevr_64

If the PThreads variant is used, then more libraries are required:

-L/<freevr-path>/lib -lfreevr_64pt -ldl -lpthread

By default FreeVR will build two example applications: "travel" and "inputs". The "travel" application is meant to demonstrate the ability to walk around objects, most of which are fixed to the physical (real) world, and then travel relative to one object in the virtual world (a white pyramid). Object placement is primarily meant to be interesting in a 9'x9' CAVE-style VR system. The "input" application is intended to quickly visualize the state of all the VR inputs, and thus give a sense of whether they are being correctly read/interpreted. The "input" application also works well when FreeVR is being used for for of the side-effects by which VR inputs can be output to other applications (be they other VR systems or not).

FreeVR VR Tutorials

The FreeVR webpage includes a subpage of VR tutorial examples. Presently the only tutorials available for download is the OpenGL suite. However, there are also collections for building with OpenSceneGraph, and the ODE Physics Engine. In the (hopefully) near future, these will be added to the FreeVR webpage.


FreeVR Utility Suite

In addition to the FreeVR library for building new VR applications, the FreeVR package includes many additional tools, most of which are for testing various input devices and protocols. Perhaps the most useful of these are the tools that report VR inputs from the VRPN input server, the Vrui VRDeviceDaemon, and the DTrack server from AR-Tracking.

What these tools provide is a live output of whatever input values are transmitted from these servers. The output can be in one of three forms:

  • Readable text to the terminal
  • CSV text to the terminal
  • ASCII-art style rendering to the terminal

Other input readers include several for specialized input devices, such as the Space Navigator, Polhemus Fastrak (and related) devices.

In addition to the input-testing utilities, there is also a pair of tools useful for reverse-engineering data streams of input devices. One of these ("serialspy") was useful during the era when many devices connected to computers via the RS-232 hardware protocol and sent serial data to readable ports. The other tool ("socketspy") is similarly useful to help interpret data streams that are sent via TCP/IP protocol from client to server. Both act as "man-in-the-middle" interceptors that output the values to the terminal, and also continue to pass the data between client and server to allow them to continue functioning normally.

See Also