Installation Guide

This section describes how to install OpenPTrack and the necessary dependencies, such as the Robot Operating System (ROS).

Ubuntu 14.04 (64-bit, desktop version)

The following steps will install both ROS (Indigo) and OpenPTrack on a PC. The installation process takes approximately 30 minutes per CPU.

1. Clone OpenPTrack repository from GitHub.

sudo apt-get install git -y
git clone https://github.com/OpenPTrack/open_ptrack.git

2. Install ROS.

cd open_ptrack/scripts
chmod +x *.sh
./ros_install.sh

source /opt/ros/indigo/setup.bash
./ros_configure.sh

3. Install OpenPTrack.

./openptrack_install.sh

N.B.: For all interdependencies to compile without error, sometimes Step 3 must be run twice. The error will generally look like:

[ 98%] Built target tracker
make: *** [all] Error 2
Invoking "make" failed

3.1 Symlink for /open_ptrack

To reduce the chance of OpenPTrack library compile errors, we need to remove the open_ptrack folder in your /home directory, and create a symlink to the open_ptrack folder contained in the /home/workspace/ folder. An example of how to do this would be to delete:

/home/open_ptrack

Now create the symlink in your /home folder to the /open_ptrack folder contained in /home/workspace/ :

ln -s  ~/workspace/ros/catkin/src/open_ptrack ~/open_ptrack 

4. Configure Kinect.

There is a udev issue with some Kinects. To prevent/fix this, follow these instructions.

Upon starting a Kinect sensor for calibration, you will need to complete the step (above) if you receive the following error:

[ INFO] [1414031641.954680151]: No devices connected.... waiting for devices to be connected

5. Configure Point Grey Stereo Cameras (optional).

To use stereo pairs composed of Point Grey cameras, install and build (from source) the ROS wrapper for Point Grey cameras from the OpenPTrack/pointgrey_camera_driver repository:

cd ~/workspace/ros/catkin/src
git clone https://github.com/OpenPTrack/pointgrey_camera_driver.git
cd ~/workspace/ros/catkin
catkin_make --force-cmake

6. Kinect V2 Installation.

This section describes how to install the Kinect v2 OpenPTrack dependencies:

6.1: Install your graphic card drivers (if not already installed), e.g.:

 sudo apt-get install nvidia-331-dev

After the installation, if you are using a Nvidia card, substitute the default OpenCL libraries (old and not standards-compliant) with working ones:

 sudo apt-get install ocl-icd-opencl-dev

6.2: Install Kinect 2 driver and ROS package:

 cd ~/workspace/ros/catkin/src
 source ~/.profile 
 roscd open_ptrack/../scripts
 chmod +x kinect2_install.sh
 ./kinect2_install.sh

6.3: Reboot.

6.4: Sometimes the Kinect 2 will not work because the OS parameters are not set correctly. To set those parameters correctly, run:

 cd ~/workspace/ros/catkin/devel/lib/kinect2_bridge
 sudo ./kinect2_bridge

This allows you to perform some operations as super-user. After you launch the executable, an error print in the terminal is normal.

This is the error that will be displayed in the terminal:

 [FATAL] [1430869490.307185716]: ROS_MASTER_URI is not defined in the environment. Either type the     following or (preferrably) add this to your ~/.bashrc file in order set up your local machine as a ROS master:

 export ROS_MASTER_URI=http://localhost:11311

 then, type 'roscore' in another shell to actually launch the master program.

7. Test.

7.1. Test Point Cloud:

 roslaunch kinect2_bridge kinect2_bridge.launch

If everything is okay, you should see the Kinect v2 point cloud in a RViz:

 rosrun rviz rviz

Set the Global Options/Fixed Frame as:

 /kinect2_head_rgb_optical_frame

N.B.: If the fixed frame combo box only shows map topic, and does not allow selection of anything else, manually copy and paste the text kinect2_head_rgb_optical_frame over map, and then hit enter. If this fixed frame is not set, the points will not display.

Add a PointCloud2 visualization, and set the topic as:

 /kinect2_head/depth_lowres/points

You can test the Point Cloud frame rate with:

 rostopic hz /kinect2_head/depth_lowres/points 

7.2. Test Single-Camera Tracking:

Before continuing, if your roslaunch kinect2_bridge kinect2_bridge.launch process is still running, hit ctrl-c in that window, and wait for it to quit before continuing.

 roslaunch tracking detection_and_tracking_kinect2.launch

N.B.: This has been tested with Ubuntu kernel 3.13.0-37-generic. There were some USB3 issues with previous versions of the kernel.

N.B.2: After every reboot, one must run step 6.4 to reset permissions and allow Kinect 2 to work for detection.

8. Configure time synchronization on all hosts.

OpenPtrack requires times synchronization to a millisecond or better. To enable time synchronization, follow this guide.

After initial installation, to periodically update to the latest release, follow these steps.