========================================================================
README for Motion Capture Visualization
Copyright (c) 2026 Oliver Kreylos
========================================================================

Overview
========

The Motion Capture Visualization package contains code to visualize
motion capture data, and extract and visualize 3D mesh data from multi-
camera synchronized video sequences via space carving or photogrammetric
reconstruction.

The Motion Capture Visualization package is based on the Vrui software
development toolkit (see https://github.com/vrui-vr/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. More
information about the Motion Capture Visualization package can be found
at https://github.com/vrui-vr/motioncapturevisualization.

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

The Motion Capture Visualization package requires Vrui version 15.0
build 001 or newer.

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

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

It is also recommended to skip optional steps 4 and 6 in the following
instructions. The Motion Capture Visualization package does not need to
be installed in order to be used; installation (to a system directory
such as /usr/local) is only recommended if the Motion Capture
Visualization package will be used from multiple user accounts.

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

1. Change into ~/src directory and unpack the Motion Capture Visualization
   package tarball:
   > cd ~/src
   > tar xfz <download path>/MotionCaptureVisualization-<version>.tar.gz
   - or -
   > tar xf <download path>/MotionCaptureVisualization-<version>.tar

2. Change into the MotionCaptureVisualization base directory:
   > cd MotionCaptureVisualization-<version>

3. If the Vrui version installed in step 0 was not 15.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. Optional: Adapt makefile if the Motion Capture Visualization package
   is to be installed in a different location, for example /usr/local.
   Set INSTALLDIR to the desired target location. The Motion Capture
   Visualization package will then be installed in <INSTALLDIR>/bin
   (where <INSTALLDIR> is the value of INSTALLDIR set in the makefile).

5. Build the Motion Capture Visualization package:
   > make
   This creates executables in ./bin.

6. Optional: Install the Motion Capture Visualization package in the
   selected target location. This is only necessary if the INSTALLDIR
   variable in the makefile was changed. By default, the Motion Capture
   Visualization package can be run from its base directory. To install:
   > make install
   - or, if the target location is a system directory -
   > sudo make install
   This will copy all executables into <INSTALLDIR>/bin.

7. Optional: Add directory containing the Motion Capture Visualization
   package executable (in ~/src/MotionCaptureVisualization-<version>/bin
   in the default installation, in <INSTALLDIR>/bin otherwise) to the
   user's search path. This allows running the Motion Capture
   Visualization package from any directory. Using csh or tcsh:
   > setenv PATH ${PATH}:~/src/MotionCaptureVisualization-<version>/bin
   - or -
   > setenv PATH ${PATH}:<INSTALLDIR>/bin
   where <INSTALLDIR> is the target location set in the makefile.
   Using bash:
   > export PATH=${PATH}:~/src/MotionCaptureVisualization-<version>/bin
   - or -
   > export PATH=${PATH}:<INSTALLDIR>/bin
   These lines can also be added to the user's .cshrc or .bashrc files
   to make the additions persist between logins.

Running the MotionCaptureVisualization
======================================

These instructions assume that the MotionCaptureVisualization was
installed in its base directory, (see steps 4 and 6 above).

1. On MacOS X: Start X11. The Motion Capture Visualization package
   requires a running X server, but, if preferred, it can be started
   from a MacOS X terminal instead of xterm.

2. Start the main executable, MotionCaptureViewer, and provide the name
   of a motion capture trace file in CSV format as argument:
   > MotionCaptureViewer SomeTraceFile.csv

3. See Vrui's HTML documentation on Vrui's basic user interface and how
   to use the Motion Capture Visualization package.