Merge landing page with introduction.

The existing introduction was a bit redundant and also
was not really an introduction. Also updated the build
instructions to reflect the new reality on Mac OSX.

Also updated the beginning of the tutorial to be a bit
gentler and updated the history to be more consistent

Change-Id: Ife38c1949252cf9f4c6301856957f2d38365f313

docs/source/about.rst

@@ -1,46 +0,0 @@
-.. _chapter-about:
-
-=====
-About
-=====
-
-Ceres Solver grew out of the need for general least squares solving at Google.
-Around 2010, Sameer Agarwal and Keir Mierle decided to replace a custom bundle
-adjuster at Google with something more modern. After two years of on-and-off
-development, Ceres Solver was released as open source in May of 2012.
-
-Acknowledgements
-----------------
-
-A number of people have helped with the development and open sourcing
-of Ceres.
-
-Fredrik Schaffalitzky when he was at Google started the development of
-Ceres, and even though much has changed since then, many of the ideas
-from his original design are still present in the current code.
-
-Amongst Ceres' users at Google two deserve special mention: William
-Rucklidge and James Roseborough. William was the first user of
-Ceres. He bravely took on the task of porting production code to an
-as-yet unproven optimization library, reporting bugs and helping fix
-them along the way. James is perhaps the most sophisticated user of
-Ceres at Google. He has reported and fixed bugs and helped evolve the
-API for the better.
-
-Since the initial release of Ceres, a number of people have
-contributed to Ceres by porting it to new platforms, reporting bugs,
-fixing bugs and adding new functionality. We acknowledge all of these
-contributions in the :ref:`chapter-version-history`.
-
-Origin of the name Ceres Solver
--------------------------------
-While there is some debate as to who invented the method of Least Squares
-[Stigler]_, there is no debate that it was `Carl Friedrich Gauss
-<http://en.wikipedia.org/wiki/Carl_Friedrich_Gauss>`_ who brought it to the
-attention of the world. Using just 22 observations of the newly discovered
-asteroid `Ceres <http://en.wikipedia.org/wiki/Ceres_(dwarf_planet)>`_, 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.
-

docs/source/building.rst

@@ -1,13 +1,19 @@
 .. _chapter-building:
 
-=====================
-Building & Installing
-=====================
+=======================
+Building & Installation
+=======================
+
+Getting the source code
+=======================
+.. _section-source:
+
+You can start with the `latest stable release
+<http://ceres-solver.org/ceres-solver-1.8.0.tar.gz>`_ . Or if you want
+the latest version, you can clone the git repository
+  .. code-block:: bash
 
-Stable Ceres Solver releases are available for download at
-`code.google.com <http://code.google.com/p/ceres-solver/>`_. For the
-more adventurous, the git repository is hosted on `Gerrit
-<https://ceres-solver-review.googlesource.com/>`_.
+       git clone https://ceres-solver.googlesource.com/ceres-solver
 
 .. _section-dependencies:
 
@@ -185,21 +191,36 @@ this.
 
 Building on Mac OS X
 ====================
-
-On OS X, we recommend using the `homebrew
-<http://mxcl.github.com/homebrew/>`_ package manager to install the
-dependencies. There is no need to install ``BLAS`` or ``LAPACK``
-separately as OS X ships with optimized ``BLAS`` and ``LAPACK``
-routines as part of the `vecLib
-<https://developer.apple.com/library/mac/#documentation/Performance/Conceptual/vecLib/Reference/reference.html>`_
-framework.
-
 .. NOTE::
 
  Ceres will not compile using Xcode 4.5.x (Clang version 4.1) due to a bug in that version of
  Clang.  If you are running Xcode 4.5.x, please update to Xcode >= 4.6.x before attempting to
  build Ceres.
 
+
+On OS X, we recommend using the `homebrew
+<http://mxcl.github.com/homebrew/>`_ package manager to install Ceres.
+
+.. 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.
+
+You can also install each of the dependencies by hand using `homebrew
+<http://mxcl.github.com/homebrew/>`_. There is no need to install
+``BLAS`` or ``LAPACK`` separately as OS X ships with optimized
+``BLAS`` and ``LAPACK`` routines as part of the `vecLib
+<https://developer.apple.com/library/mac/#documentation/Performance/Conceptual/vecLib/Reference/reference.html>`_
+framework.
+
 .. code-block:: bash
 
       # CMake
@@ -211,7 +232,6 @@ framework.
       # SuiteSparse and CXSparse
       brew install suite-sparse
 
-
 We are now ready to build and test Ceres.
 
 .. code-block:: bash
@@ -223,7 +243,6 @@ We are now ready to build and test Ceres.
    make -j3
    make test
 
-
 Like the Linux build, you should now be able to run
 ``bin/simple_bundle_adjuster``.
 

docs/source/features.rst

@@ -0,0 +1,92 @@
+========
+Features
+========
+.. _chapter-features:
+
+* **Code Quality** - Ceres Solver has been used in production at
+  Google for more than three years now. It is used to solve a wide
+  variety of problems, both in size and complexity. The code runs on
+  Google's data centers, desktops and on cellphones. It is clean,
+  extensively tested and well documented code that is actively
+  developed and supported.
+
+* **Modeling API** - It is rarely the case that one starts with the
+  exact and complete formulation of the problem that one is trying to
+  solve. Ceres's modeling API has been designed so that the user can
+  easily build and modify the objective function, one term at a
+  time. And to do so without worrying about how the solver is going to
+  deal with the resulting changes in the sparsity/structure of the
+  underlying problem. Indeed we take great care to separate the
+  modeling of the optimization problem from solving it. The two can be
+  done more or less completely independently of each other.
+
+  - **Derivatives** Supplying derivatives is perhaps the most tedious
+    and error prone part of using an optimization library.  Ceres
+    ships with `automatic`_ and `numeric`_ differentiation. So you
+    never have to compute derivatives by hand (unless you really want
+    to). Not only this, Ceres allows you to mix automatic, numeric and
+    analytical derivatives in any combination that you want.
+
+  - **Robust Loss Functions** Most non-linear least squares problems
+    involve data. If there is data, there will be outliers. Ceres
+    allows the user to *shape* their residuals using robust loss
+    functions to reduce the influence of outliers.
+
+  - **Local Parameterization** In many cases, some parameters lie on a
+    manifold other than Euclidean space, e.g., rotation matrices. In
+    such cases, the user can specify the geometry of the local tangent
+    space by specifying a LocalParameterization object.
+
+* **Solver Choice** Depending on the size, sparsity structure, time &
+  memory budgets, and solution quality requiremnts, different
+  optimization algorithms will suit different needs. To this end,
+  Ceres Solver comes with a variety of optimization algorithms, some
+  of them the result of the author's own research.
+
+  - **Trust Region Solvers** - Ceres supports Levenberg-Marquardt,
+    Powell's Dogleg, and Subspace dogleg methods. The key
+    computational cost in all of these methods is the solution of a
+    linear system. To this end Ceres ships with a variety of linear
+    solvers - dense QR and dense Cholesky factorization (using
+    `Eigen`_ or `LAPACK`_) for dense problems, sparse Cholesky
+    factorization (`SuiteSparse`_ or `CXSparse`_) for large sparse
+    problems custom Schur complement based dense, sparse, and
+    iterative linear solvers for `bundle adjustment`_ problems.
+
+  - **Line Search Solvers** - When the problem size is so large that
+    storing and factoring the Jacobian is not feasible or a low
+    accuracy solution is required cheaply, Ceres offers a number of
+    line search based algorithms. This includes a number of variants
+    of Non-linear Conjugate Gradients, BFGS and LBFGS.
+
+* **Speed** - Ceres code has been extensively optimized, with C++
+  templating, hand written linear algebra routines and OpenMP based
+  multithreading of the Jacobian evaluation and the linear solvers.
+
+* **Solution Quality** Ceres is the best performing solver on the NIST
+  problem set used by Mondragon and Borchers for benchmarking
+  non-linear least squares solvers.
+
+* **Covariance estimation** - Evaluate the sensitivity/uncertainty of
+  the solution by evaluating all or part of the covariance
+  matrix. Ceres is one of the few solvers that allows you to to do
+  this analysis at scale.
+
+* **Community** Since its release as an open source software, Ceres
+  has developed an active developer community that contributes new
+  features, bug fixes and support.
+
+* **Portability** - Runs on *Linux*, *Windows*, *Mac OS X*, *Android*
+  *and iOS*.
+
+* **BSD Licensed** The BSD license offers the flexibility to ship your
+  application
+
+.. _solution quality: https://groups.google.com/forum/#!topic/ceres-solver/UcicgMPgbXw
+.. _bundle adjustment: http://en.wikipedia.org/wiki/Bundle_adjustment
+.. _SuiteSparse: http://www.cise.ufl.edu/research/sparse/SuiteSparse/
+.. _Eigen: http://eigen.tuxfamily.org/
+.. _LAPACK: http://www.netlib.org/lapack/
+.. _CXSparse: https://www.cise.ufl.edu/research/sparse/CXSparse/
+.. _automatic: http://en.wikipedia.org/wiki/Automatic_differentiation
+.. _numeric: http://en.wikipedia.org/wiki/Numerical_differentiation

docs/source/history.rst

@@ -0,0 +1,27 @@
+.. _chapter-history:
+
+=======
+History
+=======
+
+Ceres Solver grew out of the need for general least squares solving at
+Google. In early 2010, Sameer Agarwal and Fredrik Schaffalitzky
+started the development of Ceres Solver. Fredrik left Google shortly
+thereafter and Keir Mierle stepped in to take his place. After two
+years of on-and-off development, Ceres Solver was released as open
+source in May of 2012.
+
+Origin of the name
+------------------
+
+While there is some debate as to who invented the method of Least
+Squares [Stigler]_, there is no debate that it was `Carl Friedrich
+Gauss
+<http://www-groups.dcs.st-and.ac.uk/~history/Biographies/Gauss.html>`_
+who brought it to the attention of the world. Using just 22
+observations of the newly discovered asteroid `Ceres
+<http://en.wikipedia.org/wiki/Ceres_(dwarf_planet)>`_, 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.

docs/source/index.rst

@@ -11,7 +11,7 @@ Ceres Solver
    :maxdepth: 3
    :hidden:
 
-   introduction
+   features
    building
    tutorial
    modeling
@@ -19,41 +19,43 @@ Ceres Solver
    faqs
    contributing
    version_history
-   about
+   history
    bibliography
    license
 
-Ceres Solver is an industrial-grade C++ library for modeling and
-solving `nonlinear least squares`_ problems. These problems comes up
-in a broad range of areas across science and engineering - from
-`fitting curves`_ in statistics, to constructing `3D models from
-photographs`_ in computer vision.
+Ceres Solver is an open source C++ library for modeling and solving
+large complicated `nonlinear least squares`_ problems. It is a feature
+rich, mature and performant library which has been used in production
+since 2010. At Google, Ceres Solver is used to:
 
-Ceres Solver features an integrated modeling layer with automatic
-differentiation (you can also use numeric and/or analytic
-derivatives), well optimized code with extensive tests and state of
-the art performance on a variety of problems.
+* Estimate the pose of `Street View`_ cars, aircrafts, and satellites.
+* Build 3D models for `PhotoTours`_.
+* Estmate satellite image sensor characteristics.
+* Stitch `panoramas`_ or apply `Lens Blur`_ on Android.
+* Solve `bundle adjustment`_ and SLAM problems in `Project Tango`_.
 
-Ceres Solver is used in Google `Street View`_, Google `PhotoTours`_,
-Google `PhotoSphere`_, `Project Tango`_, `Blender`_, and more.
+Outside Google, Ceres is used for solving problems in computer vision,
+computer graphics, astronomy and physics. e.g., `Willow Garage`_ uses
+it to solve SLAM problems and `Blender`_ uses it for for planar
+tracking and bundle adjustment.
 
 .. _nonlinear least squares: http://en.wikipedia.org/wiki/Non-linear_least_squares
 .. _fitting curves: http://en.wikipedia.org/wiki/Nonlinear_regression
-.. _3D models from photographs: http://en.wikipedia.org/wiki/Structure_from_motion
+.. _bundle adjustment: http://en.wikipedia.org/wiki/Structure_from_motion
 .. _Street View: http://youtu.be/z00ORu4bU-A
 .. _PhotoTours: http://google-latlong.blogspot.com/2012/04/visit-global-landmarks-with-photo-tours.html
-.. _PhotoSphere: http://www.google.com/maps/about/contribute/photosphere/
+.. _panoramas: http://www.google.com/maps/about/contribute/photosphere/
 .. _Project Tango: https://www.google.com/atap/projecttango/
 .. _Blender: http://mango.blender.org/development/planar-tracking-preview/
+.. _Willow Garage: https://www.willowgarage.com/blog/2013/08/09/enabling-robots-see-better-through-improved-camera-calibration
+.. _Lens Blur: http://googleresearch.blogspot.com/2014/04/lens-blur-in-new-google-camera-app.html
 
 Getting started
 ---------------
 
 * Download the `latest stable release
-  <http://ceres-solver.org/ceres-solver-1.8.0.tar.gz>`_
-  or, for those wanting the latest
-* Clone the development version or `browse the source
-  <https://ceres-solver.googlesource.com/ceres-solver>`_
+  <http://ceres-solver.org/ceres-solver-1.8.0.tar.gz>`_ or clone the
+  Git repository for the latest development version.
 
   .. code-block:: bash
 

docs/source/introduction.rst

@@ -1,71 +0,0 @@
-.. _chapter-introduction:
-
-============
-Introduction
-============
-
-What is Ceres Solver?
----------------------
-Ceres is an industrial-grade C++ library for modeling and solving large and
-small nonlinear least squares problems of the form
-
-.. math:: \frac{1}{2}\sum_{i} \rho_i\left(\left\|f_i\left(x_{i_1}, ... ,x_{i_k}\right)\right\|^2\right).
-
-For a brief introduction to nonlinear solving in general, see the
-:ref:`chapter-tutorial`.
-
-Who uses Ceres Solver?
-----------------------
-
-* `Google Street View`_ panorama poses are computed with Ceres (`see video`_)
-* `Google Photo Tours`_ employ Ceres to pose all the photos
-* `Google Maps and Earth`_ imagery spatial alignment and satellite sensor calibration is done with Ceres
-* `Project Tango`_ uses Ceres as part of the SLAM pipeline
-* `Willow Garage's`_ SLAM pipeline uses Ceres for realtime bundle adjustment
-* `Android`_ uses Ceres for image processing and stitching, including for `Photo Sphere`_
-* `Blender's`_ `motion tracking module`_ depends critically on Ceres, using it
-  for 2D tracking, 3D reconstruction, panorama tracking, plane tracking, and
-  more; see the results in `Tears of Steel`_
-
-.. _Google Street View: http://www.google.com/maps/about/behind-the-scenes/streetview/
-.. _see video: https://www.youtube.com/watch?v=z00ORu4bU-A
-.. _Google Photo Tours: http://googlesystem.blogspot.com/2012/04/photo-tours-in-google-maps.html
-.. _Google Maps and Earth: http://www.google.com/earth/
-.. _Project Tango: https://www.google.com/atap/projecttango/
-.. _Willow Garage's: https://www.willowgarage.com/blog/2013/08/09/enabling-robots-see-better-through-improved-camera-calibration
-.. _Android: https://android.googlesource.com/platform/external/ceres-solver/
-.. _Photo Sphere: http://www.google.com/maps/about/contribute/photosphere/
-.. _Blender's: http://blender.org
-.. _motion tracking module: http://wiki.blender.org/index.php/Doc:2.6/Manual/Motion_Tracking
-.. _Tears of Steel: http://mango.blender.org/
-
-Why use Ceres Solver?
----------------------
-* Ceres has an **integrated modelling layer**, making it easy and intutive to
-  model large, complex cost functions with interacting terms, such as a moving
-  vehicle with multiple sensors and tricky dynamics.
-* Ceres has **integrated automatic differentiation**, avoiding the error-prone
-  task of manually computing derivatives.
-* Ceres can model a **wide variety of problems**, beyond simple nonlinear least
-  squares, thanks to robust loss functions and local parameterizations (e.g.
-  for quaternions).
-* Ceres is **very fast**, thanks to threaded cost function evaluators, threaded linear
-  solvers, and generous amounts of engineering time spent optimizing.
-* Ceres has **multiple nonlinear solvers** including trust region (fast, uses
-  more memory) and line search (slower, uses less memory).
-* Ceres has **multiple linear solvers** for both sparse and dense systems,
-  leveraging Eigen or MKL for dense solving, CHOLMOD or CXSparse for sparse
-  solving, and specialized linear solvers for bundle adjustment.
-* Ceres has **thorough automated tests** ensuring it is high-quality
-* Ceres is **industrial grade** thanks to **many compute-years** spent
-  running its code, analyzing the results, and improving it.
-* Ceres has **world-class solution quality**, with the best known results of
-  any least squares solver on the `NIST least squares precision benchmark`_.
-* Ceres has an **active community** encouraging contributions and mentoring
-  those starting out.
-* Ceres runs on **many platforms** including Linux, Windows, Mac OS X, Android, and
-  iOS (sort of).
-* Ceres is **liberally licensed (BSD)** so that you can use it freely in
-  commercial applications without releasing your code.
-
-.. _NIST least squares precision benchmark: https://groups.google.com/forum/#!topic/ceres-solver/UcicgMPgbXw

docs/source/tutorial.rst

@@ -12,6 +12,19 @@ Ceres solves robustified non-linear least squares problems of the form
 .. math:: \frac{1}{2}\sum_{i} \rho_i\left(\left\|f_i\left(x_{i_1}, ... ,x_{i_k}\right)\right\|^2\right).
    :label: ceresproblem
 
+Problems of this form comes up in a broad range of areas across
+science and engineering - from `fitting curves`_ in statistics, to
+constructing `3D models from photographs`_ in computer vision.
+
+.. _fitting curves: http://en.wikipedia.org/wiki/Nonlinear_regression
+.. _3D model from photographs: http://en.wikipedia.org/wiki/Bundle_adjustment
+
+In this chapter we will learn how to solve :eq:`ceresproblem` using
+Ceres Solver. Full working code for all the examples described in this
+chapter and more can be found in the `examples
+<https://ceres-solver.googlesource.com/ceres-solver/+/master/examples/>`_
+directory.
+
 The expression
 :math:`\rho_i\left(\left\|f_i\left(x_{i_1},...,x_{i_k}\right)\right\|^2\right)`
 is known as a ``ResidualBlock``, where :math:`f_i(\cdot)` is a
@@ -33,12 +46,6 @@ more familiar `non-linear least squares problem
 .. math:: \frac{1}{2}\sum_{i} \left\|f_i\left(x_{i_1}, ... ,x_{i_k}\right)\right\|^2.
    :label: ceresproblem2
 
-In this chapter we will learn how to solve :eq:`ceresproblem` using
-Ceres Solver. Full working code for all the examples described in this
-chapter and more can be found in the `examples
-<https://ceres-solver.googlesource.com/ceres-solver/+/master/examples/>`_
-directory.
-
 .. _section-hello-world:
 
 Hello World!