pycvcam.optimize_input_points_gn#

optimize_input_points_gn(transform, output_points, guess, *, transpose=False, max_iterations=None, max_time=None, ftol=None, xtol=None, gtol=None, auto=False, eps=None, verbose=False, return_convergence=False)[source]#

Optimize the input points of the transformation using the given output points.

Estimate the optimized input points of the transformation such that the transformed input points match the output points.

Warning

This method can only be used if the dimensions check input_dim <= output_dim.

Lets consider a set of output points \(X_O\) with shape (…, dim) and a set of input points \(\vec{X}_I\) with shape (…, input_dim). We search \(\vec{X}_I = \vec{X}_{I_0} + \delta \vec{X}_I\) such that:

\[\vec{X}_O = \text{Transform}(\vec{X}_I, \lambda) = T(\vec{X}_{I_0} + \delta \vec{X}_I, \lambda)\]

We have:

\[\nabla_{X} T (\vec{X}_{I_0}, \lambda) \delta \vec{X}_I = \vec{X}_O - T(\vec{X}_{I_0}, \lambda)\]

The corrections are computed using the following equations :

\[J \delta \vec{X}_I = R\]

Where \(J = \nabla_{X} T (\vec{X}_{I_0}, \lambda)\) is the Jacobian matrix of the transformation with respect to the input points, and \(R = \vec{X}_O - T(\vec{X}_{I_0}, \lambda)\) is the residual vector. \(\vec{X}_{I_0}\) is the initial guess for the input points.

Note

The auto parameter sets the stopping criteria (ftol, xtol, and gtol) to 1e-8. If any of the stopping criteria is already specified, it will be overridden by the user-specified value.

Parameters:

  • transform (Transform) – The transformation object used for optimization.

  • output_points (ArrayLike) – The output points to be matched. Shape (…, dim) (or (dim, …) if transpose is True). tional[ArrayLike], optional

  • guess (ArrayLike) – The initial guess for the input points of the transformation with shape (…, dim).

  • transpose (bool, optional) – If True, the output points are transposed to shape (dim, …) before optimization, and the optimized input points are transposed back to shape (input_dim, …) before returning. Default is False.

  • max_iterations (Optional[int]) – The maximum number of iterations for the optimization. Default is None, which means no limit on the number of iterations.

  • max_time (Optional[int]) – The maximum time in seconds for the optimization. Default is None, which means no limit on the time.

  • ftol (Optional[Real], optional) – Stop criterion by the change of the cost function. The optimization process is stopped when dF < ftol * F. The default value is None, which means the ftol criterion is not used for stopping the optimization.

  • xtol (Optional[Real], optional) – Stop criterion by the change of the parameters. The optimization process is stopped when norm(dx) < xtol * (xtol + norm(x)). The default value is None, which means the xtol criterion is not used for stopping the optimization.

  • gtol (Optional[Real], optional) – Stop criterion by the norm of the gradient. The optimization process is stopped when norm(g_scaled, ord=numpy.inf) < gtol where g_scaled is the value of the gradient scaled to account for the presence of the bounds. The default value is None, which means the gtol criterion is not used for stopping the optimization.

  • auto (bool, optional) – If True, the stopping criteria (ftol, xtol, and gtol) are all set to 1e-8. If any of the stopping criteria is already specified, it will be overridden by the user-specified value. Default is False.

  • eps (Optional[Real], optional) – The convergence threshold for the optimization. The optimization process is stopped when the change in the cost function is less than eps. Default is None, which means no convergence threshold is used.

  • verbose (bool) – If True, print the optimization progress and diagnostics. Default is False.

  • return_convergence (bool) – If True, the function returns a tuple of (optimized_input_points, convergence_status), where convergence_status is a numpy array of shape (n_points,) indicating the convergence status of each point.

Returns:

  • numpy.ndarray – The optimized input points of the transformation with shape (…, dim).

  • numpy.ndarray, optional – The convergence status of each point, where:

    • 0 means not converged,

    • 1 means converged by ftol criterion,

    • 2 means converged by xtol criterion,

    • 3 means converged by gtol criterion,

    • 4 means converged by eps criterion,

    • 5 means diverged by NaN values,

    • 6 means maximum number of iterations reached,

    • 7 means maximum time reached,

    • inf means warning not evaluated yet.

Return type:

ndarray

See also

optimize_chains_input_points_gn

Optimize the input points based of the result of chains of transformations using the Gauss-Newton optimization method.

On this page

This Page