========================================================================
README for Collaboration Infrastructure version 4.0
Copyright (c) 2008-2020 Oliver Kreylos
========================================================================

Overview
========

The Collaboration Infrastructure is a framework for the development of
collaborative immersive applications between multiple sites, based on a
client-server architecture. Any number of clients can dynamically
connect to a central collaboration server to participate in a
collaborative session. While connected, clients see representations of
the viewers and input devices of all other connected clients, can see
audio and/or 2D or 3D video from other clients supporting those options,
and can use shared annotation tools. The capabilities of the basic
collaboration infrastructure can be augmented by providing additional
protocol plug-ins, such as the bundled audio/video transmission plug-in,
or by integrating derived versions of the basic collaboration framework
into applications.

The Collaboration Infrastructure is an extension of the Vrui software
development toolkit (see
http://www.idav.ucdavis.edu/~okreylos/ResDev/Vrui), and runs in a
variety of environments ranging from laptop or desktop computers over
semi-immersive environments such as Geowalls to fully immersive virtual
reality environments such as CAVEs or head-mounted VR displays.

The Collaboration Infrastructure's development was supported by the
University of California, Davis, by the UC Davis W.M. Keck Center for
Active Visualization in the Earth Sciences (KeckCAVES,
http://www.keckcaves.org), the W.M. Keck Foundation, and the National
Science Foundation.

Requirements
============

The Collaboration Infrastructure requires Vrui version 6.0 build 001 or
newer. To support audio and 2D video transmission, PulseAudio, libspeex,
libopus, and libtheora have to be installed.

Installation Guide
==================

It is recommended to download or move the source packages for Vrui and
the Collaboration Infrastructure into a src directory underneath the
user's home directory. Otherwise, references to ~/src in the following
instructions need to be changed.

0. Install Vrui from ~/src/Vrui-<version>-<build> (see Vrui README file).

1. Change into ~/src directory and unpack the Collaboration
   Infrastructure tarball:
   > cd ~/src
   > tar xfz <download path>/CollaborationInfrastructure-<version>.tar.gz
   - or -
   > tar xf <download path>/CollaborationInfrastructure-<version>.tar

2. Change into the Collaboration Infrastructure base directory:
   > cd CollaborationInfrastructure-<version>

3. If the Vrui version installed in step 0 was not 6.0, or Vrui's
   installation directory was changed from the default of /usr/local,
   adapt the makefile using a text editor. Change the value of
   VRUI_MAKEDIR close to the beginning of the file as follows:
   VRUI_MAKEDIR := <Vrui install dir>/share/make
   Where <Vrui install dir> is the installation directory chosen in
   step 0. Use $(HOME) to refer to the user's home directory instead
   of ~.

4. Build the Collaboration Infrastructure:
   > make

5. Install the Collaboration Infrastructure:
   > make install
   or, if Vrui was installed in a system location,
   > sudo make install

Configuring the Local Collaboration Environment
===============================================

The runtime system of the Collaboration Infrastructure is configured via
a configuration file Collaboration.cfg in Vrui's configuration
directory, which is the etc subdirectory inside Vrui's installation
directory, or, by default, /usr/local/etc/Vrui-6.0. The configuration
file contains sections for the collaboration server and the
collaboration client, the latter of which in turn includes a section for
each configured protocol plug-in.

The most important change is to set the host name and port address of
the collaboration server in the CollaborationClient section. This is the
default server to which the collaboration client will connect when
started. Depending on the collaborative application, the server can be
overriden by other settings or by command line parameters. For example,
the CollaborationClientTest program in Vrui's bin directory accepts a
-server <host name>:<port address> command line argument.

Other important settings are the sound and video device names in the
Agora section (Agora is the protocol plug-in for shared audio and 2D
video).