| OpenCV 5.0.0alpha Open Source Computer Vision

Loading...
Searching...
No Matches
Classes | Public Types | Public Member Functions | List of all members
cv::LevMarq Class Reference
3D vision functionality

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

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

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