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++
