Try it in one minute
No dataset and no ROS installation are needed:
python -m pip install "https://github.com/rsasaki0109/Calibrex/releases/download/v0.6.4/calibrex-0.6.4-py3-none-any.whl"
calibrex demo check # new in 0.6.5
The demo writes a small simulated IMU + 4D radar bag and runs calibrex check on it
twice, in a few seconds:
- with the true mounting as the deployed calibration, the check passes;
- with the same mounting turned 4° in pitch, it fails, and names the axis
(
pitch 4.31/0.5 deg [fail]).
It shows what the command prints and how to read it. It is simulated data, not evidence
of accuracy; the real-data results are below.
Your own bag in three commands
calibrex check my_bag/ --plan # seconds: which sensor pairs can be checked, and why not the others
calibrex check my_bag/ --max-duration-s 120 --html check.html # the first 120 s
calibrex check my_bag/ --max-duration-s 120 --tf fixed.urdf # re-check another calibration: seconds, from the cache
- The calibration is read from the bag's
/tf_static; pass --tf (URDF, Kalibr,
FAST-LIO config, frames.yaml) when the bag has none.
- The first run is slow for LiDAR and camera pairs: the estimators register every scan
or track every frame. Measured on a shared CPU: 8.5 min for 40 s of Hesai LiDAR + IMU,
28 min for 180 s of Livox MID360 with the lever arm, on one core.
check now uses every
CPU for its nearest-neighbour queries, about 20 % faster on four cores with identical
estimates. Start with --max-duration-s 120 and --pairs; a re-check of the same
recording takes about 3 s.
inconclusive is not a pass. It means the recording could not judge that pair; the
next steps block at the end of the output says what to try.pass (partial: roll, pitch only) vouches for the named axes only.- Camera pairs need OpenCV:
pip install 'calibrex[opencv]' after the wheel.
The workflow
calibrex estimate my_bag/ --output est/ --html est.html # 1. no calibration yet: measure it, export frames.yaml / static transforms / URDF
calibrex check other_bag/ --tf est/frames.yaml --html check.html # 2. is the deployed calibration still right on another recording?
calibrex drift day1/ day2/ day3/ --output drift/ --html drift.html # 3. did it change over time, and in which bag?
| Step | Command | You get |
|---|
| 1 | calibrex estimate <bag> | per pair each axis with its std and whether the data observed it; frames.yaml (loads with --tf), static_transform_publisher commands, URDF joints (and a Kalibr camchain); axes the data did not observe are marked NOT MEASURED, never written as measured; --html report |
| 2 | calibrex check <bag2> --tf frames.yaml | pass / warn / fail / inconclusive per axis, the axes it could not judge, the error the data could have detected, next steps, progress while it runs; --html report. Without --tf it reads the bag's /tf_static |
| 3 | calibrex drift <bag1> <bag2> ... | per axis stable / drift / inconclusive across recordings of one rig; the deviating bag and the size of the change |
What it covers
| Pair | check judges | estimate / drift |
|---|
| IMU ↔ LiDAR | rotation, clock offset, lever arm when observed | yes |
| camera ↔ IMU | rotation, clock offset (needs intrinsics) | yes |
| camera ↔ LiDAR | rotation only, targetless edge alignment; translation is never judged | needs a rough --tf prior; rotation only |
| LiDAR ↔ LiDAR | rotation and translation | needs a rough --tf prior |
| GNSS ↔ LiDAR, GNSS ↔ IMU | antenna lever arm | yes |
| LiDAR / IMU / INS / wheels ↔ vehicle | the rotation axes the motion excites (roll is unobservable on planar driving); opt-in with --vehicle-frame | yes |
| camera focal length | deployed focal lengths | check only |
Every row reports per axis whether the data could judge it. camera-LiDAR is development evidence,
not a claim: on KITTI and Hilti recordings the unmodified reference never warned or failed and 23 of
27 perturbed candidates were flagged (results).
Your bag format
check, estimate and drift read the bag as it is, with no conversion and no ROS installation;
the format is detected from the file:
| Your bag | Notes |
|---|
rosbag2 directory or .db3 (sqlite3) | per-message zstd / lz4 needs calibrex[rosbag2-compression] |
ROS 2 MCAP (.mcap) | chunks none, zstd or lz4 |
ROS 1 .bag | chunks none, bz2 or lz4 (calibrex[rosbag1-lz4] for lz4) |
This is the beginning of the README. Read the rest at the original. Read the full README ↗
