Stable Ceres Solver releases are available for download at code.google.com. For the more adventurous, the git repository is hosted on Gerrit.
Ceres relies on a number of open source libraries, some of which are optional. For details on customizing the build process, see Customizing the build .
1. CMake is a cross platform build system. Ceres needs a relatively recent version of CMake (version 2.8.0 or better).
2. eigen3 is used for doing all the low level matrix and linear algebra operations.
3. 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 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 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 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 and LAPACK routines are needed by SuiteSparse, and optionally used by Ceres directly for some operations. We recommend ATLAS, which includes BLAS and LAPACK routines. It is also possible to use OpenBLAS . However, one needs to be careful to turn off the threading inside OpenBLAS as it conflicts with use of threads in Ceres.
We will use Ubuntu 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).
# 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.
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].
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.
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
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
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
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
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
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
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
Ceres Solver Report
-------------------
Original Reduced
Parameter blocks 22122 22122
Parameters 66462 66462
Residual blocks 83718 83718
Residual 167436 167436
Trust Region Strategy LEVENBERG_MARQUARDT
Given Used
Linear solver DENSE_SCHUR DENSE_SCHUR
Preconditioner N/A N/A
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
Number of iterations:
Successful 6
Unsuccessful 0
Total 6
Time (in seconds):
Preprocessor 2.229e-01
Evaluator::Residuals 7.438e-02
Evaluator::Jacobians 6.790e-01
Linear Solver 1.681e+00
Minimizer 2.547e+00
Postprocessor 1.920e-02
Total 2.823e+00
Termination: FUNCTION_TOLERANCE
On OS X, we recommend using the homebrew package manager to install the dependencies. 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 framework.
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.
# 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.
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.
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)
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:
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:
Download the Android NDK. Run ndk-build from inside the jni directory. Use the libceres.a that gets created.
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 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>.
Ceres uses the CMake 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:
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:
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.
Once the library is installed with make install, it is possible to use CMake with FIND_PACKAGE() in order to compile user code against Ceres. For example, for examples/helloworld.cc the following CMakeList.txt can be used:
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})
Additionally, when CMake has found Ceres it can check the package version, if it has been specified in the FIND_PACKAGE() call. For example:
FIND_PACKAGE(Ceres 1.2.3 REQUIRED)
The version is an optional argument.
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.,
FIND_PACKAGE(Ceres REQUIRED PATHS "/some/where/local/")
Note that this can be used to have multiple versions of Ceres installed.