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"
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 | 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 | the tail-end version of all the minor-change versions. | ||
but should generally work for other versions of | (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 | <LI> Download FreeVR | ||
: Download from the [http:// | : 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 | : <CODE>% tar -zxf freevr_0.7e.tar.gz</CODE> | ||
: <CODE>% cd | : <CODE>% cd freevr_0.7e</CODE> | ||
<LI> Compile | <LI> Compile | ||
: <CODE>% make - | : For major OSes, there are quick targets that will build the library and some test applications: | ||
:: (this | :* <CODE>% make linux</CODE> | ||
:* <CODE>% make darwin</CODE> — This is for MacOS (Darwin is the Mac window manager) | |||
:* <CODE>% make cygwin</CODE> — This is the MS-Windows version and requires ''Cygwin'' | |||
: There are also two specialty targets useful on Linux systems: | |||
:* <CODE>% make pt</CODE> — the pthreads-compatible version for Linux | |||
:* <CODE>% make st</CODE> — 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 | ||
: | : 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.) | |||
:: (NOTE: | |||
</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 | 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>". | |||
Detailed information on creating/altering a FreeVR configuration file can | |||
be found in the online in the [https://freevr.org/vradmin_guide.html FreeVR VR Administrator's Guild]. | |||
Here are some | 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; | ||
* | * FreeVR sections are contained in C-style curly brackets (<CODE>{</CODE> and <CODE>}</CODE>); | ||
* 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 "<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; | |||
=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.: | ||
: <CODE>-I/''<freevr-path>''/include</CODE> | |||
And in the linking line, the library should be included. E.g.: | |||
: <CODE>-L/''<freevr-path>''/lib -lfreevr_64</CODE> | |||
If the PThreads variant is used, then more libraries are required: | |||
: <CODE>-L/''<freevr-path>''/lib -lfreevr_64pt -ldl -lpthread</CODE> | |||
By default FreeVR will build two example applications: "<CODE>travel</CODE>" and "<CODE>inputs</CODE>". | |||
The "<CODE>travel</CODE>" 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 "<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:// | * [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.
- Download FreeVR
- Download from the FreeVR Download page
- Untar in a local directory
% tar -zxf freevr_0.7e.tar.gz
% cd freevr_0.7e
- 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
- For major OSes, there are quick targets that will build the library and some test applications:
- 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.)
- 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.
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.