pyvale.calib.calibstereo module

Stereo camera calibration routines for dot-target image pairs.

class ReprojError(*values)[source]

Bases: str, Enum

Available reprojection error formulations for calibration refinement.

RMSE = 'RMSE'
MEAN = 'MEAN'
MSE = 'MSE'
calibrate_stereo(dots_cam0, dots_cam1, grid, img_dims, filenames=None, optimize_distortion=True, precision=0.001, max_iter=40, num_threads=None, error_formulation='RMSE')[source]

Estimate stereo camera calibration parameters from matched dot targets.

The function starts with OpenCV single-camera and stereo calibration to get an initial estimate, then passes the flattened parameters to the C++ bundle adjustment routine for refinement. The returned calibration is stored in Pyvale dataclasses and uses millimetres for translation and degrees for the stereo rotation angles.

Parameters:

  • dots_cam0 (list[np.ndarray] or np.ndarray) – Matched 2D image coordinates for camera 0 and camera 1. Each image pair must contain the same number of points in the same order.

  • dots_cam1 (list[np.ndarray] or np.ndarray) – Matched 2D image coordinates for camera 0 and camera 1. Each image pair must contain the same number of points in the same order.

  • grid (list[np.ndarray] or np.ndarray) – Corresponding 3D calibration target coordinates for each image pair. The first dimension must match the number of image pairs.

  • img_dims (list[int] or np.ndarray) – Image dimensions as [width, height] in pixels.

  • filenames (list[str] or list[pathlib.Path] or None, optional) – Optional names for the calibration images. This is currently only checked for length consistency when provided.

  • optimize_distortion (bool, optional) – If True, refine radial and tangential distortion coefficients. If False, distortion coefficients are set to zero before refinement.

  • precision (float, optional) – Convergence tolerance passed to the C++ optimizer.

  • max_iter (int, optional) – Maximum number of C++ refinement iterations.

  • num_threads (int or None, optional) – Number of OpenMP threads to use in the C++ optimizer. If None, the current runtime default is used.

  • error_formulation ({"RMSE", "MEAN", "MSE"}, optional) – Error metric used by the C++ calibration optimizer.

Returns:

tuple[Calib, np.ndarray, np.ndarray] – The refined stereo calibration, followed by per-point reprojection errors for camera 0 and camera 1.

Raises:

  • TypeError – If the camera point arrays and grid are not provided using compatible container types, or if optimize_distortion is not boolean.

  • ValueError – If image-pair counts, point counts, shapes, filenames, image dimensions, or the error formulation are invalid.