Purge all remaining references to (defunct) LocalParameterization
Change-Id: Iad2a49bfa6916c22929d822e07f754ef77ed023d
diff --git a/docs/source/gradient_solver.rst b/docs/source/gradient_solver.rst
index cb27cd1..afb95aa 100644
--- a/docs/source/gradient_solver.rst
+++ b/docs/source/gradient_solver.rst
@@ -48,12 +48,6 @@
:class:`GradientProblem`
------------------------
-.. NOTE::
-
- The :class:`LocalParameterization` interface and associated classes
- are deprecated. They will be removed in the version 2.2.0. Please use
- :class:`Manifold` based constructor instead.
-
.. class:: GradientProblem
.. code-block:: c++
@@ -62,11 +56,8 @@
public:
explicit GradientProblem(FirstOrderFunction* function);
GradientProblem(FirstOrderFunction* function,
- LocalParameterization* parameterization);
- GradientProblem(FirstOrderFunction* function,
Manifold* manifold);
int NumParameters() const;
- int NumLocalParameters() const { return NumTangentParameters(); }
int NumTangentParameters() const;
bool Evaluate(const double* parameters, double* cost, double* gradient) const;
bool Plus(const double* x, const double* delta, double* x_plus_delta) const;
@@ -80,22 +71,18 @@
form of the objective function.
Structurally :class:`GradientProblem` is a composition of a
-:class:`FirstOrderFunction` and optionally a
-:class:`LocalParameterization` or a :class:`Manifold`.
+:class:`FirstOrderFunction` and optionally a :class:`Manifold`.
The :class:`FirstOrderFunction` is responsible for evaluating the cost
and gradient of the objective function.
-The :class:`LocalParameterization`/:class:`Manifold` is responsible
-for going back and forth between the ambient space and the local
-tangent space. When a :class:`LocalParameterization` or a
-:class:`Manifold` is not provided, then the tangent space is assumed
-to coincide with the ambient Euclidean space that the gradient vector
-lives in.
+The :class:`Manifold` is responsible for going back and forth between the
+ambient space and the local tangent space. When a :class:`Manifold` is not
+provided, then the tangent space is assumed to coincide with the ambient
+Euclidean space that the gradient vector lives in.
The constructor takes ownership of the :class:`FirstOrderFunction` and
-:class:`LocalParameterization` or :class:`Manifold` objects passed to
-it.
+:class:`Manifold` objects passed to it.
.. function:: void Solve(const GradientProblemSolver::Options& options, const GradientProblem& problem, double* parameters, GradientProblemSolver::Summary* summary)
@@ -499,23 +486,11 @@
Number of parameters in the problem.
-.. member:: int GradientProblemSolver::Summary::num_local_parameters
-
- Dimension of the tangent space of the problem. This is different
- from :member:`GradientProblemSolver::Summary::num_parameters` if a
- :class:`LocalParameterization`/:class:`Manifold` object is used.
-
- .. NOTE::
-
- ``num_local_parameters`` is deprecated and will be removed in
- Ceres Solver version 2.2.0. Please use ``num_tangent_parameters``
- instead.
-
.. member:: int GradientProblemSolver::Summary::num_tangent_parameters
Dimension of the tangent space of the problem. This is different
from :member:`GradientProblemSolver::Summary::num_parameters` if a
- :class:`LocalParameterization`/:class:`Manifold` object is used.
+ :class:`Manifold` object is used.
.. member:: LineSearchDirectionType GradientProblemSolver::Summary::line_search_direction_type
diff --git a/docs/source/nnls_covariance.rst b/docs/source/nnls_covariance.rst
index b86b5f6..2c3c05d 100644
--- a/docs/source/nnls_covariance.rst
+++ b/docs/source/nnls_covariance.rst
@@ -115,7 +115,7 @@
four dimensional quaternion used to parameterize :math:`SO(3)`,
which is a three dimensional manifold. In cases like this, the
user should use an appropriate
- :class:`LocalParameterization`. Not only will this lead to better
+ :class:`Manifold`. Not only will this lead to better
numerical behaviour of the Solver, it will also expose the rank
deficiency to the :class:`Covariance` object so that it can
handle it correctly.
diff --git a/docs/source/nnls_modeling.rst b/docs/source/nnls_modeling.rst
index 6ec14bf..555940e 100644
--- a/docs/source/nnls_modeling.rst
+++ b/docs/source/nnls_modeling.rst
@@ -1826,448 +1826,11 @@
Manifold* manifold = new AutoDiffManifold<QuaternionFunctor, 4, 3>;
-
-:class:`LocalParameterization`
-==============================
-
-.. NOTE::
-
- The :class:`LocalParameterization` interface and associated classes
- are deprecated. They will be removed in the version 2.2.0. Please use
- :class:`Manifold` instead.
-
-.. class:: LocalParameterization
-
- In many optimization problems, especially sensor fusion problems,
- one has to model quantities that live in spaces known as `Manifolds
- <https://en.wikipedia.org/wiki/Manifold>`_ , for example the
- rotation/orientation of a sensor that is represented by a
- `Quaternion
- <https://en.wikipedia.org/wiki/Quaternions_and_spatial_rotation>`_.
-
- Manifolds are spaces, which locally look like Euclidean spaces. More
- precisely, at each point on the manifold there is a linear space
- that is tangent to the manifold. It has dimension equal to the
- intrinsic dimension of the manifold itself, which is less than or
- equal to the ambient space in which the manifold is embedded.
-
- For example, the tangent space to a point on a sphere in three
- dimensions is the two dimensional plane that is tangent to the
- sphere at that point. There are two reasons tangent spaces are
- interesting:
-
- 1. They are Euclidean spaces, so the usual vector space operations
- apply there, which makes numerical operations easy.
-
- 2. Movement in the tangent space translate into movements along the
- manifold. Movements perpendicular to the tangent space do not
- translate into movements on the manifold.
-
- Moving along the 2 dimensional plane tangent to the sphere and
- projecting back onto the sphere will move you away from the point
- you started from but moving along the normal at the same point and
- the projecting back onto the sphere brings you back to the point.
-
- Besides the mathematical niceness, modeling manifold valued
- quantities correctly and paying attention to their geometry has
- practical benefits too:
-
- 1. It naturally constrains the quantity to the manifold throughout
- the optimization, freeing the user from hacks like *quaternion
- normalization*.
-
- 2. It reduces the dimension of the optimization problem to its
- *natural* size. For example, a quantity restricted to a line, is a
- one dimensional object regardless of the dimension of the ambient
- space in which this line lives.
-
- Working in the tangent space reduces not just the computational
- complexity of the optimization algorithm, but also improves its
- numerical behaviour of the algorithm.
-
- A basic operation one can perform on a manifold is the
- :math:`\boxplus` operation that computes the result of moving along
- delta in the tangent space at x, and then projecting back onto the
- manifold that x belongs to. Also known as a *Retraction*,
- :math:`\boxplus` is a generalization of vector addition in Euclidean
- spaces. Formally, :math:`\boxplus` is a smooth map from a
- manifold :math:`\mathcal{M}` and its tangent space
- :math:`T_\mathcal{M}` to the manifold :math:`\mathcal{M}` that
- obeys the identity
-
- .. math:: \boxplus(x, 0) = x,\quad \forall x.
-
- That is, it ensures that the tangent space is *centered* at :math:`x`
- and the zero vector is the identity element. For more see
- [Hertzberg]_ and section A.6.9 of [HartleyZisserman]_.
-
- Let us consider two examples:
-
- The Euclidean space :math:`\mathbb{R}^n` is the simplest example of a
- manifold. It has dimension :math:`n` (and so does its tangent space)
- and :math:`\boxplus` is the familiar vector sum operation.
-
- .. math:: \boxplus(x, \Delta) = x + \Delta
-
- A more interesting case is :math:`SO(3)`, the special orthogonal
- group in three dimensions - the space of :math:`3\times3` rotation
- matrices. :math:`SO(3)` is a three dimensional manifold embedded in
- :math:`\mathbb{R}^9` or :math:`\mathbb{R}^{3\times 3}`.
-
- :math:`\boxplus` on :math:`SO(3)` is defined using the *Exponential*
- map, from the tangent space (:math:`\mathbb{R}^3`) to the manifold. The
- Exponential map :math:`\operatorname{Exp}` is defined as:
-
- .. math::
-
- \operatorname{Exp}([p,q,r]) = \left [ \begin{matrix}
- \cos \theta + cp^2 & -sr + cpq & sq + cpr \\
- sr + cpq & \cos \theta + cq^2& -sp + cqr \\
- -sq + cpr & sp + cqr & \cos \theta + cr^2
- \end{matrix} \right ]
-
- where,
-
- .. math::
- \theta = \sqrt{p^2 + q^2 + r^2}, s = \frac{\sin \theta}{\theta},
- c = \frac{1 - \cos \theta}{\theta^2}.
-
- Then,
-
- .. math::
-
- \boxplus(x, \Delta) = x \operatorname{Exp}(\Delta)
-
- The ``LocalParameterization`` interface allows the user to define
- and associate with parameter blocks the manifold that they belong
- to. It does so by defining the ``Plus`` (:math:`\boxplus`) operation
- and its derivative with respect to :math:`\Delta` at :math:`\Delta =
- 0`.
-
- .. code-block:: c++
-
- class LocalParameterization {
- public:
- virtual ~LocalParameterization() = default;
- virtual bool Plus(const double* x,
- const double* delta,
- double* x_plus_delta) const = 0;
- virtual bool ComputeJacobian(const double* x, double* jacobian) const = 0;
- virtual bool MultiplyByJacobian(const double* x,
- const int num_rows,
- const double* global_matrix,
- double* local_matrix) const;
- virtual int GlobalSize() const = 0;
- virtual int LocalSize() const = 0;
- };
-
-
-.. function:: int LocalParameterization::GlobalSize()
-
- The dimension of the ambient space in which the parameter block
- :math:`x` lives.
-
-.. function:: int LocalParameterization::LocalSize()
-
- The size of the tangent space that :math:`\Delta` lives in.
-
-.. function:: bool LocalParameterization::Plus(const double* x, const double* delta, double* x_plus_delta) const
-
- :func:`LocalParameterization::Plus` implements :math:`\boxplus(x,\Delta)`.
-
-.. function:: bool LocalParameterization::ComputeJacobian(const double* x, double* jacobian) const
-
- Computes the Jacobian matrix
-
- .. math:: J = D_2 \boxplus(x, 0)
-
- in row major form.
-
-.. function:: bool MultiplyByJacobian(const double* x, const int num_rows, const double* global_matrix, double* local_matrix) const
-
- ``local_matrix = global_matrix * jacobian``
-
- ``global_matrix`` is a ``num_rows x GlobalSize`` row major matrix.
- ``local_matrix`` is a ``num_rows x LocalSize`` row major matrix.
- ``jacobian`` is the matrix returned by :func:`LocalParameterization::ComputeJacobian` at :math:`x`.
-
- This is only used by :class:`GradientProblem`. For most normal
- uses, it is okay to use the default implementation.
-
-Ceres Solver ships with a number of commonly used instances of
-:class:`LocalParameterization`. Another great place to find high
-quality implementations of :math:`\boxplus` operations on a variety of
-manifolds is the `Sophus <https://github.com/strasdat/Sophus>`_
-library developed by Hauke Strasdat and his collaborators.
-
-:class:`IdentityParameterization`
----------------------------------
-
-.. NOTE::
-
- :class:`IdentityParameterization` is deprecated. It will be removed
- in version 2.2.0 of Ceres Solver. Please use
- :class:`EuclideanManifold` instead.
-
-.. class:: IdentityParameterization
-
-A trivial version of :math:`\boxplus` is when :math:`\Delta` is of the
-same size as :math:`x` and
-
-.. math:: \boxplus(x, \Delta) = x + \Delta
-
-This is the same as :math:`x` living in a Euclidean manifold.
-
-:class:`QuaternionParameterization`
------------------------------------
-
-.. NOTE::
-
- :class:`QuaternionParameterization` is deprecated. It will be
- removed in version 2.2.0 of Ceres Solver. Please use
- :class:`QuaternionManifold` instead.
-
-.. class:: QuaternionParameterization
-
-Another example that occurs commonly in Structure from Motion problems
-is when camera rotations are parameterized using a quaternion. This is
-a 3-dimensional manifold that lives in 4-dimensional space.
-
-.. math:: \boxplus(x, \Delta) = \left[ \cos(|\Delta|), \frac{\sin\left(|\Delta|\right)}{|\Delta|} \Delta \right] \otimes x
-
-The multiplication :math:`\otimes` between the two 4-vectors on the right
-hand side is the standard quaternion product.
-
-:class:`EigenQuaternionParameterization`
-----------------------------------------
-
-.. NOTE::
-
- :class:`EigenQuaternionParameterization` is deprecated. It will be
- removed in version 2.2.0 of Ceres Solver. Please use
- :class:`EigenQuaternionManifold` instead.
-
-.. class:: EigenQuaternionParameterization
-
-`Eigen <http://eigen.tuxfamily.org/index.php?title=Main_Page>`_ uses a
-different internal memory layout for the elements of the quaternion
-than what is commonly used. Specifically, Eigen stores the elements in
-memory as :math:`(x, y, z, w)`, i.e., the *real* part (:math:`w`) is
-stored as the last element. Note, when creating an Eigen quaternion
-through the constructor the elements are accepted in :math:`w, x, y,
-z` order.
-
-Since Ceres operates on parameter blocks which are raw ``double``
-pointers this difference is important and requires a different
-parameterization. :class:`EigenQuaternionParameterization` uses the
-same ``Plus`` operation as :class:`QuaternionParameterization` but
-takes into account Eigen's internal memory element ordering.
-
-:class:`SubsetParameterization`
--------------------------------
-
-.. NOTE::
-
- :class:`SubsetParameterization` is deprecated. It will be removed
- in version 2.2.0 of Ceres Solver. Please use
- :class:`SubsetManifold` instead.
-
-.. class:: SubsetParameterization
-
-Suppose :math:`x` is a two dimensional vector, and the user wishes to
-hold the first coordinate constant. Then, :math:`\Delta` is a scalar
-and :math:`\boxplus` is defined as
-
-.. math:: \boxplus(x, \Delta) = x + \left[ \begin{array}{c} 0 \\ 1 \end{array} \right] \Delta
-
-:class:`SubsetParameterization` generalizes this construction to hold
-any part of a parameter block constant by specifying the set of
-coordinates that are held constant.
-
-.. NOTE::
- It is legal to hold all coordinates of a parameter block to constant
- using a :class:`SubsetParameterization`. It is the same as calling
- :func:`Problem::SetParameterBlockConstant` on that parameter block.
-
-:class:`HomogeneousVectorParameterization`
-------------------------------------------
-
-.. NOTE::
-
- :class:`HomogeneousVectorParameterization` is deprecated. It will
- be removed in version 2.2.0 of Ceres Solver. Please use
- :class:`SphereManifold` instead.
-
-.. class:: HomogeneousVectorParameterization
-
-In computer vision, homogeneous vectors are commonly used to represent
-objects in projective geometry such as points in projective space. One
-example where it is useful to use this over-parameterization is in
-representing points whose triangulation is ill-conditioned. Here it is
-advantageous to use homogeneous vectors, instead of an Euclidean
-vector, because it can represent points at and near infinity.
-
-:class:`HomogeneousVectorParameterization` defines a
-:class:`LocalParameterization` for an :math:`n-1` dimensional
-manifold that embedded in :math:`n` dimensional space where the
-scale of the vector does not matter, i.e., elements of the
-projective space :math:`\mathbb{P}^{n-1}`. It assumes that the last
-coordinate of the :math:`n`-vector is the *scalar* component of the
-homogeneous vector, i.e., *finite* points in this representation are
-those for which the *scalar* component is non-zero.
-
-Further, ``HomogeneousVectorParameterization::Plus`` preserves the
-scale of :math:`x`.
-
-:class:`LineParameterization`
------------------------------
-
-.. NOTE::
-
- :class:`LineParameterization` is deprecated. It will be removed in
- version 2.2.0 of Ceres Solver. Please use :class:`LineManifold`
- instead.
-
-.. class:: LineParameterization
-
-This class provides a parameterization for lines, where the line is
-defined using an origin point and a direction vector. So the
-parameter vector size needs to be two times the ambient space
-dimension, where the first half is interpreted as the origin point
-and the second half as the direction. This local parameterization is
-a special case of the `Affine Grassmannian manifold
-<https://en.wikipedia.org/wiki/Affine_Grassmannian_(manifold))>`_
-for the case :math:`\operatorname{Graff}_1(R^n)`.
-
-Note that this is a parameterization for a line, rather than a point
-constrained to lie on a line. It is useful when one wants to optimize
-over the space of lines. For example, :math:`n` distinct points in 3D
-(measurements) we want to find the line that minimizes the sum of
-squared distances to all the points.
-
-:class:`ProductParameterization`
---------------------------------
-
-.. NOTE::
-
- :class:`ProductParameterization` is deprecated. It will be removed
- in version 2.2.0 of Ceres Solver. Please use
- :class:`ProductManifold` instead.
-
-.. class:: ProductParameterization
-
-Consider an optimization problem over the space of rigid
-transformations :math:`SE(3)`, which is the Cartesian product of
-:math:`SO(3)` and :math:`\mathbb{R}^3`. Suppose you are using
-Quaternions to represent the rotation, Ceres ships with a local
-parameterization for that and :math:`\mathbb{R}^3` requires no, or
-:class:`IdentityParameterization` parameterization. So how do we
-construct a local parameterization for a parameter block a rigid
-transformation?
-
-In cases, where a parameter block is the Cartesian product of a number
-of manifolds and you have the local parameterization of the individual
-manifolds available, :class:`ProductParameterization` can be used to
-construct a local parameterization of the Cartesian product. For the
-case of the rigid transformation, where say you have a parameter block
-of size 7, where the first four entries represent the rotation as a
-quaternion, a local parameterization can be constructed as
-
-.. code-block:: c++
-
- ProductParameterization se3_param(new QuaternionParameterization(),
- new IdentityParameterization(3));
-
-
-:class:`AutoDiffLocalParameterization`
-======================================
-
-.. NOTE::
-
- :class:`AutoDiffParameterization` is deprecated. It will be removed
- in version 2.2.0 of Ceres Solver. Please use
- :class:`AutoDiffManifold` instead.
-
-.. class:: AutoDiffLocalParameterization
-
- :class:`AutoDiffLocalParameterization` does for
- :class:`LocalParameterization` what :class:`AutoDiffCostFunction`
- does for :class:`CostFunction`. It allows the user to define a
- templated functor that implements the
- :func:`LocalParameterization::Plus` operation and it uses automatic
- differentiation to implement the computation of the Jacobian.
-
- To get an auto differentiated local parameterization, you must
- define a class with a templated operator() (a functor) that computes
-
- .. math:: x' = \boxplus(x, \Delta x),
-
- For example, Quaternions have a three dimensional local
- parameterization. Its plus operation can be implemented as (taken
- from `internal/ceres/autodiff_local_parameterization_test.cc
- <https://ceres-solver.googlesource.com/ceres-solver/+/master/internal/ceres/autodiff_local_parameterization_test.cc>`_
- )
-
- .. code-block:: c++
-
- 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 > 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;
- }
- };
-
- Given this struct, the auto differentiated local
- parameterization can now be constructed as
-
- .. code-block:: c++
-
- LocalParameterization* local_parameterization =
- new AutoDiffLocalParameterization<QuaternionPlus, 4, 3>;
- | |
- Global Size ---------------+ |
- Local Size -------------------+
-
-
-
:class:`Problem`
================
.. class:: Problem
- .. NOTE:: We are currently in the process of transitioning from
- :class:`LocalParameterization` to :class:`Manifolds` in the
- Ceres Solver API. During this period, :class:`Problem` will
- support using both :class:`Manifold` and
- :class:`LocalParameterization` objects interchangeably. In
- particular, adding a :class:`LocalParameterization` to a
- parameter block is the same as adding a :class:`Manifold` to
- that parameter block. For methods in the API affected by this
- change, see their documentation below.
-
:class:`Problem` holds the robustified bounds constrained
non-linear least squares problem :eq:`ceresproblem_modeling`. To
create a least squares problem, use the
@@ -2331,18 +1894,16 @@
**Ownership**
:class:`Problem` by default takes ownership of the
- ``cost_function``, ``loss_function``, ``local_parameterization``,
- and ``manifold`` pointers. These objects remain live for the life
- of the :class:`Problem`. If the user wishes to keep control over
- the destruction of these objects, then they can do this by setting
- the corresponding enums in the :class:`Problem::Options` struct.
+ ``cost_function``, ``loss_function`` and ``manifold`` pointers. These
+ objects remain live for the life of the :class:`Problem`. If the user wishes
+ to keep control over the destruction of these objects, then they can do this
+ by setting the corresponding enums in the :class:`Problem::Options` struct.
Note that even though the Problem takes ownership of objects,
``cost_function`` and ``loss_function``, it does not preclude the
user from re-using them in another residual block. Similarly the
- same ``local_parameterization`` or ``manifold`` object can be used
- with multiple parameter blocks. The destructor takes care to call
- delete on each owned object exactly once.
+ same ``manifold`` object can be used with multiple parameter blocks. The
+ destructor takes care to call delete on each owned object exactly once.
.. class:: Problem::Options
@@ -2370,25 +1931,6 @@
loss functions on destruction. The destructor is careful to delete
the pointers only once, since sharing loss functions is allowed.
-.. member:: Ownership Problem::Options::local_parameterization_ownership
-
- .. NOTE::
-
- `Problem::Options::local_parameterization_ownership` is
- deprecated. It will be removed in Ceres Solver version
- 2.2.0. Please move to using Manifolds and use
- `Problem::Options::manifold_ownership` instead.
-
- Default: ``TAKE_OWNERSHIP``
-
- This option controls whether the Problem object owns the local
- parameterizations.
-
- If set to ``TAKE_OWNERSHIP``, then the problem object will delete the
- local parameterizations on destruction. The destructor is careful
- to delete the pointers only once, since sharing local
- parameterizations is allowed.
-
.. member:: Ownership Problem::Options::manifold_ownership
Default: ``TAKE_OWNERSHIP``
@@ -2529,49 +2071,8 @@
problem.AddResidualBlock(new MyUnaryCostFunction(...), nullptr, v1);
problem.AddResidualBlock(new MyBinaryCostFunction(...), nullptr, v2);
-.. function:: void Problem::AddParameterBlock(double* values, int size, LocalParameterization* local_parameterization)
-
- .. NOTE::
-
- This method is deprecated and will be removed in Ceres Solver
- version 2.2.0. Please move to using the :class:`Manifold` based version
- of `AddParameterBlock`.
-
- During the transition from :class:`LocalParameterization` to
- :class:`Manifold`, internally the
- :class:`LocalParameterization` is treated as a
- :class:`Manifold` by wrapping it using a `ManifoldAdapter`
- object. So :func:`Problem::HasManifold` will return true,
- :func:`Problem::GetManifold` will return the wrapped object and
- :func:`Problem::ParameterBlockTangentSize` will return the value of
- :func:`LocalParameterization::LocalSize`.
-
- Add a parameter block with appropriate size and parameterization to the
- problem. It is okay for ``local_parameterization`` to be ``nullptr``.
-
- Repeated calls with the same arguments are ignored. Repeated calls
- with the same double pointer but a different size results in a crash
- (unless :member:`Solver::Options::disable_all_safety_checks` is set to ``true``).
-
- Repeated calls with the same double pointer and size but different
- :class:`LocalParameterization` is equivalent to calling
- `SetParameterization(local_parameterization)`, i.e., any previously
- associated :class:`LocalParameterization` or :class:`Manifold`
- object will be replaced with the `local_parameterization`.
-
-
.. function:: void Problem::AddParameterBlock(double* values, int size, Manifold* manifold)
- .. NOTE::
-
- During the transition from :class:`LocalParameterization` to
- :class:`Manifold`, calling `AddParameterBlock` with a
- :class:`Manifold` when a :class:`LocalParameterization` is
- already associated with the parameter block is okay. It is
- equivalent to calling `SetManifold(manifold)`, i.e., any
- previously associated :class:`LocalParameterization` or
- :class:`Manifold` object will be replaced with the manifold.
-
Add a parameter block with appropriate size and Manifold to the
problem. It is okay for ``manifold`` to be ``nullptr``.
@@ -2581,8 +2082,8 @@
Repeated calls with the same double pointer and size but different
:class:`Manifold` is equivalent to calling `SetManifold(manifold)`,
- i.e., any previously associated :class:`LocalParameterization` or
- :class:`Manifold` object will be replaced with the `manifold`.
+ i.e., any previously associated :class:`Manifold` object will be replaced
+ with the `manifold`.
.. function:: void Problem::AddParameterBlock(double* values, int size)
@@ -2621,8 +2122,8 @@
depend on the parameter are also removed, as described above in
:func:`RemoveResidualBlock()`.
- The parameterization of the parameter block, if it exists, will
- persist until the deletion of the problem.
+ The manifold of the parameter block, if it exists, will persist until the
+ deletion of the problem.
If :member:`Problem::Options::enable_fast_removal` is ``true``, then the removal
is fast (almost constant time). Otherwise, removing a parameter
@@ -2647,88 +2148,16 @@
Returns ``true`` if a parameter block is set constant, and false
otherwise. A parameter block may be set constant in two ways:
either by calling ``SetParameterBlockConstant`` or by associating a
- :class:`LocalParameterization` or :class:`Manifold` with a zero
- dimensional tangent space with it.
-
-.. function:: void Problem::SetParameterization(double* values, LocalParameterization* local_parameterization)
-
- .. NOTE::
-
- This method is deprecated and will be removed in Ceres Solver
- version 2.2.0. Please move to using the SetManifold instead.
-
- During the transition from :class:`LocalParameterization` to
- :class:`Manifold`, calling `AddParameterBlock` with a
- :class:`Manifold` when a :class:`LocalParameterization` is
- already associated with the parameter block is okay. It is
- equivalent to calling `SetManifold(manifold)`, i.e., any
- previously associated :class:`LocalParameterization` or
- :class:`Manifold` object will be replaced with the manifold.
-
- Set the :class:`LocalParameterization` for the parameter
- block. Calling :func:`Problem::SetParameterization` with
- ``nullptr`` will clear any previously set
- :class:`LocalParameterization` or :class:`Manifold` for the
- parameter block.
-
- Repeated calls will cause any previously associated
- :class:`LocalParameterization` or :class:`Manifold` object to be
- replaced with the ``local_parameterization``.
-
- The ``local_parameterization`` is owned by the :class:`Problem` by
- default (See :class:`Problem::Options` to override this behaviour).
-
- It is acceptable to set the same :class:`LocalParameterization` for
- multiple parameter blocks; the Problem destructor is careful to
- delete :class:`LocalParameterizations` only once.
-
-.. function:: LocalParameterization* Problem::GetParameterization(const double* values) const
-
- Get the local parameterization object associated with this
- parameter block. If there is no parameterization object associated
- then ``nullptr`` is returned
-
- .. NOTE::
-
- This method is deprecated and will be removed in Ceres Solver
- version 2.2.0. Please move to using the
- :func:`Problem::GetParameterization` instead.
-
- Note also that if a :class:`LocalParameterization` is
- associated with a parameter block, :func:`Problem::HasManifold`
- will return true and :func:`Problem::GetManifold` will return
- the :class:`LocalParameterization` wrapped in a
- ``ManifoldAdapter``.
-
- The converse is NOT true, i.e., if a :class:`Manifold` is
- associated with a parameter block,
- :func:`Problem::HasParameterization` will return ``false`` and
- :func:`Problem::GetParameterization` will return a
- ``nullptr``.
-
-.. function:: bool HasParameterization(const double* values) const;
-
- Returns ``true`` if a :class:`LocalParameterization` is associated
- with this parameter block, ``false`` otherwise.
-
- .. NOTE::
-
- This method is deprecated and will be removed in the next public
- release of Ceres Solver. Use :func:`Problem::HasManifold` instead.
-
- Note also that if a :class:`Manifold` is associated with the
- parameter block, this method will return ``false``.
+ :class:`Manifold` with a zero dimensional tangent space with it.
.. function:: void SetManifold(double* values, Manifold* manifold);
Set the :class:`Manifold` for the parameter block. Calling
:func:`Problem::SetManifold` with ``nullptr`` will clear any
- previously set :class:`LocalParameterization` or :class:`Manifold`
- for the parameter block.
+ previously set :class:`Manifold` for the parameter block.
Repeated calls will result in any previously associated
- :class:`LocalParameterization` or :class:`Manifold` object to be
- replaced with ``manifold``.
+ :class:`Manifold` object to be replaced with ``manifold``.
``manifold`` is owned by :class:`Problem` by default (See
:class:`Problem::Options` to override this behaviour).
@@ -2740,22 +2169,12 @@
Get the :class:`Manifold` object associated with this parameter block.
- If there is no :class:`Manifold` or :class:`LocalParameterization`
- object associated then ``nullptr`` is returned.
-
- .. NOTE::
-
- During the transition from :class:`LocalParameterization` to
- :class:`Manifold`, internally the :class:`LocalParameterization` is
- treated as a :class:`Manifold` by wrapping it using a ``ManifoldAdapter``
- object. So calling :func:`Problem::GetManifold` on a parameter block with a
- :class:`LocalParameterization` associated with it will return the
- :class:`LocalParameterization` wrapped in a ManifoldAdapter.
+ If there is no :class:`Manifold` object associated with the parameter block,
+ then ``nullptr`` is returned.
.. function:: bool HasManifold(const double* values) const;
- Returns ``true`` if a :class:`Manifold` or a
- :class:`LocalParameterization` is associated with this parameter
+ Returns ``true`` if a :class:`Manifold` is associated with this parameter
block, ``false`` otherwise.
.. function:: void Problem::SetParameterLowerBound(double* values, int index, double lower_bound)
@@ -2808,27 +2227,11 @@
The size of the parameter block.
-.. function:: int Problem::ParameterBlockLocalSize(const double* values) const
-
- The dimension of the tangent space of the
- :class:`LocalParameterization` or :class:`Manifold` for the
- parameter block. If there is no :class:`LocalParameterization` or
- :class:`Manifold` associated with this parameter block, then
- ``ParameterBlockLocalSize = ParameterBlockSize``.
-
- .. NOTE::
-
- This method is deprecated and will be removed in Ceres Solver
- Version 2.2.0. Use :func:`Problem::ParameterBlockTangentSize`
- instead.
-
.. function:: int Problem::ParameterBlockTangentSize(const double* values) const
- The dimension of the tangent space of the
- :class:`LocalParameterization` or :class:`Manifold` for the
- parameter block. If there is no :class:`LocalParameterization` or
- :class:`Manifold` associated with this parameter block, then
- ``ParameterBlockLocalSize = ParameterBlockSize``.
+ The dimension of the tangent space of the :class:`Manifold` for the
+ parameter block. If there is no :class:`Manifold` associated with this
+ parameter block, then ``ParameterBlockTangentSize = ParameterBlockSize``.
.. function:: bool Problem::HasParameterBlock(const double* values) const
@@ -2889,10 +2292,9 @@
memory locations to have been modified.
The returned cost and jacobians have had robustification and
- :class:`LocalParameterization`/:class:`Manifold` applied already;
- for example, the jacobian for a 4-dimensional quaternion parameter
- using the :class:`QuaternionManifold` is ``num_residuals x 3``
- instead of ``num_residuals x 4``.
+ :class:`Manifold` applied already; for example, the jacobian for a
+ 4-dimensional quaternion parameter using the :class:`QuaternionManifold` is
+ ``num_residuals x 3`` instead of ``num_residuals x 4``.
``apply_loss_function`` as the name implies allows the user to
switch the application of the loss function on and off.
@@ -2962,11 +2364,10 @@
.. NOTE::
- If no :class:`LocalParameterization`/:class:`Manifold` are used,
- then the size of the gradient vector is the sum of the sizes of
- all the parameter blocks. If a parameter block has a local
- parameterization, then it contributes "LocalSize" entries to the
- gradient vector.
+ If no :class:`Manifold` are used, then the size of the gradient vector is
+ the sum of the sizes of all the parameter blocks. If a parameter block has
+ a manifold then it contributes "TangentSize" entries to the gradient
+ vector.
.. NOTE::
diff --git a/include/ceres/covariance.h b/include/ceres/covariance.h
index 612e036..18a485a 100644
--- a/include/ceres/covariance.h
+++ b/include/ceres/covariance.h
@@ -146,7 +146,7 @@
// a. The rank deficiency arises from overparameterization. e.g., a
// four dimensional quaternion used to parameterize SO(3), which is
// a three dimensional manifold. In cases like this, the user should
-// use an appropriate LocalParameterization/Manifold. Not only will this lead
+// use an appropriate Manifold. Not only will this lead
// to better numerical behaviour of the Solver, it will also expose
// the rank deficiency to the Covariance object so that it can
// handle it correctly.
@@ -408,11 +408,9 @@
const double* parameter_block2,
double* covariance_block) const;
- // Return the block of the cross-covariance matrix corresponding to
- // parameter_block1 and parameter_block2.
- // Returns cross-covariance in the tangent space if a local
- // parameterization is associated with either parameter block;
- // else returns cross-covariance in the ambient space.
+ // Returns the block of the cross-covariance in the tangent space if a
+ // manifold is associated with either parameter block; else returns
+ // cross-covariance in the ambient space.
//
// Compute must be called before the first call to
// GetCovarianceBlock and the pair <parameter_block1,
@@ -444,9 +442,8 @@
double* covariance_matrix) const;
// Return the covariance matrix corresponding to parameter_blocks
- // in the tangent space if a local parameterization is associated
- // with one of the parameter blocks else returns the covariance
- // matrix in the ambient space.
+ // in the tangent space if a manifold is associated with one of the parameter
+ // blocks else returns the covariance matrix in the ambient space.
//
// Compute must be called before calling GetCovarianceMatrix and all
// parameter_blocks must have been present in the vector
diff --git a/include/ceres/problem.h b/include/ceres/problem.h
index 909d1fc..fd29978 100644
--- a/include/ceres/problem.h
+++ b/include/ceres/problem.h
@@ -53,7 +53,6 @@
class CostFunction;
class EvaluationCallback;
class LossFunction;
-class LocalParameterization;
class Manifold;
class Solver;
struct CRSMatrix;
@@ -122,8 +121,7 @@
public:
struct CERES_EXPORT Options {
// These flags control whether the Problem object owns the CostFunctions,
- // LossFunctions, LocalParameterizations, and Manifolds passed into the
- // Problem.
+ // LossFunctions, and Manifolds passed into the Problem.
//
// If set to TAKE_OWNERSHIP, then the problem object will delete the
// corresponding object on destruction. The destructor is careful to delete
@@ -269,15 +267,14 @@
//
// Repeated calls with the same double pointer and size but different Manifold
// is equivalent to calling SetManifold(manifold), i.e., any previously
- // associated LocalParameterization or Manifold object will be replaced with
- // the manifold.
+ // associated Manifold object will be replaced with the manifold.
void AddParameterBlock(double* values, int size, Manifold* manifold);
- // Remove a parameter block from the problem. The LocalParameterization or
- // Manifold of the parameter block, if it exists, will persist until the
- // deletion of the problem (similar to cost/loss functions in residual block
- // removal). Any residual blocks that depend on the parameter are also
- // removed, as described above in RemoveResidualBlock().
+ // Remove a parameter block from the problem. The Manifold of the parameter
+ // block, if it exists, will persist until the deletion of the problem
+ // (similar to cost/loss functions in residual block removal). Any residual
+ // blocks that depend on the parameter are also removed, as described above
+ // in RemoveResidualBlock().
//
// If Problem::Options::enable_fast_removal is true, then the removal is fast
// (almost constant time). Otherwise, removing a parameter block will incur a
@@ -308,16 +305,15 @@
// Returns true if a parameter block is set constant, and false otherwise. A
// parameter block may be set constant in two ways: either by calling
- // SetParameterBlockConstant or by associating a LocalParameterization or
- // Manifold with a zero dimensional tangent space with it.
+ // SetParameterBlockConstant or by associating a Manifold with a zero
+ // dimensional tangent space with it.
bool IsParameterBlockConstant(const double* values) const;
// Set the Manifold for the parameter block. Calling SetManifold with nullptr
- // will clear any previously set LocalParameterization or Manifold for the
- // parameter block.
+ // will clear any previously set Manifold for the parameter block.
//
- // Repeated calls will result in any previously associated
- // LocalParameterization or Manifold object to be replaced with the manifold.
+ // Repeated calls will result in any previously associated Manifold object to
+ // be replaced with the manifold.
//
// The manifold is owned by the Problem by default (See Problem::Options to
// override this behaviour).
@@ -330,8 +326,8 @@
// If there is no Manifold object associated then nullptr is returned.
const Manifold* GetManifold(const double* values) const;
- // Returns true if a Manifold or a LocalParameterization is associated with
- // this parameter block, false otherwise.
+ // Returns true if a Manifold is associated with this parameter block, false
+ // otherwise.
bool HasManifold(const double* values) const;
// Set the lower/upper bound for the parameter at position "index".
@@ -364,10 +360,9 @@
// The size of the parameter block.
int ParameterBlockSize(const double* values) const;
- // The dimension of the tangent space of the LocalParameterization or Manifold
- // for the parameter block. If there is no LocalParameterization or Manifold
- // associated with this parameter block, then ParameterBlockTangentSize =
- // ParameterBlockSize.
+ // The dimension of the tangent space of the Manifold for the parameter block.
+ // If there is no Manifold associated with this parameter block, then
+ // ParameterBlockTangentSize = ParameterBlockSize.
int ParameterBlockTangentSize(const double* values) const;
// Is the given parameter block present in this problem or not?
@@ -467,11 +462,11 @@
//
// is the way to do so.
//
- // Note 2: If no LocalParameterizations or Manifolds are used, then the size
- // of the gradient vector (and the number of columns in the jacobian) is the
- // sum of the sizes of all the parameter blocks. If a parameter block has a
- // LocalParameterization or Manifold, then it contributes "TangentSize"
- // entries to the gradient vector (and the number of columns in the jacobian).
+ // Note 2: If no Manifolds are used, then the size of the gradient vector (and
+ // the number of columns in the jacobian) is the sum of the sizes of all the
+ // parameter blocks. If a parameter block has a Manifold, then it contributes
+ // "TangentSize" entries to the gradient vector (and the number of columns in
+ // the jacobian).
//
// Note 3: This function cannot be called while the problem is being solved,
// for example it cannot be called from an IterationCallback at the end of an
@@ -502,11 +497,10 @@
// returns false, the caller should expect the output memory locations to have
// been modified.
//
- // The returned cost and jacobians have had robustification and
- // LocalParameterization/Manifold applied already; for example, the jacobian
- // for a 4-dimensional quaternion parameter using the
- // "QuaternionParameterization" is num_residuals by 3 instead of num_residuals
- // by 4.
+ // The returned cost and jacobians have had robustification and Manifold
+ // applied already; for example, the jacobian for a 4-dimensional quaternion
+ // parameter using the "QuaternionParameterization" is num_residuals by 3
+ // instead of num_residuals by 4.
//
// apply_loss_function as the name implies allows the user to switch the
// application of the loss function on and off.
diff --git a/include/ceres/solver.h b/include/ceres/solver.h
index 61804aa..09c6525 100644
--- a/include/ceres/solver.h
+++ b/include/ceres/solver.h
@@ -953,7 +953,7 @@
// Dimension of the tangent space of the problem (or the number of
// columns in the Jacobian for the problem). This is different
// from num_parameters if a parameter block is associated with a
- // LocalParameterization/Manifold.
+ // Manifold.
int num_effective_parameters = -1;
// Number of residual blocks in the problem.
@@ -974,7 +974,7 @@
// number of columns in the Jacobian for the reduced
// problem). This is different from num_parameters_reduced if a
// parameter block in the reduced problem is associated with a
- // LocalParameterization/Manifold.
+ // Manifold.
int num_effective_parameters_reduced = -1;
// Number of residual blocks in the reduced problem.
diff --git a/internal/ceres/problem_impl.h b/internal/ceres/problem_impl.h
index 0ef3497..88f09e0 100644
--- a/internal/ceres/problem_impl.h
+++ b/internal/ceres/problem_impl.h
@@ -200,9 +200,8 @@
std::unique_ptr<internal::Program> program_;
// TODO(sameeragarwal): Unify the shared object handling across object types.
- // Right now we are using vectors for LocalParameterization and Manifold
- // objects and reference counting for CostFunctions and LossFunctions. Ideally
- // this should be done uniformly.
+ // Right now we are using vectors for Manifold objects and reference counting
+ // for CostFunctions and LossFunctions. Ideally this should be done uniformly.
// When removing parameter blocks, manifolds have ambiguous
// ownership. Instead of scanning the entire problem to see if the