Autodiff local parameterization class
This class is used to create local parameterization
with Jacobians computed via automatic differentiation.
To get an auto differentiated local parameterization,
class with a templated operator() (a functor) that
computes
plus_delta = Plus(x, delta);
shall be defined.
Then given such functor, the auto differentiated local
parameterization can be constructed as
LocalParameterization* local_parameterization =
new AutoDiffLocalParameterization<PlusFunctor, 4, 3>;
| |
Global Size ---------------+ |
Local Size -------------------+
See autodiff_local_parameterization.h for more information
and usage example.
Initial implementation by Keir Mierle, finished by self
and integrated into Ceres and covered with unit tests
by Sameer Agarwal.
Change-Id: I1b3e48ae89f81e0cf1f51416c5696e18223f4b21
diff --git a/include/ceres/autodiff_local_parameterization.h b/include/ceres/autodiff_local_parameterization.h
new file mode 100644
index 0000000..1099061
--- /dev/null
+++ b/include/ceres/autodiff_local_parameterization.h
@@ -0,0 +1,144 @@
+// Ceres Solver - A fast non-linear least squares minimizer
+// Copyright 2013 Google Inc. All rights reserved.
+// http://code.google.com/p/ceres-solver/
+//
+// 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: sergey.vfx@gmail.com (Sergey Sharybin)
+// mierle@gmail.com (Keir Mierle)
+// sameeragarwal@google.com (Sameer Agarwal)
+
+#ifndef CERES_PUBLIC_AUTODIFF_LOCAL_PARAMETERIZATION_H_
+#define CERES_PUBLIC_AUTODIFF_LOCAL_PARAMETERIZATION_H_
+
+#include "ceres/internal/autodiff.h"
+#include "ceres/internal/scoped_ptr.h"
+#include "ceres/local_parameterization.h"
+
+namespace ceres {
+
+// Create local parameterization with Jacobians computed via automatic
+// differentiation. For more information on local parameterizations,
+// see include/ceres/local_parameterization.h
+//
+// To get an auto differentiated local parameterization, you must define
+// a class with a templated operator() (a functor) that computes
+//
+// x_plus_delta = Plus(x, delta);
+//
+// the template parameter T. The autodiff framework substitutes appropriate
+// "Jet" objects for T in order to compute the derivative when necessary, but
+// this is hidden, and you should write the function as if T were a scalar type
+// (e.g. a double-precision floating point number).
+//
+// The function must write the computed value in the last argument (the only
+// non-const one) and return true to indicate success.
+//
+// For example, Quaternions have a three dimensional local
+// parameterization. It's plus operation can be implemented as (taken
+// from interncal/ceres/auto_diff_local_parameterization_test.cc)
+//
+// struct QuaternionPlus {
+// template<typename T>
+// bool operator()(const T* x, const T* delta, T* x_plus_delta) const {
+// const T squared_norm_delta =
+// delta[0] * delta[0] + delta[1] * delta[1] + delta[2] * delta[2];
+//
+// T q_delta[4];
+// if (squared_norm_delta > T(0.0)) {
+// T norm_delta = sqrt(squared_norm_delta);
+// const T sin_delta_by_delta = sin(norm_delta) / norm_delta;
+// q_delta[0] = cos(norm_delta);
+// q_delta[1] = sin_delta_by_delta * delta[0];
+// q_delta[2] = sin_delta_by_delta * delta[1];
+// q_delta[3] = sin_delta_by_delta * delta[2];
+// } else {
+// // We do not just use q_delta = [1,0,0,0] here because that is a
+// // constant and when used for automatic differentiation will
+// // lead to a zero derivative. Instead we take a first order
+// // approximation and evaluate it at zero.
+// q_delta[0] = T(1.0);
+// q_delta[1] = delta[0];
+// q_delta[2] = delta[1];
+// q_delta[3] = delta[2];
+// }
+//
+// QuaternionProduct(q_delta, x, x_plus_delta);
+// return true;
+// }
+// };
+//
+// Then given this struct, the auto differentiated local
+// parameterization can now be constructed as
+//
+// LocalParameterization* local_parameterization =
+// new AutoDiffLocalParameterization<QuaternionPlus, 4, 3>;
+// | |
+// Global Size ---------------+ |
+// Local Size -------------------+
+//
+// WARNING: Since the functor will get instantiated with different types for
+// T, you must to convert from other numeric types to T before mixing
+// computations with other variables of type T. In the example above, this is
+// seen where instead of using k_ directly, k_ is wrapped with T(k_).
+
+template <typename Functor, int kGlobalSize, int kLocalSize>
+class AutoDiffLocalParameterization : public LocalParameterization {
+ public:
+ virtual ~AutoDiffLocalParameterization() {}
+ virtual bool Plus(const double* x,
+ const double* delta,
+ double* x_plus_delta) const {
+ return Functor()(x, delta, x_plus_delta);
+ }
+
+ virtual bool ComputeJacobian(const double* x, double* jacobian) const {
+ double zero_delta[kLocalSize];
+ for (int i = 0; i < kLocalSize; ++i) {
+ zero_delta[i] = 0.0;
+ }
+
+ double x_plus_delta[kGlobalSize];
+ for (int i = 0; i < kGlobalSize; ++i) {
+ x_plus_delta[i] = 0.0;
+ }
+
+ const double* parameter_ptrs[2] = {x, zero_delta};
+ double* jacobian_ptrs[2] = { NULL, jacobian };
+ return internal::AutoDiff<Functor, double, kGlobalSize, kLocalSize>
+ ::Differentiate(Functor(),
+ parameter_ptrs,
+ kGlobalSize,
+ x_plus_delta,
+ jacobian_ptrs);
+ }
+
+ virtual int GlobalSize() const { return kGlobalSize; }
+ virtual int LocalSize() const { return kLocalSize; }
+};
+
+} // namespace ceres
+
+#endif // CERES_PUBLIC_AUTODIFF_LOCAL_PARAMETERIZATION_H_
diff --git a/include/ceres/ceres.h b/include/ceres/ceres.h
index 7878806..ac76e97 100644
--- a/include/ceres/ceres.h
+++ b/include/ceres/ceres.h
@@ -38,6 +38,7 @@
#define CERES_ABI_VERSION 1.5.0
#include "ceres/autodiff_cost_function.h"
+#include "ceres/autodiff_local_parameterization.h"
#include "ceres/cost_function.h"
#include "ceres/cost_function_to_functor.h"
#include "ceres/crs_matrix.h"
diff --git a/internal/ceres/CMakeLists.txt b/internal/ceres/CMakeLists.txt
index 8a90935..3734c08 100644
--- a/internal/ceres/CMakeLists.txt
+++ b/internal/ceres/CMakeLists.txt
@@ -238,6 +238,7 @@
CERES_TEST(array_utils)
CERES_TEST(autodiff)
CERES_TEST(autodiff_cost_function)
+ CERES_TEST(autodiff_local_parameterization)
CERES_TEST(blas)
CERES_TEST(block_random_access_dense_matrix)
CERES_TEST(block_random_access_sparse_matrix)
diff --git a/internal/ceres/autodiff_local_parameterization_test.cc b/internal/ceres/autodiff_local_parameterization_test.cc
new file mode 100644
index 0000000..7e90177
--- /dev/null
+++ b/internal/ceres/autodiff_local_parameterization_test.cc
@@ -0,0 +1,184 @@
+// Ceres Solver - A fast non-linear least squares minimizer
+// Copyright 2013 Google Inc. All rights reserved.
+// http://code.google.com/p/ceres-solver/
+//
+// 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: sameeragarwal@google.com (Sameer Agarwal)
+
+#include <cmath>
+#include "ceres/autodiff_local_parameterization.h"
+#include "ceres/fpclassify.h"
+#include "ceres/local_parameterization.h"
+#include "ceres/rotation.h"
+#include "gtest/gtest.h"
+
+namespace ceres {
+namespace internal {
+
+struct IdentityPlus {
+ template <typename T>
+ bool operator()(const T* x, const T* delta, T* x_plus_delta) const {
+ for (int i = 0; i < 3; ++i) {
+ x_plus_delta[i] = x[i] + delta[i];
+ }
+ return true;
+ }
+};
+
+
+TEST(AutoDiffLocalParameterizationTest, IdentityParameterization) {
+ AutoDiffLocalParameterization<IdentityPlus, 3, 3>
+ parameterization;
+
+ double x[3] = {1.0, 2.0, 3.0};
+ double delta[3] = {0.0, 1.0, 2.0};
+ double x_plus_delta[3] = {0.0, 0.0, 0.0};
+ parameterization.Plus(x, delta, x_plus_delta);
+
+ EXPECT_EQ(x_plus_delta[0], 1.0);
+ EXPECT_EQ(x_plus_delta[1], 3.0);
+ EXPECT_EQ(x_plus_delta[2], 5.0);
+
+ double jacobian[9];
+ parameterization.ComputeJacobian(x, jacobian);
+ int k = 0;
+ for (int i = 0; i < 3; ++i) {
+ for (int j = 0; j < 3; ++j, ++k) {
+ EXPECT_EQ(jacobian[k], (i == j) ? 1.0 : 0.0);
+ }
+ }
+}
+
+struct QuaternionPlus {
+ template<typename T>
+ bool operator()(const T* x, const T* delta, T* x_plus_delta) const {
+ const T squared_norm_delta =
+ delta[0] * delta[0] + delta[1] * delta[1] + delta[2] * delta[2];
+
+ T q_delta[4];
+ if (squared_norm_delta > T(0.0)) {
+ T norm_delta = sqrt(squared_norm_delta);
+ const T sin_delta_by_delta = sin(norm_delta) / norm_delta;
+ q_delta[0] = cos(norm_delta);
+ q_delta[1] = sin_delta_by_delta * delta[0];
+ q_delta[2] = sin_delta_by_delta * delta[1];
+ q_delta[3] = sin_delta_by_delta * delta[2];
+ } else {
+ // We do not just use q_delta = [1,0,0,0] here because that is a
+ // constant and when used for automatic differentiation will
+ // lead to a zero derivative. Instead we take a first order
+ // approximation and evaluate it at zero.
+ q_delta[0] = T(1.0);
+ q_delta[1] = delta[0];
+ q_delta[2] = delta[1];
+ q_delta[3] = delta[2];
+ }
+
+ QuaternionProduct(q_delta, x, x_plus_delta);
+ return true;
+ }
+};
+
+void QuaternionParameterizationTestHelper(const double* x,
+ const double* delta) {
+ const double kTolerance = 1e-14;
+ double x_plus_delta_ref[4] = {0.0, 0.0, 0.0, 0.0};
+ double jacobian_ref[12];
+
+
+ QuaternionParameterization ref_parameterization;
+ ref_parameterization.Plus(x, delta, x_plus_delta_ref);
+ ref_parameterization.ComputeJacobian(x, jacobian_ref);
+
+ double x_plus_delta[4] = {0.0, 0.0, 0.0, 0.0};
+ double jacobian[12];
+ AutoDiffLocalParameterization<QuaternionPlus, 4, 3> parameterization;
+ parameterization.Plus(x, delta, x_plus_delta);
+ parameterization.ComputeJacobian(x, jacobian);
+
+ for (int i = 0; i < 4; ++i) {
+ EXPECT_NEAR(x_plus_delta[i], x_plus_delta_ref[i], kTolerance);
+ }
+
+ const double x_plus_delta_norm =
+ sqrt(x_plus_delta[0] * x_plus_delta[0] +
+ x_plus_delta[1] * x_plus_delta[1] +
+ x_plus_delta[2] * x_plus_delta[2] +
+ x_plus_delta[3] * x_plus_delta[3]);
+
+ EXPECT_NEAR(x_plus_delta_norm, 1.0, kTolerance);
+
+ for (int i = 0; i < 12; ++i) {
+ EXPECT_TRUE(IsFinite(jacobian[i]));
+ EXPECT_NEAR(jacobian[i], jacobian_ref[i], kTolerance)
+ << "Jacobian mismatch: i = " << i
+ << "\n Expected \n" << ConstMatrixRef(jacobian_ref, 4, 3)
+ << "\n Actual \n" << ConstMatrixRef(jacobian, 4, 3);
+ }
+}
+
+TEST(AutoDiffLocalParameterization, QuaternionParameterizationZeroTest) {
+ double x[4] = {0.5, 0.5, 0.5, 0.5};
+ double delta[3] = {0.0, 0.0, 0.0};
+ QuaternionParameterizationTestHelper(x, delta);
+}
+
+
+TEST(AutoDiffLocalParameterization, QuaternionParameterizationNearZeroTest) {
+ double x[4] = {0.52, 0.25, 0.15, 0.45};
+ double norm_x = sqrt(x[0] * x[0] +
+ x[1] * x[1] +
+ x[2] * x[2] +
+ x[3] * x[3]);
+ for (int i = 0; i < 4; ++i) {
+ x[i] = x[i] / norm_x;
+ }
+
+ double delta[3] = {0.24, 0.15, 0.10};
+ for (int i = 0; i < 3; ++i) {
+ delta[i] = delta[i] * 1e-14;
+ }
+
+ QuaternionParameterizationTestHelper(x, delta);
+}
+
+TEST(AutoDiffLocalParameterization, QuaternionParameterizationNonZeroTest) {
+ double x[4] = {0.52, 0.25, 0.15, 0.45};
+ double norm_x = sqrt(x[0] * x[0] +
+ x[1] * x[1] +
+ x[2] * x[2] +
+ x[3] * x[3]);
+
+ for (int i = 0; i < 4; ++i) {
+ x[i] = x[i] / norm_x;
+ }
+
+ double delta[3] = {0.24, 0.15, 0.10};
+ QuaternionParameterizationTestHelper(x, delta);
+}
+
+} // namespace internal
+} // namespace ceres
