Camera Calibration

Tools for ChArUco and checkerboard calibration of perspective and fisheye lenses from ordinary single-camera images: print a board, capture photos, estimate intrinsics, export JSON / ROS YAML, undistort, and visualize distortion. PS3 Eye live capture and preview helpers are included too.

Each tool lives in its own folder with a full README (flags, examples, notes). Implementation is in camera_calibration/; run everything from the repo root.

Fisheye support: see the single-image workflow for angular and asymmetric models, stable validation, cached observations and spherical output.

Setup

python3 -m venv .venv
source .venv/bin/activate
python -m pip install -e .

Or python -m pip install -r requirements.txt and run from the repo root. The CLI is python -m camera_calibration <command> (or camera-calibration after an editable install).

Tools

Tool	Command	README
Generate a ChArUco board	python -m camera_calibration generate-charuco	generate-charuco/README.md
Calibrate, assess coverage and compare models	python -m camera_calibration calibrate	calibrate/README.md
Undistort images	python -m camera_calibration undistort	undistort/README.md
Visualize K / distortion	python -m camera_calibration visualize	visualize/README.md
Diagnose a capture set	python -m camera_calibration diagnose	diagnose/README.md
Validate on held-out images	python -m camera_calibration validate	validate/README.md
Live ChArUco (PS3 Eye)	python live-calibration/live_charuco_calibration.py	live-calibration/README.md
PS3 Eye preview / focus	python ps3eye-tools/test_ps3eye_preview.py	ps3eye-tools/README.md

Examples

Print a tiled A1 board, then calibrate from photos of it:

python -m camera_calibration generate-charuco \
  --paper A1 --tile-paper A3 --margin 10 \
  --squares-x 7 --squares-y 10

python -m camera_calibration calibrate path/to/images \
  --board charuco \
  --squares-x 7 --squares-y 10 --square-size 79.14 \
  --dictionary DICT_4X4_50 --auto-select \
  --camera-name ps3eye

Same square-count flags work for a checkerboard (--board checkerboard). Then undistort or inspect the result:

python -m camera_calibration undistort path/to/photo.jpg \
  --calibration output/ps3eye-charuco-simple.json \
  --output output/undistorted/photo.jpg

python -m camera_calibration visualize output/ps3eye-charuco-simple.json

Count squares (not inner corners) for both board types. --square-size is the measured edge of one square.

New calibrations use encoded pixels and ignore EXIF display orientation. Images with different dimensions are rejected rather than rotated to fit. Legacy profiles retain their previous loading policy. See coordinate policies.

Layout

camera_calibration/   # library + unified CLI
generate-charuco/     # board PDF/PNG
calibrate/            # folder calibration + ROS YAML notes
undistort/
visualize/
diagnose/
validate/
live-calibration/     # PS3 Eye live ChArUco
ps3eye-tools/         # PS3 Eye preview / focus
docs/images/