Clone this repository if you want to build Ubitrack from the source code.
All other repositories are added as submodules to this repository
###1. Required tools In order to build ubitrack the following tools have to be installed:
-
Git
-
C++ Compiler like gcc or MSVC
-
Python (at least Version 2.7, e.g. PythonXY )
-
cmake (only required for building OpenCV for Android)
You can compile Ubitrack for Windows, Linux and Android on the appropriate system. However, the cross-compilation for Android is only possible on Linux. If there are any differences to the compilation for Linux, they are explained in the appropriate section.
###1.1 How to install build-tools
Ubitrack-Compilation for Windows:
Download PythonXY, Scons and Git from the official website, install them and make sure they are working and added to your system-path by opening a console and typing:
scons
Windows should respond in the following way:
scons: *** No SConstruct file found.
File "C:\Program Files (x86)\Python 2.7\Scripts\..\Lib\site-packages\scons-2.3.0\SCons\Script\Main.py", line 905, in _main
Doing the similar with git
git --version
sould be answered with something like:
git version 1.8.5.2.msysgit.0
Ubitrack-Compilation for Linux/Android on Linux
Ubuntu is shipped with gcc and python pre-installed, to install Git and Scons, open up a terminal and type:
sudo apt-get install git scons
Ubitrack-Compilation for Android on Linux
Android-NDK-Toolchain:
In addition to scons, for the compilation of Ubitrack for Android we need to compile an Android standalone-toolchain. Therefore, you have to download the Android-NDK. This HowTo will use a certain repository-files for the Boost-for-Android compilation, which needs the Android-NDK-Version 8e. If you are able to port Boost to Android on your own, feel free to download the newest Android-NDK, otherwise please download Android-NDK-Version-r8e-64-bit or Android-NDK-Version-r8e-32-bit according to your Linux architecture. Afterwards, extract the downloaded archive file in a folder of your choice, open up a terminal and change to appropriate directory where you extracted the android-ndk. In case of ndk-r8e:
cd ~/Downloads/android-ndk-r8e/
Afterwards, just run the sh-script in the following way which will install the standalone-toolchain of the defined Android-API level (--platform=android-9) in the folder of your choice (install-dir=/home/<username>/android/android-ndk-toolchain): For a 64-bit architecture run the following script:
sh build/tools/make-standalone-toolchain.sh --platform=android-9 --install-dir=$HOME/android/android-ndk-toolchain --system=linux-x86_64
And for a 32-bit architecture:
sh build/tools/make-standalone-toolchain.sh --platform=android-9 --install-dir=$HOME/android/android-ndk-toolchain
###2. Setting up buildenvironment
With terminal or command of your operating system, change your current directory to the folder where you want to clone ubitrack and run:
git clone https://github.com/Ubitrack/buildenvironment.git ubitrack
cd ubitrack
###3. Adding additional components as submodules There are several components represented by repositories which can be added as submodules to ubitrack. These components have to be placed in the <ubitrack>/modules folder. Usually you will need utcore, utvision, utdataflow, utfacade, utcomponents and utvisioncomponents:
| Component | Description | Repository |
|---|---|---|
| utvisualization | contains a standalone 3D rendering module. Mostly for quick visualizations and debugging | https://github.com/Ubitrack/utvisualization.git |
| utvisioncomponents | contains algorithms working on (mostly) camera images. | https://github.com/Ubitrack/utvisioncomponents.git |
| utfacade | contains frontend adapters for ubitrack dataflow networks. Also contains the utConsole. | https://github.com/Ubitrack/utfacade.git |
| utdataflow | contains the dataflow network and related graph methods. | https://github.com/Ubitrack/utdataflow.git |
| utcore | contains fundamental datastructures and algorithms. Needed by all other modules. | https://github.com/Ubitrack/utcore.git |
| utcomponents | contains basic dataflow modules. These cover most common tracking and registration cases. | https://github.com/Ubitrack/utvisioncomponents.git |
| directshow | contains MS Windows specific directshow framegrabber | https://github.com/Ubitrack/directshow.git |
| buildenvironment | contains general build scripts | https://github.com/Ubitrack/utvisualization.git |
git submodule add https://github.com/Ubitrack/utcore.git modules/utcore
####3.b Automized adding submodules <scripts that will do that for you in {YourDirectory}/misc/setup/[windows|linux]>
Ubitrack-Compilation for Windows:
For Windows open a Git- or Command-Console, change to the <ubitrack> folder and execute
misc\setup\windows\addStandardModules.bat
Ubitrack-Compilation for Linux/Android on Linux:
In order to add all components, just execute the following script for linux:
sh misc/setup/linux/addStandardModules.sh
###4. Configure the needed libraries Ubitrack is based on the following libraries:
Mandatory
- Boost (> 1.35)
Optional
These libraries have to be downloaded and configured. In order to do that, there exist three possible ways, the first one described in 4.1 offers ready-to-use download packages and uses the Ubitrack library finder. The Ubitrack library finder needs all the libraries in one specific folder. 4.2 configures the libraries by the command line and in 4.3 each possible configuration and path is manually set by editing a textfile.
####4.1 Make use of the Ubitrack library finder
Ubitrack is able to find libraries which have a specific folder structure that looks like this:
<LibrariesDirectory>/[linux|windows|android]_[x64|x86]/LibraryName/[bin|include|lib|lib_debug].
An example for windows would be:
external_libraries\windows_x64\boost
external_libraries\windows_x64\boost\include
external_libraries\windows_x64\boost\lib
external_libraries\windows_x64\boost\lib_debug
The Ubitrack library finder will take all library files in the "lib" and "lib_debug" folders and link to their paths. So you have to separate the release and debug libraries in different folders.
Ubitrack-Compilation for Windows:
If you are running Windows with Visual Studio 10, you can download the following ready-to-use library packages and extract them e.g. in the <ubitrack> folder:
This results in a structure that should look like this:
<ubitrack>\external_libraries\windows_x64\
<ubitrack>\external_libraries\windows_x86\
However, if you have a different version to Visual Studio 10, you can use Lapack, OpenCV and Freeglut from the archive file above. For Visual Studio, have a look at the prebuilds which are can be downloaded from the official Boost-Website. Alternatively, you can have a look at PointClouds. After you have downloaded and extracted Boost, you have to copy the header, library and dlls to the approproate directories. In case of Windows 64-bit, Boost 1.5.5 and Visual Studio 11.0, this can be done in the following way:
xcopy "C:\boost_1_55_0\boost" "<ubitrack>\external_libraries\windows_x64\boost\include\boost\" /S /E
xcopy "C:\boost_1_55_0\lib64-msvc-11.0\*.dll" "<ubitrack>\external_libraries\windows_x64\boost\bin\" /S /I /Y
xcopy "C:\boost_1_55_0\lib64-msvc-11.0\*-vc110-mt-1_55.lib" "<ubitrack>\external_libraries\windows_x64\boost\lib\" /S /I /Y
xcopy "C:\boost_1_55_0\lib64-msvc-11.0\*-vc110-mt-gd-1_55.lib" "<ubitrack>\external_libraries\windows_x64\boost\lib_debug\" /S /I /Y
Ubitrack-Compilation for Linux on Linux:
If you have not already done, yet, you can download and install BOOST, LAPACK and Freeglut with the terminal:
sudo apt-get update
sudo apt-get install libboost-all-dev libblas-dev liblapack-dev libopencv-dev freeglut3-dev
As these libraries are installed to the /usr/lib/ folder, an easy way to result in the Ubitrack library finder required folder structure is to link from the external_libraries folder to the /usr/local/include/. This example shows how it is done for linux_x64-architecture:
cd /path/to/external_libraries
mkdir -p linux_x64/boost/lib/
mkdir -p linux_x64/boost/include/
//linking for boost
ln -s /usr/lib/libboost_filesystem.* boost/include/lib/
ln -s /usr/lib/libboost_program_options.* boost/include/lib/
ln -s /usr/lib/libboost_regex.* boost/include/lib/
ln -s /usr/lib/libboost_serialization.* boost/include/lib/
ln -s /usr/lib/libboost_system.* boost/include/lib/
ln -s /usr/lib/libboost_thread.* boost/include/lib/
ln -s /usr/include/boost boost/include/include/
//linking for lapack
mkdir -p lapack/lib
ln -s /usr/lib/lapack/liblapack.a lapack/lib/
ln -s /usr/lib/lapack/liblapack.so lapack/lib/
ln -s /usr/lib/lapack/libblas.a lapack/lib/
ln -s /usr/lib/lapack/llibblas.so lapack/lib/
//linking for freeglut
mkdir -p glut/lib
mkdir -p glut/include
ln -s /usr/lib/x86_64-linux-gnu/libglut* glut/lib/
ln -s /usr/include/GL/ glut/include/
For OpenCV have a look at the official Guide OpenCV Installation in Linux or a special Ubuntu-Guide OpenCV on Ubuntu. After that, the libraries and includes can be linked to the external_libraries folder:
//linking for opencv
mkdir -p opencv/lib
mkdir -p opencv/include
Ubitrack-Compilation for Android on Linux:
In order to build Ubitrack for Android, you have to place BOOST, LAPACK and OpenCV for Android in the external_libraries\linux_android folder.
BOOST for Android:
Because there is no official BOOST for Android available, we will use a build-script from a certain repository which does porting for us. Therefore, clone the repository in a folder of your choice and run the build-android.sh script with the path to the extracted android-ndk-8e as argument. The script will download and compile boost.
cd ~/Downloads/
git clone https://github.com/inetic/Boost-for-Android.git
cd Boost-for-Android/
sh build-android.sh ~/Downloads/android-ndk-r8e/ --with-libraries=date_time,filesystem,iostreams,program_options,regex,serialization,signals,system,thread
After the successful compilation, you will find the Boost-libraries in the <boost>\build\lib\ subfolder and header files in the <boost>\build\include\boost-<boost-version>\ -folder. Then, create the external_libraries\linux_android\boost "include" and "lib"-folder:
mkdir -p linux_android/boost/include
mkdir -p linux_android/boost/lib
Afterwards link or copy the files to your these new folders:
<cp -r build/lib /path/to/external_libraries/linux_android/boost/>
//change to the directory where Boost have been downloaded
cd ~/Downloads/Boost-for-Android/
//copy and rename libraries to fit: libboost_%libname%-mt.a
cp -r build/lib/libboost_date_time-gcc-mt-1_53.a /path/to/external_libraries/linux_android/boost/lib/libboost_time-mt.a
cp -r build/lib/libboost_filesystem-gcc-mt-1_53.a /path/to/external_libraries/linux_android/boost/lib/libboost_filesystem-mt.a
cp -r build/lib/libboost_iostreams-gcc-mt-1_53.a /path/to/external_libraries/linux_android/boost/lib/libboost_iostreams-mt.a
cp -r build/lib/libboost_program_options-gcc-mt-1_53.a /path/to/external_libraries/linux_android/boost/lib/libboost_program_options-mt.a
cp -r build/lib/libboost_regex-gcc-mt-1_53.a /path/to/external_libraries/linux_android/boost/lib/libboost_regex-mt.a
cp -r build/lib/libboost_serialization-gcc-mt-1_53.a /path/to/external_libraries/linux_android/boost/lib/libboost_serialization-mt.a
cp -r build/lib/libboost_signals-gcc-mt-1_53.a /path/to/external_libraries/linux_android/boost/lib/libboost_signals-mt.a
cp -r build/lib/libboost_system-gcc-mt-1_53.a /path/to/external_libraries/linux_android/boost/lib/libboost_system-mt.a
cp -r build/lib/libboost_thread-gcc-mt-1_53.a /path/to/external_libraries/linux_android/boost/lib/libboost_thread-mt.a
cp -r build/lib/libboost_wserialization-gcc-mt-1_53.a /path/to/external_libraries/linux_android/boost/lib/libboost_wserialization-mt.a
cp -r build/include/boost-1_53/* /path/to/external_libraries/linux_android/boost/include/
LAPACK for Android:
Similar to the compilation of Boost for Android, for Lapack we need to clone a certain repository. After that, we build the Android-library files with the previously downloaded Android-NDK which was downloaded to the ~/Downloads/android-ndk-r8e/ folder.
cd ~/Downloads/
git clone https://github.com/simonlynen/android_libs.git
//android_libs/lapack folder was created
cd android-ndk-r8e/
//tells the ndk where to look for the lapack-project we want to compile
export NDK_PROJECT_PATH=~/Downloads/android_libs/lapack/
./ndk-build
After that, we can copy or link the Lapack-libraries from the android_libs/lapack/obj/local/armeabi-v7a folder to the created external_libraries/android/lapack/bin directory.
cd /path/to/external_libraries/
mkdir -p android/lapack/lib/
cp -r ~/Downloads/android_libs/lapack/obj/local/armeabi-v7a/*.a android/lapack/lib/
OpenCV for Android:
The last library we need for the Ubitrack for Android is OpenCV for Android. Therefore exist two possibilities: In a. the prebuilds which can be downloaded from the official OpenCV webpage are used and b. describes how to compile OpenCV4Android from source and and which of the build libraries have to be copied.
a. Using OpenCV for Android prebuilds
Download the precompiled libraries from the official OpenCV-Website. Extract the downloaded zip-archive on a destination of your choice (here in ~/Downloads) and copy the libraries and include files from the appropriate directory to the external_libraries/android/opencv/ folder:
cd path/to/external_libraries/
mkdir -p linux_android/opencv/lib/
mkdir -p linux_android/opencv/include/
cp -r ~/Downloads/OpenCV-2.4.8-android-sdk/sdk/native/libs/armeabi-v7a/* linux_android/opencv/lib/
cp -r ~/Downloads/OpenCV-2.4.8-android-sdk/sdk/native/3rdparty/libs/armeabi-v7a/* linux_android/opencv/lib/
cp -r ~/Downloads/OpenCV-2.4.8-android-sdk/sdk/native/jni/include/* linux_android/opencv/include/
b. Building OpenCV for Android
Similar to the previous library builds, you have to clone and compile OpenCV4Android in the following way:
NOTE: For further information or if any problems occur have a look at the official Building OpenCV4Android-Guide.
cd ~/Downloads/
git clone git://code.opencv.org/opencv.git
//opencv folder was created
//path to the previously compiled android-standalone-toolchain, here ~/android/android-standalone-toolchain
export ANDROID_STANDALONE_TOOLCHAIN=~/android/android-ndk-toolchain/
cd opencv/platforms
sh ./scripts/cmake_android_arm.sh
cd build_android_arm
make -j2
make install
cd path/to/external_libraries/
mkdir -p linux_android/opencv/lib/
mkdir -p linux_android/opencv/include/
cp -r ~/Downloads/opencv/platforms/build_android_arm/install/sdk/native/libs/armeabi-v7a/* linux_android/opencv/lib/
cp -r ~/Downloads/opencv/platforms/build_android_arm/install/sdk/native/3rdparty/libs/armeabi-v7a/* linux_android/opencv/lib/
cp -r ~/Downloads/opencv/platforms/build_android_arm/install/sdk/native/jni/include/* linux_android/opencv/include/
<cp -r ~/Downloads/OpenCV-2.4.8-android-sdk/sdk/native/libs/armeabi-v7a/* android/opencv/lib/> <cp -r ~/Downloads/OpenCV-2.4.8-android-sdk/sdk/native/jni/include/* android/opencv/include/>
Ubitrack-Compilation for Windows/Android/Linux:
If you have placed the libraries in a different folder to <ubitrack>/external_libraries, you have to specify the path where Ubitrack has to search for the libraries. This can be done by executing the following command in the <ubitrack> folder:
Windows example:
scons EXTERNAL_LIBRARIES=/home/user/path/to/all/external/libraries/
Linux example:
scons EXTERNAL_LIBRARIES=/home/user/path/to/all/external/libraries/
Alternatively, you can execute
scons
and afterwards add the following line manually to the <ubitrack>/config.cache file: Note: The first time this document may be empty.
Windows example:
EXTERNAL_LIBRARIES = '/home/user/path/to/all/external_libraries/'
Linux example:
EXTERNAL_LIBRARIES = '/home/user/path/to/all/external_libraries/'
Taking similar steps, you can easily extend Ubitrack by additional libraries for your own need.
####4.2 Configure the libraries using command line options and library finder
In this option, the library configuration is done by appending parameters to a scons call similar to the previous section. This method gives you the ability to define your own library-folder structure as you may already have installed some of the libraries in different directories. Just like in the previous section, you can write the parameters into a <ubitrack>\config.cache document, alternatively. For how to get/install the library files, have a look at section 4.1.
The basic syntax for these parameters looks like this:
{LIBNAME}_{PARAMERTER}_{PLATFORM}_{CONFIGURATION}
Examples:
{LIBNAME}:
- BOOST, OPENCV, LAPACK, GLUT
{PARAMETER}:
- INCLUDEPATH (path to include files)
- LIBPATH (path to library files)
- LIBS (comma separated list of library files to link against)
- DEFINES (C++ defines passed to the compiler )
{PLATFORM}:
- x64 (64bit)
- x86 (32bit)
- android (armeabi-v7a)
{CONFIGURATION}:
- RELEASE (in this case empty)
- DEBUG
Full Examples for library configurations by a scons call:
scons BOOST_LIBPATH=/path/to/boost/lib
scons BOOST_LIBPATH_DEBUG=/path/to/boost/lib_debug
scons BOOST_LIBPATH_X86_DEBUG=/path/to/boost/x64/debug
scons BOOST_LIBPATH_ANDROID=/path/to/boost/android/lib
scons OPENCV_LIBS="opencv_stitching242.lib, opencv_legacy242.lib"
####4.3 Set everything by hand
Run the scons command once. After that the library configurations are stored in <ubitrack>/config/configStorage. Edit the files and set Include/Library Paths and Libraries to link against.
Set havelib to true and add "HAVE_{LIBNAME}" to CPPDEFINES:
havelib = true
cppdefines = ["HAVE_LAPACK"]
Example:
[x64_release]
havelib = true
cpppath = ["C:\\Libraries\\freeglut\\freeglut-2.8.0\\include"]
libpath = ["C:\\Libraries\\freeglut\\freeglut-2.8.0\\lib\\x64"]
libs = ["freeglut.lib"]
cppdefines = ["HAVE_GLUT"]
###5. Compile Ubitrack
For the compilation of Ubitrack for Windows/Linux run:
scons install-all
For the compilation of Ubitrack for Android you have to specify the android-platform once. This configuration will stay until it is changed by e.g. PLATFORM=x64.
scons PLATFORM=android
scons install-all
Speed up the build process for parallel builds:
scons install-all -j{NumProcessors}
Clean the build by calling:
scons -c
You can see all command line parameters by calling:
scons -h
Create a Visual Studio Project:
scons vcproj