Installation

1.0 获取源代码

您可以从 latest stable release 版本开始。 或者，如果您想要最新版本，可以克隆 git 存储库

git clone https://ceres-solver.googlesource.com/ceres-solver

2.0 依赖

Ceres Solver 2.2 requires a fully C++17-compliant compiler.

Ceres 依赖于许多开源库，其中一些是可选的。

  • CMake 3.16 or later required.

  • Eigen 3.3 or later required.

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 在整个Ceres中被广泛使用，用于记录有关内存分配和求解各个部分所消耗的时间、内部错误条件等的详细信息。Ceres开发人员广泛使用它来观察和分析Ceres的性能。glog 允许您从命令行控制其行为。从 -logtostderr 开始，您可以添加-v=N以增加N的值，从而获得越来越多关于Ceres内部的详细信息。

    Ceres还提供了一种称为 miniglog 的 glog 的最小替代品，该替代品可以通过 miniglog 构建选项启用。 miniglog 是为不支持完整版 glog 的平台提供的。为了减少依赖性，在已经支持 glog 的平台上使用 miniglog 可能很诱人。虽然没有什么可以阻止用户这样做，但我们强烈建议不要这样做。miniglog 的性能比 glog 差，而且更难控制和使用。为了减少依赖性，在已经支持glog的平台上使用miniglog是可行的，但我们强烈建议不要这样做。miniglog的性能比glog差，而且更难控制和使用。

  • gflags. 构建 example 和 test 时的依赖，通常是 glog 的依赖项。

  • SuiteSparse 4.5.6 or later。求解大型稀疏线性系统所需。 可选的，强烈建议用于大尺度的 BA 问题。SuiteSparse 的 CMake 本机版本可以在各种平台上编译（例如，使用 Visual Studio、Xcode、MinGW 等），由 CMake support for SuiteSparse 支持维护。

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.

  • Apple’s Accelerate sparse solvers. Optional：Apple 的 Accelerate 稀疏求解器。 从 Xcode 9.0 开始，Apple 的 Accelerate 框架支持跨 macOS、iOS 等解决稀疏线性系统。 可选的。

  • SuiteSparse 需要 BLAS 和 LAPACK ，Ceres 也可选择直接使用进行某些操作。为了在基于 x86 的 Linux 系统上获得最佳性能，我们建议使用 Intel MKL。另外两个不错的选择是ATLAS，其中包括 "BLAS "和 "LAPACK "例程，以及OpenBLAS。不过，需要注意在 OpenBLAS 中 关闭线程，因为它与 Ceres 中线程的使用相冲突。MacOS 已将优化的 LAPACK 和 BLAS 实现作为 Accelerate 框架的一部分。Ceres 编译系统会自动检测并使用它。对于 Windows，情况要复杂得多。LAPACK For Windows 有详细说明。Optional but required for SuiteSparse.

  • CUDA Optional：如果您有英伟达™（NVIDIA®）图形处理器，Ceres Solver 可使用 CMake 标志 USE_CUDA 来加速高斯-牛顿线性系统的求解。目前，这种支持仅限于使用 CUDA 附带的密集线性求解器。因此，GPU 加速可用于加速 DENSE_QR、DENSE_NORMAL_CHOLESKY 和 DENSE_SCHUR。这还能为 DENSE_NORMAL_CHOLESKY 和 DENSE_SCHUR 启用 CUDA 混合精度求解。

3.0 Linux

我们将使用 Ubuntu 作为 Linux 发行版的示例。

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.

首先安装所有依赖项。

# 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

现在，我们已准备好构建、测试和安装 Ceres。

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

您还可以尝试使用其中一个问题运行命令行 BA 应用程序，该问题来自华盛顿大学的 BAL 数据集[Agarwal]。

bin/simple_bundle_adjuster ../ceres-solver-2.2.0/data/problem-16-22106-pre.txt

这将使用 DENSE_SCHUR 线性求解器对 Ceres 进行最多 10 次迭代。输出结果应该是这样的

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)

4.0 macOS

在 macOS 上，可以使用 Homebrew（推荐）或 MacPorts 安装 Ceres Solver。如果使用 Homebrew，那么

brew install ceres-solver

将安装最新的稳定版本和所有必需的依赖项，同时如下命令将安装 git 仓库中的最新版本。

brew install ceres-solver --HEAD

如果使用 MacPorts，那么如下命令将安装最新版本。

sudo port install ceres-solver

你也可以使用 Homebrew 手工安装每个依赖项。无需单独安装 BLAS 或 LAPACK，因为 macOS 已将优化的 BLAS 和 LAPACK 例程作为 vecLib 框架的一部分随附。

# CMake
brew install cmake
# google-glog and gflags
brew install glog gflags
# Eigen3
brew install eigen
# SuiteSparse
brew install suite-sparse

现在，我们已准备好构建、测试和安装 Ceres。

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

5.0 Windows

5.1 Using a Library Manager

vcpkg 是 Microsoft Windows 的库管理器，可用于安装 Ceres Solver 及其所有依赖项。

  1. 在 Windows 环境下，按照 guide 将库管理器安装到顶层目录 vcpkg/ 中，例如使用 Visual Studio 2022 社区版，或直接运行

    git clone https://github.com/Microsoft/vcpkg.git
cd vcpkg
.\bootstrap-vcpkg.bat
.\vcpkg integrate install

  2. 使用 vcpkg 安装并构建 Ceres 及其所有依赖项，例如 64 位 Windows 版

    vcpkg\vcpkg.exe install ceres:x64-windows

    或使用可选组件，如 SuiteSparse，使用

    vcpkg\vcpkg.exe install ceres[suitesparse]:x64-windows

  3. 将 vcpkg 软件包与 Visual Studio 集成，使其能够自动查找 vcpkg 安装的所有库。

    vcpkg\vcpkg.exe integrate install

5.2 Building from Source

Ceres Solver 也可从源代码构建。我们基本不在Windows开发，因此这里并没有做详细翻译，读者可去官网查看。

6.0 Android

DOC

7.0 iOS

DOC

8.0 Customizing the build

通过在 CMake 中设置适当的选项，可以减少构建 Ceres 所需的库，并自定义构建过程。这些选项可以在 CMake GUI 中设置，或在命令行运行 CMake 时通过 -D<OPTION>=<ON/OFF> 设置。保险起见，只有在知道自己在做什么的情况下，才能修改这些选项的默认值。

如果您在调用 CMake 时通过 -D<VARIABLE>=<VALUE> 设置变量，请务必理解，这会在每次配置开始时强制覆盖 CMake 缓存中的变量 <VARIABLE>。

如果您调用 CMake curses 终端图形用户界面（通过 ccmake，例如 ccmake -D<VARIABLE>=<VALUE> <PATH_TO_SRC>），这可能会导致混乱。在这种情况下，即使您在 CMake GUI 中更改了 <VARIABLE> 的值，您的更改也会被每次配置开始时通过 -D<VARIABLE>=<VALUE>（如果存在）传递的值覆盖。

因此，通常不通过 -D 向 CMake 传递值，而是在 CMake GUI 中交互式地尝试它们的值会更方便。如果它们不在标准视图中，请使用 <t>切换到高级视图。

8.1 Modifying default compilation flags

CMAKE_CXX_FLAGS 变量可用于为编译定义额外的默认编译标志。例如，如果您希望使用 -march=native 来构建 Ceres，而这在默认情况下是不启用的（即使 CMAKE_BUILD_TYPE=Release 也是如此），您可以调用 CMake：

cmake -DCMAKE_CXX_FLAGS="-march=native" <PATH_TO_CERES_SOURCE>

The use of -march=native will limit portability, as it will tune the implementation to the specific CPU of the compiling machine (e.g. use of AVX if available). Run-time segfaults may occur if you then tried to run the resulting binaries on a machine with a different processor, even if it is from the same family (e.g. x86) if the specific options available are different. Note that the performance gains from the use of -march=native are not guaranteed to be significant.

使用 -march=native会限制可移植性，因为它会根据编译机器的特定 CPU 来调整实现（例如，如果可用，则使用 AVX）。如果在不同处理器的机器上运行生成的二进制文件，即使是相同系列的处理器（如 x86），如果可用的特定选项不同，也可能出现运行时故障。请注意，使用 -march=native所带来的性能提升并不能显著保证。

8.2 Options controlling Ceres configuration

  1. LAPACK [Default: ON]： 如果启用此选项，并且找到了 BLAS 和 LAPACK 库，Ceres 将启用直接使用 LAPACK （即 Ceres 本身将调用它们）。如果禁用该选项，Ceres 将不需要 LAPACK 或 BLAS。不过，如果 LAPACK=OFF SUITESPARSE=ON ，Ceres 仍有可能通过 SuiteSparse 间接调用 LAPACK 例程。最后请注意，如果 LAPACK=ON 和 SUITESPARSE=ON ，SuiteSparse 和 Ceres 使用的 LAPACK 和 BLAS 库应该是相同的。

  2. SUITESPARSE [Default: ON]: 默认情况下，如果 SuiteSparse 及其所有依赖项都存在，Ceres 将链接到 SuiteSparse。关闭此选项可在不使用SuiteSparse的情况下构建 Ceres。

  3. ACCELERATESPARSE [Default: ON]: 默认情况下，如果检测到支持稀疏线性系统求解的苹果加速框架版本，Ceres 将直接链接到该框架。请注意，在苹果操作系统上，Accelerate 通常也提供 BLAS/LAPACK 实现，因此无论 ACCELERATESPARSE 的值如何，都会与之链接。

  4. EIGENSPARSE [Default: ON]: 默认情况下，Ceres 将使用 Eigen 的稀疏 Cholesky 因式分解。

  5. GFLAGS [Default: ON]: 关闭此选项可在不使用 gflags 的情况下构建 Ceres。这也会阻止某些示例代码的构建。

  6. MINIGLOG [Default: OFF]: Ceres 包含一个精简的 glog 实现，可以选择用它来替代 glog，从而移除 glog 作为必需的依赖。开启此选项可使用最小化的 glog 实现。

  7. SCHUR_SPECIALIZATIONS [Default: ON]: 如果您担心二进制文件大小/编译时间，而不是 "SPARSE_SCHUR "求解器的一些微小（10-20%）性能提升，您可以通过将其 "关闭 "来禁用一些模板特化。

  8. BUILD_SHARED_LIBS [Default: OFF]: 默认情况下，Ceres 是以静态库的形式构建的，开启此选项，Ceres 将以共享库的形式构建。

  9. EXPORT_BUILD_DIR [Default: OFF]: 默认情况下，Ceres 只为安装而配置，因此必须安装后客户端才能使用它。开启此选项可将 Ceres 的构建目录位置导出到用户的本地 CMake 软件包注册表，在调用find_package(Ceres)时，使用 CMake 的客户端项目将在该注册表中检测到 Ceres，而无需安装。

  10. BUILD_DOCUMENTATION [Default: OFF]: 使用此功能可以编译文档，需要 Sphinx 和 sphinx-rtd-theme 软件包，可从 Python 软件包索引中获取。此外，"make ceres_docs "可用于仅构建文档。

  11. MSVC_USE_STATIC_CRT [Default: OFF] 仅限 Windows： 默认情况下，Ceres 将使用 Visual Studio 默认的共享 C-Run Time (CRT) 库。打开此选项可使用 static C-Run Time 库。

  12. LIB_SUFFIX [Default: "64" on non-Debian/Arch based 64-bit Linux, otherwise: ""]: 要追加到库安装目录的后缀，从： ${CMAKE_INSTALL_PREFIX}/lib${LIB_SUFFIX}构建。文件系统层次标准建议 64 位系统将本地库安装到 lib64 而不是 lib。大多数 Linux 发行版都遵循这一惯例，但 Debian 和基于 Arch 的发行版不遵循这一惯例。请注意，"LIB_SUFFIX" 的一般合理值只有 "" 和 "64"。虽然默认情况下，Ceres 会自动检测非基于 Debian/Arch 的 64 位 Linux 发行版，并将 LIB_SUFFIX 默认为 "64"，但可通过在调用 CMake 时手动指定 LIB_SUFFIX 来覆盖此默认值： 调用 CMake 时，可使用 -DLIB_SUFFIX=<VALUE> 手动指定 LIB_SUFFIX 来覆盖。

8.3 Options controlling Ceres dependency locations

Ceres 使用 CMake find_package 函数查找所有依赖项。在所有支持的平台上，如果库提供标准配置文件，那么预计可以在 find_package（Eigen、gflags）的“Config”模式中找到。这意味着您可以使用标准的 CMake 工具来定制这些依赖项的位置，例如 CMAKE_PREFIX_PATH、 <DEPENDENCY_NAME>_DIR 变量，或者自 CMake 3.12 起使用 <DEPENDENCY_NAME>_ROOT 变量。

其他依赖项可使用 "Find<DEPENDENCY_NAME>.cmake "脚本查找，这些脚本要么包含在 Ceres 中（适用于大多数依赖项），要么作为 "CMake "的标准配置随附（适用于 "LAPACK "和 "BLAS"）。这些脚本将为每个依赖项搜索各种操作系统的所有 "标准 "安装位置。不过，特别是对于 Windows，它们可能会找不到库，在这种情况下，您必须手动指定其安装位置。随 Ceres 提供的 Find<DEPENDENCY_NAME>.cmake 脚本支持两种方法：

PreviousWhy Ceres ?NextNon-linear Least Squares

Last updated