diff --git a/docs/source/building.rst b/docs/source/building.rst index 4860b0d7f..a34c1fcdb 100644 --- a/docs/source/building.rst +++ b/docs/source/building.rst @@ -500,7 +500,7 @@ Options controlling Ceres configuration #. ``OPENMP [Default: ON]``: On certain platforms like Android, multi-threading with ``OpenMP`` is not supported. Turn this ``OFF`` - to disable multithreading. + to disable multi-threading. #. ``BUILD_SHARED_LIBS [Default: OFF]``: By default Ceres is built as a static library, turn this ``ON`` to instead build Ceres as a @@ -623,7 +623,7 @@ 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., +the **PATHS** option to the ``FIND_PACKAGE()`` command, e.g., .. code-block:: cmake diff --git a/docs/source/contributing.rst b/docs/source/contributing.rst index b169dbfb4..fa36d2ceb 100644 --- a/docs/source/contributing.rst +++ b/docs/source/contributing.rst @@ -114,7 +114,7 @@ Submitting a change git push origin HEAD:refs/for/master When the push succeeds, the console will display a URL showing the - address of the review. Go to the URL and add atleast one of the + address of the review. Go to the URL and add at least one of the maintainers (Sameer Agarwal, Keir Mierle, or Alex Stewart) as reviewers. 3. Wait for a review. diff --git a/docs/source/index.rst b/docs/source/index.rst index 26b318a2f..0349eb9ca 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -35,7 +35,7 @@ since 2010. At Google, Ceres Solver is used to: * Solve `bundle adjustment`_ and SLAM problems in `Project Tango`_. Outside Google, Ceres is used for solving problems in computer vision, -computer graphics, astronomy and physics. e.g., `Willow Garage`_ uses +computer graphics, astronomy and physics. For example, `Willow Garage`_ uses it to solve SLAM problems and `Blender`_ uses it for for planar tracking and bundle adjustment. diff --git a/docs/source/modeling.rst b/docs/source/modeling.rst index 4b333c4ce..b88d62e18 100644 --- a/docs/source/modeling.rst +++ b/docs/source/modeling.rst @@ -758,8 +758,8 @@ the corresponding accessors. This information will be verified by the .. math:: cost(x) = ||A(x - b)||^2 - where, the matrix A and the vector b are fixed and x is the - variable. In case the user is interested in implementing a cost + where, the matrix :math:`A` and the vector :math:`b` are fixed and :math:`x` + is the variable. In case the user is interested in implementing a cost function of the form .. math:: cost(x) = (x - \mu)^T S^{-1} (x - \mu) @@ -913,7 +913,7 @@ their shape graphically. More details can be found in Given a loss function :math:`\rho(s)` and a scalar :math:`a`, :class:`ScaledLoss` implements the function :math:`a \rho(s)`. - Since we treat the a ``NULL`` Loss function as the Identity loss + Since we treat a ``NULL`` Loss function as the Identity loss function, :math:`rho` = ``NULL``: is a valid input and will result in the input being scaled by :math:`a`. This provides a simple way of implementing a scaled ResidualBlock. @@ -930,7 +930,7 @@ their shape graphically. More details can be found in This templated class allows the user to implement a loss function whose scale can be mutated after an optimization problem has been - constructed. e.g, + constructed, e.g, .. code-block:: c++ @@ -1141,7 +1141,7 @@ Instances .. math:: x' = \boxplus(x, \Delta x), For example, Quaternions have a three dimensional local - parameterization. It's plus operation can be implemented as (taken + parameterization. Its plus operation can be implemented as (taken from `internal/ceres/autodiff_local_parameterization_test.cc `_ ) @@ -1178,7 +1178,7 @@ Instances } }; - Then given this struct, the auto differentiated local + Given this struct, the auto differentiated local parameterization can now be constructed as .. code-block:: c++ @@ -1619,7 +1619,7 @@ within Ceres Solver's automatic differentiation framework. .. function:: void QuaternionRotatePoint(const T q[4], const T pt[3], T result[3]) - With this function you do not need to assume that q has unit norm. + With this function you do not need to assume that :math:`q` has unit norm. It does assume that the norm is non-zero. .. function:: void QuaternionProduct(const T z[4], const T w[4], T zw[4]) diff --git a/docs/source/solving.rst b/docs/source/solving.rst index 91713e03b..c80e88d58 100644 --- a/docs/source/solving.rst +++ b/docs/source/solving.rst @@ -13,7 +13,7 @@ Introduction ============ Effective use of Ceres requires some familiarity with the basic -components of a nonlinear least squares solver, so before we describe +components of a non-linear least squares solver, so before we describe how to configure and use the solver, we will take a brief look at how some of the core optimization algorithms in Ceres work. @@ -21,7 +21,7 @@ Let :math:`x \in \mathbb{R}^n` be an :math:`n`-dimensional vector of variables, and :math:`F(x) = \left[f_1(x), ... , f_{m}(x) \right]^{\top}` be a :math:`m`-dimensional function of :math:`x`. We are interested in -solving the following optimization problem [#f1]_ . +solving the optimization problem [#f1]_ .. math:: \arg \min_x \frac{1}{2}\|F(x)\|^2\ . \\ L \le x \le U @@ -120,8 +120,8 @@ of the constrained optimization problem :label: trp There are a number of different ways of solving this problem, each -giving rise to a different concrete trust-region algorithm. Currently -Ceres, implements two trust-region algorithms - Levenberg-Marquardt +giving rise to a different concrete trust-region algorithm. Currently, +Ceres implements two trust-region algorithms - Levenberg-Marquardt and Dogleg, each of which is augmented with a line search if bounds constraints are present [Kanzow]_. The user can choose between them by setting :member:`Solver::Options::trust_region_strategy_type`. @@ -247,7 +247,7 @@ entire two dimensional subspace spanned by these two vectors and finds the point that minimizes the trust region problem in this subspace [ByrdSchnabel]_. -The key advantage of the Dogleg over Levenberg Marquardt is that if +The key advantage of the Dogleg over Levenberg-Marquardt is that if the step computation for a particular choice of :math:`\mu` does not result in sufficient decrease in the value of the objective function, Levenberg-Marquardt solves the linear approximation from scratch with @@ -265,7 +265,7 @@ Inner Iterations Some non-linear least squares problems have additional structure in the way the parameter blocks interact that it is beneficial to modify -the way the trust region step is computed. e.g., consider the +the way the trust region step is computed. For example, consider the following regression problem .. math:: y = a_1 e^{b_1 x} + a_2 e^{b_3 x^2 + c_1} @@ -521,7 +521,7 @@ turn implies that the matrix :math:`H` is of the form .. math:: H = \left[ \begin{matrix} B & E\\ E^\top & C \end{matrix} \right]\ , :label: hblock -where, :math:`B \in \mathbb{R}^{pc\times pc}` is a block sparse matrix +where :math:`B \in \mathbb{R}^{pc\times pc}` is a block sparse matrix with :math:`p` blocks of size :math:`c\times c` and :math:`C \in \mathbb{R}^{qs\times qs}` is a block diagonal matrix with :math:`q` blocks of size :math:`s\times s`. :math:`E \in \mathbb{R}^{pc\times qs}` is a @@ -560,7 +560,7 @@ c`. The block :math:`S_{ij}` corresponding to the pair of images observe at least one common point. -Now, eq-linear2 can be solved by first forming :math:`S`, solving for +Now, :eq:`linear2` can be solved by first forming :math:`S`, solving for :math:`\Delta y`, and then back-substituting :math:`\Delta y` to obtain the value of :math:`\Delta z`. Thus, the solution of what was an :math:`n\times n`, :math:`n=pc+qs` linear system is reduced to the @@ -622,7 +622,7 @@ Another option for bundle adjustment problems is to apply PCG to the reduced camera matrix :math:`S` instead of :math:`H`. One reason to do this is that :math:`S` is a much smaller matrix than :math:`H`, but more importantly, it can be shown that :math:`\kappa(S)\leq -\kappa(H)`. Cseres implements PCG on :math:`S` as the +\kappa(H)`. Ceres implements PCG on :math:`S` as the ``ITERATIVE_SCHUR`` solver. When the user chooses ``ITERATIVE_SCHUR`` as the linear solver, Ceres automatically switches from the exact step algorithm to an inexact step algorithm. @@ -709,7 +709,7 @@ these preconditioners and refers to them as ``JACOBI`` and For bundle adjustment problems arising in reconstruction from community photo collections, more effective preconditioners can be constructed by analyzing and exploiting the camera-point visibility -structure of the scene [KushalAgarwal]. Ceres implements the two +structure of the scene [KushalAgarwal]_. Ceres implements the two visibility based preconditioners described by Kushal & Agarwal as ``CLUSTER_JACOBI`` and ``CLUSTER_TRIDIAGONAL``. These are fairly new preconditioners and Ceres' implementation of them is in its early @@ -747,14 +747,14 @@ Given such an ordering, Ceres ensures that the parameter blocks in the lowest numbered elimination group are eliminated first, and then the parameter blocks in the next lowest numbered elimination group and so on. Within each elimination group, Ceres is free to order the -parameter blocks as it chooses. e.g. Consider the linear system +parameter blocks as it chooses. For example, consider the linear system .. math:: x + y &= 3\\ 2x + 3y &= 7 There are two ways in which it can be solved. First eliminating -:math:`x` from the two equations, solving for y and then back +:math:`x` from the two equations, solving for :math:`y` and then back substituting for :math:`x`, or first eliminating :math:`y`, solving for :math:`x` and back substituting for :math:`y`. The user can construct three orderings here. @@ -1001,7 +1001,7 @@ elimination group [LiSaad]_. During the bracketing phase of a Wolfe line search, the step size is increased until either a point satisfying the Wolfe conditions - is found, or an upper bound for a bracket containinqg a point + is found, or an upper bound for a bracket containing a point satisfying the conditions is found. Precisely, at each iteration of the expansion: @@ -1094,7 +1094,7 @@ elimination group [LiSaad]_. Default: ``1e6`` The ``LEVENBERG_MARQUARDT`` strategy, uses a diagonal matrix to - regularize the the trust region step. This is the lower bound on + regularize the trust region step. This is the lower bound on the values of this diagonal matrix. .. member:: double Solver::Options::max_lm_diagonal @@ -1102,7 +1102,7 @@ elimination group [LiSaad]_. Default: ``1e32`` The ``LEVENBERG_MARQUARDT`` strategy, uses a diagonal matrix to - regularize the the trust region step. This is the upper bound on + regularize the trust region step. This is the upper bound on the values of this diagonal matrix. .. member:: int Solver::Options::max_num_consecutive_invalid_steps @@ -1347,7 +1347,7 @@ elimination group [LiSaad]_. on each Newton/Trust region step using a coordinate descent algorithm. For more details, see :ref:`section-inner-iterations`. -.. member:: double Solver::Options::inner_itearation_tolerance +.. member:: double Solver::Options::inner_iteration_tolerance Default: ``1e-3`` @@ -1410,7 +1410,7 @@ elimination group [LiSaad]_. #. ``|gradient|`` is the max norm of the gradient. #. ``|step|`` is the change in the parameter vector. #. ``tr_ratio`` is the ratio of the actual change in the objective - function value to the change in the the value of the trust + function value to the change in the value of the trust region model. #. ``tr_radius`` is the size of the trust region radius. #. ``ls_iter`` is the number of linear solver iterations used to @@ -1419,7 +1419,7 @@ elimination group [LiSaad]_. ``ITERATIVE_SCHUR`` it is the number of iterations of the Conjugate Gradients algorithm. #. ``iter_time`` is the time take by the current iteration. - #. ``total_time`` is the the total time taken by the minimizer. + #. ``total_time`` is the total time taken by the minimizer. For ``LINE_SEARCH_MINIMIZER`` the progress display looks like @@ -1438,7 +1438,7 @@ elimination group [LiSaad]_. #. ``h`` is the change in the parameter vector. #. ``s`` is the optimal step length computed by the line search. #. ``it`` is the time take by the current iteration. - #. ``tt`` is the the total time taken by the minimizer. + #. ``tt`` is the total time taken by the minimizer. .. member:: vector Solver::Options::trust_region_minimizer_iterations_to_dump @@ -1530,7 +1530,7 @@ elimination group [LiSaad]_. Callbacks that are executed at the end of each iteration of the :class:`Minimizer`. They are executed in the order that they are specified in this vector. By default, parameter blocks are updated - only at the end of the optimization, i.e when the + only at the end of the optimization, i.e., when the :class:`Minimizer` terminates. This behavior is controlled by :member:`Solver::Options::update_state_every_variable`. If the user wishes to have access to the update parameter blocks when his/her @@ -1840,7 +1840,7 @@ elimination group [LiSaad]_. ``values[rows[i]]`` ... ``values[rows[i + 1] - 1]`` are the values of the non-zero columns of row ``i``. -e.g, consider the 3x4 sparse matrix +e.g., consider the 3x4 sparse matrix .. code-block:: c++ @@ -2078,7 +2078,7 @@ The three arrays will be: `True` if the user asked for inner iterations to be used as part of the optimization and the problem structure was such that they were - actually performed. e.g., in a problem with just one parameter + actually performed. For example, in a problem with just one parameter block, inner iterations are not performed. .. member:: vector inner_iteration_ordering_given diff --git a/docs/source/tutorial.rst b/docs/source/tutorial.rst index 79714f6ad..2d8da68ab 100644 --- a/docs/source/tutorial.rst +++ b/docs/source/tutorial.rst @@ -527,7 +527,7 @@ gives us: Starting from parameter values :math:`m = 0, c=0` with an initial objective function value of :math:`121.173` Ceres finds a solution :math:`m= 0.291861, c = 0.131439` with an objective function value of -:math:`1.05675`. These values are a a bit different than the +:math:`1.05675`. These values are a bit different than the parameters of the original model :math:`m=0.3, c= 0.1`, but this is expected. When reconstructing a curve from noisy data, we expect to see such deviations. Indeed, if you were to evaluate the objective @@ -562,9 +562,9 @@ below. Notice how the fitted curve deviates from the ground truth. :align: center To deal with outliers, a standard technique is to use a -:class:`LossFunction`. Loss functions, reduce the influence of +:class:`LossFunction`. Loss functions reduce the influence of residual blocks with high residuals, usually the ones corresponding to -outliers. To associate a loss function in a residual block, we change +outliers. To associate a loss function with a residual block, we change .. code-block:: c++