mirror of
https://github.com/ceres-solver/ceres-solver.git
synced 2026-08-30 00:50:37 +08:00
Sameer Agarwal
c4cd29dd7c
The existing introduction was a bit redundant and also was not really an introduction. Also updated the build instructions to reflect the new reality on Mac OSX. Also updated the beginning of the tutorial to be a bit gentler and updated the history to be more consistent Change-Id: Ife38c1949252cf9f4c6301856957f2d38365f313
505 lines
19 KiB
ReStructuredText
505 lines
19 KiB
ReStructuredText
.. _chapter-building:
|
|
|
|
=======================
|
|
Building & Installation
|
|
=======================
|
|
|
|
Getting the source code
|
|
=======================
|
|
.. _section-source:
|
|
|
|
You can start with the `latest stable release
|
|
<http://ceres-solver.org/ceres-solver-1.8.0.tar.gz>`_ . Or if you want
|
|
the latest version, you can clone the git repository
|
|
.. code-block:: bash
|
|
|
|
git clone https://ceres-solver.googlesource.com/ceres-solver
|
|
|
|
.. _section-dependencies:
|
|
|
|
Dependencies
|
|
============
|
|
|
|
Ceres relies on a number of open source libraries, some of which are
|
|
optional. For details on customizing the build process, see
|
|
:ref:`section-customizing` .
|
|
|
|
1. `CMake <http://www.cmake.org>`_ is a cross platform build
|
|
system. Ceres needs a relatively recent version of CMake (version
|
|
2.8.0 or better).
|
|
|
|
2. `eigen3 <http://eigen.tuxfamily.org/index.php?title=Main_Page>`_ is
|
|
used for doing all the low level matrix and linear algebra operations.
|
|
|
|
3. `google-glog <http://code.google.com/p/google-glog>`_ is
|
|
used for error checking and logging. Ceres needs glog version 0.3.1 or
|
|
later. Version 0.3 (which ships with Fedora 16) has a namespace bug
|
|
which prevents Ceres from building. Ceres contains a stripped-down,
|
|
minimal version of ``glog`` called ``miniglog``, which can be enabled
|
|
with the ``MINIGLOG`` build option. If enabled, it replaces the
|
|
requirement for ``glog``. However, in general it is recommended that
|
|
you use the full ``glog``.
|
|
|
|
4. `gflags <http://code.google.com/p/gflags>`_ is a library for
|
|
processing command line flags. It is used by some of the examples and
|
|
tests. While it is not strictly necessary to build the library, we
|
|
strongly recommend building the library with gflags.
|
|
|
|
5. `SuiteSparse
|
|
<http://www.cise.ufl.edu/research/sparse/SuiteSparse/>`_ is used for
|
|
sparse matrix analysis, ordering and factorization. In particular
|
|
Ceres uses the AMD, CAMD, COLAMD and CHOLMOD libraries. This is an optional
|
|
dependency.
|
|
|
|
6. `CXSparse <http://www.cise.ufl.edu/research/sparse/CXSparse/>`_ is
|
|
a sparse matrix library similar in scope to ``SuiteSparse`` but with
|
|
no dependencies on ``LAPACK`` and ``BLAS``. This makes for a simpler
|
|
build process and a smaller binary. The simplicity comes at a cost --
|
|
for all but the most trivial matrices, ``SuiteSparse`` is
|
|
significantly faster than ``CXSparse``. This is an optional dependency.
|
|
|
|
7. `BLAS <http://www.netlib.org/blas/>`_ and `LAPACK
|
|
<http://www.netlib.org/lapack/>`_ routines are needed by
|
|
SuiteSparse, and optionally used by Ceres directly for some operations.
|
|
We recommend `ATLAS <http://math-atlas.sourceforge.net/>`_,
|
|
which includes BLAS and LAPACK routines. It is also possible to use
|
|
`OpenBLAS <https://github.com/xianyi/OpenBLAS>`_ . However, one needs
|
|
to be careful to `turn off the threading
|
|
<https://github.com/xianyi/OpenBLAS/wiki/faq#wiki-multi-threaded>`_
|
|
inside ``OpenBLAS`` as it conflicts with use of threads in Ceres.
|
|
|
|
.. _section-linux:
|
|
|
|
Building on Linux
|
|
=================
|
|
We will use `Ubuntu <http://www.ubuntu.com>`_ as our example
|
|
platform. Start by installing all the dependencies.
|
|
|
|
.. NOTE::
|
|
|
|
Up to at least Ubuntu 13.10, the SuiteSparse package in the official
|
|
package repository (built from SuiteSparse v3.4.0) **cannot** be used
|
|
to build Ceres as a *shared* library. Thus if you want to build
|
|
Ceres as a shared library using SuiteSparse, you must perform a
|
|
source install of SuiteSparse. It is recommended that you use the
|
|
current version of SuiteSparse (4.2.1 at the time of writing).
|
|
|
|
.. code-block:: bash
|
|
|
|
# CMake
|
|
sudo apt-get install cmake
|
|
# gflags
|
|
tar -xvzf gflags-2.0.tar.gz
|
|
cd gflags-2.0
|
|
./configure --prefix=/usr/local
|
|
make
|
|
sudo make install.
|
|
# google-glog must be configured to use the previously installed gflags
|
|
tar -xvzf glog-0.3.2.tar.gz
|
|
cd glog-0.3.2
|
|
./configure --with-gflags=/usr/local/
|
|
make
|
|
sudo make install
|
|
# BLAS & LAPACK
|
|
sudo apt-get install libatlas-base-dev
|
|
# Eigen3
|
|
sudo apt-get install libeigen3-dev
|
|
# SuiteSparse and CXSparse (optional)
|
|
# - If you want to build Ceres as a *static* library (the default)
|
|
# you can use the SuiteSparse package in the main Ubuntu package
|
|
# repository:
|
|
sudo apt-get install libsuitesparse-dev
|
|
# - However, if you want to build Ceres as a *shared* library, you must
|
|
# perform a source install of SuiteSparse (and uninstall the Ubuntu
|
|
# package if it is currently installed.
|
|
|
|
We are now ready to build and test Ceres.
|
|
|
|
.. code-block:: bash
|
|
|
|
tar zxf ceres-solver-1.8.0.tar.gz
|
|
mkdir ceres-bin
|
|
cd ceres-bin
|
|
cmake ../ceres-solver-1.8.0
|
|
make -j3
|
|
make test
|
|
|
|
You can also try running the command line bundling application with one of the
|
|
included problems, which comes from the University of Washington's BAL
|
|
dataset [Agarwal]_.
|
|
|
|
.. code-block:: bash
|
|
|
|
bin/simple_bundle_adjuster ../ceres-solver-1.8.0/data/problem-16-22106-pre.txt
|
|
|
|
This runs Ceres for a maximum of 10 iterations using the
|
|
``DENSE_SCHUR`` linear solver. The output should look something like
|
|
this.
|
|
|
|
.. code-block:: bash
|
|
|
|
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: 8.73e-02 tt: 2.61e-01
|
|
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: 1.85e-01 tt: 4.46e-01
|
|
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: 1.74e-01 tt: 6.20e-01
|
|
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: 1.74e-01 tt: 7.94e-01
|
|
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: 1.73e-01 tt: 9.67e-01
|
|
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: 1.75e-01 tt: 1.14e+00
|
|
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: 1.75e-01 tt: 1.32e+00
|
|
|
|
Ceres Solver Report
|
|
-------------------
|
|
Original Reduced
|
|
Parameter blocks 22122 22122
|
|
Parameters 66462 66462
|
|
Residual blocks 83718 83718
|
|
Residual 167436 167436
|
|
|
|
Minimizer TRUST_REGION
|
|
|
|
Dense linear algebra library EIGEN
|
|
Trust region strategy LEVENBERG_MARQUARDT
|
|
|
|
Given Used
|
|
Linear solver DENSE_SCHUR DENSE_SCHUR
|
|
Threads 1 1
|
|
Linear solver threads 1 1
|
|
Linear solver ordering AUTOMATIC 22106, 16
|
|
|
|
Cost:
|
|
Initial 4.185660e+06
|
|
Final 1.803390e+04
|
|
Change 4.167626e+06
|
|
|
|
Minimizer iterations 6
|
|
Successful steps 6
|
|
Unsuccessful steps 0
|
|
|
|
Time (in seconds):
|
|
Preprocessor 0.173
|
|
|
|
Residual evaluation 0.115
|
|
Jacobian evaluation 0.498
|
|
Linear solver 0.517
|
|
Minimizer 1.242
|
|
|
|
Postprocessor 0.003
|
|
Total 1.437
|
|
|
|
Termination: CONVERGENCE (Function tolerance reached. |cost_change|/cost: 1.769750e-09 <= 1.000000e-06)
|
|
|
|
.. section-osx:
|
|
|
|
Building on Mac OS X
|
|
====================
|
|
.. NOTE::
|
|
|
|
Ceres will not compile using Xcode 4.5.x (Clang version 4.1) due to a bug in that version of
|
|
Clang. If you are running Xcode 4.5.x, please update to Xcode >= 4.6.x before attempting to
|
|
build Ceres.
|
|
|
|
|
|
On OS X, we recommend using the `homebrew
|
|
<http://mxcl.github.com/homebrew/>`_ package manager to install Ceres.
|
|
|
|
.. code-block:: bash
|
|
|
|
brew install ceres-solver
|
|
|
|
will install the latest stable version along with all the required
|
|
dependencies and
|
|
|
|
.. code-block:: bash
|
|
|
|
brew install ceres-solver --HEAD
|
|
|
|
will install the latest version in the git repo.
|
|
|
|
You can also install each of the dependencies by hand using `homebrew
|
|
<http://mxcl.github.com/homebrew/>`_. There is no need to install
|
|
``BLAS`` or ``LAPACK`` separately as OS X ships with optimized
|
|
``BLAS`` and ``LAPACK`` routines as part of the `vecLib
|
|
<https://developer.apple.com/library/mac/#documentation/Performance/Conceptual/vecLib/Reference/reference.html>`_
|
|
framework.
|
|
|
|
.. code-block:: bash
|
|
|
|
# CMake
|
|
brew install cmake
|
|
# google-glog and gflags
|
|
brew install glog
|
|
# Eigen3
|
|
brew install eigen
|
|
# SuiteSparse and CXSparse
|
|
brew install suite-sparse
|
|
|
|
We are now ready to build and test Ceres.
|
|
|
|
.. code-block:: bash
|
|
|
|
tar zxf ceres-solver-1.8.0.tar.gz
|
|
mkdir ceres-bin
|
|
cd ceres-bin
|
|
cmake ../ceres-solver-1.8.0
|
|
make -j3
|
|
make test
|
|
|
|
Like the Linux build, you should now be able to run
|
|
``bin/simple_bundle_adjuster``.
|
|
|
|
.. _section-windows:
|
|
|
|
Building on Windows with Visual Studio
|
|
======================================
|
|
|
|
On Windows, we support building with Visual Studio 2010 or newer. Note
|
|
that the Windows port is less featureful and less tested than the
|
|
Linux or Mac OS X versions due to the unavailability of SuiteSparse
|
|
and ``CXSparse``. Building is also more involved since there is no
|
|
automated way to install the dependencies.
|
|
|
|
#. Make a toplevel directory for deps & build & src somewhere: ``ceres/``
|
|
#. Get dependencies; unpack them as subdirectories in ``ceres/``
|
|
(``ceres/eigen``, ``ceres/glog``, etc)
|
|
|
|
#. ``Eigen`` 3.1 (needed on Windows; 3.0.x will not work). There is
|
|
no need to build anything; just unpack the source tarball.
|
|
|
|
#. ``google-glog`` Open up the Visual Studio solution and build it.
|
|
#. ``gflags`` Open up the Visual Studio solution and build it.
|
|
|
|
#. Unpack the Ceres tarball into ``ceres``. For the tarball, you
|
|
should get a directory inside ``ceres`` similar to
|
|
``ceres-solver-1.3.0``. Alternately, checkout Ceres via ``git`` to
|
|
get ``ceres-solver.git`` inside ``ceres``.
|
|
|
|
#. Install ``CMake``,
|
|
|
|
#. Make a dir ``ceres/ceres-bin`` (for an out-of-tree build)
|
|
|
|
#. Run ``CMake``; select the ``ceres-solver-X.Y.Z`` or
|
|
``ceres-solver.git`` directory for the CMake file. Then select the
|
|
``ceres-bin`` for the build dir.
|
|
|
|
#. Try running ``Configure``. It won't work. It'll show a bunch of options.
|
|
You'll need to set:
|
|
|
|
#. ``EIGEN_INCLUDE_DIR``
|
|
#. ``GLOG_INCLUDE_DIR``
|
|
#. ``GLOG_LIBRARY``
|
|
#. ``GFLAGS_INCLUDE_DIR``
|
|
#. ``GFLAGS_LIBRARY``
|
|
|
|
to the appropriate place where you unpacked/built them. If any of the
|
|
variables are not visible in the ``CMake`` GUI, toggle to the
|
|
*Advanced View* with ``<t>``.
|
|
|
|
#. You may have to tweak some more settings to generate a MSVC
|
|
project. After each adjustment, try pressing Configure & Generate
|
|
until it generates successfully.
|
|
|
|
#. Open the solution and build it in MSVC
|
|
|
|
|
|
To run the tests, select the ``RUN_TESTS`` target and hit **Build
|
|
RUN_TESTS** from the build menu.
|
|
|
|
Like the Linux build, you should now be able to run
|
|
``bin/simple_bundle_adjuster``.
|
|
|
|
Notes:
|
|
|
|
#. The default build is Debug; consider switching it to release mode.
|
|
#. Currently ``system_test`` is not working properly.
|
|
#. Building Ceres as a DLL is not supported; patches welcome.
|
|
#. CMake puts the resulting test binaries in ``ceres-bin/examples/Debug``
|
|
by default.
|
|
#. The solvers supported on Windows are ``DENSE_QR``, ``DENSE_SCHUR``,
|
|
``CGNR``, and ``ITERATIVE_SCHUR``.
|
|
#. We're looking for someone to work with upstream ``SuiteSparse`` to
|
|
port their build system to something sane like ``CMake``, and get a
|
|
supported Windows port.
|
|
|
|
|
|
.. _section-android:
|
|
|
|
Building on Android
|
|
===================
|
|
|
|
|
|
Download the ``Android NDK``. Run ``ndk-build`` from inside the
|
|
``jni`` directory. Use the ``libceres.a`` that gets created.
|
|
|
|
.. _section-customizing:
|
|
|
|
Customizing the build
|
|
=====================
|
|
|
|
It is possible to reduce the libraries needed to build Ceres and
|
|
customize the build process by setting the appropriate options in
|
|
``CMake``. These options can either be set in the ``CMake`` GUI,
|
|
or via ``-D<OPTION>=<ON/OFF>`` when running ``CMake`` from the
|
|
command line. In general, you should only modify these options from
|
|
their defaults if you know what you are doing.
|
|
|
|
.. NOTE::
|
|
|
|
If you are setting variables via ``-D<VARIABLE>=<VALUE>`` when calling
|
|
``CMake``, it is important to understand that this forcibly **overwrites** the
|
|
variable ``<VARIABLE>`` in the ``CMake`` cache at the start of *every configure*.
|
|
|
|
This can lead to confusion if you are invoking the ``CMake``
|
|
`curses <http://www.gnu.org/software/ncurses/ncurses.html>`_ terminal GUI
|
|
(via ``ccmake``, e.g. ```ccmake -D<VARIABLE>=<VALUE> <PATH_TO_SRC>``).
|
|
In this case, even if you change the value of ``<VARIABLE>`` in the ``CMake``
|
|
GUI, your changes will be **overwritten** with the value passed via
|
|
``-D<VARIABLE>=<VALUE>`` (if one exists) at the start of each configure.
|
|
|
|
As such, it is generally easier not to pass values to ``CMake`` via ``-D``
|
|
and instead interactively experiment with their values in the ``CMake`` GUI.
|
|
If they are not present in the *Standard View*, toggle to the *Advanced View*
|
|
with ``<t>``.
|
|
|
|
Options controlling Ceres configuration
|
|
---------------------------------------
|
|
|
|
#. ``LAPACK [Default: ON]``: By default Ceres will use ``LAPACK`` (&
|
|
``BLAS``) if they are found. Turn this ``OFF`` to build Ceres
|
|
without ``LAPACK``. Turning this ``OFF`` also disables
|
|
``SUITESPARSE`` as it depends on ``LAPACK``.
|
|
|
|
#. ``SUITESPARSE [Default: ON]``: By default, Ceres will link to
|
|
``SuiteSparse`` if it and all of its dependencies are present. Turn
|
|
this ``OFF`` to build Ceres without ``SuiteSparse``. Note that
|
|
``LAPACK`` must be ``ON`` in order to build with ``SuiteSparse``.
|
|
|
|
#. ``CXSPARSE [Default: ON]``: By default, Ceres will link to
|
|
``CXSparse`` if all its dependencies are present. Turn this ``OFF``
|
|
to build Ceres without ``CXSparse``.
|
|
|
|
#. ``GFLAGS [Default: ON]``: Turn this ``OFF`` to build Ceres without
|
|
``gflags``. This will also prevent some of the example code from
|
|
building.
|
|
|
|
#. ``MINIGLOG [Default: OFF]``: Ceres includes a stripped-down,
|
|
minimal implementation of ``glog`` which can optionally be used as
|
|
a substitute for ``glog``, thus removing ``glog`` as a required
|
|
dependency. Turn this ``ON`` to use this minimal ``glog``
|
|
implementation.
|
|
|
|
#. ``SCHUR_SPECIALIZATIONS [Default: ON]``: If you are concerned about
|
|
binary size/compilation time over some small (10-20%) performance
|
|
gains in the ``SPARSE_SCHUR`` solver, you can disable some of the
|
|
template specializations by turning this ``OFF``.
|
|
|
|
#. ``OPENMP [Default: ON]``: On certain platforms like Android,
|
|
multi-threading with ``OpenMP`` is not supported. Turn this ``OFF``
|
|
to disable multithreading.
|
|
|
|
#. ``BUILD_SHARED_LIBS [Default: OFF]``: By default Ceres is built as
|
|
a static library, turn this ``ON`` to instead build Ceres as a
|
|
shared library.
|
|
|
|
#. ``BUILD_DOCUMENTATION [Default: OFF]``: Use this to enable building
|
|
the documentation, requires `Sphinx <http://sphinx-doc.org/>`_. In
|
|
addition, ``make ceres_docs`` can be used to build only the
|
|
documentation.
|
|
|
|
#. ``MSVC_USE_STATIC_CRT [Default: OFF]`` *Windows Only*: By default
|
|
Ceres will use the Visual Studio default, *shared* C-Run Time (CRT) library.
|
|
Turn this ``ON`` to use the *static* C-Run Time library instead.
|
|
|
|
|
|
Options controlling Ceres dependency locations
|
|
----------------------------------------------
|
|
|
|
Ceres uses the ``CMake``
|
|
`find_package <http://www.cmake.org/cmake/help/v2.8.12/cmake.html#command:find_package>`_
|
|
function to find all of its dependencies using
|
|
``Find<DEPENDENCY_NAME>.cmake`` scripts which are either included in Ceres
|
|
(for most dependencies) or are shipped as standard with ``CMake``
|
|
(for ``LAPACK`` & ``BLAS``). These scripts will search all of the "standard"
|
|
install locations for various OSs for each dependency. However, particularly
|
|
for Windows, they may fail to find the library, in this case you will have to
|
|
manually specify its installed location. The ``Find<DEPENDENCY_NAME>.cmake``
|
|
scripts shipped with Ceres support two ways for you to do this:
|
|
|
|
#. Set the *hints* variables specifying the *directories* to search in
|
|
preference, but in addition, to the search directories in the
|
|
``Find<DEPENDENCY_NAME>.cmake`` script:
|
|
|
|
- ``<DEPENDENCY_NAME (CAPS)>_INCLUDE_DIR_HINTS``
|
|
- ``<DEPENDENCY_NAME (CAPS)>_LIBRARY_DIR_HINTS``
|
|
|
|
These variables should be set via ``-D<VAR>=<VALUE>``
|
|
``CMake`` arguments as they are not visible in the GUI.
|
|
|
|
#. Set the variables specifying the *explicit* include directory
|
|
and library file to use:
|
|
|
|
- ``<DEPENDENCY_NAME (CAPS)>_INCLUDE_DIR``
|
|
- ``<DEPENDENCY_NAME (CAPS)>_LIBRARY``
|
|
|
|
This bypasses *all* searching in the
|
|
``Find<DEPENDENCY_NAME>.cmake`` script, but validation is still
|
|
performed.
|
|
|
|
These variables are available to set in the ``CMake`` GUI. They
|
|
are visible in the *Standard View* if the library has not been
|
|
found (but the current Ceres configuration requires it), but
|
|
are always visible in the *Advanced View*. They can also be
|
|
set directly via ``-D<VAR>=<VALUE>`` arguments to ``CMake``.
|
|
|
|
.. _section-using-ceres:
|
|
|
|
Using Ceres with CMake
|
|
======================
|
|
|
|
Once the library is installed with ``make install``, it is possible to
|
|
use CMake with `FIND_PACKAGE()
|
|
<http://www.cmake.org/cmake/help/v2.8.10/cmake.html#command:find_package>`_
|
|
in order to compile **user code** against Ceres. For example, for
|
|
`examples/helloworld.cc
|
|
<https://ceres-solver.googlesource.com/ceres-solver/+/master/examples/helloworld.cc>`_
|
|
the following CMakeList.txt can be used:
|
|
|
|
.. code-block:: cmake
|
|
|
|
CMAKE_MINIMUM_REQUIRED(VERSION 2.8)
|
|
|
|
PROJECT(helloworld)
|
|
|
|
FIND_PACKAGE(Ceres REQUIRED)
|
|
INCLUDE_DIRECTORIES(${CERES_INCLUDE_DIRS})
|
|
|
|
# helloworld
|
|
ADD_EXECUTABLE(helloworld helloworld.cc)
|
|
TARGET_LINK_LIBRARIES(helloworld ${CERES_LIBRARIES})
|
|
|
|
Specify Ceres version
|
|
---------------------
|
|
|
|
Additionally, when CMake has found Ceres it can check the package
|
|
version, if it has been specified in the `FIND_PACKAGE()
|
|
<http://www.cmake.org/cmake/help/v2.8.10/cmake.html#command:find_package>`_
|
|
call. For example:
|
|
|
|
.. code-block:: cmake
|
|
|
|
FIND_PACKAGE(Ceres 1.2.3 REQUIRED)
|
|
|
|
The version is an optional argument.
|
|
|
|
Local installations
|
|
-------------------
|
|
|
|
If Ceres was installed in a non-standard path by specifying
|
|
-DCMAKE_INSTALL_PREFIX="/some/where/local", then the user should add
|
|
the **PATHS** option to the ``FIND_PACKAGE()`` command. e.g.,
|
|
|
|
.. code-block:: cmake
|
|
|
|
FIND_PACKAGE(Ceres REQUIRED PATHS "/some/where/local/")
|
|
|
|
Note that this can be used to have multiple versions of Ceres
|
|
installed.
|