Various small changes. 1. Compact build instructions. 2. Lots of small edits by Simon Fuhrmann. Change-Id: I8c0c67922021041dcf7f4ecdb6c6e6dd2e2fd7e5
diff --git a/docs/Makefile b/docs/Makefile deleted file mode 100644 index fe17b50..0000000 --- a/docs/Makefile +++ /dev/null
@@ -1,153 +0,0 @@ -# Makefile for Sphinx documentation -# - -# You can set these variables from the command line. -SPHINXOPTS = -SPHINXBUILD = sphinx-build -PAPER = -BUILDDIR = build - -# Internal variables. -PAPEROPT_a4 = -D latex_paper_size=a4 -PAPEROPT_letter = -D latex_paper_size=letter -ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) source -# the i18n builder cannot share the environment and doctrees with the others -I18NSPHINXOPTS = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) source - -.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest gettext - -help: - @echo "Please use \`make <target>' where <target> is one of" - @echo " html to make standalone HTML files" - @echo " dirhtml to make HTML files named index.html in directories" - @echo " singlehtml to make a single large HTML file" - @echo " pickle to make pickle files" - @echo " json to make JSON files" - @echo " htmlhelp to make HTML files and a HTML help project" - @echo " qthelp to make HTML files and a qthelp project" - @echo " devhelp to make HTML files and a Devhelp project" - @echo " epub to make an epub" - @echo " latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter" - @echo " latexpdf to make LaTeX files and run them through pdflatex" - @echo " text to make text files" - @echo " man to make manual pages" - @echo " texinfo to make Texinfo files" - @echo " info to make Texinfo files and run them through makeinfo" - @echo " gettext to make PO message catalogs" - @echo " changes to make an overview of all changed/added/deprecated items" - @echo " linkcheck to check all external links for integrity" - @echo " doctest to run all doctests embedded in the documentation (if enabled)" - -clean: - -rm -rf $(BUILDDIR)/* - -html: - $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html - @echo - @echo "Build finished. The HTML pages are in $(BUILDDIR)/html." - -dirhtml: - $(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml - @echo - @echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml." - -singlehtml: - $(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml - @echo - @echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml." - -pickle: - $(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle - @echo - @echo "Build finished; now you can process the pickle files." - -json: - $(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json - @echo - @echo "Build finished; now you can process the JSON files." - -htmlhelp: - $(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp - @echo - @echo "Build finished; now you can run HTML Help Workshop with the" \ - ".hhp project file in $(BUILDDIR)/htmlhelp." - -qthelp: - $(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp - @echo - @echo "Build finished; now you can run "qcollectiongenerator" with the" \ - ".qhcp project file in $(BUILDDIR)/qthelp, like this:" - @echo "# qcollectiongenerator $(BUILDDIR)/qthelp/CeresSolver.qhcp" - @echo "To view the help file:" - @echo "# assistant -collectionFile $(BUILDDIR)/qthelp/CeresSolver.qhc" - -devhelp: - $(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp - @echo - @echo "Build finished." - @echo "To view the help file:" - @echo "# mkdir -p $$HOME/.local/share/devhelp/CeresSolver" - @echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/CeresSolver" - @echo "# devhelp" - -epub: - $(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub - @echo - @echo "Build finished. The epub file is in $(BUILDDIR)/epub." - -latex: - $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex - @echo - @echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex." - @echo "Run \`make' in that directory to run these through (pdf)latex" \ - "(use \`make latexpdf' here to do that automatically)." - -latexpdf: - $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex - @echo "Running LaTeX files through pdflatex..." - $(MAKE) -C $(BUILDDIR)/latex all-pdf - @echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex." - -text: - $(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text - @echo - @echo "Build finished. The text files are in $(BUILDDIR)/text." - -man: - $(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man - @echo - @echo "Build finished. The manual pages are in $(BUILDDIR)/man." - -texinfo: - $(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo - @echo - @echo "Build finished. The Texinfo files are in $(BUILDDIR)/texinfo." - @echo "Run \`make' in that directory to run these through makeinfo" \ - "(use \`make info' here to do that automatically)." - -info: - $(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo - @echo "Running Texinfo files through makeinfo..." - make -C $(BUILDDIR)/texinfo info - @echo "makeinfo finished; the Info files are in $(BUILDDIR)/texinfo." - -gettext: - $(SPHINXBUILD) -b gettext $(I18NSPHINXOPTS) $(BUILDDIR)/locale - @echo - @echo "Build finished. The message catalogs are in $(BUILDDIR)/locale." - -changes: - $(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes - @echo - @echo "The overview file is in $(BUILDDIR)/changes." - -linkcheck: - $(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck - @echo - @echo "Link check complete; look for any errors in the above output " \ - "or in $(BUILDDIR)/linkcheck/output.txt." - -doctest: - $(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest - @echo "Testing of doctests in the sources finished, look at the " \ - "results in $(BUILDDIR)/doctest/output.txt."
diff --git a/docs/make.bat b/docs/make.bat deleted file mode 100644 index 005a432..0000000 --- a/docs/make.bat +++ /dev/null
@@ -1,190 +0,0 @@ -@ECHO OFF - -REM Command file for Sphinx documentation - -if "%SPHINXBUILD%" == "" ( - set SPHINXBUILD=sphinx-build -) -set BUILDDIR=build -set ALLSPHINXOPTS=-d %BUILDDIR%/doctrees %SPHINXOPTS% source -set I18NSPHINXOPTS=%SPHINXOPTS% source -if NOT "%PAPER%" == "" ( - set ALLSPHINXOPTS=-D latex_paper_size=%PAPER% %ALLSPHINXOPTS% - set I18NSPHINXOPTS=-D latex_paper_size=%PAPER% %I18NSPHINXOPTS% -) - -if "%1" == "" goto help - -if "%1" == "help" ( - :help - echo.Please use `make ^<target^>` where ^<target^> is one of - echo. html to make standalone HTML files - echo. dirhtml to make HTML files named index.html in directories - echo. singlehtml to make a single large HTML file - echo. pickle to make pickle files - echo. json to make JSON files - echo. htmlhelp to make HTML files and a HTML help project - echo. qthelp to make HTML files and a qthelp project - echo. devhelp to make HTML files and a Devhelp project - echo. epub to make an epub - echo. latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter - echo. text to make text files - echo. man to make manual pages - echo. texinfo to make Texinfo files - echo. gettext to make PO message catalogs - echo. changes to make an overview over all changed/added/deprecated items - echo. linkcheck to check all external links for integrity - echo. doctest to run all doctests embedded in the documentation if enabled - goto end -) - -if "%1" == "clean" ( - for /d %%i in (%BUILDDIR%\*) do rmdir /q /s %%i - del /q /s %BUILDDIR%\* - goto end -) - -if "%1" == "html" ( - %SPHINXBUILD% -b html %ALLSPHINXOPTS% %BUILDDIR%/html - if errorlevel 1 exit /b 1 - echo. - echo.Build finished. The HTML pages are in %BUILDDIR%/html. - goto end -) - -if "%1" == "dirhtml" ( - %SPHINXBUILD% -b dirhtml %ALLSPHINXOPTS% %BUILDDIR%/dirhtml - if errorlevel 1 exit /b 1 - echo. - echo.Build finished. The HTML pages are in %BUILDDIR%/dirhtml. - goto end -) - -if "%1" == "singlehtml" ( - %SPHINXBUILD% -b singlehtml %ALLSPHINXOPTS% %BUILDDIR%/singlehtml - if errorlevel 1 exit /b 1 - echo. - echo.Build finished. The HTML pages are in %BUILDDIR%/singlehtml. - goto end -) - -if "%1" == "pickle" ( - %SPHINXBUILD% -b pickle %ALLSPHINXOPTS% %BUILDDIR%/pickle - if errorlevel 1 exit /b 1 - echo. - echo.Build finished; now you can process the pickle files. - goto end -) - -if "%1" == "json" ( - %SPHINXBUILD% -b json %ALLSPHINXOPTS% %BUILDDIR%/json - if errorlevel 1 exit /b 1 - echo. - echo.Build finished; now you can process the JSON files. - goto end -) - -if "%1" == "htmlhelp" ( - %SPHINXBUILD% -b htmlhelp %ALLSPHINXOPTS% %BUILDDIR%/htmlhelp - if errorlevel 1 exit /b 1 - echo. - echo.Build finished; now you can run HTML Help Workshop with the ^ -.hhp project file in %BUILDDIR%/htmlhelp. - goto end -) - -if "%1" == "qthelp" ( - %SPHINXBUILD% -b qthelp %ALLSPHINXOPTS% %BUILDDIR%/qthelp - if errorlevel 1 exit /b 1 - echo. - echo.Build finished; now you can run "qcollectiongenerator" with the ^ -.qhcp project file in %BUILDDIR%/qthelp, like this: - echo.^> qcollectiongenerator %BUILDDIR%\qthelp\CeresSolver.qhcp - echo.To view the help file: - echo.^> assistant -collectionFile %BUILDDIR%\qthelp\CeresSolver.ghc - goto end -) - -if "%1" == "devhelp" ( - %SPHINXBUILD% -b devhelp %ALLSPHINXOPTS% %BUILDDIR%/devhelp - if errorlevel 1 exit /b 1 - echo. - echo.Build finished. - goto end -) - -if "%1" == "epub" ( - %SPHINXBUILD% -b epub %ALLSPHINXOPTS% %BUILDDIR%/epub - if errorlevel 1 exit /b 1 - echo. - echo.Build finished. The epub file is in %BUILDDIR%/epub. - goto end -) - -if "%1" == "latex" ( - %SPHINXBUILD% -b latex %ALLSPHINXOPTS% %BUILDDIR%/latex - if errorlevel 1 exit /b 1 - echo. - echo.Build finished; the LaTeX files are in %BUILDDIR%/latex. - goto end -) - -if "%1" == "text" ( - %SPHINXBUILD% -b text %ALLSPHINXOPTS% %BUILDDIR%/text - if errorlevel 1 exit /b 1 - echo. - echo.Build finished. The text files are in %BUILDDIR%/text. - goto end -) - -if "%1" == "man" ( - %SPHINXBUILD% -b man %ALLSPHINXOPTS% %BUILDDIR%/man - if errorlevel 1 exit /b 1 - echo. - echo.Build finished. The manual pages are in %BUILDDIR%/man. - goto end -) - -if "%1" == "texinfo" ( - %SPHINXBUILD% -b texinfo %ALLSPHINXOPTS% %BUILDDIR%/texinfo - if errorlevel 1 exit /b 1 - echo. - echo.Build finished. The Texinfo files are in %BUILDDIR%/texinfo. - goto end -) - -if "%1" == "gettext" ( - %SPHINXBUILD% -b gettext %I18NSPHINXOPTS% %BUILDDIR%/locale - if errorlevel 1 exit /b 1 - echo. - echo.Build finished. The message catalogs are in %BUILDDIR%/locale. - goto end -) - -if "%1" == "changes" ( - %SPHINXBUILD% -b changes %ALLSPHINXOPTS% %BUILDDIR%/changes - if errorlevel 1 exit /b 1 - echo. - echo.The overview file is in %BUILDDIR%/changes. - goto end -) - -if "%1" == "linkcheck" ( - %SPHINXBUILD% -b linkcheck %ALLSPHINXOPTS% %BUILDDIR%/linkcheck - if errorlevel 1 exit /b 1 - echo. - echo.Link check complete; look for any errors in the above output ^ -or in %BUILDDIR%/linkcheck/output.txt. - goto end -) - -if "%1" == "doctest" ( - %SPHINXBUILD% -b doctest %ALLSPHINXOPTS% %BUILDDIR%/doctest - if errorlevel 1 exit /b 1 - echo. - echo.Testing of doctests in the sources finished, look at the ^ -results in %BUILDDIR%/doctest/output.txt. - goto end -) - -:end
diff --git a/docs/source/_themes/armstrong/layout.html b/docs/source/_themes/armstrong/layout.html index 6e9a1f5..3faa34c 100644 --- a/docs/source/_themes/armstrong/layout.html +++ b/docs/source/_themes/armstrong/layout.html
@@ -59,12 +59,6 @@ {%- if last_updated %} {% trans last_updated=last_updated|e %}Last updated on {{ last_updated }}.{% endtrans %} {%- endif %} -{%- if show_sphinx %} - {% trans sphinx_version=sphinx_version|e %}Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> {{ sphinx_version }}.{% endtrans %} -{%- endif %} -{%- if theme_show_rtd %} - {% trans %}<br />Theme based on <a href="http://readthedocs.org/">Read The Docs</a>{% endtrans %} -{% endif %} </div>
diff --git a/docs/source/building.rst b/docs/source/building.rst index 3edcac8..36fecf9 100644 --- a/docs/source/building.rst +++ b/docs/source/building.rst
@@ -4,8 +4,8 @@ Building ======== -Ceres source code and documentation are hosted at -http://code.google.com/p/ceres-solver/ . +Ceres source code and documentation are hosted at `code.google.com +<http://code.google.com/p/ceres-solver/>`_. .. _section-dependencies: @@ -41,10 +41,12 @@ dependency. 6. `CXSparse <http://www.cise.ufl.edu/research/sparse/CXSparse/>`_ is -used for sparse matrix analysis, ordering and factorization. While it -is similar to SuiteSparse in scope, its performance is a bit worse but -is a much simpler library to build and does not have any other -dependencies. This is an optional dependency. +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``. + 7. `BLAS <http://www.netlib.org/blas/>`_ and `LAPACK <http://www.netlib.org/lapack/>`_ routines are needed by @@ -62,73 +64,41 @@ Building on Linux ================= -We will use `Ubuntu <http://www.ubuntu.com>`_ as our example platform. +We will use `Ubuntu <http://www.ubuntu.com>`_ as our example +platform. Start by installing all the dependencies. -#. ``CMake`` +.. code-block:: bash - .. code-block:: bash - - sudo apt-get install cmake - -#. ``gflags`` can either be installed from source via the ``autoconf`` - invocation - - .. code-block:: bash - + # CMake + sudo apt-hey install cmake + # gflags tar -xvzf gflags-2.0.tar.gz cd gflags-2.0 ./configure --prefix=/usr/local make sudo make install. - - - or via the ``deb`` or ``rpm`` packages available on the ``gflags`` website. - -#. ``google-glog`` must be configured to use the previously installed - ``gflags``, rather than the stripped down version that is bundled - with ``google-glog``. Assuming you have it installed in ``/usr/local`` the - following ``autoconf`` invocation installs it. - - .. code-block:: bash - + # 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 - -#. ``Eigen`` - - .. code-block:: bash - - sudo apt-get install libeigen3-dev - -#. ``SuiteSparse`` and ``CXSparse`` - - .. code-block:: bash - - sudo apt-get install libsuitesparse-dev - - This should automatically bring in the necessary ``BLAS`` and - ``LAPACK`` dependencies. By co-incidence on Ubuntu, this also - installs ``CXSparse``. - -#. ``protobuf`` - - .. code-block:: bash - - sudo apt-get install libprotobuf-dev - + # Eigen3 + sudo apt-get install libeigen3-dev + # SuiteSparse and CXSparse + sudo apt-get install libsuitesparse-dev + # protobuf + sudo apt-get install libprotobuf-dev We are now ready to build and test Ceres. Note that ``CMake`` requires the exact path to the ``libglog.a`` and ``libgflag.a``. .. code-block:: bash - tar zxf ceres-solver-1.2.1.tar.gz + tar zxf ceres-solver-1.5.0.tar.gz mkdir ceres-bin cd ceres-bin - cmake ../ceres-solver-1.2.1 + cmake ../ceres-solver-1.5.0 make -j3 make test @@ -139,7 +109,7 @@ .. code-block:: bash bin/simple_bundle_adjuster \ - ../ceres-solver-1.2.1/data/problem-16-22106-pre.txt \ + ../ceres-solver-1.5.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 @@ -200,39 +170,20 @@ ==================== On OS X, we recommend using the `homebrew -<http://mxcl.github.com/homebrew/>`_ package manager. +<http://mxcl.github.com/homebrew/>`_ package manager. Start by +installing all the dependencies. +.. code-block:: bash -#. ``CMake`` - - .. code-block:: bash - + # CMake brew install cmake - -#. ``google-glog`` and ``gflags`` - -Installing ``google-glog`` takes also brings in ``gflags`` as a dependency. - - .. code-block:: bash - + # google-glog and gflags brew install glog - -#. ``Eigen3`` - - .. code-block:: bash - + # Eigen2 brew install eigen - -#. ``SuiteSparse`` and ``CXSparse`` - - .. code-block:: bash - + # SuiteSparse and CXSparse brew install suite-sparse - -#. ``protobuf`` - - .. code-block:: bash - + # protobuf brew install protobuf @@ -240,10 +191,10 @@ .. code-block:: bash - tar zxf ceres-solver-1.2.1.tar.gz + tar zxf ceres-solver-1.5.0.tar.gz mkdir ceres-bin cd ceres-bin - cmake ../ceres-solver-1.2.1 + cmake ../ceres-solver-1.5.0 make -j3 make test @@ -267,7 +218,7 @@ (``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. + 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. @@ -285,7 +236,7 @@ ``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. +#. Try running ``Configure``. It won't work. It'll show a bunch of options. You'll need to set: #. ``GLOG_INCLUDE`` @@ -339,36 +290,36 @@ customize the build process by passing appropriate flags to ``CMake``. Use these flags only if you really know what you are doing. -#. ``-DPROTOBUF=OFF`` : ``protobuf`` is a big dependency and if you do not - care for the tests that depend on it and the logging support it - enables, you can use this flag to turn it off. +#. ``-DPROTOBUF=OFF``: ``protobuf`` is a large and complicated + dependency. If you do not care for the tests that depend on it and + the logging support it enables, you can use this flag to turn it + off. -#. ``-DSUITESPARSE=OFF`` : By default, Ceres will link to +#. ``-DSUITESPARSE=OFF``: By default, Ceres will link to ``SuiteSparse`` if all its dependencies are present. Use this flag - to buils Ceres without ``SuiteSparse``. This will also disable - dependency checking for ``LAPACK`` and ``BLAS`` This saves on + to build Ceres without ``SuiteSparse``. This will also disable + dependency checking for ``LAPACK`` and ``BLAS``. This saves on binary size, but the resulting version of Ceres is not suited to large scale problems due to the lack of a sparse Cholesky solver. This will reduce Ceres' dependencies down to ``Eigen``, ``gflags`` and ``google-glog``. -#. ``-DCXSPARSE=OFF`` : By default, Ceres will link to ``CXSparse`` if all +#. ``-DCXSPARSE=OFF``: By default, Ceres will link to ``CXSparse`` if all its dependencies are present. Use this flag to buils Ceres without ``CXSparse``. This saves on binary size, but the resulting version of Ceres is not suited to large scale problems due to the lack of a sparse Cholesky solver. This will reduce Ceres' dependencies down to ``Eigen``, ``gflags`` and ``google-glog``. -#. ``-DGFLAGS=OFF`` : Use this flag to build Ceres without +#. ``-DGFLAGS=OFF``: Use this flag to build Ceres without ``gflags``. This will also prevent some of the example code from building. -#. ``-DSCHUR_SPECIALIZATIONS=OFF`` : If you are concerned about binary +#. ``-DSCHUR_SPECIALIZATIONS=OFF``: 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 using this flag. -#. ``-DOPENMP=OFF`` : On certain platforms like Android, - multithreading with ``OpenMP`` is not supported. Use this flag to +#. ``-DOPENMP=OFF``: On certain platforms like Android, + multi-threading with ``OpenMP`` is not supported. Use this flag to disable multithreading. -
diff --git a/docs/source/index.rst b/docs/source/index.rst index 8aaeca6..e6ea8ef 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst
@@ -21,5 +21,3 @@ version_history bibliography license - -
diff --git a/docs/source/introduction.rst b/docs/source/introduction.rst index 33d847f..4e9e967 100644 --- a/docs/source/introduction.rst +++ b/docs/source/introduction.rst
@@ -24,7 +24,7 @@ #. Automatic and numeric differentiation. -#. Robust loss functions and Local parameterizations. +#. Robust loss functions and local parameterizations. #. Multithreading. @@ -59,11 +59,12 @@ squares problems, please start by reading the :ref:`chapter-tutorial`. -.. [#f2] While there is some debate as to who invented of the method - of Least Squares [Stigler]_. There is no debate that it was - Carl Friedrich Gauss's prediction of the orbit of the newly - discovered asteroid Ceres based on just 41 days of - observations that brought it to the attention of the world +.. [#f2] While there is some debate as to who invented the method of + Least Squares [Stigler]_, there is no debate that it was Carl + Friedrich brought it to the attention of the world. Using + just 22 observations of the newly discovered asteroid Ceres, + Gauss used the method of least squares to correctly predict + when and where the asteroid will emerge from behind the Sun [TenenbaumDirector]_. We named our solver after Ceres to celebrate this seminal event in the history of astronomy, statistics and optimization.
diff --git a/docs/source/modeling.rst b/docs/source/modeling.rst index ae5cfdf..d17423a 100644 --- a/docs/source/modeling.rst +++ b/docs/source/modeling.rst
@@ -1018,7 +1018,7 @@ functions. These functions are templated so that the user can use them within Ceres Solver's automatic differentiation framework. -.. function:: template<typename T> void AngleAxisToQuaternion(T const* angle_axis, T* quaternion); +.. function:: void AngleAxisToQuaternion<T>(T const* angle_axis, T* quaternion) Convert a value in combined axis-angle representation to a quaternion. @@ -1027,7 +1027,7 @@ and whose direction is aligned with the axis of rotation, and ``quaternion`` is a 4-tuple that will contain the resulting quaternion. -.. function:: template<typename T> void QuaternionToAngleAxis(T const* quaternion, T* angle_axis); +.. function:: void QuaternionToAngleAxis<T>(T const* quaternion, T* angle_axis) Convert a quaternion to the equivalent combined axis-angle representation. @@ -1037,13 +1037,13 @@ whose norm is the angle of rotation in radians, and whose direction is the axis of rotation. -.. function:: template <typename T> void RotationMatrixToAngleAxis(T const * R, T * angle_axis); -.. function:: template <typename T> void AngleAxisToRotationMatrix(T const * angle_axis, T * R); +.. function:: void RotationMatrixToAngleAxis<T>(T const * R, T * angle_axis) +.. function:: void AngleAxisToRotationMatrix<T>(T const * angle_axis, T * R) Conversions between 3x3 rotation matrix (in column major order) and axis-angle rotation representations. -.. function:: template <typename T> void EulerAnglesToRotationMatrix(const T* euler, int row_stride, T* R); +.. function:: void EulerAnglesToRotationMatrix<T>(const T* euler, int row_stride, T* R) Conversions between 3x3 rotation matrix (in row major order) and Euler angle (in degrees) rotation representations. @@ -1052,7 +1052,7 @@ axes, respectively. They are applied in that same order, so the total rotation R is Rz * Ry * Rx. -.. function:: template <typename T> inline void QuaternionToScaledRotation(const T q[4], T R[3 * 3]); +.. function:: void QuaternionToScaledRotation<T>(const T q[4], T R[3 * 3]) Convert a 4-vector to a 3x3 scaled rotation matrix. @@ -1079,12 +1079,12 @@ such that :math:`\det(Q) = 1` and :math:`Q*Q' = I`. -.. function:: template <typename T> inline void QuaternionToRotation(const T q[4], T R[3 * 3]); +.. function:: void QuaternionToRotation<T>(const T q[4], T R[3 * 3]) Same as above except that the rotation matrix is normalized by the Frobenius norm, so that :math:`R R' = I` (and :math:`\det(R) = 1`). -.. function:: template <typename T> inline void UnitQuaternionRotatePoint(const T q[4], const T pt[3], T result[3]); +.. function:: void UnitQuaternionRotatePoint<T>(const T q[4], const T pt[3], T result[3]) Rotates a point pt by a quaternion q: @@ -1095,22 +1095,22 @@ result you get for a unit quaternion. -.. function:: template <typename T> inline void QuaternionRotatePoint(const T q[4], const T pt[3], T result[3]); +.. function:: void QuaternionRotatePoint<T>(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. It does assume that the norm is non-zero. -.. function:: template<typename T> inline void QuaternionProduct(const T z[4], const T w[4], T zw[4]); +.. function:: void QuaternionProduct<T>(const T z[4], const T w[4], T zw[4]) .. math:: zw = z * w - where :math`*` is the Quaternion product between 4-vectors. + where :math:`*` is the Quaternion product between 4-vectors. -.. function:: template<typename T> inline void CrossProduct(const T x[3], const T y[3], T x_cross_y[3]); +.. function:: void CrossProduct<T>(const T x[3], const T y[3], T x_cross_y[3]) .. math:: \text{x_cross_y} = x \times y -.. function:: template<typename T> inline void AngleAxisRotatePoint(const T angle_axis[3], const T pt[3], T result[3]); +.. function:: void AngleAxisRotatePoint<T>(const T angle_axis[3], const T pt[3], T result[3]) .. math:: y = R(\text{angle_axis}) x
diff --git a/docs/source/tutorial.rst b/docs/source/tutorial.rst index df910ef..a8ffc31 100644 --- a/docs/source/tutorial.rst +++ b/docs/source/tutorial.rst
@@ -8,6 +8,11 @@ .. _section-hello-world: +Full working code for all the examples described in this chapter and +more can be found in the `example +<https://ceres-solver.googlesource.com/ceres-solver/+/master/examples/>`_ +directory. + Hello World! ============ @@ -26,7 +31,7 @@ component. When solving a problem with Ceres, the first thing to do is to define -a subclass of CostFunction. It is responsible for computing +a subclass of :class:`CostFunction`. It is responsible for computing the value of the residual function and its derivative (also known as the Jacobian) with respect to :math:`x`. @@ -42,7 +47,7 @@ residuals[0] = 10 - x; // Compute the Jacobian if asked for. - if (jacobians != NULL && jacobians[0] != NULL) { + if (jacobians != NULL) { jacobians[0][0] = -1; } return true; @@ -50,21 +55,22 @@ }; -SimpleCostFunction is provided with an input array of -parameters, an output array for residuals and an optional output array -for Jacobians. In our example, there is just one parameter and one -residual and this is known at compile time, therefore we can save some -code and instead of inheriting from CostFunction, we can -instaed inherit from the templated SizedCostFunction class. +``SimpleCostFunction`` is provided with an input array of +``parameters``, an output array for ``residuals`` and an optional +output array for ``jacobians``. In our example, there is just one +parameter and one residual and this is known at compile time, +therefore we can save some code and instead of inheriting from +:class:`CostFunction`, we can instead inherit from the templated +:class:`SizedCostFunction` class. -The jacobians array is optional, Evaluate is expected to check when it -is non-null, and if it is the case then fill it with the values of the -derivative of the residual function. In this case since the residual -function is linear, the Jacobian is constant. +The ``jacobians`` array is optional, ``Evaluate`` is expected to check +when it is non-null, and if it is the case then fill it with the +values of the derivative of the residual function. In this case since +the residual function is linear, the Jacobian is constant. Once we have a way of computing the residual vector, it is now time to -construct a Non-linear least squares problem using it and have Ceres +construct a non-linear least squares problem using it and have Ceres solve it. .. code-block:: c++ @@ -114,9 +120,9 @@ .. rubric:: Footnotes -.. [#f1] Full working code for this and other - examples in this manual can be found in the examples directory. Code - for this example can be found in ``examples/quadratic.cc``. +.. [#f1] Full working code for this example can found in + `examples/quadratic.cc + <https://ceres-solver.googlesource.com/ceres-solver/+/master/examples/quadratic.cc>`_ .. [#f2] Actually the solver ran for three iterations, and it was by looking at the value returned by the linear solver in the third @@ -165,7 +171,7 @@ residuals[0] = sqrt(10.0) * (x1 - x4) * (x1 - x4) - if (jacobians != NULL) { + if (jacobians != NULL && jacobians[0] != NULL) { jacobians[0][0] = 2.0 * sqrt(10.0) * (x1 - x4); jacobians[0][1] = 0.0; jacobians[0][2] = 0.0; @@ -211,10 +217,10 @@ Note also that the parameters are not packed into a single array, they are instead passed as separate arguments to -``operator()``. Similarly we can define classes ``F1``,``F2`` +``operator()``. Similarly we can define classes ``F1``, ``F2`` and ``F4``. Then let us consider the construction and solution of the problem. For brevity we only describe the relevant bits of -code [#f3]_ . +code [#f3]_. .. code-block:: c++ @@ -302,21 +308,22 @@ numerically differentiated implementation of ``examples/quadratic.cc``. -**We recommend that if possible, automatic differentiation should be -used. The use of C++ templates makes automatic differentiation -extremely efficient, whereas numeric differentiation can be quite -expensive, prone to numeric errors and leads to slower convergence.** +**We recommend automatic differentiation if possible. The use of C++ +templates makes automatic differentiation extremely efficient, whereas +numeric differentiation can be quite expensive, prone to numeric +errors and leads to slower convergence.** .. rubric:: Footnotes -.. [#f3] The full source code for this example can be found in ``examples/powell.cc``. +.. [#f3] The full source code for this example can be found in +.. `examples/powell.cc +.. <https://ceres-solver.googlesource.com/ceres-solver/+/master/examples/powell.cc>`_. .. _section-fitting: -Fitting a Curve to Data -======================= - +Curve Fitting +============= The examples we have seen until now are simple optimization problems with no data. The original purpose of least squares and non-linear @@ -324,7 +331,7 @@ appropriate that we now consider an example of such a problem [#f4]_. It contains data generated by sampling the curve :math:`y = e^{0.3x + 0.1}` and adding Gaussian noise with standard deviation -:math:`\sigma = 0.2`.}. Let us fit some data to the curve +:math:`\sigma = 0.2`. Let us fit some data to the curve .. math:: y = e^{mx + c}. @@ -356,7 +363,7 @@ ``CostFunction`` for every observation. -.. code-block: c++ +.. code-block:: c++ double m = 0.0; double c = 0.0; @@ -531,7 +538,7 @@ this is a reasonable thing to do, bundle adjustment problems have a special sparsity structure that can be exploited to solve them much more efficiently. Ceres provides three specialized solvers -(collectively known as Schur based solvers) for this task. The example +(collectively known as Schur-based solvers) for this task. The example code uses the simplest of them ``DENSE_SCHUR``. .. code-block:: c++