OpenCV  5.0.0-pre
Open Source Computer Vision
Classes | Public Types | Public Member Functions | List of all members
cv::LevMarq Class Reference

Levenberg-Marquadt solver. More...

#include <opencv2/3d.hpp>

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 (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)
 
 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)
 
Report optimize ()
 
Report run (InputOutputArray param)
 Runs optimization using the passed vector of parameters as the start point. More...
 

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

"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(err_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
nvarsNumber of variables in a param vector
callback"Long" callback, produces jacobian and residuals for each energy term, returns true on success
settingsLevMarq settings structure, see LevMarqBase class for details
maskIndicates what variables are fixed during optimization (zeros) and what vars to optimize (non-zeros)
matrixTypeType of matrix used in the solver; only DENSE and AUTO are supported now
paramTypeType of optimized parameters; only LINEAR is supported now
nerrsEnergy terms amount. If zero, callback-generated jacobian size is used instead
solveMethodWhat method to use for linear system solving

◆ 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
nvarsNumber of variables in a param vector
callbackNormal callback, produces J^T*J and J^T*b directly instead of J and b, returns true on success
settingsLevMarq settings structure, see LevMarqBase class for details
maskIndicates what variables are fixed during optimization (zeros) and what vars to optimize (non-zeros)
matrixTypeType of matrix used in the solver; only DENSE and AUTO are supported now
paramTypeType of optimized parameters; only LINEAR is supported now
LtoRIndicates what part of symmetric matrix to copy to another part: lower or upper. Used only with alt. callback
solveMethodWhat method to use for linear system solving

◆ 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
paramInput/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
settingsLevMarq settings structure, see LevMarqBase class for details
maskIndicates what variables are fixed during optimization (zeros) and what vars to optimize (non-zeros)
matrixTypeType of matrix used in the solver; only DENSE and AUTO are supported now
paramTypeType of optimized parameters; only LINEAR is supported now
nerrsEnergy terms amount. If zero, callback-generated jacobian size is used instead
solveMethodWhat method to use for linear system solving

◆ 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
paramInput/output vector containing starting param vector and resulting optimized params
callbackNormal callback, produces J^T*J and J^T*b directly instead of J and b, returns true on success
settingsLevMarq settings structure, see LevMarqBase class for details
maskIndicates what variables are fixed during optimization (zeros) and what vars to optimize (non-zeros)
matrixTypeType of matrix used in the solver; only DENSE and AUTO are supported now
paramTypeType of optimized parameters; only LINEAR is supported now
LtoRIndicates what part of symmetric matrix to copy to another part: lower or upper. Used only with alt. callback
solveMethodWhat method to use for linear system solving

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
paraminitial/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: