Camera calibration (ChArUco)

Calibrate camera intrinsics from a live camera using a ChArUco board (OpenCV DICT_5X5_1000). Results are written as JSON (camera_matrix, distortion_coefficients, reprojection error, image count).

Setup

pip install -r requirements.txt

Board

Use a ChArUco board that matches the dictionary and the grid sizes you configure in run.py (width / height are square counts; square_size / marker_size are physical sizes in meters).

• Board generator (Holy Cows): cowlibration-board

Usage (run.py)

1. Open run.py and set the Calibration() chain to match your camera index, board geometry, and resolution.
2. Print or display the board and move it through many poses in view of the camera.
3. Run:

python run.py

A preview window shows detections. Press q to stop capture and run calibration (at least 3 frames with valid detections are required).

If you enable with_manual_capture(True), detections are still rendered live, but frames are only added when you press Space. Press q to finish and calibrate.

If you enable with_max_detection_accuracy(True), the tool stops skipping frames and runs the heaviest detection/refinement path on every frame, even for live camera input.

If you enable with_preview_rectified_captures(True), the tool shows a post-calibration slideshow of the captured images with overlays removed and the board rectified from the solved calibration.

By default, run.py writes a timestamped file under outputs/ (see get_default_output_file_path()). Outputs are JSON; see Output JSON below.

What to edit in run.py

Call	Meaning
with_input(PORT(n))	Camera device index (0, 1, …).
with_input(IMAGES("path"))	Use a folder of images instead of a live camera (same resolution for every image; supports HEIC/HEIF with local decoder tools, and runs more aggressive offline detection).
with_output_file_path(...)	Where to save the calibration JSON.
with_square_size / with_marker_size	Square and marker sizes in meters.
with_width / with_height	Board size in squares (ChArUco grid).
with_resolution(w, h)	Requested capture size.
with_limit_fps(k)	Skip k frames between detections (0 = detect every frame).
with_manual_capture(True)	Show live detections continuously and capture only on Space.
with_max_detection_accuracy(True)	Process every frame with the heaviest detection path.
with_preview_rectified_captures(True)	Show a post-calibration slideshow of rectified captures.
with_use_wpilib(True)	Use WPILib cscore instead of OpenCV VideoCapture (optional).
with_set_fps(True) + with_fps(n)	Ask the driver for a fixed FPS (optional; can be flaky on some systems).

The Calibration class and its methods live in calibrate.py if you need more options.

Output JSON

• camera_matrix — 3×3 row-major flatten
• distortion_coefficients — five coefficients
• avg_reprojection_error
• num_images — number of valid detection frames used

Advanced: command line (calibrate.py)

For one-off runs without editing code, you can use the CLI. Provide exactly one of --port or --image_folder, plus --output_file_path, board sizes, and optional resolution / FPS flags. Add --manual_capture for the space-to-capture flow, --max_detection_accuracy for the slowest/strongest detector path, and --preview_rectified_captures for the rectified slideshow. Run python calibrate.py --help for the full list.