.. _chapter-installation: ============ Installation ============ Getting the source code ======================= .. _section-source: You can start with the `latest stable release `_ . 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 ============ .. note :: Ceres Solver 2.2 requires a **fully C++17-compliant** compiler. 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` . - `CMake `_ 3.16 or later **required**. - `Eigen `_ 3.3 or later **required**. .. NOTE :: Ceres can also use Eigen as a sparse linear algebra library. Please see the documentation for ``EIGENSPARSE`` for more details. - `glog `_ 0.3.5 or later. **Recommended** ``glog`` is used extensively throughout Ceres for logging detailed information about memory allocations and time consumed in various parts of the solve, internal error conditions etc. The Ceres developers use it extensively to observe and analyze Ceres's performance. `glog `_ allows you to control its behaviour from the command line. Starting with ``-logtostderr`` you can add ``-v=N`` for increasing values of ``N`` to get more and more verbose and detailed information about Ceres internals. Ceres also ships with a minimal replacement of ``glog`` called ``miniglog`` that can be enabled with the ``MINIGLOG`` build option. ``miniglog`` is supplied for platforms which do not support the full version of ``glog``. In an attempt to reduce dependencies, it may be tempting to use ``miniglog`` on platforms which already support ``glog``. While there is nothing preventing the user from doing so, we strongly recommend against it. ``miniglog`` has worse performance than ``glog`` and is much harder to control and use. - `gflags `_. Needed to build examples and tests and usually a dependency for glog. - `SuiteSparse `_ 4.5.6 or later. Needed for solving large sparse linear systems. **Optional; strongly recommended for large scale bundle adjustment** .. NOTE :: If SuiteSparseQR is found, Ceres attempts to find the Intel Thread Building Blocks (TBB) library. If found, Ceres assumes SuiteSparseQR was compiled with TBB support and will link to the found TBB version. You can customize the searched TBB location with the ``TBB_ROOT`` variable. A CMake native version of SuiteSparse that can be compiled on a variety of platforms (e.g., using Visual Studio, Xcode, MinGW, etc.) is maintained by the `CMake support for SuiteSparse `_ project. - `Apple's Accelerate sparse solvers `_. As of Xcode 9.0, Apple's Accelerate framework includes support for solving sparse linear systems across macOS, iOS et al. **Optional** - `BLAS `_ and `LAPACK `_ routines are needed by ``SuiteSparse``, and optionally used by Ceres directly for some operations. For best performance on ``x86`` based Linux systems we recommend using `Intel MKL `_. Two other good options are `ATLAS `_, which includes ``BLAS`` and ``LAPACK`` routines and `OpenBLAS `_ . However, one needs to be careful to `turn off the threading `_ inside ``OpenBLAS`` as it conflicts with use of threads in Ceres. MacOS ships with an optimized ``LAPACK`` and ``BLAS`` implementation as part of the ``Accelerate`` framework. The Ceres build system will automatically detect and use it. For Windows things are much more complicated. `LAPACK For Windows `_ has detailed instructions.. **Optional but required for** ``SuiteSparse``. - `CUDA `_ If you have an NVIDIA GPU then Ceres Solver can use it accelerate the solution of the Gauss-Newton linear systems using the CMake flag ``USE_CUDA``. Currently this support is limited to using the dense linear solvers that ship with ``CUDA``. As a result GPU acceleration can be used to speed up ``DENSE_QR``, ``DENSE_NORMAL_CHOLESKY`` and ``DENSE_SCHUR``. This also enables ``CUDA`` mixed precision solves for ``DENSE_NORMAL_CHOLESKY`` and ``DENSE_SCHUR``. **Optional**. .. _section-linux: Linux ===== We will use `Ubuntu `_ as our example linux distribution. .. NOTE:: Ceres Solver always supports the previous and current Ubuntu LTS releases, currently 18.04 and 20.04, using the default Ubuntu repositories and compiler toolchain. Support for earlier versions is not guaranteed or maintained. Start by installing all the dependencies. .. code-block:: bash # CMake sudo apt-get install cmake # google-glog + gflags sudo apt-get install libgoogle-glog-dev libgflags-dev # Use ATLAS for BLAS & LAPACK sudo apt-get install libatlas-base-dev # Eigen3 sudo apt-get install libeigen3-dev # SuiteSparse (optional) sudo apt-get install libsuitesparse-dev We are now ready to build, test, and install Ceres. .. code-block:: bash tar zxf ceres-solver-2.2.0.tar.gz mkdir ceres-bin cd ceres-bin cmake ../ceres-solver-2.2.0 make -j3 make test # Optionally install Ceres, it can also be exported using CMake which # allows Ceres to be used without requiring installation, see the documentation # for the EXPORT_BUILD_DIR option for more information. make install 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-2.2.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 iter cost cost_change |gradient| |step| tr_ratio tr_radius ls_iter iter_time total_time 0 4.185660e+06 0.00e+00 1.09e+08 0.00e+00 0.00e+00 1.00e+04 0 2.18e-02 6.57e-02 1 1.062590e+05 4.08e+06 8.99e+06 0.00e+00 9.82e-01 3.00e+04 1 5.07e-02 1.16e-01 2 4.992817e+04 5.63e+04 8.32e+06 3.19e+02 6.52e-01 3.09e+04 1 4.75e-02 1.64e-01 3 1.899774e+04 3.09e+04 1.60e+06 1.24e+02 9.77e-01 9.26e+04 1 4.74e-02 2.11e-01 4 1.808729e+04 9.10e+02 3.97e+05 6.39e+01 9.51e-01 2.78e+05 1 4.75e-02 2.59e-01 5 1.803399e+04 5.33e+01 1.48e+04 1.23e+01 9.99e-01 8.33e+05 1 4.74e-02 3.06e-01 6 1.803390e+04 9.02e-02 6.35e+01 8.00e-01 1.00e+00 2.50e+06 1 4.76e-02 3.54e-01 Solver Summary (v 2.2.0-eigen-(3.4.0)-lapack-suitesparse-(7.1.0)-metis-(5.1.0)-acceleratesparse-eigensparse) Original Reduced Parameter blocks 22122 22122 Parameters 66462 66462 Residual blocks 83718 83718 Residuals 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 ordering AUTOMATIC 22106,16 Schur structure 2,3,9 2,3,9 Cost: Initial 4.185660e+06 Final 1.803390e+04 Change 4.167626e+06 Minimizer iterations 7 Successful steps 7 Unsuccessful steps 0 Time (in seconds): Preprocessor 0.043895 Residual only evaluation 0.029855 (7) Jacobian & residual evaluation 0.120581 (7) Linear solver 0.153665 (7) Minimizer 0.339275 Postprocessor 0.000540 Total 0.383710 Termination: CONVERGENCE (Function tolerance reached. |cost_change|/cost: 1.769759e-09 <= 1.000000e-06) .. section-macos: macOS ===== On macOS, you can either use `Homebrew `_ (recommended) or `MacPorts `_ to install Ceres Solver. If using `Homebrew `_, then .. 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. If using `MacPorts `_, then .. code-block:: bash sudo port install ceres-solver will install the latest version. You can also install each of the dependencies by hand using `Homebrew `_. There is no need to install ``BLAS`` or ``LAPACK`` separately as macOS ships with optimized ``BLAS`` and ``LAPACK`` routines as part of the `vecLib `_ framework. .. code-block:: bash # CMake brew install cmake # google-glog and gflags brew install glog gflags # Eigen3 brew install eigen # SuiteSparse brew install suite-sparse We are now ready to build, test, and install Ceres. .. code-block:: bash tar zxf ceres-solver-2.2.0.tar.gz mkdir ceres-bin cd ceres-bin cmake ../ceres-solver-2.2.0 make -j3 make test # Optionally install Ceres, it can also be exported using CMake which # allows Ceres to be used without requiring installation, see the # documentation for the EXPORT_BUILD_DIR option for more information. make install .. _section-windows: Windows ======= Using a Library Manager ----------------------- `vcpkg `_ is a library manager for Microsoft Windows that can be used to install Ceres Solver and all its dependencies. #. Install the library manager into a top-level directory ``vcpkg/`` on Windows following the `guide `_, e.g., using Visual Studio 2022 community edition, or simply run .. code:: bat git clone https://github.com/Microsoft/vcpkg.git cd vcpkg .\bootstrap-vcpkg.bat .\vcpkg integrate install #. Use vcpkg to install and build Ceres and all its dependencies, e.g., for 64 bit Windows .. code:: bat vcpkg\vcpkg.exe install ceres:x64-windows Or with optional components, e.g., SuiteSparse, using .. code:: bat vcpkg\vcpkg.exe install ceres[suitesparse]:x64-windows #. Integrate vcpkg packages with Visual Studio to allow it to automatically find all the libraries installed by vcpkg. .. code:: bat vcpkg\vcpkg.exe integrate install #. To use Ceres in a CMake project, follow our :ref:`instructions `. Building from Source -------------------- Ceres Solver can also be built from source. For this purpose, we support Visual Studio 2019 and newer. .. NOTE:: If you find the following CMake difficult to set up, then you may be interested in a `Microsoft Visual Studio wrapper `_ for Ceres Solver by Tal Ben-Nun. #. Create a top-level directory for dependencies, build, and sources somewhere, e.g., ``ceres/`` #. Get dependencies; unpack them as subdirectories in ``ceres/`` (``ceres/eigen``, ``ceres/glog``, etc.) #. ``Eigen`` 3.3 . Configure and optionally install Eigen. It should be exported into the CMake package registry by default as part of the configure stage so installation should not be necessary. #. ``google-glog`` Open up the Visual Studio solution and build it. #. ``gflags`` Open up the Visual Studio solution and build it. #. (Experimental) ``SuiteSparse`` Previously SuiteSparse was not available on Windows, recently it has become possible to build it on Windows using the `suitesparse-metis-for-windows `_ project. If you wish to use ``SuiteSparse``, follow their instructions for obtaining and building it. Alternatively, Ceres Solver supports ``SuiteSparse`` binary packages available for Visual Studio 2019 and 2022 provided by the `CMake support for SuiteSparse `_ project that also include `reference LAPACK `_ (and BLAS). The binary packages are used by Ceres Solver for continuous testing on Github. #. Unpack the Ceres tarball into ``ceres``. For the tarball, you should get a directory inside ``ceres`` similar to ``ceres-solver-2.2.0``. Alternately, checkout Ceres via ``git`` to get ``ceres-solver.git`` inside ``ceres``. #. Install ``CMake``, #. Create a directory ``ceres/ceres-bin`` (for an out-of-tree build) #. If you use the above binary ``SuiteSparse`` package, make sure CMake can find it, e.g., by assigning the path of the directory that contains the unzipped contents to the ``CMAKE_PREFIX_PATH`` environment variable. In a Windows command prompt this can be achieved as follows: .. code:: bat export CMAKE_PREFIX_PATH=C:/Downloads/SuiteSparse-5.11.0-cmake.1-vc16-Win64-Release-shared-gpl #. 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 directory. #. Try running ``Configure`` which can fail at first because some dependencies cannot be automatically located. In this case, you must set the following CMake variables to the appropriate directories where you unpacked/built them: #. ``Eigen3_DIR`` (Set to directory containing ``Eigen3Config.cmake``) #. ``GLOG_INCLUDE_DIR_HINTS`` #. ``GLOG_LIBRARY_DIR_HINTS`` #. (Optional) ``gflags_DIR`` (Set to directory containing ``gflags-config.cmake``) #. (SuiteSparse binary package) ``BLAS_blas_LIBRARY`` and ``LAPACK_lapack_LIBRARY`` CMake variables must be `explicitly set` to ``/lib/blas.lib`` and ``/lib/lapack.lib``, respectively, both located in the unzipped package directory ````. If any of the variables are not visible in the ``CMake`` GUI, create a new entry for them. We recommend using the ``_(INCLUDE/LIBRARY)_DIR_HINTS`` variables rather than setting the ``_INCLUDE_DIR`` & ``_LIBRARY`` variables directly to keep all of the validity checking, and to avoid having to specify the library files manually. #. 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``. .. note:: #. The default build is ``Debug``; consider switching it to ``Release`` for optimal performance. #. CMake puts the resulting test binaries in ``ceres-bin/examples/Debug`` by default. #. Without a sparse linear algebra library, only a subset of solvers is usable, namely: ``DENSE_QR``, ``DENSE_SCHUR``, ``CGNR``, and ``ITERATIVE_SCHUR``. .. _section-android: Android ======= .. NOTE:: You will need Android NDK r15 or higher to build Ceres solver. To build Ceres for Android, we need to force ``CMake`` to find the toolchains from the Android NDK instead of using the standard ones. For example, assuming you have specified ``$NDK_DIR``: .. code-block:: bash cmake \ -DCMAKE_TOOLCHAIN_FILE=\ $NDK_DIR/build/cmake/android.toolchain.cmake \ -DEigen3_DIR=/path/to/Eigen3Config.cmake \ -DANDROID_ABI=arm64-v8a \ -DANDROID_STL=c++_shared \ -DANDROID_NATIVE_API_LEVEL=android-29 \ -DBUILD_SHARED_LIBS=ON \ -DMINIGLOG=ON \ You can build for any Android STL or ABI, but the c++_shared STL and the armeabi-v7a or arm64-v8a ABI are recommended for 32bit and 64bit architectures, respectively. Several API levels may be supported, but it is recommended that you use the highest level that is suitable for your Android project. .. NOTE:: You must always use the same API level and STL library for your Android project and the Ceres binaries. After building, you get a ``libceres.so`` library, which you can link in your Android build system by using a ``PREBUILT_SHARED_LIBRARY`` target in your build script. If you are building any Ceres samples and would like to verify your library, you will need to place them in an executable public directory together with ``libceres.so`` on your Android device (e.g. in /data/local/tmp) and ensure that the STL library from your NDK is present in that same directory. You may then execute the sample by running for example: .. code-block:: bash adb shell cd /data/local/tmp LD_LIBRARY_PATH=/data/local/tmp ./helloworld Note that any solvers or other shared dependencies you include in your project must also be present in your android build config and your test directory on Android. .. _section-ios: iOS === .. NOTE:: You need iOS version 7.0 or higher to build Ceres Solver. To build Ceres for iOS, we need to force ``CMake`` to find the toolchains from the iOS SDK instead of using the standard ones. For example: .. code-block:: bash cmake \ -DCMAKE_TOOLCHAIN_FILE=../ceres-solver/cmake/iOS.cmake \ -DEigen3_DIR=/path/to/Eigen3Config.cmake \ -DIOS_PLATFORM= \ ``PLATFORM`` can be: ``OS``, ``SIMULATOR`` or ``SIMULATOR64``. You can build for ``OS`` (``armv7``, ``armv7s``, ``arm64``), ``SIMULATOR`` (``i386``) or ``SIMULATOR64`` (``x86_64``) separately and use ``lipo`` to merge them into one static library. See ``cmake/iOS.cmake`` for more options. .. NOTE:: iOS version 11.0+ requires a 64-bit architecture, so you cannot build for armv7/armv7s with iOS 11.0+ (only arm64 is supported). After building, you will get a ``libceres.a`` library, which you will need to add to your Xcode project. The default CMake configuration builds a bare bones version of Ceres Solver that only depends on Eigen (``MINIGLOG`` is compiled into Ceres if it is used), this should be sufficient for solving small to moderate sized problems. If you decide to use ``LAPACK`` and ``BLAS``, then you also need to add ``Accelerate.framework`` to your Xcode project's linking dependency. .. _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