1 .. _chapter-building: 2 3 ===================== 4 Building Ceres Solver 5 ===================== 6 7 Stable Ceres Solver releases are available for download at 8 `code.google.com <http://code.google.com/p/ceres-solver/>`_. For the 9 more adventurous, the git repository is hosted on `Gerrit 10 <https://ceres-solver-review.googlesource.com/>`_. 11 12 .. _section-dependencies: 13 14 Dependencies 15 ============ 16 17 Ceres relies on a number of open source libraries, some of which are 18 optional. For details on customizing the build process, see 19 :ref:`section-customizing` . 20 21 1. `CMake <http://www.cmake.org>`_ is a cross platform build 22 system. Ceres needs a relatively recent version of CMake (version 23 2.8.0 or better). 24 25 2. `eigen3 <http://eigen.tuxfamily.org/index.php?title=Main_Page>`_ is 26 used for doing all the low level matrix and linear algebra operations. 27 28 3. `google-glog <http://code.google.com/p/google-glog>`_ is 29 used for error checking and logging. Ceres needs glog version 0.3.1 or 30 later. Version 0.3 (which ships with Fedora 16) has a namespace bug 31 which prevents Ceres from building. 32 33 4. `gflags <http://code.google.com/p/gflags>`_ is a library for 34 processing command line flags. It is used by some of the examples and 35 tests. While it is not strictly necessary to build the library, we 36 strongly recommend building the library with gflags. 37 38 39 5. `SuiteSparse 40 <http://www.cise.ufl.edu/research/sparse/SuiteSparse/>`_ is used for 41 sparse matrix analysis, ordering and factorization. In particular 42 Ceres uses the AMD, CAMD, COLAMD and CHOLMOD libraries. This is an optional 43 dependency. 44 45 6. `CXSparse <http://www.cise.ufl.edu/research/sparse/CXSparse/>`_ is 46 a sparse matrix library similar in scope to ``SuiteSparse`` but with 47 no dependencies on ``LAPACK`` and ``BLAS``. This makes for a simpler 48 build process and a smaller binary. The simplicity comes at a cost -- 49 for all but the most trivial matrices, ``SuiteSparse`` is 50 significantly faster than ``CXSparse``. 51 52 7. `BLAS <http://www.netlib.org/blas/>`_ and `LAPACK 53 <http://www.netlib.org/lapack/>`_ routines are needed by 54 SuiteSparse. We recommend `ATLAS 55 <http://math-atlas.sourceforge.net/>`_, which includes BLAS and LAPACK 56 routines. It is also possible to use `OpenBLAS 57 <https://github.com/xianyi/OpenBLAS>`_ . However, one needs to be 58 careful to `turn off the threading 59 <https://github.com/xianyi/OpenBLAS/wiki/faq#wiki-multi-threaded>`_ 60 inside ``OpenBLAS`` as it conflicts with use of threads in Ceres. 61 62 .. _section-linux: 63 64 Building on Linux 65 ================= 66 We will use `Ubuntu <http://www.ubuntu.com>`_ as our example 67 platform. Start by installing all the dependencies. 68 69 .. code-block:: bash 70 71 # CMake 72 sudo apt-get install cmake 73 # gflags 74 tar -xvzf gflags-2.0.tar.gz 75 cd gflags-2.0 76 ./configure --prefix=/usr/local 77 make 78 sudo make install. 79 # google-glog must be configured to use the previously installed gflags 80 tar -xvzf glog-0.3.2.tar.gz 81 cd glog-0.3.2 82 ./configure --with-gflags=/usr/local/ 83 make 84 sudo make install 85 # BLAS & LAPACK 86 sudo apt-get install libatlas-base-dev 87 # Eigen3 88 sudo apt-get install libeigen3-dev 89 # SuiteSparse and CXSparse 90 sudo apt-get install libsuitesparse-dev 91 92 We are now ready to build and test Ceres. 93 94 .. code-block:: bash 95 96 tar zxf ceres-solver-1.7.0.tar.gz 97 mkdir ceres-bin 98 cd ceres-bin 99 cmake ../ceres-solver-1.7.0 100 make -j3 101 make test 102 103 You can also try running the command line bundling application with one of the 104 included problems, which comes from the University of Washington's BAL 105 dataset [Agarwal]_. 106 107 .. code-block:: bash 108 109 bin/simple_bundle_adjuster ../ceres-solver-1.7.0/data/problem-16-22106-pre.txt 110 111 This runs Ceres for a maximum of 10 iterations using the 112 ``DENSE_SCHUR`` linear solver. The output should look something like 113 this. 114 115 .. code-block:: bash 116 117 0: f: 4.185660e+06 d: 0.00e+00 g: 1.09e+08 h: 0.00e+00 rho: 0.00e+00 mu: 1.00e+04 li: 0 it: 1.16e-01 tt: 3.39e-01 118 1: f: 1.062590e+05 d: 4.08e+06 g: 8.99e+06 h: 5.36e+02 rho: 9.82e-01 mu: 3.00e+04 li: 1 it: 3.90e-01 tt: 7.29e-01 119 2: f: 4.992817e+04 d: 5.63e+04 g: 8.32e+06 h: 3.19e+02 rho: 6.52e-01 mu: 3.09e+04 li: 1 it: 3.52e-01 tt: 1.08e+00 120 3: f: 1.899774e+04 d: 3.09e+04 g: 1.60e+06 h: 1.24e+02 rho: 9.77e-01 mu: 9.26e+04 li: 1 it: 3.60e-01 tt: 1.44e+00 121 4: f: 1.808729e+04 d: 9.10e+02 g: 3.97e+05 h: 6.39e+01 rho: 9.51e-01 mu: 2.78e+05 li: 1 it: 3.62e-01 tt: 1.80e+00 122 5: f: 1.803399e+04 d: 5.33e+01 g: 1.48e+04 h: 1.23e+01 rho: 9.99e-01 mu: 8.33e+05 li: 1 it: 3.54e-01 tt: 2.16e+00 123 6: f: 1.803390e+04 d: 9.02e-02 g: 6.35e+01 h: 8.00e-01 rho: 1.00e+00 mu: 2.50e+06 li: 1 it: 3.59e-01 tt: 2.52e+00 124 125 Ceres Solver Report 126 ------------------- 127 Original Reduced 128 Parameter blocks 22122 22122 129 Parameters 66462 66462 130 Residual blocks 83718 83718 131 Residual 167436 167436 132 Trust Region Strategy LEVENBERG_MARQUARDT 133 134 Given Used 135 Linear solver DENSE_SCHUR DENSE_SCHUR 136 Preconditioner N/A N/A 137 Threads: 1 1 138 Linear solver threads 1 1 139 Linear solver ordering AUTOMATIC 22106,16 140 141 Cost: 142 Initial 4.185660e+06 143 Final 1.803390e+04 144 Change 4.167626e+06 145 146 Number of iterations: 147 Successful 6 148 Unsuccessful 0 149 Total 6 150 151 Time (in seconds): 152 Preprocessor 2.229e-01 153 154 Evaluator::Residuals 7.438e-02 155 Evaluator::Jacobians 6.790e-01 156 Linear Solver 1.681e+00 157 Minimizer 2.547e+00 158 159 Postprocessor 1.920e-02 160 Total 2.823e+00 161 162 Termination: FUNCTION_TOLERANCE 163 164 .. section-osx: 165 166 Building on Mac OS X 167 ==================== 168 169 On OS X, we recommend using the `homebrew 170 <http://mxcl.github.com/homebrew/>`_ package manager to install the 171 dependencies. There is no need to install ``BLAS`` or ``LAPACK`` 172 separately as OS X ships with optimized ``BLAS`` and ``LAPACK`` 173 routines as part of the `vecLib 174 <https://developer.apple.com/library/mac/#documentation/Performance/Conceptual/vecLib/Reference/reference.html>`_ 175 framework. 176 177 .. code-block:: bash 178 179 # CMake 180 brew install cmake 181 # google-glog and gflags 182 brew install glog 183 # Eigen3 184 brew install eigen 185 # SuiteSparse and CXSparse 186 brew install suite-sparse 187 188 189 We are now ready to build and test Ceres. 190 191 .. code-block:: bash 192 193 tar zxf ceres-solver-1.7.0.tar.gz 194 mkdir ceres-bin 195 cd ceres-bin 196 cmake ../ceres-solver-1.7.0 197 make -j3 198 make test 199 200 201 Like the Linux build, you should now be able to run 202 ``bin/simple_bundle_adjuster``. 203 204 .. _section-windows: 205 206 Building on Windows with Visual Studio 207 ====================================== 208 209 On Windows, we support building with Visual Studio 2010 or newer. Note 210 that the Windows port is less featureful and less tested than the 211 Linux or Mac OS X versions due to the unavailability of SuiteSparse 212 and ``CXSparse``. Building is also more involved since there is no 213 automated way to install the dependencies. 214 215 #. Make a toplevel directory for deps & build & src somewhere: ``ceres/`` 216 #. Get dependencies; unpack them as subdirectories in ``ceres/`` 217 (``ceres/eigen``, ``ceres/glog``, etc) 218 219 #. ``Eigen`` 3.1 (needed on Windows; 3.0.x will not work). There is 220 no need to build anything; just unpack the source tarball. 221 222 #. ``google-glog`` Open up the Visual Studio solution and build it. 223 #. ``gflags`` Open up the Visual Studio solution and build it. 224 225 #. Unpack the Ceres tarball into ``ceres``. For the tarball, you 226 should get a directory inside ``ceres`` similar to 227 ``ceres-solver-1.3.0``. Alternately, checkout Ceres via ``git`` to 228 get ``ceres-solver.git`` inside ``ceres``. 229 230 #. Install ``CMake``, 231 232 #. Make a dir ``ceres/ceres-bin`` (for an out-of-tree build) 233 234 #. Run ``CMake``; select the ``ceres-solver-X.Y.Z`` or 235 ``ceres-solver.git`` directory for the CMake file. Then select the 236 ``ceres-bin`` for the build dir. 237 238 #. Try running ``Configure``. It won't work. It'll show a bunch of options. 239 You'll need to set: 240 241 #. ``GLOG_INCLUDE`` 242 #. ``GLOG_LIB`` 243 #. ``GFLAGS_LIB`` 244 #. ``GFLAGS_INCLUDE`` 245 246 to the appropriate place where you unpacked/built them. 247 248 #. You may have to tweak some more settings to generate a MSVC 249 project. After each adjustment, try pressing Configure & Generate 250 until it generates successfully. 251 252 #. Open the solution and build it in MSVC 253 254 255 To run the tests, select the ``RUN_TESTS`` target and hit **Build 256 RUN_TESTS** from the build menu. 257 258 Like the Linux build, you should now be able to run ``bin/simple_bundle_adjuster``. 259 260 Notes: 261 262 #. The default build is Debug; consider switching it to release mode. 263 #. Currently ``system_test`` is not working properly. 264 #. Building Ceres as a DLL is not supported; patches welcome. 265 #. CMake puts the resulting test binaries in ``ceres-bin/examples/Debug`` 266 by default. 267 #. The solvers supported on Windows are ``DENSE_QR``, ``DENSE_SCHUR``, 268 ``CGNR``, and ``ITERATIVE_SCHUR``. 269 #. We're looking for someone to work with upstream ``SuiteSparse`` to 270 port their build system to something sane like ``CMake``, and get a 271 supported Windows port. 272 273 274 .. _section-android: 275 276 Building on Android 277 =================== 278 279 280 Download the ``Android NDK``. Run ``ndk-build`` from inside the 281 ``jni`` directory. Use the ``libceres.a`` that gets created. 282 283 .. _section-customizing: 284 285 Customizing the build 286 ===================== 287 288 It is possible to reduce the libraries needed to build Ceres and 289 customize the build process by passing appropriate flags to 290 ``CMake``. Use these flags only if you really know what you are doing. 291 292 #. ``-DSUITESPARSE=OFF``: By default, Ceres will link to 293 ``SuiteSparse`` if all its dependencies are present. Use this flag 294 to build Ceres without ``SuiteSparse``. This will also disable 295 dependency checking for ``LAPACK`` and ``BLAS``. This will reduce 296 Ceres' dependencies down to ``Eigen``, ``gflags`` and 297 ``google-glog``. 298 299 #. ``-DCXSPARSE=OFF``: By default, Ceres will link to ``CXSparse`` if 300 all its dependencies are present. Use this flag to builds Ceres 301 without ``CXSparse``. This will reduce Ceres' dependencies down to 302 ``Eigen``, ``gflags`` and ``google-glog``. 303 304 #. ``-DGFLAGS=OFF``: Use this flag to build Ceres without 305 ``gflags``. This will also prevent some of the example code from 306 building. 307 308 #. ``-DSCHUR_SPECIALIZATIONS=OFF``: If you are concerned about binary 309 size/compilation time over some small (10-20%) performance gains in 310 the ``SPARSE_SCHUR`` solver, you can disable some of the template 311 specializations by using this flag. 312 313 #. ``-DLINE_SEARCH_MINIMIZER=OFF``: The line search based minimizer is 314 mostly suitable for large scale optimization problems, or when sparse 315 linear algebra libraries are not available. You can further save on 316 some compile time and binary size by using this flag. 317 318 #. ``-DOPENMP=OFF``: On certain platforms like Android, 319 multi-threading with ``OpenMP`` is not supported. Use this flag to 320 disable multithreading. 321 322 #. ``-DBUILD_DOCUMENTATION=ON``: Use this flag to enable building the 323 documentation. In addition, ``make ceres_docs`` can be used to 324 build only the documentation. 325 326 .. _section-using-ceres: 327 328 Using Ceres with CMake 329 ====================== 330 331 Once the library is installed with ``make install``, it is possible to 332 use CMake with `FIND_PACKAGE() 333 <http://www.cmake.org/cmake/help/v2.8.10/cmake.html#command:find_package>`_ 334 in order to compile **user code** against Ceres. For example, for 335 `examples/helloworld.cc 336 <https://ceres-solver.googlesource.com/ceres-solver/+/master/examples/helloworld.cc>`_ 337 the following CMakeList.txt can be used: 338 339 .. code-block:: cmake 340 341 CMAKE_MINIMUM_REQUIRED(VERSION 2.8) 342 343 PROJECT(helloworld) 344 345 FIND_PACKAGE(Ceres REQUIRED) 346 INCLUDE_DIRECTORIES(${CERES_INCLUDES}) 347 348 # helloworld 349 ADD_EXECUTABLE(helloworld helloworld.cc) 350 TARGET_LINK_LIBRARIES(helloworld ${CERES_LIBRARIES}) 351 352 Specify Ceres version 353 --------------------- 354 355 Additionally, when CMake has found Ceres it can check the package 356 version, if it has been specified in the `FIND_PACKAGE() 357 <http://www.cmake.org/cmake/help/v2.8.10/cmake.html#command:find_package>`_ 358 call. For example: 359 360 .. code-block:: cmake 361 362 FIND_PACKAGE(Ceres 1.2.3 REQUIRED) 363 364 The version is an optional argument. 365 366 Local installations 367 ------------------- 368 369 If Ceres was installed in a non-standard path by specifying 370 -DCMAKE_INSTALL_PREFIX="/some/where/local", then the user should add 371 the **PATHS** option to the ``FIND_PACKAGE()`` command. e.g., 372 373 .. code-block:: cmake 374 375 FIND_PACKAGE(Ceres REQUIRED PATHS "/some/where/local/") 376 377 Note that this can be used to have multiple versions of Ceres installed. 378 379 Compiling against static or shared library 380 ------------------------------------------ 381 382 .. code-block:: cmake 383 384 TARGET_LINK_LIBRARIES(helloworld ${CERES_LIBRARIES}) 385 386 will result in a statically linked binary. Changing this line to 387 388 .. code-block:: cmake 389 390 TARGET_LINK_LIBRARIES(helloworld ${CERES_LIBRARIES_SHARED}) 391 392 will result in a dynamically linked binary. 393
