Third-Party Calibrations
Converting an export: convert_opencv_calibration, convert_matlab_calibration
Both functions convert one third-party calibration export into the same two native files ("migrate" in this package means schema migration only):
<stem>_cameras.json, avgio/cameras/v6.0store holding one camera named<stem>;<stem>_poses.json, avgio/transforms/v5.0file with one pose per posed image, labeledTargetFrame{target} → ViewFrame{image}, itsunits.lengththe export'stvecunit. An image that the export leftnullgets no record.
The round trip is verified before anything is written. The original file is never touched, and an output file that already exists is refused.
What the export leaves implicit
An export does not state everything a reader needs. Each missing piece is an argument, and each is a statement about the file:
file_frameis the pixel frame ofcx, cy.convert_opencv_calibrationdefaults to OpenCV's own frame, with the top-left pixel's centre at (0, 0),PixelFrame{:opencv}.convert_matlab_calibrationdefaults to MATLAB's documented (1, 1),PixelFrame{:julia}. A fitted principal point cannot tell the two apart (two fits of one capture differ by less than a pixel), so override a default only for a file you have verified to be in another frame.file_unitis the unit oftvec, which is whatever unit the person who typed the object points used for the pattern. It is required unless the file declares it (tvec_unit, or this package's ownunitkey). A declaration that disagrees with the caller is an error, never a silent rescale. On one capture, the OpenCV export was in metres and the MATLAB export in millimetres.imagesandimage_sizeare required.imagesgives one unique, non-empty name per pose entry, in the export's order; together withimage_sizeit supplies the positional join and the image extent that an export leaves to its reader.
MATLAB specifics
- MATLAB's
mean_erroris a mean reprojection error, not an RMS, and it is recorded as such (error_statistic = "mean"). - MATLAB's board frame has x and y exchanged relative to OpenCV's for the same pattern. The poses are kept in MATLAB's own board frame, unchanged, so give
targeta name that keeps them apart from an OpenCV calibration's. - The toolbox's exports declare no
tvec_unit, sofile_unitis required. This stack's captures were typed in millimetres. - A fisheye export is read as VGC's
Scaramuzzamodel. Itsstretch_matrixis factored asS = U·Q. The parta0·Ugoes intoK, andQ, a rotation about the optical axis (a fraction of a degree in practice), goes into the camera frame. Every returned pose carries that rotation, so the camera and the poses stay one consistent model. - A non-positive
a0is MATLAB's mirrored solution, with the target behind the camera. It is refused rather than read as a camera.
The readers and the writer
The conversions are built on load_opencv_calibration and load_matlab_calibration. They return an ExternalCalibration, a foreign-format adapter holding VGC values: the camera as a CameraModel, and the poses as EuclideanMaps labeled TargetFrame{target} → CameraFrame. The conversion relabels them → ViewFrame{image}.
load_kalibr_camchain([file_frame,] path; camera = "cam0") reads one camera of a Kalibr camchain.yaml as a BoundedCamera: its camera and distortion models through kalibr_lens, its resolution as the extent, and its principal point moved from OpenCV's pixel frame (Kalibr's, which the file does not state) to COLMAP's.
save_opencv_calibration writes one of our cameras back out in the OpenCV shape. It is the one place where a pixel frame is a conversion target (to_frame) rather than a statement about a file.
The command line
bin/vgio_migrate.jl converts a third-party calibration from the shell. It is a dry run unless you give --apply: the export is converted into a temporary directory and verified, and nothing is written.
julia --project=<VisualGeometryToolkitIO> bin/vgio_migrate.jl opencv --help
… opencv --images IMGDIR --image-size 6000x4000 --file-unit m calibration_opencv_full.json
… matlab --images IMGLIST --image-size 6000x4000 --file-unit mm --target board_matlab \
--apply calibration_matlab_fisheye.json