`charucal calibrate`¶

The calibrate command guides you through capturing board images and produces a calibration.json file that can be loaded at runtime by CameraTransformer.

Usage¶

charucal calibrate [OPTIONS]

ChArUco pattern options¶

These must match the physical board you printed.

Option	Type	Description
`--width INT`	integer	Number of squares along the horizontal axis
`--height INT`	integer	Number of squares along the vertical axis
`--square-length METERS`	float	Side length of one chessboard square in meters
`--marker-length METERS`	float	Side length of the ArUco marker inside each square in meters
`--dict NAME`	string	ArUco dictionary. Accepts `DICT_4X4_100`, `4X4_100`, or the raw integer constant (default: `DICT_4X4_100`)

Input options¶

The --camera flag is repeated once per physical camera. Each invocation accepts either a live device or a set of image files.

Option	Description
`--camera SOURCE [SOURCE ...]`	Camera index (integer), video path, or image glob(s). Repeat for each camera.
`--resolution WIDTHxHEIGHT`	Override resolution for live cameras (e.g. `1920x1080`)
`--fps INT`	Override framerate for live cameras

Live cameras¶

Pass device indices (integers). On most Linux systems /dev/video0 is 0, /dev/video1 is 1, and so on.

charucal calibrate \
  --width 10 --height 8 \
  --square-length 0.115 --marker-length 0.086 \
  --camera 0 \
  --camera 1 \
  --camera 2

Image files¶

Pass glob patterns. Each --camera can match multiple files, which is useful when images are named with a frame index.

charucal calibrate \
  --width 10 --height 8 \
  --square-length 0.115 --marker-length 0.086 \
  --camera "captures/cam0/*.jpg" \
  --camera "captures/cam1/*.jpg" \
  --camera "captures/cam2/*.jpg"

All cameras must have the same number of frames

When using image files, each --camera must match the same number of files. Each set of matched files is treated as one capture, so the first file from each camera forms the first capture, the second file from each camera forms the second capture, and so on.

Output options¶

Option	Default	Description
`--output PATH`	`calibration.json`	Destination path for the calibration JSON file
`--ref-camera INDEX`	auto	Override the reference camera index

Interactive controls (live mode)¶

Key	Action
`Space`	Save the current frame set as a capture (only works when all cameras detect corners)
`Enter`	Finish capturing and run calibration
`Q` or `Esc`	Abort without saving

The terminal displays a live grid diagram for every camera. Each cell represents one inner corner of the ChArUco board:

██ — corner detected
░░ — corner not detected

The status below each grid changes from red to green when enough corners are visible.

Image review mode¶

When you supply image files, ChArUcal automatically processes every frame set and then presents an interactive review screen where you can browse the results and exclude bad frames before calibration runs.

Key	Action
`H` or `Left`	Previous capture
`L` or `Right`	Next capture
`Space`	Toggle include / exclude for the current capture
`Enter`	Run calibration on included captures
`Q` or `Esc`	Abort without saving

Examples¶

Three webcams, large board, custom output path:

charucal calibrate \
  --width 12 --height 9 \
  --square-length 0.08 --marker-length 0.06 \
  --camera 0 --camera 1 --camera 2 \
  --output results/my_rig.json

Two cameras from pre-captured JPEG frames:

charucal calibrate \
  --width 10 --height 8 \
  --square-length 0.115 --marker-length 0.086 \
  --camera "frames/left_*.jpg" \
  --camera "frames/right_*.jpg"

Force 1080p and 30 FPS on live cameras:

charucal calibrate \
  --width 10 --height 8 \
  --square-length 0.115 --marker-length 0.086 \
  --camera 0 --camera 1 \
  --resolution 1920x1080 --fps 30

charucal calibrate¶