Add readme for the sampled_function example.

Change-Id: I9468b6a7b9f2ffdd2bf9f0dd1f4e1d5f894e540c

examples/CMakeLists.txt

@@ -72,9 +72,6 @@ target_link_libraries(robust_curve_fitting ceres)
 add_executable(simple_bundle_adjuster simple_bundle_adjuster.cc)
 target_link_libraries(simple_bundle_adjuster ceres)
 
-add_executable(sampled_function sampled_function.cc)
-target_link_libraries(sampled_function ceres)
-
 if (GFLAGS)
   # The CERES_GFLAGS_NAMESPACE compile definition is NOT stored in
   # CERES_COMPILE_OPTIONS (and thus config.h) as Ceres itself does not
@@ -116,3 +113,5 @@ if (GFLAGS)
   target_link_libraries(robot_pose_mle ceres ${GFLAGS_LIBRARIES})
 
 endif (GFLAGS)
+
+add_subdirectory(sampled_function)

examples/sampled_function/CMakeLists.txt

@@ -0,0 +1,39 @@
+# Ceres Solver - A fast non-linear least squares minimizer
+# Copyright 2015 Google Inc. All rights reserved.
+# http://ceres-solver.org/
+#
+# Redistribution and use in source and binary forms, with or without
+# modification, are permitted provided that the following conditions are met:
+#
+# * Redistributions of source code must retain the above copyright notice,
+#   this list of conditions and the following disclaimer.
+# * Redistributions in binary form must reproduce the above copyright notice,
+#   this list of conditions and the following disclaimer in the documentation
+#   and/or other materials provided with the distribution.
+# * Neither the name of Google Inc. nor the names of its contributors may be
+#   used to endorse or promote products derived from this software without
+#   specific prior written permission.
+#
+# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+# AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+# IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+# ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
+# LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+# CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+# SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+# INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+# CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+# ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+# POSSIBILITY OF SUCH DAMAGE.
+#
+# Author: vitus@google.com (Michael Vitus)
+
+# Only Ceres itself should be compiled with CERES_BUILDING_SHARED_LIBRARY
+# defined, any users of Ceres will have CERES_USING_SHARED_LIBRARY defined
+# for them in Ceres' config.h if appropriate.
+if (BUILD_SHARED_LIBS)
+  remove_definitions(-DCERES_BUILDING_SHARED_LIBRARY)
+endif()
+
+add_executable(sampled_function sampled_function.cc)
+target_link_libraries(sampled_function ceres)

examples/sampled_function/README.md

@@ -0,0 +1,42 @@
+Sampled Functions
+--
+
+It is common to not have an analytical representation of the optimization
+problem but rather a table of values at specific inputs. This commonly occurs
+when working with images or when the functions in the problem are expensive to
+evaluate. To use this data in an optimization problem we can use interpolation
+to evaluate the function and derivatives at intermediate input values.
+
+There are many libraries that implement a variety of interpolation schemes, but
+it is difficult to use them in Ceres' automatic differentiation framework.
+Instead, Ceres provides the ability to interpolate one and two dimensional data.
+
+The one dimensional interpolation is based on the Cubic Hermite Spline. This
+interpolation method requires knowledge of the function derivatives at the
+control points, however we only know the function values. Consequently, we will
+use the data to estimate derivatives at the control points. The choice of how to
+compute the derivatives is not unique and Ceres uses the Catmull–Rom Spline
+variant which uses `0.5 * (p_{k+1} - p_{k-1})` as the derivative for control
+point `p_k.` This produces a first order differentiable interpolating
+function. The two dimensional interpolation scheme is a generalization of the
+one dimensional scheme where the interpolating function is assumed to be
+separable in the two dimensions.
+
+This example shows how to use interpolation schemes within the Ceres automatic
+differentiation framework. This is a one dimensional example and the objective
+function is to minimize `0.5 * f(x)^2` where `f(x) = (x - 4.5)^2`.
+
+It is also possible to use analytical derivatives with the provided
+interpolation schemes by using a `SizedCostFunction` and defining the
+``Evaluate` function. For this example, the evaluate function would be:
+
+```c++
+bool Evaluate(double const* const* parameters, double* residuals, double** jacobians) const {
+  if (jacobians == NULL || jacobians[0] == NULL)
+    interpolator_.Evaluate(parameters[0][0], residuals);
+  else
+    interpolator_.Evaluate(parameters[0][0], residuals, jacobians[0]);
+
+  return true;
+}
+```