cv::LevMarq Class Reference

Levenberg-Marquadt solver. More...

#include <opencv2/3d.hpp>

Collaboration diagram for cv::LevMarq:

Classes
struct	Report
	Optimization report. More...
struct	Settings
	Structure to keep LevMarq settings. More...

Public Types
typedef std::function< bool(InputOutputArray, OutputArray, OutputArray)>	LongCallback
typedef std::function< bool(InputOutputArray, OutputArray, OutputArray, double &)>	NormalCallback

Public Member Functions
	LevMarq (InputOutputArray param, LongCallback callback, const Settings &settings=Settings(), InputArray mask=noArray(), MatrixType matrixType=MatrixType::AUTO, VariableType paramType=VariableType::LINEAR, int nerrs=0, int solveMethod=DECOMP_SVD)
	LevMarq (InputOutputArray param, NormalCallback callback, const Settings &settings=Settings(), InputArray mask=noArray(), MatrixType matrixType=MatrixType::AUTO, VariableType paramType=VariableType::LINEAR, bool LtoR=false, int solveMethod=DECOMP_SVD)
	LevMarq (int nvars, LongCallback callback, const Settings &settings=Settings(), InputArray mask=noArray(), MatrixType matrixType=MatrixType::AUTO, VariableType paramType=VariableType::LINEAR, int nerrs=0, int solveMethod=DECOMP_SVD)
	LevMarq (int nvars, NormalCallback callback, const Settings &settings=Settings(), InputArray mask=noArray(), MatrixType matrixType=MatrixType::AUTO, VariableType paramType=VariableType::LINEAR, bool LtoR=false, int solveMethod=DECOMP_SVD)
Report	optimize ()
Report	run (InputOutputArray param)
	Runs optimization using the passed vector of parameters as the start point.

Detailed Description

Levenberg-Marquadt solver.

A Levenberg-Marquadt algorithm locally minimizes an objective function value (aka energy, cost or error) starting from current param vector. To do that, at each iteration it repeatedly calculates the energy at probe points until it's reduced. To calculate a probe point, a linear equation is solved: (J^T*J + lambda*D)*dx = -J^T*b where J is a function jacobian, b is a vector of residuals (aka errors or energy terms), D is a diagonal matrix generated from J^T*J diagonal and lambda changes for each probe point. Then the resulting dx is "added" to current variable and it forms a probe value. "Added" is quoted because in some groups (e.g. SO(3) group) such an increment can be a non-trivial operation.

For more details, please refer to Wikipedia page (https://en.wikipedia.org/wiki/Levenberg%E2%80%93Marquardt_algorithm).

This solver supports fixed variables and two forms of callback function:

1. Generating ordinary jacobian J and residual vector err ("long")
2. Generating normal equation matrix J^T*J and gradient vector J^T*err

Currently the solver supports dense jacobian matrix and linear parameter increment.

Member Typedef Documentation

LongCallback

typedef std::function<bool(InputOutputArray, OutputArray, OutputArray)> cv::LevMarq::LongCallback

"Long" callback: f(param, &err, &J) -> bool Computes error and Jacobian for the specified vector of parameters, returns true on success.

param: the current vector of parameters err: output vector of errors: err_i = actual_f_i - ideal_f_i J: output Jacobian: J_ij = d(ideal_f_i)/d(param_j)

Param vector values may be changed by the callback only if they are fixed. Changing non-fixed variables may lead to incorrect results. When J=noArray(), it means that it does not need to be computed. Dimensionality of error vector and param vector can be different. The callback should explicitly allocate (with "create" method) each output array (unless it's noArray()).

NormalCallback

typedef std::function<bool(InputOutputArray, OutputArray, OutputArray, double&)> cv::LevMarq::NormalCallback

Normal callback: f(param, &JtErr, &JtJ, &errnorm) -> bool

Computes squared L2 error norm, normal equation matrix J^T*J and J^T*err vector where J is MxN Jacobian: J_ij = d(err_i)/d(param_j) err is Mx1 vector of errors: err_i = actual_f_i - ideal_f_i M is a number of error terms, N is a number of variables to optimize. Make sense to use this class instead of usual Callback if the number of error terms greatly exceeds the number of variables.

param: the current Nx1 vector of parameters JtErr: output Nx1 vector J^T*err JtJ: output NxN matrix J^T*J errnorm: output total error: dot(err, err)

Param vector values may be changed by the callback only if they are fixed. Changing non-fixed variables may lead to incorrect results. If JtErr or JtJ are empty, they don't have to be computed. The callback should explicitly allocate (with "create" method) each output array (unless it's noArray()).

Constructor & Destructor Documentation

LevMarq() [1/4]

cv::LevMarq::LevMarq	(	int	nvars,
		LongCallback	callback,
		const Settings &	settings = Settings(),
		InputArray	mask = noArray(),
		MatrixType	matrixType = MatrixType::AUTO,
		VariableType	paramType = VariableType::LINEAR,
		int	nerrs = 0,
		int	solveMethod = DECOMP_SVD
	)

Creates a solver

Parameters

nvars	Number of variables in a param vector
callback	"Long" callback, produces jacobian and residuals for each energy term, returns true on success
settings	LevMarq settings structure, see LevMarqBase class for details
mask	Indicates what variables are fixed during optimization (zeros) and what vars to optimize (non-zeros)
matrixType	Type of matrix used in the solver; only DENSE and AUTO are supported now
paramType	Type of optimized parameters; only LINEAR is supported now
nerrs	Energy terms amount. If zero, callback-generated jacobian size is used instead
solveMethod	What method to use for linear system solving

Here is the call graph for this function:

LevMarq() [2/4]

cv::LevMarq::LevMarq	(	int	nvars,
		NormalCallback	callback,
		const Settings &	settings = Settings(),
		InputArray	mask = noArray(),
		MatrixType	matrixType = MatrixType::AUTO,
		VariableType	paramType = VariableType::LINEAR,
		bool	LtoR = false,
		int	solveMethod = DECOMP_SVD
	)

Creates a solver

Parameters

nvars	Number of variables in a param vector
callback	Normal callback, produces J^T*J and J^T*b directly instead of J and b, returns true on success
settings	LevMarq settings structure, see LevMarqBase class for details
mask	Indicates what variables are fixed during optimization (zeros) and what vars to optimize (non-zeros)
matrixType	Type of matrix used in the solver; only DENSE and AUTO are supported now
paramType	Type of optimized parameters; only LINEAR is supported now
LtoR	Indicates what part of symmetric matrix to copy to another part: lower or upper. Used only with alt. callback
solveMethod	What method to use for linear system solving

Here is the call graph for this function:

LevMarq() [3/4]

cv::LevMarq::LevMarq	(	InputOutputArray	param,
		LongCallback	callback,
		const Settings &	settings = Settings(),
		InputArray	mask = noArray(),
		MatrixType	matrixType = MatrixType::AUTO,
		VariableType	paramType = VariableType::LINEAR,
		int	nerrs = 0,
		int	solveMethod = DECOMP_SVD
	)

Creates a solver

Parameters

param	Input/output vector containing starting param vector and resulting optimized params
callback	"Long" callback, produces jacobian and residuals for each energy term, returns true on success
settings	LevMarq settings structure, see LevMarqBase class for details
mask	Indicates what variables are fixed during optimization (zeros) and what vars to optimize (non-zeros)
matrixType	Type of matrix used in the solver; only DENSE and AUTO are supported now
paramType	Type of optimized parameters; only LINEAR is supported now
nerrs	Energy terms amount. If zero, callback-generated jacobian size is used instead
solveMethod	What method to use for linear system solving

Here is the call graph for this function:

LevMarq() [4/4]

cv::LevMarq::LevMarq	(	InputOutputArray	param,
		NormalCallback	callback,
		const Settings &	settings = Settings(),
		InputArray	mask = noArray(),
		MatrixType	matrixType = MatrixType::AUTO,
		VariableType	paramType = VariableType::LINEAR,
		bool	LtoR = false,
		int	solveMethod = DECOMP_SVD
	)

Creates a solver

Parameters

param	Input/output vector containing starting param vector and resulting optimized params
callback	Normal callback, produces J^T*J and J^T*b directly instead of J and b, returns true on success
settings	LevMarq settings structure, see LevMarqBase class for details
mask	Indicates what variables are fixed during optimization (zeros) and what vars to optimize (non-zeros)
matrixType	Type of matrix used in the solver; only DENSE and AUTO are supported now
paramType	Type of optimized parameters; only LINEAR is supported now
LtoR	Indicates what part of symmetric matrix to copy to another part: lower or upper. Used only with alt. callback
solveMethod	What method to use for linear system solving

Here is the call graph for this function:

Member Function Documentation

optimize()

Report cv::LevMarq::optimize

(

)

Runs Levenberg-Marquadt algorithm using current settings and given parameters vector. The method returns the optimization report.

run()

Report cv::LevMarq::run

(

InputOutputArray

param

)

Runs optimization using the passed vector of parameters as the start point.

The final vector of parameters (whether the algorithm converged or not) is stored at the same vector. This method can be used instead of the optimize() method if rerun with different start points is required. The method returns the optimization report.

Parameters

param

initial/final vector of parameters.

Note that the dimensionality of parameter space is defined by the size of param vector, and the dimensionality of optimized criteria is defined by the size of err vector computed by the callback.

---

The documentation for this class was generated from the following file:

• opencv2/3d.hpp