pyvale.calib.calibdotdetect module

Dot target detection utilities for stereo camera calibration.

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.

initial_reconstruction(dots_cam0, dots_cam1, grid, img_dims, num_file_pairs)

Estimate per-image camera intrinsics and poses for an initial solution.

This helper performs independent nonlinear intrinsics fits for each camera and image pair, then estimates the target pose with OpenCV solvePnP. It is mainly useful for diagnostics and older calibration experiments; the main stereo calibration path uses OpenCV calibration followed by C++ refinement.

Parameters:

• dots_cam0 (sequence[np.ndarray]) – Detected 2D calibration dot coordinates for each camera.

• dots_cam1 (sequence[np.ndarray]) – Detected 2D calibration dot coordinates for each camera.

• grid (sequence[np.ndarray]) – Matching 3D calibration target coordinates for each image pair.

• img_dims (sequence[int]) – Image dimensions as [width, height] in pixels.

• num_file_pairs (int) – Number of image pairs to process.

Returns:

tuple[list[dict], list[dict]] – Per-image intrinsic matrices, distortion vectors, poses, mean errors, and optimizer success flags for camera 0 and camera 1.

reprojection_intrinsics_error(params, gridpoints, dots)

Return point-wise reprojection residuals for intrinsics optimization.

Parameters:

• params (array-like) – Intrinsic and distortion parameters ordered as [fx, fy, cx, cy, k1, k2, p1, p2, k3].

• gridpoints (np.ndarray) – 3D calibration target coordinates.

• dots (np.ndarray) – Observed 2D dot coordinates for one image.

Returns:

np.ndarray – Flattened x and y reprojection residuals. If pose estimation fails, a large residual vector is returned.

create_blob_detector(light)

Create an OpenCV blob detector for light or dark calibration dots.

Parameters:

light (bool) – If True, detect bright dots. If False, detect dark dots.

Returns:

cv2.SimpleBlobDetector – Configured blob detector with area, circularity, colour, and inertia filters suitable for the calibration target.

get_file_list(path0, path1)

Resolve and pair camera image paths from two glob patterns.

If the two glob patterns produce different numbers of files, paths with unmatched base names are reported and excluded. Matching is based on get_base_name().

Parameters:

• path0 (pathlib.Path) – Glob patterns or concrete paths for camera 0 and camera 1 images.

• path1 (pathlib.Path) – Glob patterns or concrete paths for camera 0 and camera 1 images.

Returns:

tuple[list[pathlib.Path], list[pathlib.Path]] – Paired camera 0 and camera 1 paths.

Raises:

FileNotFoundError – If either pattern resolves to no files.

get_base_name(filename)

Return the shared base name used to pair stereo calibration images.

Parameters:

filename (str or pathlib.Path) – Calibration image filename expected to end with _<digit>.tiff.

Returns:

str or None – Filename prefix before the camera/image suffix, or None if the filename does not match the expected pattern.

order_triangle_points_by_angle(pts)

Order three triangle points by decreasing internal angle.

The missing-dot marker is identified from a triangle of light blobs. Ordering by internal angle gives a consistent point order before estimating the affine mapping from image coordinates to target-grid coordinates.

Parameters:

pts (np.ndarray) – Three (x, y) points.

Returns:

np.ndarray – The same three points ordered from largest to smallest internal angle.

angle_between(p1, p2, p3)

Calculate the angle at p2 formed by points p1, p2, and p3.

Parameters:

• p1 (np.ndarray) – Two-dimensional points.

• p2 (np.ndarray) – Two-dimensional points.

• p3 (np.ndarray) – Two-dimensional points.

Returns:

float – Angle in degrees.