pycvcam.optimize_parameters_gn#

optimize_parameters_gn(transform, input_points, output_points, *, guess=None, mask=None, transform_kwargs=None, max_iterations=None, max_time=None, ftol=None, xtol=None, gtol=None, auto=False, filter_nans=False, verbose_level=0, return_history=False, inplace=False)[source]#

Optimize the parameters of a Transform object such that the transformed input points match the output points using a Gauss-Newton optimization method.

Lets consider a set of input points \(\vec{X}_I\) with shape (…, input_dim) and a set of output points \(\vec{X}_O\) with shape (…, output_dim). We search \(\lambda = \lambda_0 + \delta \lambda\) such that:

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

Note

The current parameters of the transformation are not directly modified.

We have:

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

The corrections are computed using the following equations:

\[J^{T} J \delta \lambda = J^{T} R\]

Where \(J = \nabla_{\lambda} T (\vec{X}_I, \lambda_0)\) is the Jacobian matrix of the transformation with respect to the parameters, and \(R = \vec{X}_O - T(\vec{X}_I, \lambda_0)\) is the residual vector.

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:

transform (Transform) – The transformation object to be optimized. The constants attribute of the transformation must be set before calling this function. If the parameters attribute of the transformation is set, it will be used as the initial guess for the optimization if the guess parameter is None. Note that the input Transform object is not modified during the optimization process, a copy of the object is created and modified internally to perform the optimization if inplace is False.
input_points (ArrayLike) – The input points with shape (…, input_dim) such that their transformation is expected to match the output points.
output_points (ArrayLike) – The output points to be matched with shape (…, output_dim).
guess (Optional[ArrayLike], optional) – The initial guess for the parameters of the transformation with shape (n_params,). If None, the current parameters of the transformation are used.
mask (Optional[ArrayLike], optional) – A mask array of shape (n_params,) indicating which parameters should be optimized. Elements with a value of True are optimized, while elements with a value of False are kept fixed. Default is None, which means all parameters are optimized.
transform_kwargs (Optional[Dict], optional) – Additional keyword arguments for the transform._transform method. Default is None, which means no additional keyword arguments are passed to the transformation.
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.
max_time (Optional[Real], optional) – Stop criterion by the computation time of the optimization. The optimization process is stopped when the time since the start of the optimization exceeds max_time seconds. 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.
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_history (bool, optional) – If True, the function returns a history of the parameters during the optimization process. Default is False.
inplace (bool, optional) – If True, the optimization is performed in-place, modifying the parameters of the input transformation. If False (default), a copy of the transformation is created and modified internally to perform the optimization, leaving the input transformation unchanged.

Returns:

parameters (numpy.ndarray) – The optimized parameters of the transformation with shape (n_params,). This 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.
history (List[numpy.ndarray], optional) – A history of the optimization process including the parameters with shape (n_params,). Returned only if return_history is True.

Return type:

ndarray

pycvcam.optimize_parameters_gn#

This Page