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.

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_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. Run python calibrate.py --help for the full list.