pycvcam.optimize_camera_lm#

optimize_camera_lm(intrinsic, distortion, extrinsic, world_points, image_points, *, guess_intrinsic=None, guess_distortion=None, guess_extrinsic=None, mask_intrinsic=None, mask_distortion=None, mask_extrinsic=None, intrinsic_kwargs=None, distortion_kwargs=None, extrinsic_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 the parameters of the intrinsic, distortion, and extrinsic transformations of a camera model such that the projection of the world points matches the image points using the scipy.optimize.least_squares method. The computation is done with the Levenberg-Marquardt algorithm.

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:

intrinsic (Optional[Intrinsic]) – The intrinsic transformation of the camera model to be optimized. If None, the intrinsic transformation is not included in the optimization.
distortion (Optional[Distortion]) – The distortion transformation of the camera model to be optimized. If None, the distortion transformation is not included in the optimization.
extrinsic (Optional[Extrinsic]) – The extrinsic transformation of the camera model to be optimized. If None, the extrinsic transformation is not included in the optimization.
world_points (ArrayLike) – The world points with shape (…, 3) such that their projection is expected to match the image points.
image_points (ArrayLike) – The image points to be matched with shape (…, 2).
guess_intrinsic (Optional[ArrayLike], optional) – The initial guess for the parameters of the intrinsic transformation with shape (n_intrinsic_params,). If None, the current parameters of the intrinsic transformation are used. Default is None.
guess_distortion (Optional[ArrayLike], optional) – The initial guess for the parameters of the distortion transformation with shape (n_distortion_params,). If None, the current parameters of the distortion transformation are used. Default is None.
guess_extrinsic (Optional[ArrayLike], optional) – The initial guess for the parameters of the extrinsic transformation with shape (n_extrinsic_params,). If None, the current parameters of the extrinsic transformation are used. Default is None.
mask_intrinsic (Optional[ArrayLike], optional) – A mask array of shape (n_intrinsic_params,) indicating which parameters of the intrinsic transformation 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 of the intrinsic transformation are optimized.
mask_distortion (Optional[ArrayLike], optional) – A mask array of shape (n_distortion_params,) indicating which parameters of the distortion transformation 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 of the distortion transformation are optimized.
mask_extrinsic (Optional[ArrayLike], optional) – A mask array of shape (n_extrinsic_params,) indicating which parameters of the extrinsic transformation 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 of the extrinsic transformation are optimized.
intrinsic_kwargs (Optional[Dict], optional) – Additional keyword arguments for the intrinsic._transform method. Default is None, which means no additional keyword arguments are passed to the intrinsic transformation.
distortion_kwargs (Optional[Dict], optional) – Additional keyword arguments for the distortion._transform method. Default is None, which means no additional keyword arguments are passed to the distortion transformation.
extrinsic_kwargs (Optional[Dict], optional) – Additional keyword arguments for the extrinsic._transform method. Default is None, which means no additional keyword arguments are passed to the extrinsic 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.
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 the scipy.optimize.OptimizeResult object containing information about the convergence of the optimization process. Default is False, which means only the optimized parameters are returned. If all transformations are None, or all parameters of the transformations are masked, the result output will be None.
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, numpy.ndarray, numpy.ndarray]) – A tuple containing the optimized parameters of the intrinsic, distortion, and extrinsic transformations with shapes (n_intrinsic_params,), (n_distortion_params,), and (n_extrinsic_params,) respectively. Each array contains both the optimized parameters (corresponding to True values in the respective masks) and the fixed parameters (corresponding to False values in the respective masks), where the fixed parameters are equal to their initial values.
result (scipy.optimize.OptimizeResult, optional) – The result of the optimization process containing information about the convergence of the optimization. Returned only if return_result is True and at least one of the transformations is not None and has at least one parameter to optimize, otherwise None.

Warning

Only contains the parameters that were optimized (i.e., the parameters corresponding to True values in the mask_intrinsic, mask_distortion, and mask_extrinsic), and not the full parameter vectors of the transformations.

Return type:

Tuple[ndarray, ndarray, ndarray]

pycvcam.optimize_camera_lm#

This Page