Configuration

CamCalib is config-driven: one YAML describes the board, the inputs, and the solve. This page documents every key. For the commands that consume them see the CLI reference.

Camera-only config

`board`

Key	Type	Required for	Description
`board_type`	`apriltag \| chessboard \| aruco`	all	Target family
`rows`, `cols`	int	all	Tag rows/cols; inner corners for chessboard
`tag_size`	float (m)	apriltag	Tag edge length
`tag_spacing`	float	apriltag	Gap between tags as a fraction of `tag_size`
`tag_family`	string	apriltag	e.g. `t36h11`
`square_size`	float (m)	chessboard	Square edge length
`marker_size`	float (m)	aruco	Marker edge length
`marker_separation`	float (m)	aruco	Gap between markers
`aruco_dict`	string	aruco	OpenCV dictionary name

`cameras[]`

Key	Type	Default	Description
`camera_id`	int	—	Index; `reference_camera` refers to it
`name`	string	—	Label used in reports
`source_type`	`images \| rosbag_topic \| ros2bag \| euroc \| timestamped_images \| video`	—	Input format
`source_path`	path	—	Directory, bag, or EuRoC camera folder
`topic`	string	—	Image topic — bag sources only
`distortion_model`	`radtan \| equidistant \| double_sphere \| eucm \| fov \| omni_radtan`	—	See Camera model
`shutter_type`	`global \| rolling`	`global`	`rolling` enables readout calibration
`factor_hz`	float	`0`	Subsample to this frame rate; `0` uses every frame

Models may be mixed across cameras in one rig.

`optimizer`

Key	Type	Default	Description
`max_iterations`	int	`15`	LM iterations for the joint solve
`max_init_frames`	int	`100`	Cap on frames used for OpenCV init; `0` = no cap
`pixel_sigma`	float	`1.0`	Observation noise, pixels
`huber_threshold`	float	`1.345`	Huber robust-loss threshold

Top-level

Key	Type	Default	Description
`corner_subsample`	`top_left \| two_diag \| all`	`top_left`	Corners kept per AprilGrid tag. `top_left` gives 3–5× speedup for under 0.1% quality drift; auto-falls back to `all` on sparse data
`rerun_outliers`	bool	`true`	Outlier-driven second pass, with a pathology guardrail
`optimize_time_offset`	bool	`false`	Camera–camera time offsets; multi-camera only
`rerun_visualization`	bool	`true`	Launch the Rerun 3D viewer; suppressed in batch
`reference_camera`	int	`0`	Camera the extrinsics are expressed against
`output_file`	path	—	Result path
`output_format`	`yaml \| json`	`yaml`	Result format

Camera–IMU config

A different shape: input / board / camera_input / solve / output.

`input`

Key	Type	Description
`format`	`ros1 \| ros2 \| euroc`	Input format
`path`	path	Bag file or EuRoC `mav0` directory
`bags`	list of paths	Batch mode — calibrate many sequences from one config, each into `bag<NN>/cam_imu.json`
`imu_topics`	list	IMU topics; the first is the base IMU
`imus`	list of objects	Per-IMU options, e.g. `{gyro_only: true}`
`window_mode`	`manual \| …`	`manual` honours the explicit `t0`/`window` below
`t0`	float (s)	Window start
`window`	float (s)	Window length
`cache_dir`	path	Detection cache — reused across runs

`camera_input`

Cam-IMU calibration is a two-step workflow: calibrate the cameras first, then feed that result in here.

Key	Type	Default	Description
`path`	path	—	Camera calibration produced by `camcalib calibrate`
`free_intrinsics`	bool	`false`	Re-estimate intrinsics rather than pinning them
`estimate_readout`	bool	`false`	Estimate rolling-shutter readout here

`solve`

Key	Type	Default	Description
`state_hz`	float	`30.0`	Rate of pose/velocity/bias state nodes. Matters on dynamic rigs — reproj, lever, and `td` alias at low rates and plateau near 30 Hz; flat on gentle sequences
`max_iterations`	int	—	LM iterations
`imu_intrinsics`	`dw_da \| …`	—	Which IMU intrinsics to solve
`imu_intrinsics_model`	`kalibr \| rpng \| calyx`	—	Parameterisation. A convention, not a quality lever — all three recover identical extrinsics. See IMU model
`estimate_t_ga`	bool	`false`	Estimate the base IMU’s internal gyro↔accel offset
`sigma_t_ga`	float	—	Staged prior on `t_ga`
`corner_subsample`	`top_left \| two_diag \| all`	`top_left`	As above
`sigma_td_prior`	float	—	Prior on the camera–IMU time offset; `0.0` disables
`init_kwargs`	object	—	Initialiser options, e.g. `{keyframe_hz: 2.0, scale_rel_tol: 0.3}`

`output`

Key	Type	Description
`path`	path	Result JSON

Worked example

input:
  format: ros1
  path: /data/tum_vi/raw/dataset-calib-imu1.bag
  imu_topics: ["/imu0"]
  window_mode: manual
  t0: 3.0
  window: 45.0
  cache_dir: /tmp/camcalib_tumvi_detcache
board: {board_type: apriltag, rows: 6, cols: 6, tag_size: 0.088, tag_spacing: 0.3, tag_family: t36h11}
camera_input:
  path: /tmp/tumvi_calib_ds_cam0.yaml
  free_intrinsics: false
  estimate_readout: false
solve:
  state_hz: 8.0
  max_iterations: 40
  imu_intrinsics: dw_da
  corner_subsample: top_left
  sigma_td_prior: 0.0
  init_kwargs: {keyframe_hz: 2.0, scale_rel_tol: 0.3}
output:
  path: /tmp/tumvi_imu1_ds.json

More under examples/configs/ in the repository — tumvi_cam_imu/, tga_t265*/, looperrobotics/, gilabs/.