pycvcam.optimize_chains_lm#

optimize_chains_lm(seq_transforms, seq_chains, seq_inputs, seq_outputs, *, seq_guesses=None, seq_masks=None, seq_transform_kwargs=None, max_iterations=None, ftol=None, xtol=None, gtol=None, auto=False, loss=None, filter_nans=False, verbose_level=0, return_result=False, inplace=False)[source]#

Optimize several Transform objects according multiple chains of transformations using the scipy.optimize.least_squares method. The computation is done with Levenberg-Marquardt algorithm.

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)

The optimization process is then defined as:

\[\min_{\lambda_0, \lambda_1, ..., \lambda_{N_T-1}} \sum_{i=0}^{N_C-1} \|R_i(\lambda_0, \lambda_1, ..., \lambda_{N_T-1})\|^2\]

where \(R_i\) is the residual vector for the chain \(C_i\) defined as:

\[R_i(\lambda_0, \lambda_1, ..., \lambda_{N_T-1}) = \vec{X}_O - C_i(\vec{X}_I, \lambda_0, \lambda_1, ..., \lambda_{N_T-1})\]

Note

This method can be used to optimize the parameters of any transformations that implement the _transform method.

Important

At least one of the stopping criteria (ftol, xtol, or gtol) must be specified for the optimization to stop. You can also set auto to True to use 1e-8 for all stopping criteria.

Parameters:

seq_transforms (Sequence[Transform]) – A sequence of \(N_T\) Transform objects to be optimized. The constants attribute of each transformation must be set before calling this function. If the parameters attribute of a transformation is set, it will be used as the initial guess for the optimization if the seq_guesses parameter is None. Note that the input Transform objects are not modified during the optimization process, a copy of each object is created and modified internally to perform the optimization if inplace is False.
seq_chains (Sequence[Sequence[int]]) – A sequence of \(N_C\) chains of transformations. Each chain is defined as a sequence of indices corresponding to the transformations in the chain. Each chain must be non-empty and contain valid indices (i.e., integers between 0 and \(N_T-1\)).
seq_inputs (Sequence[ArrayLike]) – A sequence of \(N_C\) arrays of input points with shape (…, input_dim) such that their transformation through the corresponding chain is expected to match the output points.
seq_outputs (Sequence[ArrayLike]) – A sequence of \(N_C\) arrays of output points to be matched with shape (…, output_dim).
seq_guesses (Optional[Sequence[ArrayLike]], optional) – A sequence of \(N_T\) arrays of initial guesses for the parameters of each transformation with shape (n_params,). If None or if seq_guesses[i] is None, the associated parameters of the transformation seq_transforms[i] are used. Default is None.
seq_masks (Optional[Sequence[ArrayLike]], optional) – A sequence of \(N_T\) arrays of masks with shape (n_params,) indicating which parameters of each transformation should be optimized. Elements with a value of True are optimized, while elements with a value of False are kept fixed. If None or if seq_masks[i] is None, all parameters of the transformation seq_transforms[i] are optimized. Default is None.
seq_transform_kwargs (Optional[Sequence[Dict]], optional) – A sequence of \(N_T\) dictionaries of additional keyword arguments for the _transform method of each transformation. If None or if seq_transform_kwargs[i] is None, no additional keyword arguments are passed to the transformation seq_transforms[i]. Default is None.
max_iterations (Optional[Integral], optional) – Stop criterion by the number of iterations. The optimization process is stopped when the number of iterations exceeds max_iterations. Default is None, which means no limit on the number of iterations.
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.
loss (Optional[str], optional) – If specified, the optimization will use a robust loss function to reduce the influence of outliers in the optimization. The available loss functions are ‘huber’, ‘cauchy’, ‘arctan’, ‘soft_l1’, and ‘linear’. Default is None, which means the standard least squares loss is used (i.e., ‘linear’).
filter_nans (bool, optional) –
If True, NaN values in the residuals are filtered out before computing the cost and the Jacobian. This can help improve the robustness of the optimization in the presence of outliers or invalid data. Default is False.

Warning

The optimization can try to expulse all points as outliers to reduce the cost to zero, which can lead to a failure of the optimization. Use with caution.
verbose_level (int, optional) – Level of algorithm’s verbosity: - 0 (default) : work silently. - 1 : display a termination report. - 2 : display progress during iterations. - 3 : display initial jacobian analysis and progress during iterations.
return_result (bool, optional) – If True, the function returns a dictionary containing the optimization result including the optimized parameters, the cost, the number of iterations, and other information about the optimization process. Default is False.
inplace (bool, optional) – If True, the optimization is performed in-place, modifying the parameters of the input transformations. If False (default), copies of the transformations are created and modified internally to perform the optimization, leaving the input transformations unchanged.

Returns:

parameters (Tuple[numpy.ndarray, …]) – A tuple of \(N_T\) arrays of optimized parameters for each transformation with shape (n_params,). Each array contains both the optimized parameters (corresponding to True values in the mask) and the fixed parameters (corresponding to False values in the mask), where the fixed parameters are equal to their initial values.
result (scipy.optimize.OptimizeResult, optional) – If return_result is True, the full result object from scipy.optimize.least_squares is also returned, which includes information about the optimization process, such as the optimized parameters, cost function value, number of iterations, and convergence status.

Return type:

Tuple[ndarray, …]

pycvcam.optimize_chains_lm#

This Page