-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathREADME.md~
483 lines (294 loc) · 21.5 KB
/
README.md~
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
buildenvironment
================
Clone this repository if you want to build Ubitrack from the source code.
All other repositories are added as submodules to this repository
How to build Ubitrack
---------------------
###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](http://code.google.com/p/pythonxy/) )
- [Scons](http://www.scons.org/)
- 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](http://code.google.com/p/pythonxy/), [Scons](http://www.scons.org/) and [Git](http://git-scm.com/download/win) 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](http://developer.android.com/tools/sdk/ndk/index.html), otherwise please download [Android-NDK-Version-r8e-64-bit](http://dl.google.com/android/ndk/android-ndk-r8e-linux-x86_64.tar.bz2) or [Android-NDK-Version-r8e-32-bit](http://dl.google.com/android/ndk/android-ndk-r8e-linux-x86.tar.bz2) 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
Android-SDK:
In addition to the android-ndk-toolchain, we need the android-sdk for the compilation of Lapack which is described later on. Download and extract the [Android-SDK](http://developer.android.com/sdk/index.html) to a folder of your choice e.g. /home/\<username\>/android/.
###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:
<table>
<tr>
<th>Component</th><th>Description</th><th>Repository</th>
</tr>
<tr>
<td>utvisualization</td><td>contains a standalone 3D rendering module. Mostly for quick visualizations and debugging</td><td>https://github.com/Ubitrack/utvisualization.git</td>
</tr>
<tr>
<td>utvisioncomponents</td><td>contains algorithms working on (mostly) camera images.</td><td>https://github.com/Ubitrack/utvisioncomponents.git</td>
</tr>
<tr>
<td>utfacade</td><td>contains frontend adapters for ubitrack dataflow networks. Also contains the utConsole.</td><td>https://github.com/Ubitrack/utfacade.git</td>
</tr>
<tr>
<td>utdataflow</td><td>contains the dataflow network and related graph methods.</td><td>https://github.com/Ubitrack/utdataflow.git</td>
</tr>
<tr>
<td>utcore</td><td>contains fundamental datastructures and algorithms. Needed by all other modules.</td><td>https://github.com/Ubitrack/utcore.git</td>
</tr>
<tr>
<td>utcomponents</td><td>contains basic dataflow modules. These cover most common tracking and registration cases.</td><td>https://github.com/Ubitrack/utvisioncomponents.git</td>
</tr>
<tr>
<td>directshow</td><td>contains MS Windows specific directshow framegrabber</td><td>https://github.com/Ubitrack/directshow.git</td>
</tr>
<tr>
<td>buildenvironment</td><td> contains general build scripts </td><td>https://github.com/Ubitrack/utvisualization.git</td>
</tr>
</table>
You can pick the submodules manually or alternatively add all existing components at once by executing a script.
####3.a Manually adding submodules
This example will create the \<ubitrack\>/module/utcore directory and add utcore as submodule.
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> 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](http://www.boost.org/) (> 1.35)
Optional
- Lapack
- [OpenCV](http://opencv.org/)
- Glut (or [Freeglut](http://freeglut.sourceforge.net/))
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:
- [Minimal (Boost and Lapack)](http://campar.in.tum.de/personal/pankratz/UbiTrack/external_libraries_min.zip)
- [All (Boost,Lapack, OpenCV, Freeglut)](http://campar.in.tum.de/personal/pankratz/UbiTrack/external_libraries_all.zip)
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 older versions of Visual Studio, have a look at the prebuilds which are can be downloaded at [PointClouds](http://pointclouds.org/downloads/windows.html) and copy the library files in the appropriate directories as shown after the explanation of the Boost-Build process. For Visual Studio 11 you have to compile Boost on your own:
Therefore, downloaded [Boost](http://www.boost.org/) and extract it in a folder of your choice, e.g. C:\Boost.
Start your "Developer Command Prompt for VS" and change to the Boost-Library location:
cd C:\Boost\boost_1_55_0
//build Boost in the current directory
bootstrap
b2 toolset=msvc --build-type=complete stage
After the compilation, you have to copy the header, library and dlls to the approproate directories. In case of Windows 64-bit, this will result in the folder-structure:
<ubitrack>\external_libraries\windows_x86\bin\*.dll
<ubitrack>\external_libraries\windows_x86\include\boost\*.hpp
<ubitrack>\external_libraries\windows_x86\lib\*.lib
<ubitrack>\external_libraries\windows_x86\lib_debug\*-gd-*.lib
NOTE: For further information or if any problems occur have a look at the official guide which can be found at C:\Boost\boost_1_55_0\more\getting_started.html
**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](http://docs.opencv.org/doc/tutorials/introduction/linux_install/linux_install.html) or a special Ubuntu-Guide [OpenCV on Ubuntu](https://help.ubuntu.com/community/OpenCV). 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](http://opencv.org/downloads.html). 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](http://code.opencv.org/projects/opencv/wiki/Building_OpenCV4Android_from_trunk).
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:**
<TODO>
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:**
<TODO>
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 with 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 paramerters 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
add "HAVE_{LIBNAME}" to CPPDEFINES
**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