pyvale.calib package

Submodules

• pyvale.calib.calibdataclass module
  • CamIntrinsics
    • CamIntrinsics.fx
    • CamIntrinsics.fy
    • CamIntrinsics.fs
    • CamIntrinsics.cx
    • CamIntrinsics.cy
    • CamIntrinsics.distortion
    • CamIntrinsics.camera_matrix
    • CamIntrinsics.__init__()
  • Calib
    • Calib.__init__()
    • Calib.cam0
    • Calib.cam1
    • Calib.translation
    • Calib.rotation
  • savetxt()
  • loadtxt()
• pyvale.calib.calibdotdetect module
  • detect_dots()
  • initial_reconstruction()
  • reprojection_intrinsics_error()
  • create_blob_detector()
  • get_file_list()
  • get_base_name()
  • order_triangle_points_by_angle()
  • angle_between()
• pyvale.calib.calibstereo module
  • ReprojError
    • ReprojError.RMSE
    • ReprojError.MEAN
    • ReprojError.MSE
  • calibrate_stereo()

Module contents

Calibration tools for stereo DIC workflows.

This package exposes the high-level calibration utilities used to detect dot calibration targets and estimate stereo camera parameters. The main public entry points are detect_dots(), calibrate_stereo(), and the Calib and CamIntrinsics result containers.

detect_dots(cam0, cam1, grid_height, grid_width, grid_spacing, hollow_dots, min_dot_fraction=0.5, visualisationCV2=False, visualisationPLT=False)

Detect and match calibration dots in synchronized stereo image pairs.

The calibration target is assumed to contain a regular dark-dot grid with three missing locations marked by light dots. The light-dot triangle is used to orient each image relative to the known grid, then dark blobs are matched to the nearest expected grid locations. Only points detected consistently in both cameras are retained.

Parameters:

• cam0 (pathlib.Path, list[pathlib.Path], np.ndarray, or str) – Camera 0 and camera 1 inputs. Paths and strings may include glob patterns. Lists must contain corresponding image paths for each camera. Array inputs are currently only shape-checked.

• cam1 (pathlib.Path, list[pathlib.Path], np.ndarray, or str) – Camera 0 and camera 1 inputs. Paths and strings may include glob patterns. Lists must contain corresponding image paths for each camera. Array inputs are currently only shape-checked.

• grid_height (int) – Number of dot rows and columns in the full calibration target.

• grid_width (int) – Number of dot rows and columns in the full calibration target.

• grid_spacing (float) – Physical spacing between neighbouring dots in the target coordinate system.

• hollow_dots (list[tuple[int, int]]) – The three missing-dot locations, expressed as (x, y) grid indices. These define the orientation marker used for matching.

• min_dot_fraction (float, optional) – Minimum fraction of grid points that must be matched for an image pair to be accepted.

• visualisationCV2 (bool, optional) – If True, show an OpenCV overlay of detected and matched points for each accepted pair.

• visualisationPLT (bool, optional) – If True, show Matplotlib diagnostic plots of the detected points and grid mapping.

Returns:

tuple[list, list, list, list, list] – Matched 2D points for camera 0, matched 2D points for camera 1, matched 3D grid points, accepted camera 0 filenames, and accepted camera 1 filenames.

Raises:

• TypeError – If the input type is unsupported.

• ValueError – If camera inputs are incompatible, image lists have different lengths, or hollow_dots is not three non-negative (x, y) tuples.

• FileNotFoundError – If a path or glob pattern does not resolve to any images.

class Calib(cam0, cam1, translation, rotation)

Bases: object

Stereo camera calibration parameters.

Variables:

• cam1 (cam0,) – Intrinsic calibration for camera 0 and camera 1.

• translation (np.ndarray) – Translation vector from camera 0 to camera 1 in millimetres.

• rotation (np.ndarray) – Euler rotation angles from camera 0 to camera 1 in degrees, ordered as [theta, phi, psi].

__init__(cam0, cam1, translation, rotation)

cam0

Camera 0 intrinsic parameters

cam1

Camera 1 intrinsic parameters

translation

Translation vector [x, y, z] in mm

rotation

Euler angles [theta, phi, psi] in degrees

class CamIntrinsics(fx, fy, fs, cx, cy, distortion)

Bases: object

Intrinsic camera parameters and distortion coefficients.

The parameters follow the usual pinhole camera model with optional skew and five OpenCV-style distortion coefficients. Focal lengths and the principal point are expressed in pixels.

fx

Focal length in x direction [pixels]

fy

Focal length in y direction [pixels]

fs

Skew coefficient [pixels]

cx

Principal point x-coordinate [pixels]

cy

Principal point y-coordinate [pixels]

distortion

Distortion coefficients [kappa1, kappa2, p1, p2, kappa3]

property camera_matrix

Return the 3x3 intrinsic camera matrix.

Returns:

np.ndarray – Matrix K with focal lengths, skew, and principal point arranged as [[fx, fs, cx], [0, fy, cy], [0, 0, 1]].

__init__(fx, fy, fs, cx, cy, distortion)

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')

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.

savetxt(calib, path, delimiter=',')

Save stereo calibration parameters to a two-column CSV file.

Parameters:

• calib (Calib) – Stereo calibration parameters to save.

• path (str or pathlib.Path) – Output CSV file path.

• delimiter (str, optional) – Delimiter to use between CSV fields. Defaults to a comma.

loadtxt(path, delimiter=',')

Load stereo calibration parameters from a two-column CSV file.

Parameters:

• path (str or pathlib.Path) – Input CSV file path.

• delimiter (str, optional) – Delimiter used between CSV fields. Defaults to a comma.

Returns:

Calib – Stereo calibration parameters read from disk.