pycvcam.optimize_chains_input_points_gn#

optimize_chains_input_points_gn(seq_transforms, seq_chains, seq_outputs, guess, *, transpose=False, seq_transform_kwargs=None, 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 based of the result of chains of transformations using the Gauss-Newton optimization method.

Note

This method does not implement bounds or scaling of the input_points, and does not provide a robust optimization process for handling non-linear problems, which can lead to divergence or convergence to local minima.

Warning

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

Lets \((T_0, T_1, ..., T_{N_T-1})\) be a tuple of \(N_T\) Transform objects, and \((C_0, C_1, ..., C_{N_C-1})\) be a tuple of \(N_C\) chains of transformations.

A chain \(C_i\) is defined as a tuple of indices corresponding to the transformations in the chain. For example:

C_0 = (1, 4, 8) -----> C_0(X) = T_8 ∘ T_4 ∘ T_1(X)

We search \(X_i\) such that the transformed points \(C_i(X_i; p)\) match the output points \(Y_i\) for each chain \(C_i\), where \(p\) is the vector of parameters of the transformations in the chain.

The residual function for each chain \(C_i\) is defined as:

\[R_i(X_i) = Y_i - C_i(X_i; p)\]
\[J_i(X_i) = -\frac{\partial C_i(X_i; p)}{\partial X_i} = \frac{\partial R_i(X_i)}{\partial X_i}\]
Parameters:

  • seq_transforms (Sequence[Transform]) – A sequence of transformations involved in the chains.

  • seq_chains (Sequence[Sequence[Integral]]) – A sequence of chains, where each chain is a sequence of indices corresponding to the transformations in seq_transforms.

  • seq_outputs (Sequence[numpy.ndarray]) – A sequence of output points corresponding to each chain, where each element has shape (n_points, output_dim).

  • guess (numpy.ndarray) – The initial guess for the input points of the transformations with shape (n_points, input_dim).

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

  • seq_transform_kwargs (Sequence[Dict]) – A sequence of dictionaries containing additional keyword arguments for each transformation in seq_transforms. Each dictionary should have the same keys as the parameters of the corresponding transformation, and the values should be the values of those parameters to be used during the optimization.

  • 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_input_points_gn

Optimize the input points of a single transformation using the Gauss-Newton optimization method.